FastSurferCNN: run_model.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 training script is called run_model.py whose options can be set through a configuration file and command line arguments:

  • --cfg: Path to the configuration file. Default: config/FastSurferVINN.yaml

  • --aug: List of augmentations to use. Default: None.

  • --opt: List of class options to use.

The --cfg file configures the model to be trained. See config/FastSurferVINN.yaml for an example and config/defaults.py for all options and default values.

The configuration options include:

Model options

  • MODEL_NAME: Name of model [FastSurferCNN, FastSurferVINN]. Default: FastSurferVINN

  • NUM_CLASSES: Number of classes to predict including background. Axial and coronal: 79 (default), Sagittal: 51.

  • NUM_FILTERS: Filter dimensions for Networks (all layers same). Default: 71

  • NUM_CHANNELS: Number of input channels (slice thickness). Default: 7

  • KERNEL_H: Height of Kernel. Default: 3

  • KERNEL_W: Width of Kernel. Default: 3

  • STRIDE_CONV: Stride during convolution. Default: 1

  • STRIDE_POOL: Stride during pooling. Default: 2

  • POOL: Size of pooling filter. Default: 2

  • BASE_RES: Base resolution of the segmentation model (after interpolation layer). Default: 1

Optimizer options

  • BASE_LR: Base learning rate. Default: 0.01

  • OPTIMIZING_METHOD: Optimization method [sgd, adam, adamW]. Default: adamW

  • MOMENTUM: Momentum for optimizer. Default: 0.9

  • NESTEROV: Enables Nesterov for optimizer. Default: True

  • LR_SCHEDULER: Learning rate scheduler [step_lr, cosineWarmRestarts, reduceLROnPlateau]. Default: cosineWarmRestarts

Data options

  • PATH_HDF5_TRAIN: Path to training hdf5-dataset

  • PATH_HDF5_VAL: Path to validation hdf5-dataset

  • PLANE: Plane to load [axial, coronal, sagittal]. Default: coronal

Training options

  • BATCH_SIZE: Input batch size for training. Default: 16

  • NUM_EPOCHS: Number of epochs to train. Default: 30

  • SIZES: Available image sizes for the multi-scale dataloader. Default: [256, 311 and 320]

  • AUG: Augmentations. Default: [“Scaling”, “Translation”]

Misc. Options

  • LOG_DIR: Log directory for run

  • NUM_GPUS: Number of GPUs to use. Default: 1

  • RNG_SEED: Select random seed. Default: 1

Any option can alternatively be set through the command-line by specifying the option name (as defined in config/defaults.py) followed by a value, such as: MODEL.NUM_CLASSES 51.

To train the network on a given hdf5-set, change into the FastSurferCNN directory and run run_model.py as in the following examples:

Example Command: Training Default FastSurferVINN

Trains FastSurferVINN on multi-resolution images in the coronal plane:

python3 run_model.py \
--cfg ./config/FastSurferVINN.yaml

Example Command: Training FastSurferVINN (Single Resolution)

Trains FastSurferVINN on single-resolution images in the sagittal plane by overriding the NUM_CLASSES, SIZES, PATH_HDF5_TRAIN, and PATH_HDF5_VAL options:

python3 run_model.py \
--cfg ./config/FastSurferVINN.yaml \
MODEL.NUM_CLASSES 51 \
DATA.SIZES 256 \
DATA.PATH_HDF5_TRAIN ./hdf5_sets/training_sagittal_single_resolution.hdf5 \
DATA.PATH_HDF5_VAL ./hdf5_sets/validation_sagittal_single_resolution.hdf5 \

Example Command: Training FastSurferCNN

Trains FastSurferCNN using a provided configuration file and specifying no augmentations:

python3 run_model.py \
--cfg custom_configs/FastSurferCNN.yaml \
--aug None

Full commandline interface of FastSurferCNN/run_model.py

Segmentation

usage: FastSurferCNN/run_model.py [-h] [--cfg CFG_FILE] [--aug AUG] ...

Positional Arguments

opts

See FastSurferCNN/config/defaults.py for all options

Named Arguments

--cfg

Path to the config file

Default: /home/runner/work/FastSurfer/FastSurfer/src/FastSurferCNN/config/FastSurferVINN.yaml

--aug

List of augmentations to use.