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.