sct_maths¶

P e r f o r m m a t h e m a t i c a l o p e r a t i o n s o n i m a g e s . 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: I n p u t f i l e . E x a m p l e : ` d a t a . n i i . g z ` Input file. Example: data.nii.gz
-o: O u t p u t f i l e . E x a m p l e : ` d a t a _ m e a n . n i i . g z ` Output file. Example: data_mean.nii.gz

OPTIONAL ARGUMENTS¶

-volumewise

P o s s i b l e c h o i c e s : 0 , 1 Possible choices: 0, 1

S p e c i f y i n g t h i s o p t i o n w i l l p r o c e s s a 4 D i m a g e i n a “ v o l u m e w i s e “ m a n n e r : Specifying this option will process a 4D image in a “volumewise” manner:

S p l i t t h e 4 D i n p u t i n t o i n d i v i d u a l 3 D v o l u m e s Split the 4D input into individual 3D volumes
A p p l y t h e m a t h s o p e r a t i o n s t o e a c h 3 D v o l u m e Apply the maths operations to each 3D volume
M e r g e t h e p r o c e s s e d 3 D v o l u m e s b a c k i n t o a s i n g l e 4 D o u t p u t i m a g e Merge the processed 3D volumes back into a single 4D output image

D e f a u l t : ` ` 0 ` ` Default: 0

BASIC OPERATIONS¶

-add

A d d f o l l o w i n g i n p u t . C a n b e a n u m b e r o r o n e o r m o r e 3 D / 4 D i m a g e s ( s e p a r a t e d w i t h s p a c e ) . E x a m p l e s : Add following input. Can be a number or one or more 3D/4D images (separated with space). Examples:

` s c t _ m a t h s - i 3 D . n i i . g z - a d d 5 ` ( R e s u l t : 3 D i m a g e w i t h ` 5 ` a d d e d t o e a c h v o x e l ) sct_maths -i 3D.nii.gz -add 5 (Result: 3D image with 5 added to each voxel)
` s c t _ m a t h s - i 3 D . n i i . g z - a d d 3 D _ 2 . n i i . g z ` ( R e s u l t : 3 D i m a g e ) sct_maths -i 3D.nii.gz -add 3D_2.nii.gz (Result: 3D image)
` s c t _ m a t h s - i 4 D . n i i . g z - a d d 4 D _ 2 . n i i . g z ` ( R e s u l t : 4 D i m a g e ) sct_maths -i 4D.nii.gz -add 4D_2.nii.gz (Result: 4D image)
` s c t _ m a t h s - i 4 D _ n i i . g z - a d d 4 D _ 2 . n i i . g z 4 D _ 3 . n i i . g z ` ( R e s u l t : 4 D i m a g e ) sct_maths -i 4D_nii.gz -add 4D_2.nii.gz 4D_3.nii.gz (Result: 4D image)

N o t e : I f y o u r t e r m i n a l s u p p o r t s i t , y o u c a n a l s o s p e c i f y m u l t i p l e i m a g e s u s i n g a p a t t e r n : Note: If your terminal supports it, you can also specify multiple images using a pattern:

` s c t _ m a t h s - i 4 D . n i i . g z - a d d 4 D _ * . n i i . g z ` ( R e s u l t : A d d i n g ` 4 D _ 2 . n i i . g z ` , ` 4 D _ 3 . n i i . g z ` , e t c . ) sct_maths -i 4D.nii.gz -add 4D_*.nii.gz (Result: Adding 4D_2.nii.gz, 4D_3.nii.gz, etc.)

N o t e : I f t h e i n p u t i m a g e i s 4 D , y o u c a n a l s o l e a v e ` - a d d ` e m p t y t o s u m t h e 3 D v o l u m e s w i t h i n t h e i m a g e : Note: If the input image is 4D, you can also leave -add empty to sum the 3D volumes within the image:

` s c t _ m a t h s - i 4 D . n i i . g z - a d d ` ( R e s u l t : 3 D i m a g e , w i t h 3 D v o l u m e s s u m m e d w i t h i n 4 D i m a g e ) sct_maths -i 4D.nii.gz -add (Result: 3D image, with 3D volumes summed within 4D image)

-sub

S u b t r a c t f o l l o w i n g i n p u t . C a n b e a n u m b e r , o r o n e o r m o r e 3 D / 4 D i m a g e s ( s e p a r a t e d w i t h s p a c e ) . Subtract following input. Can be a number, or one or more 3D/4D images (separated with space).

-mul

M u l t i p l y b y f o l l o w i n g i n p u t . C a n b e a n u m b e r , o r o n e o r m o r e 3 D / 4 D i m a g e s ( s e p a r a t e d w i t h s p a c e ) . ( S e e ` - a d d ` f o r e x a m p l e s . ) Multiply by following input. Can be a number, or one or more 3D/4D images (separated with space). (See -add for examples.)

-div

D i v i d e b y f o l l o w i n g i n p u t . C a n b e a n u m b e r , o r o n e o r m o r e 3 D / 4 D i m a g e s ( s e p a r a t e d w i t h s p a c e ) . Divide by following input. Can be a number, or one or more 3D/4D images (separated with space).

-mean

P o s s i b l e c h o i c e s : x , y , z , t Possible choices: x, y, z, t

A v e r a g e d a t a a c r o s s d i m e n s i o n . Average data across dimension.

-rms

P o s s i b l e c h o i c e s : x , y , z , t Possible choices: x, y, z, t

C o m p u t e r o o t - m e a n - s q u a r e d a c r o s s d i m e n s i o n . Compute root-mean-squared across dimension.

-std

P o s s i b l e c h o i c e s : x , y , z , t Possible choices: x, y, z, t

C o m p u t e S T D a c r o s s d i m e n s i o n . Compute STD across dimension.

-bin

B i n a r i z e i m a g e u s i n g s p e c i f i e d t h r e s h o l d . E x a m p l e : ` 0 . 5 ` Binarize image using specified threshold. Example: 0.5

-slicewise-mean

P o s s i b l e c h o i c e s : 0 , 1 , 2 Possible choices: 0, 1, 2

C o m p u t e s l i c e w i s e m e a n t h e s p e c i f i e d d i m e n s i o n . Z e r o s a r e n o t i n l c u d e d i n t h e m e a n . Compute slicewise mean the specified dimension. Zeros are not inlcuded in the mean.

THRESHOLDING METHODS¶

-otsu

T h r e s h o l d i m a g e u s i n g O t s u a l g o r i t h m ( f r o m s k i m a g e ) . S p e c i f y t h e n u m b e r o f b i n s ( e . g . 1 6 , 6 4 , 1 2 8 ) Threshold image using Otsu algorithm (from skimage). Specify the number of bins (e.g. 16, 64, 128)

-adap

T h r e s h o l d i m a g e u s i n g A d a p t i v e a l g o r i t h m ( f r o m s k i m a g e ) . P r o v i d e 2 v a l u e s s e p a r a t e d b y ` , ` t h a t c o r r e s p o n d t o t h e p a r a m e t e r s b e l o w . F o r e x a m p l e , ` - a d a p 7 , 0 ` c o r r e s p o n d s t o a b l o c k s i z e o f 7 a n d a n o f f s e t o f 0 . 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.

B l o c k s i z e : O d d s i z e o f p i x e l n e i g h b o r h o o d w h i c h i s u s e d t o c a l c u l a t e t h e t h r e s h o l d v a l u e . Block size: Odd size of pixel neighborhood which is used to calculate the threshold value.
O f f s e t : C o n s t a n t s u b t r a c t e d f r o m w e i g h t e d m e a n o f n e i g h b o r h o o d t o c a l c u l a t e t h e l o c a l t h r e s h o l d v a l u e . S u g g e s t e d o f f s e t i s 0 . Offset: Constant subtracted from weighted mean of neighborhood to calculate the local threshold value. Suggested offset is 0.

-otsu-median

T h r e s h o l d i m a g e u s i n g M e d i a n O t s u a l g o r i t h m ( f r o m D i p y ) . P r o v i d e 2 v a l u e s s e p a r a t e d b y ` , ` t h a t c o r r e s p o n d t o t h e p a r a m e t e r s b e l o w . F o r e x a m p l e , ` - o t s u - m e d i a n 3 , 5 ` c o r r e s p o n d s t o a f i l t e r s i z e o f 3 r e p e a t e d o v e r 5 i t e r a t i o n s . 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.

S i z e : R a d i u s ( i n v o x e l s ) o f t h e a p p l i e d m e d i a n f i l t e r . Size: Radius (in voxels) of the applied median filter.
I t e r a t i o n s : N u m b e r o f p a s s e s o f t h e m e d i a n f i l t e r . Iterations: Number of passes of the median filter.

-percent

T h r e s h o l d i m a g e u s i n g p e r c e n t i l e o f i t s h i s t o g r a m . Threshold image using percentile of its histogram.

-thr

L o w e r t h r e s h o l d l i m i t ( z e r o b e l o w n u m b e r ) . Lower threshold limit (zero below number).

-uthr

U p p e r t h r e s h o l d l i m i t ( z e r o a b o v e n u m b e r ) . Upper threshold limit (zero above number).

MATHEMATICAL MORPHOLOGY¶

-dilate

D i l a t e b i n a r y o r g r e y s c a l e i m a g e . Y o u c a n c u s t o m i z e t h e s t r u c t u r a l e l e m e n t b y c o m b i n i n g t h e a r g u m e n t s ` - d i l a t e ` , ` - s h a p e ` , a n d ` - d i m ` . ( T h e v a l u e s p a s s e d t o ` - d i l a t e ` w i l l c o n t r o l t h e s i d e l e n g t h o r r a d i u s o f w h a t e v e r s h a p e i s c h o s e n . ) Y o u c a n p r o v i d e e i t h e r a s i n g l e n u m b e r , o r 2 / 3 n u m b e r s s e p a r a t e d b y ` x ` ( d e p e n d i n g o n t h e s h a p e ) . 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).

E x a m p l e s : Examples:

` - s h a p e c u b e - d i l a t e 3 ` - > S i d e l e n g t h 3 - > A 3 x 3 x 3 c u b e . -shape cube -dilate 3 -> Side length 3 -> A 3x3x3 cube.
` - s h a p e b a l l - d i l a t e 2 x 2 x 5 ` - > R a d i u s 2 x 2 x 5 - > A 5 x 5 x 1 1 b a l l . -shape ball -dilate 2x2x5 -> Radius 2x2x5 -> A 5x5x11 ball.
` - s h a p e d i s k - d i l a t e 3 - d i m 2 ` - > R a d i u s 3 - > A n 7 x 7 d i s k i n t h e X - Y p l a n e , a p p l i e d t o e a c h Z s l i c e . -shape disk -dilate 3 -dim 2 -> Radius 3 -> An 7x7 disk in the X-Y plane, applied to each Z slice.
` - s h a p e s q u a r e - d i l a t e 1 x 4 - d i m 0 ` - > S i d e l e n g t h 1 x 4 - > A 1 x 4 r e c t a n g l e i n t h e Y - Z p l a n e , a p p l i e d t o e a c h X s l i c e . -shape square -dilate 1x4 -dim 0 -> Side length 1x4 -> A 1x4 rectangle in the Y-Z plane, applied to each X slice.

-erode

E r o d e b i n a r y o r g r e y s c a l e i m a g e . T h e a r g u m e n t i s i n t e r p r e t e d t h e s a m e w a y a s f o r ` - d i l a t e ` . Erode binary or greyscale image. The argument is interpreted the same way as for -dilate.

-shape

P o s s i b l e c h o i c e s : s q u a r e , c u b e , d i s k , b a l l Possible choices: square, cube, disk, ball

S h a p e o f t h e s t r u c t u r i n g e l e m e n t f o r t h e m a t h e m a t i c a l m o r p h o l o g y o p e r a t i o n . D e f a u l t : ` b a l l ` . Shape of the structuring element for the mathematical morphology operation. Default: ball.

I f a 2 D s h a p e ` { ‘ d i s k ‘ , ‘ s q u a r e ‘ } ` i s s e l e c t e d , ` - d i m ` m u s t b e s p e c i f i e d . If a 2D shape {'disk', 'square'} is selected, -dim must be specified.

D e f a u l t : ` ` [ ] ` ` Default: []

-dim

P o s s i b l e c h o i c e s : 0 , 1 , 2 Possible choices: 0, 1, 2

D i m e n s i o n o f t h e a r r a y w h i c h 2 D s t r u c t u r a l e l e m e n t w i l l b e o r t h o g o n a l t o . F o r e x a m p l e , i f y o u w i s h t o a p p l y a 2 D d i s k k e r n e l i n t h e X - Y p l a n e , l e a v i n g Z u n a f f e c t e d , p a r a m e t e r s w i l l b e : s h a p e = d i s k , d i m = 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.

D e f a u l t : ` ` [ ] ` ` Default: []

FILTERING METHODS¶

-smooth

G a u s s i a n s m o o t h i n g f i l t e r i n g . S u p p l y v a l u e s f o r s t a n d a r d d e v i a t i o n s i n m m . I f a s i n g l e v a l u e i s p r o v i d e d , i t w i l l b e a p p l i e d t o e a c h a x i s o f t h e i m a g e . I f m u l t i p l e v a l u e s a r e p r o v i d e d , t h e r e m u s t b e o n e v a l u e p e r i m a g e a x i s . ( E x a m p l e s : ` - s m o o t h 2 . 0 , 3 . 0 , 2 . 0 ` ( 3 D i m a g e ) , ` - s m o o t h 2 . 0 ` ( a n y - D i m a g e ) ) . 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

L a p l a c i a n f i l t e r i n g . S u p p l y v a l u e s f o r s t a n d a r d d e v i a t i o n s i n m m . I f a s i n g l e v a l u e i s p r o v i d e d , i t w i l l b e a p p l i e d t o e a c h a x i s o f t h e i m a g e . I f m u l t i p l e v a l u e s a r e p r o v i d e d , t h e r e m u s t b e o n e v a l u e p e r i m a g e a x i s . ( E x a m p l e s : ` - l a p l a c i a n 2 . 0 , 3 . 0 , 2 . 0 ` ( 3 D i m a g e ) , ` - l a p l a c i a n 2 . 0 ` ( a n y - D i m a g e ) ) . 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

N o n - l o c a l m e a n s a d a p t a t i v e d e n o i s i n g f r o m P . C o u p e e t a l . a s i m p l e m e n t e d i n d i p y . S e p a r a t e w i t h ` , ` E x a m p l e : ` p = 1 , b = 3 ` Non-local means adaptative denoising from P. Coupe et al. as implemented in dipy. Separate with , Example: p=1,b=3

` p ` : ( p a t c h r a d i u s ) s i m i l a r p a t c h e s i n t h e n o n - l o c a l m e a n s a r e s e a r c h e d f o r l o c a l l y , i n s i d e a c u b e o f s i d e ` 2 * p + 1 ` c e n t e r e d a t e a c h v o x e l o f i n t e r e s t . D e f a u l t : ` p = 1 ` 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 ` : ( b l o c k r a d i u s ) t h e s i z e o f t h e b l o c k t o b e u s e d ( 2 * b + 1 ) i n t h e b l o c k w i s e n o n - l o c a l m e a n s i m p l e m e n t a t i o n . D e f a u l t : ` b = 5 ` . N o t e , b l o c k r a d i u s m u s t b e s m a l l e r t h a n t h e s m a l l e r i m a g e d i m e n s i o n : d e f a u l t v a l u e i s l o w e r e d f o r s m a l l i m a g e s ) 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)

T o u s e d e f a u l t p a r a m e t e r s , w r i t e ` - d e n o i s e 1 ` To use default parameters, write -denoise 1

SIMILARITY METRIC¶

-mi: C o m p u t e t h e m u t u a l i n f o r m a t i o n ( M I ) b e t w e e n b o t h i n p u t f i l e s ( ` - i ` a n d ` - m i ` ) a s i n : h t t p s : / / s c i k i t - l e a r n . o r g / s t a b l e / m o d u l e s / g e n e r a t e d / s k l e a r n . m e t r i c s . m u t u a l _ i n f o _ s c o r e . h t m l 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: C o m p u t e t h e n o r m a l i z e d m u t u a l i n f o r m a t i o n ( M I ) b e t w e e n b o t h i n p u t f i l e s ( ` - i ` a n d ` - m i ` ) a s i n : h t t p s : / / s c i k i t - l e a r n . o r g / s t a b l e / m o d u l e s / g e n e r a t e d / s k l e a r n . m e t r i c s . n o r m a l i z e d _ m u t u a l _ i n f o _ s c o r e . h t m l 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: C o m p u t e t h e c r o s s c o r r e l a t i o n ( C C ) b e t w e e n b o t h i n p u t f i l e s ( ` - i ` a n d ` - c o r r ` ) . Compute the cross correlation (CC) between both input files (-i and -corr).

MISC ARGUMENTS¶

-symmetrize

P o s s i b l e c h o i c e s : 0 , 1 , 2 Possible choices: 0, 1, 2

S y m m e t r i z e d a t a a l o n g t h e s p e c i f i e d d i m e n s i o n . Symmetrize data along the specified dimension.

-type

P o s s i b l e c h o i c e s : u i n t 8 , i n t 1 6 , i n t 3 2 , f l o a t 3 2 , c o m p l e x 6 4 , f l o a t 6 4 , i n t 8 , u i n t 1 6 , u i n t 3 2 , i n t 6 4 , u i n t 6 4 Possible choices: uint8, int16, int32, float32, complex64, float64, int8, uint16, uint32, int64, uint64

O u t p u t t y p e . Output type.

-v

P o s s i b l e c h o i c e s : 0 , 1 , 2 Possible choices: 0, 1, 2

V e r b o s i t y . 0 : D i s p l a y o n l y e r r o r s / w a r n i n g s , 1 : E r r o r s / w a r n i n g s + i n f o m e s s a g e s , 2 : D e b u g m o d e . Verbosity. 0: Display only errors/warnings, 1: Errors/warnings + info messages, 2: Debug mode.

D e f a u l t : ` ` 1 ` ` Default: 1