Programs · ANTs and ITK

ImageMath

ImageMath applies one operation to an image (and to a second image or numbers): arithmetic, intensity clipping and scaling, Gaussian filters, binary and grayscale morphology, hole filling, padding, connected components and distance maps.

Original
ANTs 2.6.5
Command line
larmorx ants ImageMath
Python
lx.ants.image_math
Ports
  • replica larmorx Apache-2.0 validated
Evidence
every comparison with ANTs
Source
made from docs/api/ants-image-math.md and the code

What it does

The implemented operations (the others answer “not supported yet”):

Group Operations
arithmetic m, +, -, /, ^, exp, max, abs, addtozero, overadd, Decision, total, mean, vtotal, Neg
intensity TruncateImageIntensity, Normalize, RescaleImage, ThresholdAtMean, ReplaceVoxelValue
gaussian G, Laplacian, Grad, UnsharpMask
morphology MD, ME, MO, MC, GD, GE, GO, GC, FillHoles, PadImage
components GetLargestComponent, D, MaurerDistance, ExtractContours

All of them run in 2, 3 and 4 dimensions, as in ANTs; the Gaussian and morphology operations work in all of the image’s dimensions (a 4D image along time too).

Command line

text
larmorx ants ImageMath <dimension> <output> <operation> <operands...>

Everything after larmorx ants ImageMath is the original’s command line: the arguments of ANTs 2.6.5’s ImageMath, as ANTs takes them. LARMORX’s own options stand between larmorx and the family ants, so they never meet the original’s (below):

text
larmorx
        [--n-threads N]
        [--implementation auto|replica|clean-room]
        [--upstream-defects fix|reproduce]
        ants ImageMath ...

From the next release. In 0.1.0rc1, set the variables instead: OMP_NUM_THREADS, LARMORX_IMPLEMENTATION (original for the clean room) and LARMORX_UPSTREAM_DEFECTS.

Python

python
lx.ants.image_math(
    operation: str,
    *operands: Any,
    dimension: int = 3,
    n_threads: int = 1,
    upstream_defects: UpstreamDefectsName = "fix",
) -> Image

Where UpstreamDefectsName is one of "fix", "reproduce".

Run ImageMath operation on operands, as ImageMath <dimension> <output> <operation> <operands...> does.

Runs ImageMath <dimension> <output> <operation> <operands...> with images held in memory: lx.Image objects, nibabel images and (array, affine) pairs are passed without files; paths, numbers and strings are passed as on the command line (numbers as their shortest round-trip text). Returns the image the operation writes, in the type and geometry ANTs gives it. Raises lx.ants.ImageMathError with the program’s messages when it fails or writes nothing. lx.ants.image_math_operations() lists the implemented operations.

In-memory images are placed by their affine (the spatial axes) and their header’s repetition time (a fourth axis; spacing 1 without a header); files are read as ITK reads them. Each operation also has a typed function, lx.ants.truncate_image_intensity and the others the API page lists under “Typed functions”.

python
import larmorx as lx

# fMRIPrep's intensity clipping of the T1w before registration
t1 = lx.ants.truncate_image_intensity("sub-01_T1w.nii.gz", 0.01, 0.999, 256)

# The command line, on in-memory images (exactly the command-line code)
t1 = lx.ants.image_math("TruncateImageIntensity", "sub-01_T1w.nii.gz", 0.01, 0.999, 256)
both = lx.ants.add_to_zero(wm_mask, gm_mask)

# The Laplacian feature channel of fMRIPrep's brain extraction (ImageMath 3 out Laplacian in 1.5 1)
lap = lx.ants.laplacian(t1, 1.5, normalize=True)

# sMRIPrep's mask clean-up steps (ImageMath MD 2, ME 10, FillHoles 2, PadImage 10)
mask = lx.ants.morphological_dilate("brain_mask.nii.gz", 2)
csf = lx.ants.morphological_erode(csf_mask, 10)
filled = lx.ants.fill_holes(gm_mask, 2)
padded = lx.ants.pad_image(mask, 10)
largest = lx.ants.largest_component(mask)
dist = lx.ants.maurer_distance(mask)  # signed, mm, negative inside

Its result, Image, holds a voxel array placed in world space by an affine.

Field Type What it holds
data np.ndarray
affine np.ndarray
header NiftiHeader | None
implementation Implementation | None

Options

Each row joins an option of the original’s command line with the Python argument that does the same. The rows are checked against the code at every test run: the options ImageMath accepts (crates/larmorx-ants/src/cli/image_math/mod.rs) and the arguments of lx.ants.image_math (python/larmorx/ants/image_math.py), whose defaults and descriptions are taken from it. Under each option, in grey, ANTs’s own help for it.

ANTs argument (positional) Python Default Notes
1 ImageDimension (2, 3, 4) dimension=3 3 a path is read in that many dimensions
2 outputImage the result in the type and geometry ANTs gives it
3 operation operation ImageMath’s name, case-sensitive (the implemented operations are listed above the Python call)
4 and after: the operands operands images (paths, lx.Image, nibabel images, (array, affine)), numbers and strings, in the operation’s order
ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS (or NSLOTS, as ITK reads them) n_threads 1 the result does not depend on it

LARMORX’s own options

From the next release. In 0.1.0rc1, set the variables instead: OMP_NUM_THREADS, LARMORX_IMPLEMENTATION (original for the clean room) and LARMORX_UPSTREAM_DEFECTS.

They stand between larmorx and ants on the command line (larmorx --n-threads 4 ants ImageMath ...); lx.ants.image_math takes n_threads and upstream_defects as arguments, and the other is the command line’s only. Each one given wins over its environment variable, which keeps working.

Command line, then Python What it does
--n-threads N
n_threads=1
Default: every logical CPU on the command line (0), 1 in Python. The variable OMP_NUM_THREADS in 0.1.0rc1.
--implementation auto|replica|clean-room
(no Python argument)
The command line’s only: lx.ants.image_math takes no implementation. The variable LARMORX_IMPLEMENTATION in 0.1.0rc1.
--upstream-defects fix|reproduce
upstream_defects="fix"
The variable LARMORX_UPSTREAM_DEFECTS in 0.1.0rc1.

Examples

The tests run every example below (validation/tests/test_reference.py), each section in a new folder where these inputs are made first: t1w.nii.gz (a synthetic head of 40 × 48 × 40 voxels of 4 mm), mask.nii.gz (the synthetic head’s brain as a mask (1 inside, 0 outside)). The command lines run as python -m larmorx.

python
import larmorx as lx

# fMRIPrep's clipping of the T1w's intensities, through the command line's code.
clipped = lx.ants.image_math("TruncateImageIntensity", "t1w.nii.gz", 0.01, 0.999, 256)
clipped.shape  # -> (40, 48, 40)
# sMRIPrep's dilation of a mask by 2 voxels, through its typed function.
dilated = lx.ants.morphological_dilate("mask.nii.gz", 2)
dilated.data.dtype  # -> dtype('float32')
bash
larmorx ants ImageMath 3 clipped.nii.gz TruncateImageIntensity t1w.nii.gz 0.01 0.999 256
larmorx ants ImageMath 3 laplacian.nii.gz Laplacian t1w.nii.gz 1.5 1
larmorx ants ImageMath 3 dilated.nii.gz MD mask.nii.gz 2
larmorx ants ImageMath 3 filled.nii.gz FillHoles mask.nii.gz 2

Ports

ImageMath has one port: a replica.

Port Package Licence Status Records
replica larmorx (built in) Apache-2.0 validated ants-image-math

The replica: status validated for the implemented operations, against ImageMath itself (its record, 2026-10-24): 334 cases, 308 outputs compared, 303 bit-identical, 24 rejected by both alike; every output has ANTs’ exact header bytes. Of the 5 others, 3 are ^, where ANTs calls glibc’s powf, which is not correctly rounded; larmorx’s is, so up to 35 of 35,840 voxels differ by one ulp (why); 2 are grayscale morphology on an image made to hold -0.0 next to +0.0, where only the sign of a zero result differs (why). Every Gaussian case (G, Laplacian, Grad, UnsharpMask; 47 compared, in 2, 3 and 4 dimensions, fMRIPrep’s Laplacian 1.5 1 on real T1w, boldref and template images included) is bit-identical, and so is every other morphology case (100 compared: MD, ME, MO, MC, GD, GE, GO, GC, FillHoles, PadImage in 2, 3 and 4 dimensions, sMRIPrep’s MD 2/5, ME 2/10, FillHoles 2 and PadImage ±10 on real masks included), and every component and distance-map case (61 compared: GetLargestComponent, D, MaurerDistance, ExtractContours, ThresholdAtMean, ReplaceVoxelValue, in 2, 3 and 4 dimensions, on real masks and probability maps too). Compared with ANTs’ defects reproduced (LARMORX_UPSTREAM_DEFECTS=reproduce); the record’s “D13 fix pass” lists what larmorx’s default changes. One more case, FillHoles 0.5 with a hole on the first slice, compares everything but the values, which ANTs takes from memory outside the image (ANTS-19).

On the data panel (record, 2026-10-27): every ImageMath node of the fourteen finished fMRIPrep oracle runs (378 nodes, 365 distinct calls: sMRIPrep’s brain extraction and template steps, the BOLD references’ and field maps’ masks), each replayed from its node with its inputs, and nine calls on the panel’s images (truncation of the 7 T MP2RAGE, a FLAIR and a 1.5 T float T1w, Laplacians of a glioma’s and an older adult’s T2w, the stroke lesion mask’s components, morphology and holes, a 600-volume multiband-8 series times a scalar): 374 of 374 bit-identical, header bytes included.

ImageMath has one port, in pip install larmorx: the replica (crates/larmorx-ants, crates/larmorx-image; Apache-2.0; Rust larmorx_ants::image_math (operations), larmorx_ants::cli::image_math (the dispatcher), larmorx_image (ITK filters)), translated from ANTs 2.6.5 on ITK 5.4.5 (Apache-2.0).

Evidence

How each of ImageMath’s ports was measured against ANTs, case by case: its evidence.

More in the repository

The API page docs/api/ants-image-math.md holds what ImageMath shares with the page’s other programs: