CorpusCallosum: fastsurfer_cc.py

Note

We recommend running FastSurfer-CC with the standard run_fastsurfer.sh interface (see run_fastsurfer.sh)!

This page documents expert usage of FastSurfer-CC, which can be run independently with the advanced interface provided here. By default, it requires mri/orig.mgz and mri/aseg.auto_noCCseg.mgz from a FastSurfer subject; use --conformed_name and --aseg_name to override those input paths.

FastSurfer-CC is a deep learning-based pipeline for automated segmentation, analysis, and shape analysis of the corpus callosum in brain MRI scans. Also segments the fornix, localizes the anterior and posterior commissure (AC and PC) and standardizes the orientation of the brain.

The documentation is split into three files, please refer to:

  • Module Overview: Description of the pipeline, and the corpus callosum measures produced.

  • Advanced options: Quality control, custom subdivision and visualization options.

  • Output Files: List of output files and their descriptions.

Quickstart

The expert command expects an existing FastSurfer subject containing at least mri/orig.mgz and mri/aseg.auto_noCCseg.mgz by default. The input paths can be overridden with --conformed_name and --aseg_name. It reads those inputs and writes all CC outputs into the subject directory.

Native

python3 CorpusCallosum/fastsurfer_cc.py \
    --sd /data/subjects \
    --sid sub001 \
    --upright_volume mri/upright_volume.mgz \
    --qc_image qc_snapshots/callosum.png \
    --thickness_image qc_snapshots/callosum.thickness.png

Paths that are not absolute are resolved relative to /data/subjects/sub001. The upright volume is useful for checking the midplane and is the anatomical reference for manual CC editing.

Docker

The FastSurfer Docker image normally starts run_fastsurfer.sh. Expert commands therefore override the entrypoint with FastSurfer’s environment-setup wrapper and explicitly invoke fastsurfer_cc.py:

SUBJECTS_DIR=/data/fastsurfer
SID=sub001

docker run --gpus all --rm \
    --user "$(id -u):$(id -g)" \
    --volume "$SUBJECTS_DIR:/output" \
    --entrypoint /fastsurfer/tools/Docker/entrypoint.sh \
    deepmi/fastsurfer:latest \
    python3 /fastsurfer/CorpusCallosum/fastsurfer_cc.py \
    --sd /output \
    --sid "$SID" \
    --upright_volume mri/upright_volume.mgz \
    --qc_image qc_snapshots/callosum.png \
    --thickness_image qc_snapshots/callosum.thickness.png

Singularity or Apptainer

Build or download an image as described in the Singularity documentation, then bind the subject directory and invoke the expert script directly:

SUBJECTS_DIR=/data/fastsurfer
SID=sub001
FASTSURFER_SIF=/containers/fastsurfer-gpu.sif

singularity exec --nv --no-mount home,cwd -e \
    --bind "$SUBJECTS_DIR:/output" \
    "$FASTSURFER_SIF" \
    python3 /fastsurfer/CorpusCallosum/fastsurfer_cc.py \
    --sd /output \
    --sid "$SID" \
    --upright_volume mri/upright_volume.mgz \
    --qc_image qc_snapshots/callosum.png \
    --thickness_image qc_snapshots/callosum.thickness.png

The same command works with Apptainer by replacing singularity with apptainer. For CPU execution with the same image, omit --nv; FastSurfer falls back to the CPU. --no-mount home,cwd -e prevents host Python packages and environment variables from leaking into the container.

These commands generate all standard CC outputs. Morphometry is written to stats/callosum.CC.midslice.json, including 100 thickness measurements and the areas of subsegments.

The expert interface also supports supplied 3D AC/PC voxel coordinates and manual corrections of the upright CC segmentation. Copy mri/callosum.CC.upright.mgz to mri/callosum.CC.upright.manedit.mgz, edit label 192 using mri/upright_volume.mgz as the reference, and pass the edited path to --segmentation_manedit. A manual segmentation containing any fornix label-250 voxels is self-contained and authoritative for the entire fornix. If it has no label 250, the automatic upright and original-space CC segmentations from a previous run are required and supply the fornix. Choose supplied AC/PC coordinates before creating the edit and reuse the exact same coordinates and midplane method for every edit rerun; otherwise regenerate the upright reference and recreate or rebase the correction. See the advanced documentation for complete native, Docker, and Singularity/Apptainer commands.

Full command-line interface

The following section provides a detailed overview of the command-line interface for the FastSurfer-CC pipeline, including all available flags and options.

usage: fastsurfer_cc.py [-h] [-v] [--sd OUT_DIR] [--sid SID]
                        [--conformed_name CONF_NAME] [--aseg_name ASEG_NAME]
                        [--device DEVICE]
                        [--num_thickness_points NUM_THICKNESS_POINTS]
                        [--subdivisions [FRAC ...]]
                        [--subdivision_method {shape,vertical,angular,eigenvector}]
                        [--contour_smoothing CONTOUR_SMOOTHING]
                        [--slice_selection SLICE_SELECTION]
                        [--threads THREADS] [--segmentation SEGMENTATION]
                        [--segmentation_manedit SEGMENTATION_MANEDIT]
                        [--segmentation_in_orig SEGMENTATION_IN_ORIG]
                        [--cc_measures CC_MEASURES]
                        [--cc_mid_measures CC_MID_MEASURES]
                        [--upright_lta UPRIGHT_LTA]
                        [--upright_volume UPRIGHT_VOLUME]
                        [--orient_volume_lta ORIENT_VOLUME_LTA]
                        [--midplane_method {center,fsaverage,fsaverage_symmetry,fsaverage_distance_map}]
                        [--ac_coords X Y Z] [--pc_coords X Y Z]
                        [--qc_image QC_IMAGE]
                        [--save_template_dir SAVE_TEMPLATE_DIR]
                        [--thickness_image THICKNESS_IMAGE] [--surf CC_SURF]
                        [--thickness_overlay THICKNESS_OVERLAY]
                        [--cc_interactive_html CC_HTML]
                        [--cc_surf_vtk CC_SURF_VTK]
                        [--softlabels_cc SOFTLABELS_CC]
                        [--softlabels_fn SOFTLABELS_FN]
                        [--softlabels_background SOFTLABELS_BACKGROUND]

Named Arguments

-v, --verbose

Enable verbose (pass twice for debug-output).

Default: 0

--sd

Directory in which evaluation results should be written. Will be created if it does not exist.

--sid

The subject id to use.

--conformed_name

Name under which the conformed input image will be saved, in the same directory as the segmentation (the input image is always conformed first, if it is not already conformed). The original input image is saved in the output directory as $id/mri/orig/001.mgz. Default: mri/orig.mgz.

Default: 'mri/orig.mgz'

--aseg_name

Name under which the reduced aseg segmentation will be saved, in the same directory as the aparc-aseg segmentation (labels of full aparc segmentation are reduced to aseg). Default: mri/aseg.auto_noCCseg.mgz.

Default: 'mri/aseg.auto_noCCseg.mgz'

--device

Select device to run inference on: cpu, or cuda (= Nvidia gpu) or specify a certain gpu (e.g. cuda:1)

Default: 'auto'

--num_thickness_points

Number of points for thickness estimation.

Default: 100

--subdivisions

List of subdivision fractions for the corpus callosum subsegmentation.The method allows for an arbitrary number of fractions.By default it uses following Hofer-Frahms convention.

Default: [0.167, 0.500, 0.667, 0.750]

--subdivision_method

Possible choices: shape, vertical, angular, eigenvector

Method for contour subdivision. Options: <br>- shape (default): Intercallosal subdivision perpendicular to intercallosal line, <br>- vertical: orthogonal to the most anterior and posterior points in the AC/PC standardized CC contour, <br>- angular: subdivision based on equally spaced angles, as proposed by Hampel and colleagues, <br>- eigenvector: primary direction, same as FreeSurfers mri_cc.

Default: 'shape'

--contour_smoothing

Gaussian sigma for smoothing during contour detection. Higher values mean a smoother CC outline, at the cost of precision.

Default: 5

--slice_selection

Which slices to process. Options: ‘middle’, ‘all’ (default), or a specific slice number.

Default: all

Advanced options

Custom output paths, useful if no standard case directory is used. Relative paths are always relative to the subject_dir defined via –sd and –sid!

--threads

Number of threads to use (defaults to number of hardware threads: 4)

Default: 4

--segmentation, --seg

Output path for corpus callosum and fornix segmentation output.

Default: mri/callosum.CC.upright.mgz

--segmentation_manedit

Edited upright CC segmentation. If it contains fornix label 250, it is self-contained; otherwise the fornix is retained from the automatic segmentation output of a previous run.

--segmentation_in_orig

Output path for corpus callosum and fornix segmentation output in the input MRI space.

Default: mri/callosum.CC.orig.mgz

--cc_measures

Output path for surface-based corpus callosum measures describing shape and volume for each image slice.

Default: stats/callosum.CC.all_slices.json

--cc_mid_measures

Output path for surface-based corpus callosum measures of the midslice describing CC shape and volume.

Default: stats/callosum.CC.midslice.json

--upright_lta

Output path for upright LTA transform. This makes sure the midplane is at 128 in LR direction, but no nodding correction is applied.

Default: mri/transforms/cc_up.lta

--upright_volume

Output path for upright volume (input image with cc_up.lta applied).

--orient_volume_lta

Output path for orientation volume LTA transform. This makes sure the midplane is the volume center, the anterior and posterior commissures are on the coordinate line, and the posterior commissure is at the origin - standardizing the head position.

Default: mri/transforms/orient_volume.lta

--midplane_method

Possible choices: center, fsaverage, fsaverage_symmetry, fsaverage_distance_map

Midsagittal plane finding method. ‘center’: center slice of the input volume, no alignment; ‘fsaverage’: centroid-based alignment to fsaverage template; ‘fsaverage_symmetry’: fsaverage alignment + LR label-symmetry shift refinement (default); ‘fsaverage_distance_map’: fsaverage alignment + distance-map plane-fitting refinement.

Default: 'fsaverage_symmetry'

--ac_coords

Optional AC point as three floating-point coordinates in orig.mgz voxel space. Requires –pc_coords.

--pc_coords

Optional PC point as three floating-point coordinates in orig.mgz voxel space. Requires –ac_coords.

--qc_image

Output path for QC visualization image.

--save_template_dir

Directory path where to save contours.txt and thickness_values.txt files. These files can be used to visualize the CC shape and volume with the cc_visualization.py script.

--thickness_image

Output path for thickness image.

--surf

Output path for surf file for visualization in freeview, use –save_template_dir and contours.txt to obtain source CC contours.

Default: surf/callosum.surf

--thickness_overlay

Output path for corpus callosum thickness overlay file for visualization in freeview, use –save_template_dir and thickness_values.txt to obtain source CC thickness values.

Default: surf/callosum.thickness.w

--cc_interactive_html, --cc_html

Output path to the corpus callosum interactive 3D visualization HTML file.

--cc_surf_vtk

Output path for vtk file, showing the CC 3D mesh for visualization, use –save_template_dir and contours.txt to obtain source CC contours. Example: surf/callosum.vtk.

--softlabels_cc

Output path for corpus callosum softlabels, which contains the soft labels of each voxel. Example: mri/callosum.CC.soft.mgz.

--softlabels_fn

Output path for fornix softlabels, which contains the soft labels of each voxel. Example: mri/fornix.CC.soft.mgz.

--softlabels_background

Output path for background softlabels, which contains the probability of each voxel. Example: mri/background.CC.soft.mgz.

Midplane extraction

The --midplane_method flag controls how the corpus callosum pipeline refines the midsagittal plane before segmentation. This is implemented in CorpusCallosum/registration/midsagittal_plane_alignment.py. When the corpus callosum segmentation does not align well with the mid-sagittal plane, this option can be changed for better results.

Available modes are:

  • fsaverage_symmetry: (default) Align to fsaverage, then search for a small left-right shift that minimizes mirrored aseg-label mismatch near the midline

  • fsaverage: Align to fsaverage without additional refinement (matches publication)

  • center: use the geometric center of the input volume without additional refinement

  • fsaverage_distance_map: fit a midsagittal plane from left/right distance-map symmetry in fsaverage space

The refinement after fsaverage alignment is intentionally conservative, expected to only make adjustments for unusual anatomies, or significant asymmetry.

Supplying AC/PC landmarks

The expert interface accepts paired --ac_coords X Y Z and --pc_coords X Y Z arguments. Values are floating-point voxel coordinates in orig.mgz voxel space. When supplied, the landmark network is skipped and the points are used for segmentation conditioning, morphometry, QC, orientation transforms, and output measurements.

The selected midsagittal plane is minimally rotated and translated so that it contains both 3D landmarks exactly. A plane adjustment larger than 15 degrees emits a warning because this commonly indicates a coordinate-space error.

For example:

python3 CorpusCallosum/fastsurfer_cc.py \
    --sd /data/subjects \
    --sid sub001 \
    --ac_coords 127.4 126.8 128.1 \
    --pc_coords 127.9 103.6 128.7 \
    --upright_volume mri/upright_volume.mgz

For Docker or Singularity/Apptainer, append the same two options to the corresponding expert command. Coordinates are interpreted in the voxel space of the subject’s input mri/orig.mgz, not scanner RAS coordinates. Both points are required, must be finite and distinct, and must lie inside the image. A left-right AC-PC line is rejected because it does not define a stable sagittal plane. These options are available through the expert interface and are not exposed by run_fastsurfer.sh.

Manual CC edits

Warning

Choose and record any supplied AC/PC coordinates before creating a manual CC correction. The automatic run and every edit rerun must use exactly the same --ac_coords, --pc_coords, and --midplane_method values. If these values change, regenerate mri/upright_volume.mgz and mri/callosum.CC.upright.mgz and recreate or explicitly rebase the manual correction on the new upright image. Do not apply an edit created on a different upright plane. Because upright files use a standardized affine, FastSurfer-CC cannot reliably detect every stale edit from file geometry alone.

To reprocess a manual CC correction, first copy the automatic upright segmentation:

SUBJECT_DIR=/data/subjects/sub001
cp "$SUBJECT_DIR/mri/callosum.CC.upright.mgz" \
   "$SUBJECT_DIR/mri/callosum.CC.upright.manedit.mgz"

Edit label 192 in mri/callosum.CC.upright.manedit.mgz using mri/upright_volume.mgz as the anatomical reference. The manual file may also contain fornix label 250. Then rerun the expert command with the manual input:

python3 CorpusCallosum/fastsurfer_cc.py \
    --sd /data/subjects \
    --sid sub001 \
    --segmentation_manedit mri/callosum.CC.upright.manedit.mgz \
    --upright_volume mri/upright_volume.mgz \
    --qc_image qc_snapshots/callosum.png \
    --thickness_image qc_snapshots/callosum.thickness.png

If the manual segmentation contains any voxels with fornix label 250, FastSurfer-CC treats its CC and fornix as self-contained input. If label 250 is absent, FastSurfer-CC instead retains the fornix from the automatic upright and original-space CC segmentations, which must therefore exist from a previous run. It recomputes all CC-derived results and writes mri/callosum.CC.orig.manedit.mgz. The top-level run_fastsurfer.sh --edits workflow also uses this derived file for downstream inpainting. Any label-250 voxels make the manual file authoritative for the entire fornix; remove all label-250 voxels from the manual file to use the automatic fornix instead. Do not manually edit the original-space file.

Note

A direct expert invocation produces the CC outputs, including callosum.CC.orig.manedit.mgz, but does not paint them into the broader aseg outputs. Use the top-level run_fastsurfer.sh --edits workflow when that downstream integration is required. The top-level workflow does not currently accept supplied AC/PC coordinates.

The complete Docker edit rerun is:

SUBJECTS_DIR=/data/fastsurfer
SID=sub001

docker run --gpus all --rm \
    --user "$(id -u):$(id -g)" \
    --volume "$SUBJECTS_DIR:/output" \
    --entrypoint /fastsurfer/tools/Docker/entrypoint.sh \
    deepmi/fastsurfer:latest \
    python3 /fastsurfer/CorpusCallosum/fastsurfer_cc.py \
    --sd /output \
    --sid "$SID" \
    --segmentation_manedit mri/callosum.CC.upright.manedit.mgz \
    --upright_volume mri/upright_volume.mgz \
    --qc_image qc_snapshots/callosum.png \
    --thickness_image qc_snapshots/callosum.thickness.png

The example above resolves the relative manual path inside /output/$SID. A manual segmentation stored elsewhere on the host can instead be mounted read-only and passed by its absolute container path:

MANUAL_EDIT=/data/annotations/sub001_cc_manedit.mgz

docker run --gpus all --rm \
    --user "$(id -u):$(id -g)" \
    --volume "$SUBJECTS_DIR:/output" \
    --volume "$MANUAL_EDIT:/manual-edit.mgz:ro" \
    --entrypoint /fastsurfer/tools/Docker/entrypoint.sh \
    deepmi/fastsurfer:latest \
    python3 /fastsurfer/CorpusCallosum/fastsurfer_cc.py \
    --sd /output \
    --sid "$SID" \
    --segmentation_manedit /manual-edit.mgz \
    --qc_image qc_snapshots/callosum.png

The complete Singularity edit rerun is:

SUBJECTS_DIR=/data/fastsurfer
SID=sub001
FASTSURFER_SIF=/containers/fastsurfer-gpu.sif

singularity exec --nv --no-mount home,cwd -e \
    --bind "$SUBJECTS_DIR:/output" \
    "$FASTSURFER_SIF" \
    python3 /fastsurfer/CorpusCallosum/fastsurfer_cc.py \
    --sd /output \
    --sid "$SID" \
    --segmentation_manedit mri/callosum.CC.upright.manedit.mgz \
    --upright_volume mri/upright_volume.mgz \
    --qc_image qc_snapshots/callosum.png \
    --thickness_image qc_snapshots/callosum.thickness.png

An automatic CC run is only required when the manual segmentation does not contain fornix label 250. If the segmentation used as the editing reference was generated with supplied AC/PC landmarks, append the exact same --ac_coords X Y Z --pc_coords X Y Z arguments to the edit command.

Quality Control

The pipeline can produce a dedicated quality control image, showing the CC contour, AC/PC landmarks and thickness estimation. For this use the --qc_image flag. Additionally, the surface outputs, e.g. --thickness_image, can be used to visualize the CC thickness and also inform quality control. Finally, to confirm the alignment of the CC on the mid-sagittal plane, we can output the upright volume with --upright_volume flag. In this image the mid-sagittal plane is at voxel coordinate 128 in the LR direction.

An example call with all quality control outputs is: .. code-block:: bash

python3 fastsurfer_cc.py –sd /data/subjects –sid sub001

–qc_image /data/qc/sub001/qc_snapshots/callosum.png –thickness_image /data/qc/sub001/qc_snapshots/callosum.thickness.png –upright_volume /data/qc/sub001/mri/upright_volume.mgz

Custom Subdivision Schemes

The pipeline supports custom subdivision schemes for the corpus callosum with the --subdivisions flag. The fractions are relative to the total length of the corpus callosum (midline length). The default is to use the shape-based subdivision scheme (recommended) and the Hofer-Frahms convention.

We can, for example divide the CC into 4 equal parts with the shape-based subdivision scheme:

python3 fastsurfer_cc.py --sd /data/subjects --sid sub001 \
    --subdivision_method shape \
    --subdivisions 0.25 0.5 0.75

Analysis Modes

The pipeline supports different analysis modes that determine the type of template data generated.

3D Analysis

When running the main pipeline with --slice_selection all and --save_template_dir, a complete 3D template is generated:

# Generate 3D template data
python3 fastsurfer_cc.py --sd /data/subjects --sid sub001 \
    --slice_selection all \
    --save_template_dir /data/templates/sub001

The template files can be used to visualize the corpus callosum in 3D with the CorpusCallosum: cc_visualization.py script.

Benefits: - Enables volumetric thickness analysis - Supports advanced 3D visualizations with proper surface topology - Creates surface and overlay files viewable in freeview and for integration with other tools

2D Analysis

When using --slice_selection middle or a specific slice number with --save_template_dir:

# Generate 2D template data (middle slice)
python3 fastsurfer_cc.py --sd /data/subjects --sid sub001 \
    --slice_selection middle \
    --save_template_dir /data/templates/sub001

Benefits: - Faster processing for single-slice analysis - 2D visualization is most suitable for displaying downstream statistics - Compatibility with classical corpus callosum studies

Choosing Analysis Mode

Use 3D Analysis (``–slice_selection all``) when: - Surface-based visualization is required - Comprehensive thickness mapping across the entire corpus callosum is desired - Generating a 3D template, e.g. for mesh visualization or 3D thickness mapping

Use 2D Analysis (``–slice_selection middle`` or specific slice) when: - Faster processing is preferred - A specific slice is selected (e.g. to correct for errors in mid-sagittal plane selection) - Generating a 2D template, e.g. for 2D thickness mapping or plotting of cross-sectional statistics

For advanced 3D visualization options, see the CorpusCallosum: cc_visualization.py documentation.