Programs · ANTs and ITK

SmoothImage

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

What it does

SmoothImage smooths an image with a Gaussian of a given sigma, in voxels or in millimetres, or filters it with a median over a box of a given radius.

Command line

text
larmorx ants SmoothImage ImageDimension image.ext smoothingsigma outimage.ext {sigma-is-in-spacing-units-(0)/1} {medianfilter-(0)/1}

Everything after larmorx ants SmoothImage is the original’s command line: the arguments of ANTs 2.6.5’s SmoothImage, 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 SmoothImage ...

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.

SmoothImage's usage text, as the replica prints it
text
Usage:
SmoothImage ImageDimension image.ext smoothingsigma outimage.ext {sigma-is-in-spacing-units-(0)/1} {medianfilter-(0)/1}
 If using median filter, sigma is the radius of filtering, in voxels
 A separate sigma can be specified for each dimension, e.g., 1.5x1x2

Python

python
lx.ants.smooth_image(
    image: Any,
    sigma: float | Sequence[float],
    *,
    sigma_in_physical_units: bool = False,
    median: bool = False,
    n_threads: int = 1,
) -> Image

SmoothImage d in sigma out [physical] [median]: Gaussian smoothing with ITK’s SmoothingRecursiveGaussianImageFilter.

Returns a float32 lx.Image on the input’s grid; sigma is a number or one per axis.

python
import larmorx as lx

smoothed = lx.ants.smooth_image("sub-01_T1w.nii.gz", 1.5)                 # sigma 1.5 voxels
smoothed = lx.ants.smooth_image(t1w, [2.0, 2.0, 3.0], sigma_in_physical_units=True)
filtered = lx.ants.smooth_image(t1w, 1, median=True)                      # 3x3x3 median

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 SmoothImage accepts (crates/larmorx-ants/src/cli/smooth_image.rs) and the arguments of lx.ants.smooth_image (python/larmorx/ants/smoothing.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) – the image’s own dimensions; a 4D image is smoothed along time too (the time step is its spacing)
2 image.ext image path, lx.Image, nibabel image or (array, affine); read as float
3 smoothingsigma (1.5 or 1x1x2) sigma a number or one per axis; in voxels: multiplied by the spacing in float, as ANTs does
4 outimage.ext the result float32, the input’s grid
5 sigma-is-in-spacing-units (1) sigma_in_physical_units=True False sigma in mm (s for time)
6 medianfilter (1) median=True False MedianImageFilter, radius int(sigma) voxels per axis
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 SmoothImage ...); lx.ants.smooth_image takes n_threads as an argument, and the others are 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.smooth_image takes no implementation. The variable LARMORX_IMPLEMENTATION in 0.1.0rc1.
--upstream-defects fix|reproduce
(no Python argument)
The command line’s only: lx.ants.smooth_image takes no upstream_defects. 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). The command lines run as python -m larmorx.

python
import larmorx as lx

# A Gaussian of sigma 1.5 voxels, and a median over 3 x 3 x 3 voxels.
smoothed = lx.ants.smooth_image("t1w.nii.gz", 1.5)
smoothed.shape  # -> (40, 48, 40)
filtered = lx.ants.smooth_image("t1w.nii.gz", 1, median=True)
filtered.data.dtype  # -> dtype('float32')
bash
larmorx ants SmoothImage 3 t1w.nii.gz 1.5 smoothed.nii.gz
larmorx ants SmoothImage 3 t1w.nii.gz 2x2x3 smoothed_mm.nii.gz 1
larmorx ants SmoothImage 3 t1w.nii.gz 1 median.nii.gz 0 1

Ports

SmoothImage has one port: a replica.

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

The replica: status validated against SmoothImage itself (its record, 2026-10-12): 38 cases, 30 outputs compared, all bit-identical with ANTs’ exact header bytes, in 2, 3 and 4 dimensions; 7 rejected by both alike. Compared with ANTs’ defects reproduced (LARMORX_UPSTREAM_DEFECTS=reproduce); the record’s “D13 fix pass” lists what larmorx’s default changes.

On the data panel (record, 2026-10-26): fMRIPrep 25.2.6 never calls SmoothImage; on the panel’s images (a 2 mm Gaussian of the 7 T MP2RAGE, 1.5 mm of the 82-year-old’s FLAIR, a median of a child’s T1w, a 4D Gaussian of a 588-volume multiband series): 4 of 4 bit-identical, header bytes included; a zero sigma along time is refused by both.

SmoothImage has one port, in pip install larmorx: the replica (crates/larmorx-ants, crates/larmorx-image; Apache-2.0; Rust larmorx_ants::smooth_image, larmorx_image::gaussian, larmorx_image::median), translated from ANTs 2.6.5 on ITK 5.4.5 (Apache-2.0).

Evidence

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

More in the repository

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