sct_maths¶

Perform mathematical operations on images.

usage: sct_maths -i <file> -o <file> [-volumewise {0,1}] [-add [...]]
                 [-sub  [...]] [-mul [...]] [-div  [...]] [-mean {x,y,z,t}]
                 [-rms {x,y,z,t}] [-std {x,y,z,t}] [-bin <float>]
                 [-slicewise-mean {0,1,2}] [-otsu <int>] [-adap <list>]
                 [-otsu-median <list>] [-percent <int>] [-thr <float>]
                 [-uthr <float>] [-dilate <int>] [-erode <int>]
                 [-shape {square,cube,disk,ball}] [-dim {0,1,2}]
                 [-smooth <list>] [-laplacian <list>] [-denoise DENOISE]
                 [-mi <file>] [-minorm <file>] [-corr <file>]
                 [-symmetrize {0,1,2}]
                 [-type {uint8,int16,int32,float32,complex64,float64,int8,uint16,uint32,int64,uint64}]
                 [-h] [-v <int>] [-profile-time [<file>]]
                 [-trace-memory [<folder>]]

MANDATORY ARGUMENTS¶

-i: Input file. Example: data.nii.gz
-o: Output file. Example: data_mean.nii.gz

OPTIONAL ARGUMENTS¶

-volumewise

Possible choices: 0, 1

Specifying this option will process a 4D image in a “volumewise” manner:

Split the 4D input into individual 3D volumes
Apply the maths operations to each 3D volume
Merge the processed 3D volumes back into a single 4D output image

Default: 0

BASIC OPERATIONS¶

-add

Add following input. Can be a number or one or more 3D/4D images (separated with space). Examples:

sct_maths -i 3D.nii.gz -add 5 (Result: 3D image with 5 added to each voxel)
sct_maths -i 3D.nii.gz -add 3D_2.nii.gz (Result: 3D image)
sct_maths -i 4D.nii.gz -add 4D_2.nii.gz (Result: 4D image)
sct_maths -i 4D_nii.gz -add 4D_2.nii.gz 4D_3.nii.gz (Result: 4D image)

Note: If your terminal supports it, you can also specify multiple images using a pattern:

sct_maths -i 4D.nii.gz -add 4D_*.nii.gz (Result: Adding 4D_2.nii.gz, 4D_3.nii.gz, etc.)

Note: If the input image is 4D, you can also leave -add empty to sum the 3D volumes within the image:

sct_maths -i 4D.nii.gz -add (Result: 3D image, with 3D volumes summed within 4D image)

-sub

Subtract following input. Can be a number, or one or more 3D/4D images (separated with space).

-mul

Multiply by following input. Can be a number, or one or more 3D/4D images (separated with space). (See -add for examples.)

-div

Divide by following input. Can be a number, or one or more 3D/4D images (separated with space).

-mean

Possible choices: x, y, z, t

Average data across dimension.

-rms

Possible choices: x, y, z, t

Compute root-mean-squared across dimension.

-std

Possible choices: x, y, z, t

Compute STD across dimension.

-bin

Binarize image using specified threshold. Example: 0.5

-slicewise-mean

Possible choices: 0, 1, 2

Compute slicewise mean the specified dimension. Zeros are not inlcuded in the mean.

THRESHOLDING METHODS¶

-otsu

Threshold image using Otsu algorithm (from skimage). Specify the number of bins (e.g. 16, 64, 128)

-adap

Threshold image using Adaptive algorithm (from skimage). Provide 2 values separated by , that correspond to the parameters below. For example, -adap 7,0 corresponds to a block size of 7 and an offset of 0.

Block size: Odd size of pixel neighborhood which is used to calculate the threshold value.
Offset: Constant subtracted from weighted mean of neighborhood to calculate the local threshold value. Suggested offset is 0.

-otsu-median

Threshold image using Median Otsu algorithm (from Dipy). Provide 2 values separated by , that correspond to the parameters below. For example, -otsu-median 3,5 corresponds to a filter size of 3 repeated over 5 iterations.

Size: Radius (in voxels) of the applied median filter.
Iterations: Number of passes of the median filter.

-percent

Threshold image using percentile of its histogram.

-thr

Lower threshold limit (zero below number).

-uthr

Upper threshold limit (zero above number).

MATHEMATICAL MORPHOLOGY¶

-dilate

Dilate binary or greyscale image with specified size. If shape={’square’, ‘cube’}: size corresponds to the length of an edge (size=1 has no effect). If shape={’disk’, ‘ball’}: size corresponds to the radius, not including the center element (size=0 has no effect).

-erode

Erode binary or greyscale image with specified size. If shape={’square’, ‘cube’}: size corresponds to the length of an edge (size=1 has no effect). If shape={’disk’, ‘ball’}: size corresponds to the radius, not including the center element (size=0 has no effect).

-shape

Possible choices: square, cube, disk, ball

Shape of the structuring element for the mathematical morphology operation. Default: ball.

If a 2D shape {'disk', 'square'} is selected, -dim must be specified.

Default: []

-dim

Possible choices: 0, 1, 2

Dimension of the array which 2D structural element will be orthogonal to. For example, if you wish to apply a 2D disk kernel in the X-Y plane, leaving Z unaffected, parameters will be: shape=disk, dim=2.

Default: []

FILTERING METHODS¶

-smooth

Gaussian smoothing filtering. Supply values for standard deviations in mm. If a single value is provided, it will be applied to each axis of the image. If multiple values are provided, there must be one value per image axis. (Examples: -smooth 2.0,3.0,2.0 (3D image), -smooth 2.0 (any-D image)).

-laplacian

Laplacian filtering. Supply values for standard deviations in mm. If a single value is provided, it will be applied to each axis of the image. If multiple values are provided, there must be one value per image axis. (Examples: -laplacian 2.0,3.0,2.0 (3D image), -laplacian 2.0 (any-D image)).

-denoise

Non-local means adaptative denoising from P. Coupe et al. as implemented in dipy. Separate with , Example: p=1,b=3

p: (patch radius) similar patches in the non-local means are searched for locally, inside a cube of side 2*p+1 centered at each voxel of interest. Default: p=1
b: (block radius) the size of the block to be used (2*b+1) in the blockwise non-local means implementation. Default: b=5. Note, block radius must be smaller than the smaller image dimension: default value is lowered for small images)

To use default parameters, write -denoise 1

SIMILARITY METRIC¶

-mi: Compute the mutual information (MI) between both input files (-i and -mi) as in: https://scikit-learn.org/stable/modules/generated/sklearn.metrics.mutual_info_score.html
-minorm: Compute the normalized mutual information (MI) between both input files (-i and -mi) as in: https://scikit-learn.org/stable/modules/generated/sklearn.metrics.normalized_mutual_info_score.html
-corr: Compute the cross correlation (CC) between both input files (-i and -corr).

MISC ARGUMENTS¶

-symmetrize

Possible choices: 0, 1, 2

Symmetrize data along the specified dimension.

-type

Possible choices: uint8, int16, int32, float32, complex64, float64, int8, uint16, uint32, int64, uint64

Output type.

-v

Possible choices: 0, 1, 2

Verbosity. 0: Display only errors/warnings, 1: Errors/warnings + info messages, 2: Debug mode.

Default: 1

-profile-time

Enables time-based profiling of the program, dumping the results to the specified file.

If no file is specified, human-readable results are placed into a ‘time_profiling_results.txt’ document in the current directory (’/home/docs/checkouts/readthedocs.org/user_builds/spinalcordtoolbox/checkouts/stable/documentation/source’). If the specified file is a .prof file, the file will instead be in binary format, ready for use with common post-profiler utilities (such as snakeviz).

-trace-memory

Enables memory tracing of the program.

When active, a measure of the peak memory (in KiB) will be output to the file peak_memory.txt. Optionally, developers can also modify the SCT code to add additional snapshot_memory() calls. These calls will ‘snapshot’ the memory usage at that moment, saving the memory trace at that point into a second file (memory_snapshots.txt).

By default, both outputs will be placed in the current directory (’/home/docs/checkouts/readthedocs.org/user_builds/spinalcordtoolbox/checkouts/stable/documentation/source’). Optionally, you may provide an alternative directory (-trace-memory <dir_name>), in which case all files will be placed in that directory instead. Note that this WILL incur an overhead to runtime, so it is generally advised that you do not run this in conjunction with the time profiler or in time-sensitive contexts.