Programs · ANTs and ITK

ResampleImageBySpacing

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

What it does

ResampleImageBySpacing resamples an image onto a grid with a new spacing, keeping its origin and direction, after smoothing it with a Gaussian where the spacing grows, by linear or nearest-neighbour interpolation.

Command line

text
larmorx ants ResampleImageBySpacing ImageDimension inputImageFile outputImageFile outxspc outyspc {outzspacing} {dosmooth?} {addvox} {nn-interp?}

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

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.

ResampleImageBySpacing's usage text, as the replica prints it
text
Usage:
ResampleImageBySpacing  ImageDimension inputImageFile  outputImageFile outxspc outyspc {outzspacing}  {dosmooth?}  {addvox} {nn-interp?}
 addvox pads each dimension by addvox

Python

python
lx.ants.resample_image_by_spacing(
    image: Any,
    spacing: Sequence[float],
    *,
    smooth: bool = True,
    add_voxels: int = 0,
    nearest: bool = False,
    n_threads: int = 1,
    upstream_defects: UpstreamDefectsName = "fix",
) -> Image

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

ResampleImageBySpacing d in out sx sy [sz [st]] smooth addvox nn: the image resampled onto a grid with the same origin and direction and the new spacing (one value per axis; for a 4D image the last is the time step in seconds).

Returns a float32 lx.Image with the new spacing; the Python result keeps the input’s header, with the new time step in 4D.

python
import larmorx as lx

low = lx.ants.resample_image_by_spacing("sub-01_T1w.nii.gz", [2.0, 2.0, 2.0])
up = lx.ants.resample_image_by_spacing(boldref, [1.0, 1.0, 1.0], smooth=False)
labels = lx.ants.resample_image_by_spacing(seg, [1, 1, 1], smooth=False, nearest=True)

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 ResampleImageBySpacing accepts (crates/larmorx-ants/src/cli/resample_image_by_spacing.rs) and the arguments of lx.ants.resample_image_by_spacing (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) len(spacing) a path is read in that many dimensions; an in-memory image must have them
2 inputImageFile image path, lx.Image, nibabel image or (array, affine); read as float
3 outputImageFile the result float32; same origin and direction, the new spacing
4 outxspc, 5 outyspc, then outzspacing (and the time step in 4D) spacing one value per axis (atof); 4D: the last is the time step in seconds
dosmooth? (default 1), after the spacings smooth=True True per axis, a recursive Gaussian of sigma out/in − 1 input voxels where positive (ANTs: the same number in mm, ANTS-32)
addvox (default 0), after it add_voxels=0 0 added to every axis’s size
nn-interp? (default 0), last nearest=False False nearest neighbour instead of linear
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 ResampleImageBySpacing ...); lx.ants.resample_image_by_spacing 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_by_spacing 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), mask.nii.gz (the synthetic head’s brain as a mask (1 inside, 0 outside)). The command lines run as python -m larmorx.

python
import larmorx as lx

# The 4 mm head to 8 mm, smoothed first; the mask to 2 mm by nearest neighbour.
low = lx.ants.resample_image_by_spacing("t1w.nii.gz", [8.0, 8.0, 8.0])
low.shape  # -> (20, 24, 20)
labels = lx.ants.resample_image_by_spacing("mask.nii.gz", [2, 2, 2], smooth=False, nearest=True)
labels.shape  # -> (80, 96, 80)
bash
larmorx ants ResampleImageBySpacing 3 t1w.nii.gz t1w_8mm.nii.gz 8 8 8
larmorx ants ResampleImageBySpacing 3 mask.nii.gz mask_2mm.nii.gz 2 2 2 0 0 1

Ports

ResampleImageBySpacing has one port: a replica.

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

The replica: status validated against ResampleImageBySpacing itself (its record, 2026-10-24): 37 cases, 30 outputs compared, all bit-identical with ANTs’ exact header bytes and printed text, in 2, 3 and 4 dimensions; 5 rejected by both alike. Where ANTs resamples uninitialised memory, larmorx reproduces the rest (exit code, header, printed text) and fills that memory with zeros (ANTS-28). 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 ResampleImageBySpacing; on the panel’s images (the 7 T MP2RAGE to 2 mm, the 82-year-old’s FLAIR to 1 mm, the 3.5-year-old’s T1w to 1.5 mm): 3 of 3 bit-identical, header bytes included.

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

Evidence

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

More in the repository

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