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 larmorx Apache-2.0 validated
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

text
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):

text
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
text
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
     --help

Python

python
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",
) -> N4Result

Where 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.

python
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 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.n4_bias_field_correction 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). The command lines run as python -m larmorx.

python
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')
bash
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, exp and sincos are 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, cos and sincos replaced 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: