Programs · ANTs and ITK

ResampleImage

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

What it does

ResampleImage resamples an image onto a grid with a new spacing or a new size, keeping its origin and direction, by linear, nearest-neighbour, Gaussian, windowed-sinc or B-spline interpolation, and writes it in one of ANTs’ eight pixel types.

Command line

text
larmorx ants ResampleImage imageDimension inputImage outputImage MxNxO [size=1,spacing=0] [interpolate type] [pixeltype]

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

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.

ResampleImage's usage text, as the replica prints it
text
Usage: ResampleImage imageDimension inputImage outputImage MxNxO [size=1,spacing=0] [interpolate type [its parameters]] [pixeltype]
  Interpolation type:
    0. linear (default)
    1. nn
    2. gaussian [sigma=imageSpacing] [alpha=1.0]
    3. windowedSinc [type = 'c'osine, 'w'elch, 'b'lackman, 'l'anczos, 'h'amming]
    4. B-Spline [order=3]
 pixeltype  :  TYPE
  0  :  char
  1  :  unsigned char
  2  :  short
  3  :  unsigned short
  4  :  int
  5  :  unsigned int
  6  :  float (default)
  7  :  double
 larmorx reads an interpolation type's parameters right after it, and the pixel type after
 them (LARMORX_UPSTREAM_DEFECTS=reproduce reads the seventh argument as both, as ANTs does).

Python

python
lx.ants.resample_image(
    image: Any,
    spacing: float | Sequence[float] | None = None,
    *,
    size: int | Sequence[int] | None = None,
    interpolation: str = "linear",
    sigma: float | Sequence[float] | None = None,
    alpha: float = 1.0,
    window: str = "hamming",
    order: int = 3,
    pixel_type: str = "float",
    dimension: int | None = None,
    n_threads: int = 1,
    upstream_defects: UpstreamDefectsName = "fix",
) -> Image

Where UpstreamDefectsName is one of "fix", "reproduce".

ResampleImage d in out MxNxO [size?] [interpolation] [pixeltype]: the image resampled onto a grid with the same origin and direction and a new spacing or size (one value or one per axis), without smoothing.

Returns an lx.Image in pixel_type’s type. Give spacing or size, one value or one per axis.

python
import larmorx as lx

t1w_2mm = lx.ants.resample_image("sub-01_T1w.nii.gz", 2.0)
on_grid = lx.ants.resample_image(t1w, size=[128, 128, 96], interpolation="bspline")
labels = lx.ants.resample_image(seg, 1.0, interpolation="nearest", pixel_type="short")

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 ResampleImage accepts (crates/larmorx-ants/src/cli/resample_image.rs) and the arguments of lx.ants.resample_image (python/larmorx/ants/resample.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) dimension (default: the image’s) None a path is read in that many dimensions
2 inputImage, 3 outputImage image, the result the output keeps the input’s origin and direction
4 MxNxO, 5 0 (default) spacing (one value or one per axis) None size int(old spacing · old size / spacing + 0.5)
4 MxNxO, 5 1 size= (one value or one per axis) None spacing old · (old size − 1) / (size − 1)
6 interpolation 0 (default) / 1 interpolation="linear" / "nearest" "linear" any dimension
6 2, then sigma and alpha "gaussian", sigma=, alpha=1.0 sigma=None, alpha=1.0 sigma in mm, default the input spacing; 3D
6 3, then the window "sinc", window="hamming" "hamming" cosine, welch, blackman, lanczos, hamming (the first letter); radius 3; outside the image the nearest edge voxel; 3D
6 4, then the order "bspline", order=3 3 orders 0 to 5 (others are 3); 3D
pixeltype 0 to 7, after the interpolator’s parameters pixel_type="char", "uchar", "short", "ushort", "int", "uint", "float" (default), "double" "float" the type the image is read as and written in; ANTs reads it as the seventh argument whatever the interpolator (the seventh argument)
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 ResampleImage ...); lx.ants.resample_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 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.resample_image 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

# The 4 mm head to 2 mm, linear; to a size of 20 x 24 x 20 by B-spline.
fine = lx.ants.resample_image("t1w.nii.gz", 2.0)
fine.shape  # -> (80, 96, 80)
coarse = lx.ants.resample_image("t1w.nii.gz", size=[20, 24, 20], interpolation="bspline")
coarse.shape  # -> (20, 24, 20)
bash
larmorx ants ResampleImage 3 t1w.nii.gz t1w_2mm.nii.gz 2
larmorx ants ResampleImage 3 t1w.nii.gz on_grid.nii.gz 20x24x20 1 4
larmorx ants ResampleImage 3 t1w.nii.gz nearest_short.nii.gz 3 0 1 2
larmorx ants ResampleImage 3 t1w.nii.gz sinc.nii.gz 3 0 3 w 3
larmorx ants ResampleImage 3 t1w.nii.gz smooth.nii.gz 2 0 2 1.5x1.5x1.5 2 1

Ports

ResampleImage has one port: a replica.

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

The replica: status validated against ResampleImage itself (its record, 2026-10-24): 57 cases, 47 outputs compared, all bit-identical with ANTs’ exact header bytes: the eight pixel types, every interpolator (B-spline orders 0 to 5, Gaussian, windowed sinc), by spacing and by size, in 2, 3 and 4 dimensions, and a size of 1 (ANTS-29); 8 rejected by both alike. One expected divergence: B-spline, Gaussian and windowed-sinc interpolation of 2D and 4D images are not supported yet. 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 ResampleImage; on the panel’s images (the 82-year-old’s FLAIR to 1 mm, linear; the 7 T MP2RAGE to 1 mm, B-spline; a glioma’s T2w to 0.8 mm, windowed sinc; the stroke’s lesion mask to a size, nearest): 4 of 4 bit-identical, header bytes included.

ResampleImage has one port, in pip install larmorx: the replica (crates/larmorx-ants, crates/larmorx-interp; Apache-2.0; Rust larmorx_ants::resample_image, larmorx_ants::resample, larmorx_interp), translated from ANTs 2.6.5 on ITK 5.4.5 (Apache-2.0).

Evidence

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

More in the repository

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