FastSurferCNN: generate_hdf5.py

The FastSurferCNN directory contains all the source code and modules needed to run the scripts. A list of python libraries used within the code can be found in requirements.txt. The main script is called run_prediction.py within which certain options can be selected and set via the command line:

General

  • --in_dir: Path to the input volume directory (e.g /your/path/to/ADNI/fs60) or

  • --csv_file: Path to csv-file listing input volume directories

  • --t1: name of the T1-weighted MRI_volume (like mri_volume.mgz, default: orig.mgz)

  • --conformed_name: name of the conformed MRI_volume (the input volume is always first conformed, if not already, and the result is saved under the given name, default: orig.mgz)

  • --t: search tag limits processing to subjects matching the pattern (e.g. sub-* or 1030*…)

  • --sd: Path to output directory (where should predictions be saved). Will be created if it does not already exist.

  • --seg_log: name of log-file (information about processing is stored here; If not set, logs will not be saved). Saved in the same directory as the predictions.

  • --strip: strip suffix from path definition of input file to yield correct subject name. (Optional, if full path is defined for --t1)

  • --lut: FreeSurfer-style Color Lookup Table with labels to use in final prediction. Default: ./config/FastSurfer_ColorLUT.tsv

  • --seg: Name of intermediate DL-based segmentation file (similar to aparc+aseg).

Checkpoints and configs

  • --ckpt_sag: path to sagittal network checkpoint

  • --ckpt_cor: path to coronal network checkpoint

  • --ckpt_ax: path to axial network checkpoint

  • --cfg_cor: Path to the coronal config file

  • --cfg_sag: Path to the axial config file

  • --cfg_ax: Path to the sagittal config file

Optional commands

  • --clean: clean up segmentation after running it (optional)

  • --device <str>:Device for processing (auto, cpu, cuda, cuda:<device_num>), where cuda means Nvidia GPU; you can select which one e.g. “cuda:1”. Default: “auto”, check GPU and then CPU

  • --viewagg_device <str>: Define where the view aggregation should be run on. Can be auto or a device (see –device). By default (auto), the program checks if you have enough memory to run the view aggregation on the gpu. The total memory is considered for this decision. If this fails, or you actively overwrote the check with setting --viewagg_device cpu, view agg is run on the cpu. Equivalently, if you define --viewagg_device gpu, view agg will be run on the gpu (no memory check will be done).

  • --batch_size: Batch size for inference. Default=1

Example Command: Evaluation Single Subject

To run the network on MRI-volumes of subjectX in ./data (specified by --t1 flag; e.g. ./data/subjectX/t1-weighted.nii.gz), change into the FastSurferCNN directory and run the following commands:

python3 run_prediction.py --t1 ../data/subjectX/t1-weighted.nii.gz \
--sd ../output \
--t subjectX \
--seg_log ../output/temp_Competitive.log \

The output will be stored in:

  • ../output/subjectX/mri/aparc.DKTatlas+aseg.deep.mgz (large segmentation)

  • ../output/subjectX/mri/mask.mgz (brain mask)

  • ../output/subjectX/mri/aseg_noCC.mgz (reduced segmentation)

Here the logfile “temp_Competitive.log” will include the logfiles of all subjects. If left out, the logs will be written to stdout

Example Command: Evaluation whole directory

To run the network on all subjects MRI-volumes in ./data, change into the FastSurferCNN directory and run the following command:

python3 run_prediction.py --in_dir ../data \
--sd ../output \
--seg_log ../output/temp_Competitive.log \

The output will be stored in:

  • ../output/subjectX/mri/aparc.DKTatlas+aseg.deep.mgz (large segmentation)

  • ../output/subjectX/mri/mask.mgz (brain mask)

  • ../output/subjectX/mri/aseg_noCC.mgz (reduced segmentation)

  • and the log in ../output/temp_Competitive.log

Full commandline interface of FastSurferCNN/generate_hdf5.py

HDF5-Creation

usage: FastSurferCNN/generate_hdf5.py [-h] [--hdf5_name HDF5_NAME]
                                      [--plane {axial,coronal,sagittal}]
                                      [--data_dir DATA_DIR]
                                      [--thickness THICKNESS]
                                      [--csv_file CSV_FILE]
                                      [--pattern PATTERN]
                                      [--image_name IMAGE_NAME]
                                      [--gt_name GT_NAME] [--gt_nocc GT_NOCC]
                                      [--lut LUT] [--combi COMBI]
                                      [--sag_mask SAG_MASK] [--max_w MAX_W]
                                      [--edge_w EDGE_W] [--hires_w HIRES_W]
                                      [--no_grad] [--gm]
                                      [--processing {aparc,aseg,none}]
                                      [--blank_slice_thresh BLANK_SLICE_THRESH]
                                      [--sizes SIZES [SIZES ...]]

Named Arguments

--hdf5_name

path and name of hdf5-data_loader (default: ../data/hdf5_set/Multires_coronal.hdf5)

Default: “../data/hdf5_set/Multires_coronal.hdf5”

--plane

Possible choices: axial, coronal, sagittal

Which plane to put into file (axial (default), coronal or sagittal)

Default: “axial”

--data_dir

Directory with images to load

Default: “/data”

--thickness

Number of pre- and succeeding slices (default: 3)

Default: 3

--csv_file

Csv-file listing subjects to include in file

--pattern

Pattern to match files in directory.

--image_name

Default name of original images. FreeSurfer orig.mgz is default (mri/orig.mgz)

Default: “mri/orig.mgz”

--gt_name

Default name for ground truth segmentations. Default: mri/aparc.DKTatlas+aseg.mgz. If Corpus Callosum segmentation is already removed, do not set gt_nocc. (e.g. for our internal training set mri/aparc.DKTatlas+aseg.filled.mgz exists already and should be used here instead of mri/aparc.DKTatlas+aseg.mgz).

Default: “mri/aparc.DKTatlas+aseg.mgz”

--gt_nocc

Segmentation without corpus callosum (used to mask this segmentation in ground truth). If the used segmentation was already processed, do not set this argument. For a normal FreeSurfer input, use mri/aseg.auto_noCCseg.mgz.

--lut

FreeSurfer-style Color Lookup Table with labels to use in final prediction. Has to have columns: ID LabelName R G B ADefault: FASTSURFERDIR/FastSurferCNN/config/FastSurfer_ColorLUT.tsv.

Default: /config/FastSurfer_ColorLUT.tsv

--combi

Suffixes of labels names to combine. Default: Left- and Right-.

Default: [‘Left-’, ‘Right-‘]

--sag_mask

Suffixes of labels names to mask for final sagittal labels. Default: Left- and ctx-rh.

Default: (‘Left-’, ‘ctx-rh’)

--max_w

Overall max weight for any voxel in weight mask. Default=5

Default: 5

--edge_w

Weight for edges in weight mask. Default=5

Default: 5

--hires_w

Weight for hires elements (sulci, WM strands, cortex border) in weight mask. Default=None

--no_grad

Turn on to only use median weight frequency (no gradient)

Default: False

--gm

Turn on to add cortex mask for hires-processing.

Default: False

--processing

Possible choices: aparc, aseg, none

Use aseg, aparc or no specific mapping processing

Default: “aparc”

--blank_slice_thresh

Threshold value for function filter_blank_slices. Slices with number oflabeled voxels below this threshold are discarded. Default: 50.

Default: 50

--sizes

Sizes of images in the dataset. Default: 256

Default: 256