CorpusCallosum: fastsurfer_cc.py

Note

We recommend to run FastSurfer-CC with the standard run_fastsurfer.sh interfaces </overview/FLAGS.md>!

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.

For detailed documentation, please refer to:

  • Module Overview: Detailed description of the pipeline, workflow, and analysis options.

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

Quickstart

python3 fastsurfer_cc.py --sd /path/to/fastsurfer/output --sid test-case --verbose

Gives all standard outputs. The corpus callosum morphometry can be found at stats/callosum.CC.midslice.json including 100 thickness measurements and the areas of sub-segments.

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_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]
                        [--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_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 commisures are on the coordinate line, and the posterior commissure is at the origin - standardizing the head position.

Default: mri/transforms/orient_volume.lta

--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.

Corpus Callosum Pipeline

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.

Overview

This pipeline combines localization and segmentation deep learning models to:

  1. Detect AC (Anterior Commissure) and PC (Posterior Commissure) points

  2. Extract and align midplane slices

  3. Segment the corpus callosum

  4. Perform advanced morphometry for corpus callosum, including subdivision, thickness analysis, and various shape metrics

  5. Generate visualizations and measurements

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

This creates:

  • contour_<idx>.txt: Multi-slice contour data for 3D reconstruction

  • thickness_values_<idx>.txt: Thickness measurements across all slices

  • thickness_measurement_points_<idx>.txt: 3D vertex indices for thickness measurements

Benefits:

  • Enables volumetric thickness analysis

  • Supports advanced 3D visualizations with proper surface topology

  • Creates FreeSurfer-compatible overlay files for integration with other tools

For visualization instructions and outputs, see the cc_visualization.py documentation.

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

For 2D visualization instructions and outputs, see the cc_visualization.py documentation.

Choosing Analysis Mode

Use 3D Analysis (--slice_selection all) when:

  • You need complete volumetric analysis

  • Surface-based visualization is required

  • Integration with FreeSurfer workflows is needed

  • Comprehensive thickness mapping across the entire corpus callosum is desired

Use 2D Analysis (--slice_selection middle or specific slice) when:

  • Traditional single-slice morphometry is sufficient

  • Faster processing is preferred

  • Focus is on mid-sagittal cross-sectional measurements

  • Compatibility with classical corpus callosum studies is needed

Note: The default behavior is --slice_selection all for comprehensive 3D analysis. Use --slice_selection middle to process only the middle slice for faster, traditional 2D analysis.

JSON Output Structure

The pipeline generates two main JSON files with detailed measurements and analysis results:

stats/callosum.CC.midslice.json (Middle Slice Analysis)

This file contains measurements from the middle sagittal slice and includes:

Shape Measurements (single values):

  • total_area: Total corpus callosum area (mm²)

  • total_perimeter: Total perimeter length (mm)

  • circularity: Shape circularity measure (4π × area / perimeter²)

  • cc_index: Corpus callosum shape index (length/width ratio)

  • midline_length: Length along the corpus callosum midline (mm)

  • curvature: Average curve of the midline (degrees), measured by angle between it’s sub-segements

Subdivisions

  • areas: Areas of CC using an improved Hofer-Frahm sub-division method (mm²). This gives more consistent sub-segemnts while preserving the original ratios.

Thickness Analysis:

  • thickness: Average corpus callosum thickness (mm)

  • thickness_profile: Thickness profile (mm) of the corpus callosum slice (100 thickness values by default, listed from anterior to posterior CC ends)

Volume Measurements (when multiple slices processed):

  • cc_5mm_volume: Total CC volume within 5mm slab using voxel counting (mm³)

  • cc_5mm_volume_pv_corrected: Volume with partial volume correction using CC contours (mm³)

Anatomical Landmarks:

  • ac_center: Anterior commissure coordinates in original image space

  • pc_center: Posterior commissure coordinates in original image space

  • ac_center_oriented_volume: AC coordinates in standardized space (orient_volume.lta)

  • pc_center_oriented_volume: PC coordinates in standardized space (orient_volume.lta)

  • ac_center_upright: AC coordinates in upright space (cc_up.lta)

  • pc_center_upright: PC coordinates in upright space (cc_up.lta)

stats/callosum.CC.all_slices.json (Multi-Slice Analysis)

This file contains comprehensive per-slice analysis when using --slice_selection all:

Global Parameters:

  • slices_in_segmentation: Total number of slices in the segmentation volume

  • voxel_size: Voxel dimensions [x, y, z] in mm

  • subdivision_method: Method used for anatomical subdivision

  • num_thickness_points: Number of points used for thickness estimation

  • subdivision_ratios: Subdivision fractions used for regional analysis

  • contour_smoothing: Gaussian sigma used for contour smoothing

  • slice_selection: Slice selection mode used

Per-Slice Data (slices array):

Each slice entry contains the shape measurements, thickness analysis and sub-divisions as described above.