read_surf: Read Surface Data from a File

In bbuchsbaum/neurosurf: Data structures and visualization for surface-based neuroimaging data

Read Surface Data from a File

Description

This function reads surface data from a file in one of the supported formats.

Usage

read_surf(
  surface_name,
  surface_data_name = NULL,
  colind = NULL,
  nodeind = NULL
)

Arguments

surface_name	the name of the file containing the surface geometry.
surface_data_name	the name of the file containing the values to be mapped to the surface (optional).
colind	the columns/samples to load (optional), only if surface_data_name is not NULL
nodeind	the subset of node indices to load

Details

The function supports reading surface data from various formats including:

• Freesurfer ASCII (.asc)

• Freesurfer binary

• GIFTI (.gii)

• NIML Surface Dataset (.niml.dset)

The format is determined automatically from the file extension.

Value

an instance of the class: SurfaceGeometry or NeuroSurface or NeuroSurfaceVector

Examples

# Find the path to the example surface file in the package
surf_file <- system.file("extdata", "std.8.lh.white.asc", package = "neurosurfr")

# Check if the file exists
if (file.exists(surf_file)) {
  # Read the surface data
  surf <- read_surf(surf_file)

  # Display basic information about the surface
  print(surf)

  # Get summary statistics of the surface data
  summary(surf@data)

  # Visualize the surface if rgl is available
  if (requireNamespace("rgl", quietly = TRUE)) {
    # Plot the surface mesh
    rgl::open3d()
    rgl::shade3d(surf@geometry@mesh, col = "lightblue")
    rgl::title3d(main = "Example Surface")

    # If the surface has data values, color the mesh by these values
    if (length(surf@data) > 0) {
      # Normalize data to [0,1] for coloring
      norm_data <- (surf@data - min(surf@data)) / (max(surf@data) - min(surf@data))

      # Create a color palette
      colors <- grDevices::colorRampPalette(c("blue", "cyan", "green",
                                             "yellow", "red"))(100)

      # Map data values to colors
      col_idx <- ceiling(norm_data * 99) + 1
      vertex_colors <- colors[col_idx]

      # Plot colored mesh
      rgl::open3d()
      rgl::shade3d(surf@geometry@mesh, col = vertex_colors)
      rgl::title3d(main = "Surface Colored by Data Values")
    }
  }
} else {
  message("Example surface file not found. This may occur if the package ",
          "was installed without the example data.")
}


load a surface from a surface geometry file with optional mapped surface data

bbuchsbaum/neurosurf documentation built on June 10, 2025, 8:22 p.m.