Programs · ANTs and ITK
ResampleImageBySpacing
- Original
- ANTs 2.6.5
- Command line
larmorx ants ResampleImageBySpacing- Python
lx.ants.resample_image_by_spacing- Ports
- replica
larmorxApache-2.0 validated
- replica
- 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
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):
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
Usage:
ResampleImageBySpacing ImageDimension inputImageFile outputImageFile outxspc outyspc {outzspacing} {dosmooth?} {addvox} {nn-interp?}
addvox pads each dimension by addvoxPython
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",
) -> ImageWhere 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.
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 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.resample_image_by_spacing 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), mask.nii.gz (the synthetic head’s brain as a mask (1 inside, 0 outside)). The command lines run as python -m larmorx.
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)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 1Ports
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: