image_math
Perform various mathematical operations on one or several NIFTI images. The number of images required as input depends on the operation chosen. Some operations require only one image input, while some may require two or more. Several operations require a VALUE to be defined within the args.
Note: This script is loading all images in memory, will often crash after a few hundred images.
Here are the available operations and their abbreviated descriptions:
Section titled “Here are the available operations and their abbreviated descriptions:”Unary operations (IMG -> IMG):
- absolute_value: All negative values will become positive.
- ceil: Ceil all decimal values to the next integer.
- convert: Perform no operation, but simply change the data type (specified by ext.data_type).
- invert: Operation on binary image to interchange 0s and 1s in a binary mask.
- log_10: Apply a log (base 10) to all non zeros values of an image.
- log_e: Apply a natural log to all non zeros values of an image.
- lower_threshold_otsu: All values below or equal to the Otsu threshold will be set to zero and others to one. (Otsu’s method is an algorithm to perform automatic image thresholding of the background.)
- normalize_sum: Normalize the image so the sum of all values is one.
- normalize_max: Normalize the image so the maximum value is one.
- round: Round all decimal values to the closest integer.
- upper_threshold_otsu: All values below the Otsu threshold will be set to one and others to zero. Equivalent to lower_threshold_otsu followed by an inversion.
Image and value operations (IMG, VALUE -> IMG):
- blur: Apply a gaussian blur to a single image. VALUE is sigma, the standard deviation of the Gaussian kernel.
- closing: Binary morphological operation, dilation followed by an erosion.
- dilation: Binary morphological operation to spatially extend the values of an image to their neighbors. VALUE is in voxels: an integer > 0.
- erosion: Binary morphological operation to spatially shrink the volume contained in a binary image. VALUE is in voxels: an integer > 0.
- lower_clip: All values below the threshold will be set to threshold.
- lower_threshold: All values below the threshold will be set to zero and above to one.
- lower_threshold_eq: All values below or equal to the threshold will be set to zero and above to one.
- opening: Binary morphological operation, erosion followed by a dilation.
- upper_threshold: All values below the threshold will be set to one and above to zero. Equivalent to lower_threshold followed by an inversion.
- upper_threshold_eq: All values below or equal the threshold will be set to one and above to zero. Equivalent to lower_threshold_eq followed by an inversion.
- upper_clip: All values above the threshold will be set to threshold.
Pair of images operations (IMG1, IMG2 -> IMG):
- difference: Operation on binary image to keep voxels from the first file that are not in the second file (non-zeros).
- division: Divide first image by the second (danger of underflow and overflow). Ignore zeros values, excluded from the operation.
- subtraction: Subtract first image by the second (IMG_1 - IMG_2).
Multiple image operations (IMG1, IMG2, … IMGN -> IMG):
- addition: Add multiple images together.
- concatenate: Concatenate a list of 3D and 4D images into a single 4D image.
- correlation: Computes the correlation of the 3x3x3 neighborhood of each voxel, for all pair of input images. The final image is the average correlation (through all pairs).
- intersection: Operation on binary image to keep the voxels, that are non-zero, are present in all files.
- mean: Compute the mean of images. If a single 4D image is provided, average along the last dimension.
- multiplication: Multiply multiple images together (danger of underflow and overflow)
- std: Compute the standard deviation average of multiple images. If a single 4D image is provided, compute the STD along the last dimension.
- union: Operation on binary image to keep voxels, that are non-zero, in at least one file.
Keywords : absolute, addition, arithmetic, blur, ceil, clip, closing, concatenate, convert, correlation, difference, dilation, erosion, floor, image, image-processing, intersection, invert, log, math, mean, multiplication, normalize, normalize-max, normalize-sum, opening, operations, round, std, subtraction, threshold, union
Inputs
Section titled “Inputs”Input 1
Section titled “Input 1”Format : tuple val(meta), path(images), val(value)
| Type | Description | Mandatory | Pattern | |
|---|---|---|---|---|
| meta | map | Groovy Map containing sample information e.g. [ id:'sample1', single_end:false ] | True | |
| images | file | List of nifti image file involved in the mathematical operation. | True | *.{nii,nii.gz} |
| value | float | Value to use for the mathematical operation. This value will be used if ext.value is not provided. (e.g., threshold below 0.5, clip over 10, etc.). | False |
Outputs
Section titled “Outputs”Format : tuple val(meta), path(*.nii.gz)
| Type | Description | Mandatory | Pattern | |
|---|---|---|---|---|
| meta | map | Groovy Map containing sample information e.g. [ id:'sample1', single_end:false ] | True | |
| *.nii.gz | file | Resulting nifti image file after the operation. e.g. [ path(img) ] | True | *.{nii,nii.gz} |
versions
Section titled “versions”Format : path(versions.yml)
| Type | Description | Mandatory | Pattern | |
|---|---|---|---|---|
| versions.yml | file | File containing software versions | True | versions.yml |
Arguments (see process.ext)
Section titled “Arguments (see process.ext)”| Type | Description | Default | Choices | |
|---|---|---|---|---|
| operation | string | The mathematical operation to perform on the image(s). The inputs required depend on the operation chosen. Some operations require only one image input, while some may require two or more images and some may require an image and a numeric value. | - absolute_value - addition - blur - ceil - closing - concatenate - convert - correlation - difference - dilation - division - erosion - floor - intersection - invert - log_10 - log_e - lower_clip - lower_threshold - lower_threshold_eq - lower_threshold_otsu - mean - multiplication - normalize_sum - normalize_max - opening - round - std - subtraction - union - upper_clip - upper_threshold - upper_threshold_eq - upper_threshold_ots | |
| suffix | string | Suffix for the output image file. | output | |
| value | float | Value to use for the mathematical operation. This value will override any value provided in the input meta map. (e.g., threshold below 0.5, clip over 10, etc.). | ||
| data_type | string | Data type for the output image. Use the following format: uint8, int16, int32, int64, float16, float32 or float64. | float32 | |
| exclude_background | boolean | Whether to exclude the background from the operation. | False |
| Description | DOI | |
|---|---|---|
| scilpy | The Sherbrooke Connectivity Imaging Lab (SCIL) Python dMRI processing toolbox. |
Authors
Section titled “Authors”Last updated : 2025-12-22