fsbrain (version 0.7.0)

volvis.slices.with.surface: Export individual volume slices with surface contours to image files.

Description

Creates individual 2D slice images with surface contour overlays and exports them to separate files — ideal for browsing through slices one by one. This is the single-slice export counterpart of volvis.lb.with.surface, which arranges slice images in a lightbox grid. Supports optional slice index labelling and automatic skipping of empty slices (i.e., slices where no surface contour intersects the plane).

Usage

volvis.slices.with.surface(
  subjects_dir,
  subject_id,
  volume = "brain",
  surface = "white",
  hemi = "both",
  surface_color = "#FF0000",
  surface_lwd = 1,
  slices = -5,
  axis = 1L,
  silent = TRUE,
  output_dir = ".",
  output_prefix = NULL,
  image_format = "png",
  label_slices = FALSE,
  label_color = "white",
  label_size = 20,
  label_gravity = "northwest",
  skip_empty = FALSE
)

Value

invisible character vector of file paths that were written.

Arguments

subjects_dir

character string, the FreeSurfer SUBJECTS_DIR.

subject_id

character string, the subject identifier.

volume

numeric 3D array or character string. Either a 3D brain volume, or the name of a volume file to load from the subject's mri/ directory. Defaults to "brain".

surface

character string or vector of strings, the surface(s) to use for contour extraction. One or more of "white", "pial", or "inflated". Defaults to "white".

hemi

character string, one of 'lh', 'rh', or 'both'. Which hemisphere surface(s) to overlay. Defaults to "both".

surface_color

character string or character vector, the color(s) for the surface contour lines. See volvis.lb.with.surface for the color assignment rules. Defaults to "#FF0000" (red).

surface_lwd

numeric, line width for the contour lines. Defaults to 1.

slices

passed to volvis.lightbox. A negative integer N means "use every Nth slice". A numeric vector gives explicit slice indices (1-based). Defaults to -5.

axis

integer, the slice axis. 1 = sagittal, 2 = coronal, 3 = axial (in volume CRS convention). Defaults to 1L.

silent

logical, whether to suppress messages. Defaults to TRUE.

output_dir

character string, directory in which to write the slice image files. Created if it does not exist. Defaults to "." (current working directory).

output_prefix

character string, prefix for output filenames. If NULL, auto-derived as "<subject_id>". Defaults to NULL.

image_format

character string, image format for output files (e.g., "png", "jpg"). Passed to image_write. Defaults to "png".

label_slices

logical, whether to annotate each slice image with its slice index (e.g., "slice 42") in the top-left corner. Uses image_annotate. Defaults to FALSE.

label_color

character string, color for the slice label text. Defaults to "white".

label_size

integer, font size for the slice label. Defaults to 20.

label_gravity

character string, gravity for label placement, passed to image_annotate. Defaults to "northwest".

skip_empty

logical, whether to skip slices where no surface contour intersects the slice plane. Defaults to FALSE.

See Also

Other volume visualization: vis.volume.on.surface(), volvis.lb(), volvis.lb.with.surface(), volvis.lightbox()

Examples

if (FALSE) {
   fsbrain::download_optional_data();
   subjects_dir <- fsbrain::get_optional_data_filepath("subjects_dir");

   # Export all sagittal slices with white surface contours:
   volvis.slices.with.surface(subjects_dir, "subject1",
      volume="brain", surface="white", axis=1L,
      output_dir="~/qa_slices");

   # Export with slice labels, skipping empty slices:
   volvis.slices.with.surface(subjects_dir, "subject1",
      volume="brain", surface="white", axis=3L,
      output_dir="~/qa_slices", label_slices=TRUE,
      skip_empty=TRUE);

   # Both white and pial surfaces, different colors:
   volvis.slices.with.surface(subjects_dir, "subject1",
      volume="brain", surface=c("white","pial"), axis=3L,
      surface_color=c("#FF0000","#FFFF00"),
      output_dir="~/qa_slices");
}