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

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

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

Python

python
lx.ants.threshold_image(
    image: Any,
    lower: float,
    upper: float,
    inside: float = 1.0,
    outside: float = 0.0,
    *,
    n_threads: int = 1,
) -> Image

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

python
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.thresholds

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

python
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')
bash
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.gz

Ports

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: