Programs · ANTs and ITK
N4BiasFieldCorrection
N4BiasFieldCorrection removes a smooth intensity bias field from an image.
- Original
- ANTs 2.6.5
- Command line
larmorx ants N4BiasFieldCorrection- Python
lx.ants.n4_bias_field_correction- Ports
- replica
larmorxApache-2.0 validated
- replica
- Evidence
- every comparison with ANTs
- Source
- made from docs/api/ants-n4.md and the code
What it does
The method is N4 (Tustison et al., N4ITK: Improved N3 Bias Correction, IEEE TMI 29(6), 2010); fMRIPrep, sMRIPrep and sdcflows run it on BOLD references, T1w images and field maps’ magnitudes.
Command line
larmorx ants N4BiasFieldCorrection [-d 2/3/4] -i input [-x mask] [-w weight] [-r 0/(1)] [-s (4)]
[-c [50x50x50x50,0.0]] [-b [splineDistance|meshResolution,<order=3>]]
[-t [0.15,0.01,200]] [-o corrected | [corrected,biasField]] [-v (0)/1]Everything after larmorx ants N4BiasFieldCorrection is the original’s command line: the arguments of ANTs 2.6.5’s N4BiasFieldCorrection, 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 N4BiasFieldCorrection ...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.
N4BiasFieldCorrection's usage text, as the replica prints it
COMMAND:
N4BiasFieldCorrection (larmorx port of ANTs v2.6.5)
N4 is a variant of the popular N3 (nonparameteric nonuniform normalization)
retrospective bias correction algorithm (N. Tustison et al., N4ITK: Improved N3
Bias Correction, IEEE Transactions on Medical Imaging, 29(6):1310-1320, June 2010).
OPTIONS:
-d, --image-dimensionality 2/3/4
-i, --input-image inputImageFilename
-x, --mask-image maskImageFilename
-r, --rescale-intensities 0/(1)
-w, --weight-image weightImageFilename
-s, --shrink-factor 1/2/3/(4)/...
-c, --convergence [<numberOfIterations=50x50x50x50>,<convergenceThreshold=0.0>]
-b, --bspline-fitting [splineDistance,<splineOrder=3>]
[initialMeshResolution,<splineOrder=3>]
-t, --histogram-sharpening [<FWHM=0.15>,<wienerNoise=0.01>,<numberOfHistogramBins=200>]
-o, --output correctedImage
[correctedImage,<biasField>]
--version
-v, --verbose (0)/1
-h
--helpPython
lx.ants.n4_bias_field_correction(
image: Any,
mask: Any = None,
weight: Any = None,
*,
shrink_factor: int = 4,
convergence: tuple[Sequence[int], float] = ((50, 50, 50, 50), 0.0),
bspline_fitting: float | Sequence[float] | None = None,
spline_order: int = 3,
histogram_sharpening: tuple[float, float, int] = (0.15, 0.01, 200),
rescale_intensities: bool = False,
dimension: int | None = None,
n_threads: int = 1,
upstream_defects: UpstreamDefectsName = "fix",
) -> N4ResultWhere UpstreamDefectsName is one of "fix", "reproduce".
N4BiasFieldCorrection -d D -i image [-x mask] [-w weight] -s shrink -c [iters,thr] -b [fitting,order] -t [fwhm,noise,bins] [-r] -o [corrected,bias].
Returns an N4Result: corrected and bias_field, float32 images on the input’s grid (the
bias field is always returned), and iterations, every iteration as N4Iteration(level, iteration, convergence). image is a path, an lx.Image, a nibabel image or (array, affine), read as float.
import larmorx as lx
res = lx.ants.n4_bias_field_correction("sub-01_T1w.nii.gz") # ANTs' defaults
res.corrected.to_filename("sub-01_desc-n4_T1w.nii.gz")
# sMRIPrep's final N4: weight = WM probability, spline distance 200 mm, five levels
res = lx.ants.n4_bias_field_correction(
t1w, weight=wm_probseg, shrink_factor=4,
convergence=([50] * 5, 1e-7), bspline_fitting=200, n_threads=8,
)
corrected, bias = res.corrected, res.bias_field
# with a brain mask, rescaled to the input's range inside it (the command line's default)
res = lx.ants.n4_bias_field_correction(boldref, mask=brain_mask, bspline_fitting=200,
rescale_intensities=True)Its result, N4Result, holds the corrected image, the bias field (the image divided by it gives corrected, except where a mask restores or rescales voxels), and every iteration.
| Field | Type | What it holds |
|---|---|---|
corrected |
Image |
|
bias_field |
Image |
|
iterations |
tuple[N4Iteration, ...] |
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 N4BiasFieldCorrection accepts (crates/larmorx-ants/src/cli/n4_bias_field_correction.rs) and the arguments of lx.ants.n4_bias_field_correction (python/larmorx/ants/n4.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 the time axis is not shrunk but gets a spline too |
-i image, --input-image |
image |
path, lx.Image, nibabel image or (array, affine); read as float |
|
-x mask, --mask-image |
mask |
None |
N4 uses the voxels where the mask is not 0; outside it the output keeps the input’s values |
-w weight, --weight-image |
weight |
None |
the fit weights each voxel by it; voxels with weight ≤ 0 are not used |
-s 4, --shrink-factor |
shrink_factor=4 |
4 |
ShrinkImageFilter along the spatial axes; 0 acts as 1 |
-c [50x50x50x50,0.0], --convergence |
convergence=((50, 50, 50, 50), 0.0) |
((50, 50, 50, 50), 0.0) |
iterations per level (one level per entry) and the threshold that ends a level |
-b [200], --bspline-fitting |
bspline_fitting=200.0 |
None |
a spline distance in mm: the image is padded so that whole spans of 200 mm cover it |
-b [2x2x3] |
bspline_fitting=(2, 2, 3) |
None |
mesh elements per axis (control points = elements + order) |
-b [...,3] |
spline_order=3 |
3 |
|
no -b |
bspline_fitting=None |
None |
one element per axis (4 control points for cubic splines) |
-t [0.15,0.01,200], --histogram-sharpening |
histogram_sharpening=(0.15, 0.01, 200) |
(0.15, 0.01, 200) |
the Gaussian’s FWHM, the Wiener noise, the number of bins |
-r 0/(1), --rescale-intensities |
rescale_intensities=False |
False |
different default: the command line rescales whenever a mask is given unless -r 0; Python rescales only when asked (as ANTsPy). Without a mask it never applies |
-o out / -o [out,bias], --output |
the result | its corrected and bias_field, float32 images on the input’s grid |
|
-v 1, --verbose |
the result | ANTs’ progress lines; Python returns every iteration in the result’s iterations |
|
--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 N4BiasFieldCorrection ...); lx.ants.n4_bias_field_correction 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.n4_bias_field_correction 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
# ANTs' defaults: four levels of 50 iterations, shrink factor 4.
res = lx.ants.n4_bias_field_correction("t1w.nii.gz")
res.corrected.data.dtype # -> dtype('float32')larmorx ants N4BiasFieldCorrection -d 3 -i t1w.nii.gz -o [ corrected.nii.gz, bias.nii.gz ]Ports
N4BiasFieldCorrection has one port: a replica.
| Port | Package | Licence | Status | Records |
|---|---|---|---|---|
| replica | larmorx (built in) |
Apache-2.0 | validated | ants-n4 |
The replica: status validated against N4BiasFieldCorrection itself (its
record, 2026-10-24, standard tier: 52 cases, 47 pass, 5 rejected by
both alike; 46 compared cases, in 2, 3 and 4 dimensions), on every command line fMRIPrep,
sMRIPrep and sdcflows give it:
- against the unmodified ANTs 2.6.5 binary at one thread: 29 of 46 cases bit-identical.
The others differ only because glibc’s
expf,logf,expandsincosare not always correctly rounded and larmorx’s are; the differences are smaller than ANTs’ own difference between thread counts in 14 of the 17 cases, up to 5.3 times that in three, and NCC is at least 0.9999999 (corrected images) and 0.9999998 (bias fields); - against the same binary run with glibc’s
expf,logf,exp,log,sin,cosandsincosreplaced by CORE-MATH’s correctly rounded ones (LD_PRELOAD,scripts/build_crmath_preload.sh), which is the arithmetic larmorx uses: 46 of 46 cases bit-identical. ANTs’ own code is not changed; only those C-library functions are; - the same against fMRIPrep 25.2.6’s own ANTs (2.6.2), on the 45 cases of the record before it: 45 of 45 bit-identical with CORE-MATH, 29 of 45 as built (findings).
On the data panel (record, 2026-10-26): all 64 N4 nodes of the fourteen finished fMRIPrep oracle runs (the BOLD references, the brain extraction’s and the final anatomical corrections, the field maps’ magnitudes; the 3.5-year-old, the glioma, the stroke, strong motion, 1.5 T, 7 T, multiband-8 and multi-echo among them), each replayed from its node with its inputs, and sMRIPrep’s final options on five images fMRIPrep never corrects (the 7 T MP2RAGE, a 3 T MP2RAGE UNIT1, the 82-year-old’s FLAIR, a glioma’s T2w of 6 mm slices, the stroke’s T2w fitted outside its lesion): 69 of 69 bit-identical with CORE-MATH (20 to the unmodified ANTs; the others within 0.042 of ANTs’ own difference between one thread and two or three). The panel also checked the input-geometry check: a mask written from the T2w’s affine (2e-6 mm off) is refused by both.
N4BiasFieldCorrection has one port, in pip install larmorx: the replica
(crates/larmorx-ants, crates/larmorx-image; Apache-2.0; Rust
larmorx_ants::n4_bias_field_correction, larmorx_image::n4), translated from ANTs 2.6.5’s
N4BiasFieldCorrection on ITK 5.4.5’s N4BiasFieldCorrectionImageFilter (Apache-2.0). Its
result does not depend on the thread count: it is always ANTs’ one-thread result.
larmorx computes what ITK’s C++ source defines. ANTs built by GCC 11.4 at -O3 (Ubuntu
22.04’s compiler) does not: GCC bug 110182 drops two float roundings of the B-spline fit, so
such a build gives slightly different N4 results
(findings, “GCC 11 miscompiles the fit”).
Evidence
How each of N4BiasFieldCorrection’s ports was measured against ANTs, case by case: its evidence.
More in the repository
The API page docs/api/ants-n4.md holds what N4BiasFieldCorrection shares with the page’s other programs: