Programs · ANTs and ITK
DenoiseImage
DenoiseImage denoises an image by adaptive non-local means.
- Original
- ANTs 2.6.5
- Command line
larmorx ants DenoiseImage- Python
lx.ants.denoise_image- Ports
- replica
larmorxApache-2.0 validated
- replica
- Evidence
- every comparison with ANTs
- Source
- made from docs/api/ants-denoise.md and the code
What it does
The method is Manjón et al.‘s
(Adaptive non-local means denoising of MR images with spatially varying noise levels, JMRI
31:192-203, 2010); sMRIPrep runs it on every T1w (-n Rician, ANTs’ other defaults).
Command line
larmorx ants DenoiseImage [-d 2/3/4] -i input [-n Rician/(Gaussian)] [-x mask] [-s (1)/2/3/...]
[-p 1|1x1x1] [-r 2|2x2x2] [-o corrected | [corrected,<noise>]] [-v (0)/1]Everything after larmorx ants DenoiseImage is the original’s command line: the arguments of ANTs 2.6.5’s DenoiseImage, 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 DenoiseImage ...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.
DenoiseImage's usage text, as the replica prints it
COMMAND:
DenoiseImage (larmorx port of ANTs v2.6.5)
Denoise an image using a spatially adaptive filter originally described in J. V.
Manjon, P. Coupe, Luis Marti-Bonmati, D. L. Collins, and M. Robles. Adaptive
Non-Local Means Denoising of MR Images With Spatially Varying Noise Levels, Journal
of Magnetic Resonance Imaging, 31:192-203, June 2010.
OPTIONS:
-d, --image-dimensionality 2/3/4
-i, --input-image inputImageFilename
-n, --noise-model Rician/(Gaussian)
-x, --mask-image maskImageFilename
-s, --shrink-factor (1)/2/3/...
-p, --patch-radius 1
1x1x1
-r, --search-radius 2
2x2x2
-o, --output correctedImage
[correctedImage,<noiseImage>]
--version
-v, --verbose (0)/1
-h
--helpPython
lx.ants.denoise_image(
image: Any,
noise_model: Literal["Rician", "Gaussian"] = "Rician",
mask: Any = None,
shrink_factor: int = 1,
patch_radius: int | Sequence[int] = 1,
search_radius: int | Sequence[int] = 2,
*,
dimension: int | None = None,
n_threads: int = 1,
upstream_defects: UpstreamDefectsName = "fix",
) -> DenoiseResultWhere UpstreamDefectsName is one of "fix", "reproduce".
DenoiseImage -d D -i image -n model [-x mask] -s shrink -p patch -r search -o [denoised,noise]: adaptive non-local means (Manjón et al., JMRI 2010).
Returns a DenoiseResult: denoised and noise, float32 images on the input’s grid (the noise
is always returned). image is a path, an lx.Image, a nibabel image or (array, affine),
read as float.
import larmorx as lx
# sMRIPrep's call: Rician noise model, patch radius 1, search radius 2, no shrinking
res = lx.ants.denoise_image("sub-01_T1w.nii.gz", n_threads=8)
res.denoised.to_filename("sub-01_desc-denoised_T1w.nii.gz")
noise = res.noise # image − denoised
# the Gaussian model, only inside a mask, larger patches
res = lx.ants.denoise_image(t1w, "Gaussian", mask=brain_mask, patch_radius=2)Its result, DenoiseResult, holds the denoised image and the noise removed from it (image - denoised, as ANTs computes it: the noise is estimated at the filter’s resolution and resampled onto the image’s grid, then subtracted).
| Field | Type | What it holds |
|---|---|---|
denoised |
Image |
|
noise |
Image |
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 DenoiseImage accepts (crates/larmorx-ants/src/cli/denoise_image.rs) and the arguments of lx.ants.denoise_image (python/larmorx/ants/denoise.py), whose defaults and descriptions are taken from it. Under each option, in grey, ANTs’s own help for it.
| ANTs option | Python | Default | Notes |
|---|---|---|---|
-d 2/3/4, --image-dimensionality |
dimension |
None |
default: the image’s; a 4D file read with -d 3 gives its first volume; in 4D, patches and search boxes extend along time too |
-i image, --input-image |
image |
path, lx.Image, nibabel image or (array, affine); read as float |
|
-n Rician/(Gaussian), --noise-model |
noise_model="Rician" |
"Rician" |
different default: the command line’s is Gaussian, Python’s is Rician (sMRIPrep’s choice). Case does not matter |
-x mask, --mask-image |
mask |
None |
read as unsigned char (0.4 → 0; values beyond 0 to 255 clamped, ANTS-06 in Upstream defects); only voxels where it is not 0 are patch centres. Must be on the grid the filter runs on (the shrunk grid with -s above 1) |
-s 1, --shrink-factor |
shrink_factor=1 |
1 |
ShrinkImageFilter along every axis (time too); 0 acts as 1. The noise is resampled linearly onto the full grid |
-p 1 / -p 1x1x1, --patch-radius |
patch_radius=1 / (1, 1, 1) |
1 |
one value for every axis or one per axis |
-r 2 / -r 2x2x2, --search-radius |
search_radius=2 / (2, 2, 2) |
2 |
one value for every axis or one per axis |
-o out / -o [out,noise], --output |
the result | its denoised and noise, float32 images on the input’s grid |
|
-v 1, --verbose |
(command line only) | ANTs’ progress characters and the elapsed time | |
--version |
(command line only) | the version line | |
-h, --help |
(command line only) | ANTs’ short and long help | |
ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS (or NSLOTS, as ITK reads them) |
n_threads |
1 |
ANTs’ result depends on it; larmorx’s does not: it always gives ANTs’ one-thread result |
LARMORX_UPSTREAM_DEFECTS |
upstream_defects |
"fix" |
fix (default) or reproduce (Upstream defects) |
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 DenoiseImage ...); lx.ants.denoise_image 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 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.denoise_image takes no implementation. The variable LARMORX_IMPLEMENTATION in 0.1.0rc1. |
--upstream-defects fix|reproduceupstream_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). The command lines run as python -m larmorx.
import larmorx as lx
# sMRIPrep's call: the Rician noise model, ANTs' other defaults.
res = lx.ants.denoise_image("t1w.nii.gz")
res.denoised.data.dtype # -> dtype('float32')larmorx ants DenoiseImage -d 3 -i t1w.nii.gz -n Rician -s 1 -o [ denoised.nii.gz, noise.nii.gz ]Ports
DenoiseImage has one port: a replica.
| Port | Package | Licence | Status | Records |
|---|---|---|---|---|
| replica | larmorx (built in) |
Apache-2.0 | validated | ants-denoise |
The replica: status validated against DenoiseImage itself (its
record, 2026-10-24, standard tier: 51 cases, 42 pass, 9
rejected by both alike; 40 compared cases, 52 outputs), on sMRIPrep’s command line on real T1w
images and on every option, in 2, 3 and 4 dimensions:
- against the unmodified ANTs 2.6.5 binary at one thread: 7 of 40 cases (9 of 52 outputs)
bit-identical. In the others, glibc’s
expf(orexp), which is not always correctly rounded, changes a few voxels by a few float units: on sMRIPrep’s command, 5,522 of 5,898,240 voxels of ds000005’s T1w by at most 2.0e-4 and 5,389 of 11,534,336 of ds000210’s by at most 2.1e-3; 1 − NCC at most 2.2e-13 in every case, and every difference at most 2.2e-4 of ANTs’ own difference between thread counts; - against the same binary run with glibc’s
expf,exp(andlogf,log,sin,cos,sincos) replaced by CORE-MATH’s correctly rounded ones (LD_PRELOAD,scripts/build_crmath_preload.sh), which is the arithmetic larmorx uses: 52 of 52 outputs bit-identical. ANTs’ own code is not changed; only those C-library functions are. - ANTs’ own result depends on its thread count, far more than on the C library: with 2 threads a fifth of the voxels of a T1w change, by up to 97; with 8 or 12 the result also changes from run to run. larmorx always gives ANTs’ one-thread result.
On the data panel (record, 2026-10-26): sMRIPrep’s
command on every T1w of the fourteen finished oracle runs (17 calls: the 3.5-year-old, the
glioma, the stroke, strong motion, 1.5 T and 7 T among them, and the runs with several T1w), each
replayed from its node with the node’s inputs, and four images fMRIPrep never denoises (the 7 T
MP2RAGE, the 82-year-old’s FLAIR, a child’s T2w with -n Rician, the 1.5 T T1w as float with
-n Gaussian): 21 of 21 bit-identical to ANTs with CORE-MATH; against the unmodified ANTs,
glibc’s expf changes voxels in all 21, by at most 0.0015 of ANTs’ own difference between one
thread and two or three, 1 − NCC below 2e-17.
DenoiseImage has one port, in pip install larmorx: the replica (crates/larmorx-ants,
crates/larmorx-image; Apache-2.0; Rust larmorx_ants::denoise_image,
larmorx_image::adaptive_denoising), translated from ANTs 2.6.5’s DenoiseImage on the
AdaptiveNonLocalMeansDenoisingImageFilter of ITK 5.4.5’s remote module AdaptiveDenoising
(commit 24825c8d, Apache-2.0). Its result does not depend on the thread count: it is always
ANTs’ one-thread result.
Evidence
How each of DenoiseImage’s ports was measured against ANTs, case by case: its evidence.
More in the repository
The API page docs/api/ants-denoise.md holds what DenoiseImage shares with the page’s other programs: