FastSurferCNN: conform.py

conform.py conforms an MRI image the way FastSurfer does before the segmentation: to 8-bit intensities (uchar), LIA orientation and isotropic voxels, on a cube large enough for the field of view. run_fastsurfer.sh does this itself, so you only need the script to prepare or inspect images on their own, for example to check which images of a dataset FastSurfer will resample, similar to FreeSurfer’s mri_convert -c.

With --check_only, it only reports whether an image is already conformed and writes nothing. Without options, it conforms to 1 mm voxels; run_fastsurfer.sh uses --vox_size min by default, so pass --vox_size min to get the same result for high-resolution images.

Usage:

python3 <fastsurfer_home>/FastSurferCNN/data_loader/conform.py \
    -i <t1_path> -o <output_path> --vox_size min
python3 <fastsurfer_home>/FastSurferCNN/data_loader/conform.py \
    -i <t1_path> --check_only --vox_size min

Full commandline interface of FastSurferCNN/data_loader/conform.py

usage: 
Script to conform an MRI brain image to UCHAR, LIA orientation,
and 1mm or minimal isotropic voxels

USAGE:
conform.py  -i <input> -o <output> <options>
OR
conform.py  -i <input> --check_only <options>
Dependencies:
    Python 3.12+
    Numpy
    https://www.numpy.org
    Nibabel to read and write FreeSurfer data
    https://nipy.org/nibabel/

Named Arguments

--version

show program’s version number and exit

--input, -i

The path to input image.

--output, -o

The path to output image.

--order

Possible choices: 0, 1, 2, 3

The order of interpolation to use to interpolate (0=nearest, 1=linear(default), 2=quadratic, 3=cubic).

Default: 1

--check_only

Specifies that to only check whether the input image is conformed, and do not write an output image.

Default: False

--seg_input

Specifies that the input is a seg image: The default values for dtype and rescale are changed to ‘integer’ and ‘none’, which only means the dtype must be an integer and no rescaling is performed.

Default: False

--vox_size

Specifies the target voxel size to conform to (default: 1, conform to 1mm). Options: <float> between 0 and 1 (target voxel size, isotropic, similar to mri_convert’s –conform_size <size>); ‘min’ (conform to the minimum voxel size); ‘any’ (ignore this criteria, accept any voxel size even non-isotropic).

Default: 1.0

--conform_min

(Legacy, prefer –vox_size min for same functionality) Specifies that the image should be conformed to the minimal voxel size (used for high-res processing) – overwrites –vox_size.

--img_size

Specifies the image size to conform to, cube: same value for all three directions. Options: <int> (cube, sets dimension of the target image), ‘auto’ (cube, infer dimensions of image from largest field-of-view dimension, min. 256), ‘fov’ (may not be cube, set all three dimensions of image to keep the field of view the same) or ‘any’ (ignore this criteria, in practice similar to fov).

Default: auto

--rescale

Specifies whether image intensities should be rescaled. Options: <number> (default: 255, will robustly rescale intensities to this value, e.g. 0-255), ‘none’ (no intensity rescaling, i.e. all intensities stay the same and values outside of the data type are clamped to the data type range).

Default: 255

--verbose

If verbose, more detailed messages are printed.

Default: False

--log

If specified, path to a log file that is written to.

Default: ''

Advanced options

--conform_to_1mm_threshold

Advanced option to change the threshold beyond which images are conformed to 1 (default: infinity, all images are conformed to their minimum voxel size).

--dtype

Specifies the target data type of the target image or ‘any’ (default: ‘uint8’, as in FreeSurfer).

Default: uint8

--orientation

Specify the target (data) orientation. Options: ‘native’ (will not change the orientation at all, i.e. ignore the orientation), <orientation string>, e.g. ‘LIA’ or ‘RAS’ (force perfect alignment with the scanner directions, as required by FreeSurfer and similar to mri_convert’s –out_orientation), or ‘soft-<orientation string>’ like ‘soft-LIA’ (primary directions aligned, but no resampling required).

Default: lia