emorycn2l/clin-fastsurfer-3d repository overview

This image is based on the deepmi/FastSurfer model and was retrained using 200 manually-edited clinical MRI scans from the Emory Healthcare. The image can be used to segment clinical quality MRI T1 weighted 3D images into 95 brain regions, according to Freesurfer's DKT atlas. The pipeline also includes the surface reconstruction with outputs conformed to the Freesurfer formats and namings, but this feature can also be switched off. Our preliminary results showed improved performance of this model on clinical-quality images over the original fastsurfer model which was trained on high-quality research MR scans.

⁠Usage example:

docker pull  emorycn2l/clin-fastsurfer-3d
 
docker run --gpus all \
           -v /home/${user}/${my_input_data_dir}:/data \
           -v /home/${user}/${my_output_dir}:/output \
           -v /home/${user}/${my_fs_license_dir}:/fs_license \
           --rm --user $(id -u):$(id -g) \
           emorycn2l/clin-fastsurfer-3d \
           --fs_license /fs_license/license.txt \
           --t1 /data/${subject}/${session}/anat/${t1_name} \
           --sid ${out_subject_id} --sd /outdir --parallel
           *additional-fastsurfer-flags*

⁠Required Arguments

• --sd: Output directory $SUBJECTS_DIR (equivalent to FreeSurfer setup). The following directories will be created:

  • $SUBJECTS_DIR/sid/mri
  • $SUBJECTS_DIR/sid/surf

• --sid: Subject ID for the directory inside $SUBJECTS_DIR to be created ($SUBJECTS_DIR/sid/...).

• --t1: T1 full head input (not bias corrected, global path).

  • Note: Outputs will be in the conformed space (as in FreeSurfer; UCHAR, 256x256x256, 1 mm voxels, and standard slice orientation).

• --fs_license: Path to FreeSurfer license key file (not needed if only segmentation is called, see below).

  • Register (for free) at https://surfer.nmr.mgh.harvard.edu/registration.html⁠ to obtain it if you do not have FreeSurfer installed so far. The license file is usually located in $FREESURFER_HOME/license.txt or $FREESURFER_HOME/.license .

⁠Optional Pipeline Related Arguments

• --seg_only: Only run FastSurferCNN (generate segmentation, do not run the surface pipeline).

• --seg_log: Name and location for the log file for the segmentation (FastSurferCNN).
  Default: $SUBJECTS_DIR/$sid/scripts/deep-seg.log

• --surf_only: Only run the surface pipeline (recon_surf).
  Note: The segmentation created by FastSurferCNN must already exist.

• --device: Select device for neural network segmentation. Options:

  • auto, cpu, cuda, cuda:<device_num>, mps
    Default: "auto" (checks for GPU, then falls back to CPU).
    Note: "mps" is for Apple Silicon GPUs. Default location: $SUBJECTS_DIR/$sid/mri/aparc.DKTatlas+aseg.deep.mgz

• --run_cereb: Run the cerebellum sub-segmentation in case your input image resolution resolution is ~1mm or higher. Outputs cerebellar sub-segmentation with detailed WM/GM delineation. This is not recommended for use with lower resolution images.

• --cereb_segfile: Name of the cerebellum segmentation file. If not provided, only the merged segmentation will be stored. Requires an absolute path.
  Default location: $SUBJECTS_DIR/$sid/mri/cerebellum.CerebNet.nii.gz

• --run_hypothal: Run the the hypothalamus segmentation in case your input image resolution resolution is ~1mm or higher. Outputs a hypothalamic subsegmentation including 3rd ventricle, c. mammilare, fornix and optic tracts. This is not recommended for use with lower resolution images.

• --3T: Use the 3T atlas for Talairach registration instead of the default 1.5T atlas. This improves intracranial volume (eTIV) estimates and Talairach registration matrices for 3T but has minimal impact on other stats.

• --no_surfreg: Skip surface registration (sphere.reg) if you don’t plan on doing group analysis. This is automatically generated by default. Use this flag to disable it for faster processing.

⁠Other Optional Arguments

• --parallel: Process both hemispheres in parallel.
• --threads: Target number of threads for all modules (segmentation and surface pipeline).
  Default: 1 (forces FastSurfer to use a single core).
• --py: Python command used in both pipelines.
  Default: python3.10
• --conformed_name: Name of the file where the conformed input image will be saved.
  Default location: $SUBJECTS_DIR/$sid/mri/orig.mgz
• -h, --help: Display help text.