CorpusCallosum: fastsurfer_cc.py

Note

We recommend to run FastSurfer-CC with the standard run_fastsurfer.sh interfaces (see Scripts)!

This is an expert documentation for of FastSurfer CC, which can be run independently with the advanced interface provided here. However, the FastSurfer segmentation is still required as input.

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

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.

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

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.