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>]

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. You can customize the structural element by combining the arguments -dilate, -shape, and -dim. (The values passed to -dilate will control the side length or radius of whatever shape is chosen.) You can provide either a single number, or 2/3 numbers separated by x (depending on the shape).

Examples:

  • -shape cube -dilate 3 -> Side length 3 -> A 3x3x3 cube.

  • -shape ball -dilate 2x2x5 -> Radius 2x2x5 -> A 5x5x11 ball.

  • -shape disk -dilate 3 -dim 2 -> Radius 3 -> An 7x7 disk in the X-Y plane, applied to each Z slice.

  • -shape square -dilate 1x4 -dim 0 -> Side length 1x4 -> A 1x4 rectangle in the Y-Z plane, applied to each X slice.

-erode

Erode binary or greyscale image. The argument is interpreted the same way as for -dilate.

-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