% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/vis_volume.R
\name{volvis.lb.with.surface}
\alias{volvis.lb.with.surface}
\title{Visualize volume slices with surface mesh contours overlaid in lightbox view.}
\usage{
volvis.lb.with.surface(
  subjects_dir,
  subject_id,
  volume = "brain",
  surface = "white",
  hemi = "both",
  surface_color = "#FF0000",
  surface_lwd = 1,
  slices = -5,
  axis = 1L,
  per_row = 5L,
  per_col = NULL,
  border_geometry = "5x5",
  background_color = "#000000",
  silent = TRUE
)
}
\arguments{
\item{subjects_dir}{character string, the FreeSurfer SUBJECTS_DIR.}

\item{subject_id}{character string, the subject identifier.}

\item{volume}{numeric 3D array or character string. Either a 3D brain volume (e.g., from T1.mgz or brain.mgz), or the name of a volume file to load from the subject's \verb{mri/} directory. Defaults to \code{"brain"}.}

\item{surface}{character string or vector of strings, the surface(s) to use for contour extraction. One or more of \code{"white"}, \code{"pial"}, or \code{"inflated"}. If a vector, contours for all surfaces are drawn. Defaults to \code{"white"}.}

\item{hemi}{character string, one of \code{'lh'}, \code{'rh'}, or \code{'both'}. Which hemisphere surface(s) to overlay. Defaults to \code{"both"}.}

\item{surface_color}{character string or character vector, the color(s) for the surface contour lines. If a single color, all surfaces and hemispheres use it. If a vector of length \code{length(surface)}, each surface gets its own color (both hemispheres use it). If a vector of length \code{2 * length(surface)}, colors are assigned as \code{(lh_surf1, rh_surf1, lh_surf2, rh_surf2, ...)}. Defaults to \code{"#FF0000"} (red).}

\item{surface_lwd}{numeric, line width for the contour lines (passed as \code{lwd} to \code{\link[graphics]{segments}}). Defaults to 1.}

\item{slices}{passed to \code{\link[fsbrain]{volvis.lightbox}}. A negative integer N means "use every Nth slice". A numeric vector gives explicit slice indices (1-based). Defaults to \code{-5} (every 5th slice).}

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

\item{per_row}{integer, number of slice images per row in the lightbox grid. Defaults to \code{5L}.}

\item{per_col}{integer, number of rows. If \code{NULL}, computed from \code{per_row}. Defaults to \code{NULL}.}

\item{border_geometry}{character string, geometry for borders between tiles, passed to \code{\link[magick]{image_border}}. Defaults to \code{"5x5"}.}

\item{background_color}{character string, background color for borders and empty tiles. Defaults to \code{"#000000"}.}

\item{silent}{logical, whether to suppress messages. Defaults to \code{TRUE}.}
}
\value{
a magick image instance containing the lightbox with surface contours overlaid. Can be saved with \code{\link[magick]{image_write}} or displayed interactively.
}
\description{
Creates a lightbox view of 2D MRI slices with the cortical surface boundary contours drawn on top. This is the fsbrain equivalent of what FreeSurfer's \code{freeview} or \code{tkmedit} show — useful for quality assessment of surface reconstruction against the underlying MRI volume. The surface mesh is loaded from the subject's FreeSurfer directory and its intersection with each displayed slice plane is computed and drawn as colored contour lines.
}
\examples{
\dontrun{
   fsbrain::download_optional_data();
   subjects_dir <- fsbrain::get_optional_data_filepath("subjects_dir");

   # Axial slices with white surface contours in red:
   img <- volvis.lb.with.surface(subjects_dir, "subject1",
      volume="brain", surface="white", axis=3L,
      surface_color="#FF0000");
   magick::image_write(img, "~/fsbrain_qa_axial.png");

   # Coronal slices in green:
   img <- volvis.lb.with.surface(subjects_dir, "subject1",
      volume="brain", surface="white", axis=2L,
      surface_color="#00FF00");

   # Sagittal slices: left hemisphere red, right hemisphere blue:
   img <- volvis.lb.with.surface(subjects_dir, "subject1",
      volume="brain", surface="white", axis=1L,
      surface_color=c("#FF0000", "#0000FF"));

   # Single hemisphere, pial surface, every 5th slice:
   img <- volvis.lb.with.surface(subjects_dir, "subject1",
      volume="brain", surface="pial", hemi="lh",
      axis=3L, slices=-5, surface_color="#FF8800");

   # Both white and pial surfaces overlaid: white in red, pial in yellow:
   img <- volvis.lb.with.surface(subjects_dir, "subject1",
      volume="brain", surface=c("white", "pial"), axis=3L,
      surface_color=c("#FF0000", "#FFFF00"));

   # White (lh red, rh blue) + pial (lh green, rh orange):
   img <- volvis.lb.with.surface(subjects_dir, "subject1",
      volume="brain", surface=c("white", "pial"), axis=3L,
      surface_color=c("#FF0000", "#0000FF", "#00FF00", "#FF8800"));
}

}
\seealso{
Other volume visualization: 
\code{\link{vis.volume.on.surface}()},
\code{\link{volvis.lb}()},
\code{\link{volvis.lightbox}()}
}
\concept{volume visualization}
