Programs · ANTs and ITK
SmoothImage
- Original
- ANTs 2.6.5
- Command line
larmorx ants SmoothImage- Python
lx.ants.smooth_image- Ports
- replica
larmorxApache-2.0 validated
- replica
- 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
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):
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
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.5x1x2Python
lx.ants.smooth_image(
image: Any,
sigma: float | Sequence[float],
*,
sigma_in_physical_units: bool = False,
median: bool = False,
n_threads: int = 1,
) -> ImageSmoothImage 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.
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 medianIts 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 Nn_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.
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')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 1Ports
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: