Programs · ANTs and ITK

MultiplyImages

MultiplyImages multiplies an image by another image or by a number.

Original
ANTs 2.6.5
Command line
larmorx ants MultiplyImages
Python
lx.ants.multiply_images
Ports
  • replica larmorx Apache-2.0 validated
Evidence
every comparison with ANTs
Source
made from docs/api/ants-multiply-images.md and the code

What it does

sMRIPrep’s brain extraction runs it three times after Atropos (08_mult_gm, 09_relabel_wm and 12_relabel_gm).

Command line

text
larmorx ants MultiplyImages ImageDimension img1.nii img2.nii product.nii
larmorx ants MultiplyImages ImageDimension img1.nii 2.5 product.nii

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

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.

MultiplyImages's usage text, as the replica prints it
text
Usage:
MultiplyImages ImageDimension img1.nii img2.nii product.nii {smoothing}
 2nd image file may also be floating point numerical value, and program will act accordingly -- i.e. read as a number.
 Program handles vector and tensor images as well (larmorx: scalar images only)

Python

python
lx.ants.multiply_images(
    image: Any,
    other: Any,
    *,
    n_threads: int = 1,
    upstream_defects: UpstreamDefectsName = "fix",
) -> Image

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

MultiplyImages d image other out: the voxel-wise product in float32, with other a number or an image (read at image’s voxel indices; its geometry is ignored, as in ANTs).

Returns the float32 product at image’s voxel indices, as an lx.Image; other is an image or a number. A path that does not exist raises FileNotFoundError.

python
import larmorx as lx

brain = lx.ants.multiply_images("t1w.nii.gz", "brain_mask.nii.gz")
half = lx.ants.multiply_images(gm_probseg, 0.5)

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 MultiplyImages accepts (crates/larmorx-ants/src/cli/multiply_images.rs) and the arguments of lx.ants.multiply_images (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 (ANTs also accepts 1); Python takes any array shape
2 img1 image the product is at its voxel indices
3 img2 or a number other an image (its geometry is ignored: it may be larger; smaller is ANTS-07 in Upstream defects) or a number; vector and tensor images are not supported yet (ANTs multiplies component by component)
4 product the result without an output name ANTs prints “missing output filename” and aborts; larmorx exits 1
ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS n_threads 1 the result does not depend on it
LARMORX_UPSTREAM_DEFECTS upstream_defects "fix" fix (default) or reproduce (Upstream defects)

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 MultiplyImages ...); lx.ants.multiply_images 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.multiply_images 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 brain of the head: the image times its mask.
brain = lx.ants.multiply_images("t1w.nii.gz", "mask.nii.gz")
brain.data.dtype  # -> dtype('float32')
bash
larmorx ants MultiplyImages 3 t1w.nii.gz mask.nii.gz brain.nii.gz
larmorx ants MultiplyImages 3 t1w.nii.gz 0.5 half.nii.gz

Ports

MultiplyImages has one port: a replica.

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

The replica: status validated against MultiplyImages itself (its record, 2026-10-12): 15 cases, 12 compared, 3 rejected by both alike; 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): all 42 MultiplyImages nodes of the fourteen finished oracle runs (the three of sMRIPrep’s brain extraction after Atropos, 08_mult_gm, 09_relabel_wm and 12_relabel_gm, in every run), each replayed from its node with its inputs, and two calls fMRIPrep never makes (the stroke’s T2w times its lesion mask, a 588-volume multiband series times a scalar): 44 of 44 bit-identical, header bytes included.

MultiplyImages has one port, in pip install larmorx: the replica (crates/larmorx-ants; Apache-2.0; Rust larmorx_ants::multiply_images), translated from ANTs 2.6.5 (Apache-2.0).

Evidence

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

More in the repository

The API page docs/api/ants-multiply-images.md holds what MultiplyImages shares with the page’s other programs: