Programs · ANTs and ITK
ThresholdImage
ThresholdImage sets the voxels between two bounds to one value and the others to another, or labels an image’s classes by Otsu’s thresholds.
- Original
- ANTs 2.6.5
- Command line
larmorx ants ThresholdImage- Python
lx.ants.threshold_image- Ports
- replica
larmorxApache-2.0 validated
- replica
- Evidence
- every comparison with ANTs
- Source
- made from docs/api/ants-threshold-image.md and the code
What it does
sMRIPrep’s brain extraction, which fMRIPrep runs,
binarises a brain probability map with it (0.5 1 1 0).
Command line
larmorx ants ThresholdImage ImageDimension ImageIn.ext outImage.ext threshlo threshhi <insideValue> <outsideValue>
larmorx ants ThresholdImage ImageDimension ImageIn.ext outImage.ext Otsu NumberofThresholds <maskImage.ext>
larmorx ants ThresholdImage ImageDimension ImageIn.ext outImage.ext Kmeans NumberofThresholds <maskImage.ext>Everything after larmorx ants ThresholdImage is the original’s command line: the arguments of ANTs 2.6.5’s ThresholdImage, 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 ThresholdImage ...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.
ThresholdImage's usage text, as the replica prints it
Usage: ThresholdImage ImageDimension ImageIn.ext outImage.ext threshlo threshhi <insideValue> <outsideValue>
ImageDimension ImageIn.ext outImage.ext Otsu NumberofThresholds <maskImage.ext>
ImageDimension ImageIn.ext outImage.ext Kmeans NumberofThresholds <maskImage.ext> (not supported by larmorx yet)
Inclusive thresholdsPython
lx.ants.threshold_image(
image: Any,
lower: float,
upper: float,
inside: float = 1.0,
outside: float = 0.0,
*,
n_threads: int = 1,
) -> ImageThresholdImage d in out lower upper inside outside: inside where lower <= v <= upper (bounds compared in float32), else outside. A float32 image, as ANTs writes it.
Returns a float32 lx.Image: inside where lower <= v <= upper (the bounds compared in
float32), else outside; lower > upper raises ValueError (ANTs aborts). Otsu’s mode is a
function of its own, lx.ants.otsu_threshold(image, n_thresholds=1, *, mask=None, n_threads=1, upstream_defects="fix"), which returns OtsuResult(image, thresholds), the thresholds being
the upper bounds of the chosen histogram bins.
import larmorx as lx
# fMRIPrep binarises a brain probability map: 1 where 0.5 <= p <= 1, else 0
mask = lx.ants.threshold_image("prob.nii.gz", 0.5, 1.0)
# Otsu: three classes inside a brain mask (labels 1..3, 0 outside)
r = lx.ants.otsu_threshold(t1w, 2, mask=brain_mask)
r.image, r.thresholdsIts 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 ThresholdImage accepts (crates/larmorx-ants/src/cli/threshold_image.rs) and the arguments of lx.ants.threshold_image (python/larmorx/ants/threshold.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; Python takes any array shape | |
2 ImageIn.ext |
image |
path, lx.Image, nibabel image or (array, affine) |
|
3 outImage.ext |
the result | float32, as ANTs writes it | |
4 threshlo |
lower |
inclusive; read with atof, then compared in float |
|
5 threshhi |
upper |
inclusive | |
6 insideValue |
inside |
1.0 |
default 1 |
7 outsideValue |
outside |
0.0 |
default 0 |
4 Otsu, 5 NumberofThresholds |
lx.ants.otsu_threshold(image, n_thresholds) |
ITK’s OtsuMultipleThresholdsImageFilter, 128 bins, labels 0..n |
|
6 maskImage.ext (with Otsu) |
lx.ants.otsu_threshold(..., mask=...) |
ANTs’ own code: region = mask value 1 (as int), 200 bins, labels 1..n+1 inside, 0 outside; the output takes the mask’s geometry |
|
4 Kmeans, 5 NumberofThresholds, 6 maskImage.ext |
– | not supported yet | |
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 ThresholdImage ...); lx.ants.threshold_image takes n_threads as an argument, and the others are 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.threshold_image takes no implementation. The variable LARMORX_IMPLEMENTATION in 0.1.0rc1. |
--upstream-defects fix|reproduce(no Python argument) |
The command line’s only: lx.ants.threshold_image takes no upstream_defects. 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: prob.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
# 1 where 300 <= v <= 700 (the head's brain and skull), else 0.
inside = lx.ants.threshold_image("prob.nii.gz", 300.0, 700.0)
sorted(set(inside.data.ravel().tolist())) # -> [0.0, 1.0]
# Otsu's single threshold inside the mask: labels 1 and 2 there, 0 outside.
r = lx.ants.otsu_threshold("prob.nii.gz", 1, mask="mask.nii.gz")
r.image.data.dtype # -> dtype('float32')larmorx ants ThresholdImage 3 prob.nii.gz binary.nii.gz 300 700 1 0
larmorx ants ThresholdImage 3 prob.nii.gz otsu.nii.gz Otsu 1 mask.nii.gzPorts
ThresholdImage has one port: a replica.
| Port | Package | Licence | Status | Records |
|---|---|---|---|---|
| replica | larmorx (built in) |
Apache-2.0 | validated | ants-threshold-image |
The replica: status validated against ThresholdImage itself (its
record, 2026-10-12): 41 cases, 35 compared, 5 rejected
by both alike, 1 expected divergence (Kmeans, not supported yet); every compared case
bit-identical, with ANTs’ exact header bytes. 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):
sMRIPrep’s ThresholdImage in the brain extraction of all fourteen finished oracle runs, each
replayed from its node with its inputs, and four calls fMRIPrep never makes (Otsu with 4, 3 and 2
thresholds on the 7 T MP2RAGE, the 82-year-old’s FLAIR and the 1.5 T T1w as float; a range on the
stroke’s lesion mask): 18 of 18 bit-identical, header bytes included.
ThresholdImage has one port, in pip install larmorx: the replica (crates/larmorx-ants,
crates/larmorx-image; Apache-2.0; Rust larmorx_ants::threshold_image,
larmorx_image::threshold), translated from ANTs 2.6.5 on ITK 5.4.5 (Apache-2.0).
Evidence
How each of ThresholdImage’s ports was measured against ANTs, case by case: its evidence.
More in the repository
The API page docs/api/ants-threshold-image.md holds what ThresholdImage shares with the page’s other programs: