commandANTs
A thin, transparent Python wrapper for the ANTs command-line tools.
Unlike ANTsPyX — which mixes compiled bindings with opinionated defaults and
exposes only a curated slice of the CLI — commandants shells out to the ANTs
binaries directly and hides nothing:
- Every option is reachable. Typed builders cover the common flags; a
.extra_args(...)escape hatch reaches anything else (present or future). - Every command is inspectable.
.build_command()/.to_shell()return the exact argv without running anything — so you can see, log, diff, and unit-test commands even on a machine with no ANTs installed. - The real
antsRegistrationgrammar. Compose arbitrary multi-stage pipelines, put multiple metrics in one stage (multivariate registration), and use point-set metrics (PSE/ICP/JHCT) to constrain a warp with corresponding points — the thing ANTsPyX won't let you do.
Install
pip install commandants # core, zero dependencies
pip install 'commandants[io]' # + SimpleITK/numpy for in-memory images & point CSVs
pip install 'commandants[dev]' # + pytest (and the io deps)
commandants calls the ANTs binaries, so you also need ANTs available.
Getting ANTs binaries
You can point commandants at an existing ANTs install (on PATH, via
$ANTSPATH, or ants_path=...), or let it fetch the official prebuilt
binaries for you:
pip install commandants
commandants install-ants # downloads official prebuilt ANTs for your OS
commandants version # -> commandants 0.1.0 / ANTs 2.6.5.x
commandants which antsRegistration
install-ants downloads the matching archive from the
ANTsX/ANTs releases, unpacks it into a
managed per-user directory (commandants info shows where), and resolve_binary
discovers it automatically — after PATH, so a system ANTs still wins if present.
Note: unlike ANTsPyX (which bundles compiled bindings into its wheels), the ANTs CLI archives are 400–750 MB, far over PyPI's limits — so they can't ship inside the pip wheel.
commandantsstays tiny and fetches them on demand instead.
Nothing downloads implicitly. If you want auto-fetch on first use, opt in:
import os
os.environ["COMMANDANTS_AUTO_INSTALL"] = "1" # or resolve_binary(..., auto_install=True)
Other CLI subcommands: commandants list, commandants uninstall-ants,
commandants install-ants --version latest, --asset <name> to override the
platform pick.
Quickstart
from commandants import (
AntsRegistration,
Rigid,
SyN,
MI,
CC,
PSE,
Convergence,
)
reg = AntsRegistration(
dimensionality=3,
output="out_",
warped_output="out_Warped.nii.gz",
write_composite_transform=True,
verbose=True,
)
# center-of-mass initialization -> --initial-moving-transform [fixed,moving,1]
reg.initialize_from_images("fixed.nii.gz", "moving.nii.gz", init="center-of-mass")
# Stage 1: rigid, mutual information
reg.add_stage(
transform=Rigid(gradient_step=0.1),
metrics=MI("fixed.nii.gz", "moving.nii.gz", weight=1.0, bins=32, sampling="Regular", sampling_pct=0.25),
convergence=Convergence([1000, 500, 250, 100], threshold=1e-6, window=10),
shrink_factors=[8, 4, 2, 1],
smoothing_sigmas=[3, 2, 1, 0],
)
# Stage 2: SyN, driven by CC *and* constrained by a point set
reg.add_stage(
transform=SyN(gradient_step=0.1, update_field_variance=3, total_field_variance=0),
metrics=[
CC("fixed.nii.gz", "moving.nii.gz", weight=1.0, radius=4),
PSE(
"fixed_points.csv",
"moving_points.csv", # <-- constrain the warp
weight=0.5,
point_set_sigma=1.0,
sampling_pct=0.5,
),
],
convergence=Convergence([100, 70, 50, 20]),
shrink_factors=[8, 4, 2, 1],
smoothing_sigmas=[3, 2, 1, 0],
)
print(reg.to_shell()) # inspect the exact command (no ANTs needed)
result = reg.run() # execute; raises AntsRuntimeError on failure
warped = result.load("warped") # -> SimpleITK.Image (needs the [io] extra)
Presets (ANTsPyX-style)
Don't want to hand-build stages? Use a preset — it returns a ready
AntsRegistration (you still inspect/estimate/run it):
from commandants import presets
reg = presets.syn(
"fixed.nii.gz", "moving.nii.gz", "out_", warped_output="out_Warped.nii.gz", use_float=True, verbose=True
)
reg.run(stream=True)
| Preset | Stages | Center-of-mass init? |
|---|---|---|
rigid |
Rigid | yes |
affine |
Rigid → Affine | yes |
syn |
Rigid → Affine → SyN (≈ antsRegistrationSyN) | yes |
syn_only |
SyN | no (assumes pre-aligned; pass init= or initial_transform=) |
translation, similarity |
(linear) | yes |
ccf_stpt |
Rigid → Affine (Mattes MI, 64 bins) → BSplineSyN (CC) | yes |
ccf_global |
Rigid → Affine (linear only) | yes |
ccf_stpt / ccf_global are the ANTs analogue of the Allen STPT → CCF
template-construction schedule (the sibling of the elastix ccf_stpt preset). It uses
BSplineSyN — ANTs' B-spline-regularized symmetric diffeomorphic transform — as the
closest match to the STPT local step's symmetric, invertible B-spline, with CC standing in
for the original cross-correlation.
Defaults mirror ANTsPyX (single precision, Mattes MI, light winsorization, and the
same linear schedule — Rigid/Affine[0.25], 2100x1200x1200x10 iterations,
6x4x2x1 shrink to full resolution) so the presets recover large offsets the way
ANTsPyX does. Every schedule/metric/step is an overridable argument — nothing hidden. Unlike a
hand-built registration, the linear presets and syn include the
center-of-mass initialization by default, so you won't get the identity-transform
surprise from a missing --initial-moving-transform. Worked example (incl. a
memory-safe SyN and an affine→SyN-only warm-start):
examples/using_presets.py.
In-memory images (SimpleITK)
Because it wraps the ANTs binaries, commandants is path-first — the binaries
read and write files. But you don't have to manage those files: pass a
SimpleITK.Image anywhere a path is expected and it's written to a temp file
automatically (SimpleITK is used because it preserves origin/spacing/direction, so
the disk round-trip is lossless). The temp files are not hidden — the result
exposes exactly where they went:
import SimpleITK as sitk
fixed = sitk.ReadImage("fixed.nii.gz")
moving = sitk.ReadImage("moving.nii.gz")
reg = AntsRegistration(3, output="out_")
reg.initialize_from_images(fixed, moving) # SimpleITK images
reg.add_stage(SyN(), CC(fixed, moving), Convergence([100, 70, 50]), [4, 2, 1], [2, 1, 0])
result = reg.run() # writes temp inputs, runs ANTs
print(result.temp_dir) # e.g. .../commandants_ab12cd
print(result.workspace.files) # every temp file written
print(result.workspace.inputs) # {'init_fixed': '.../init_fixed.nii.gz', ...}
Control where temp files live and whether they persist:
from commandants import TempWorkspace
result = reg.run(temp_dir="D:/scratch", keep_temp=True) # choose the dir; keep files
# or hand in a managed workspace that cleans up on exit:
with TempWorkspace(base="D:/scratch", keep=False) as ws:
reg.run(workspace=ws)
Previews never touch disk — to_shell() / build_command() render in-memory
images as <sitk:...> placeholders. The same image object passed to several
arguments is written only once.
Estimate memory / runtime before running
Get a rough peak-memory (and weak runtime) estimate for a built registration before launching it — handy for sizing a SyN job:
est = reg.estimate_resources(shape=(256, 256, 180), threads=8) # or fixed=<path/SITK image>
print(est.summary())
est.peak_memory_bytes # ~2.5 GiB here; drops to ~1.3 GiB with use_float=True
est.per_stage # per-stage breakdown (the SyN stage dominates)
est.est_runtime_seconds # very rough
The image dimensions come from the fixed image (inferred from your init/metric
images, or pass fixed= / shape=). This is a documented heuristic, not a
measurement — order-of-magnitude for planning, not a guarantee. See
commandants/estimate.py for the model.
Live progress for long runs
By default run() buffers output and returns it at the end. For a long job, stream
it live instead (needs verbose=True on the builder so ANTs emits progress):
reg = AntsRegistration(3, output="reg_", verbose=True, ...)
reg.run(stream=True) # echo each line to the console
reg.run(log_file="reg.log") # write each line to a file (live, tail-able)
reg.run(stream=True, log_file="reg.log") # tee: console AND file
reg.run(on_line=lambda ln: logging.info(ln.rstrip())) # or route to logging/tqdm/...
result = reg.run(stream=True)
print(len(result.stdout)) # output is still captured regardless
stream (console), log_file (a path — opened/closed for you — or an open file
handle), and on_line (callback) are independent and combine freely. When
streaming, stdout and stderr are merged so ordering is preserved (result.stdout
holds the merged text). If output looks chunky rather than per-iteration, that's
the child process buffering, not the wrapper.
Jupyter: stream=True works in notebooks — the wrapper reads ANTs' output and
re-emits it through Python's sys.stdout (which Jupyter redirects into the cell),
flushing per line. (This is why streaming shows up where raw inherited subprocess
output would not.) For very long runs, prefer log_file= (or an on_line that
updates a single tqdm bar) to avoid flooding the cell with thousands of lines.
Understanding exit codes (e.g. -9)
ANTs has no big numbered error-code table — it exits 0/1 and puts detail in
stderr; anything else is a signal or a Windows exception. commandants
decodes them:
commandants explain -9 # or 137, -11, 3221225477, ...
result = reg.run(check=False)
if result.returncode != 0:
print(result.explain().text())
AntsRuntimeError also embeds the decoding in its message. The big one: -9
(or 137) is SIGKILL — almost always the out-of-memory killer or a cluster memory
limit, not an ANTs bug. Reach for estimate_resources() and use_float=True.
Nothing is hidden
Reach any flag the typed API doesn't model yet:
reg.extra_args("--use-estimate-learning-rate-once", "1")
Apply transforms
from commandants import AntsApplyTransforms
apply = AntsApplyTransforms(
3, "moving.nii.gz", "fixed.nii.gz", "resampled.nii.gz", interpolation="BSpline[3]", output_data_type="float"
) # stored pixel type (char/short/int/float/...)
apply.add_transform("out_1Warp.nii.gz")
apply.add_transform("out_0GenericAffine.mat") # applied first (ANTs order)
apply.run()
Precision defaults to single (
--float 1).AntsRegistrationandAntsApplyTransformscompute in single precision by default (like ANTsPyX'ssingleprecision=True, and easier on memory for large volumes). Passuse_float=Falsefor double, oruse_float=Noneto omit the flag entirely (ANTs' own default is double). This is computation precision —output_data_type=separately controls the stored pixel type of the written image.
Argument order —
input/reference, notfixed/moving. commandants uses ANTs' ownantsApplyTransformsterminology, which is not ANTsPyX's. The 2nd arg isinput_image(-i, the image whose pixels are warped) and the 3rd isreference_image(-r, the grid/space of the output) — so applying a moving→fixed transform isAntsApplyTransforms(3, moving, fixed, out). ANTs uses "input" (not "moving") on purpose: the input is often not the original moving image — it may be a label map, another channel, or a point set. Coming from ANTsPyX'sapply_transforms(fixed, moving, ...)? The mapping ismoving → input_image,fixed → reference_image. Use keywords to be safe:AntsApplyTransforms(3, input_image=moving, reference_image=fixed, output=out). (Registration is different:antsRegistrationmetrics do use fixed/moving, so commandants' metrics take(fixed, moving)— each tool follows the CLI it wraps.)
How output transforms are saved
ANTs' transform-file naming trips everyone up. With collapse_output_transforms
on (standard), a Rigid → Affine → SyN run with output="reg_" writes:
| File | What it is |
|---|---|
reg_0GenericAffine.mat |
Rigid and Affine collapsed into one linear transform |
reg_1Warp.nii.gz |
SyN forward deformation (moving → fixed) |
reg_1InverseWarp.nii.gz |
SyN inverse deformation (fixed → moving) |
The number is the position in the collapsed stack, not the stage index — so the
two linear stages share index 0 and SyN is 1. reg.expected_transforms()
predicts these filenames and hands back ready-to-apply -t lists:
info = reg.expected_transforms() # optionally pass cwd=... (where run() launches)
info["output_dir"] # absolute folder the files land in
info["files_abs"] # the files as absolute paths
info["forward"] # ['reg_1Warp.nii.gz', 'reg_0GenericAffine.mat'] (moving -> fixed)
info["inverse"] # [('reg_0GenericAffine.mat', True), 'reg_1InverseWarp.nii.gz']
The folder comes from your output prefix: a bare "reg_" lands in the working
directory at run time; "/data/sub01/reg_" lands in /data/sub01/. ANTs will
not create a missing output folder — make sure it exists (or pass run(cwd=...)).
Set write_composite_transform=True to get a single reg_Composite.h5 /
reg_InverseComposite.h5 instead. Full worked example:
examples/rigid_affine_syn.py.
Preprocessing
from commandants import N4BiasFieldCorrection
N4BiasFieldCorrection(
3,
"raw.nii.gz",
"n4.nii.gz",
bias_output="bias.nii.gz",
shrink_factor=4,
convergence_iterations=[50, 50, 50, 50],
convergence_threshold=0.0,
bspline_distance=200,
).run()
elastix (benchmark against ANTs)
commandants also wraps elastix (elastix + transformix)
through the same core, so you can run both tools with one harness. elastix is
configured by parameter maps (not flags), which commandants models as
pass-through ParameterMaps plus curated presets.
Getting elastix binaries
Exactly like ANTs: point commandants at an existing elastix (on PATH, via
$ELASTIXPATH, or elastix_path=...), or let it fetch the official prebuilt
binaries:
commandants install-elastix # downloads official prebuilt elastix for your OS
commandants version # -> ... / elastix version: 5.3.1
commandants which elastix # and: commandants which transformix
install-elastix downloads the matching archive from the
SuperElastix/elastix releases
(default 5.3.1), unpacks it into a managed per-user directory (commandants list --tool elastix shows where), and grabs transformix alongside elastix.
Resolution order mirrors ANTs — elastix_path= → $ELASTIXPATH → PATH →
managed — so a system elastix still wins if present.
Unlike the ANTs CLI (and unlike the
SimpleElastixPython package, which ships no command-line tools), elastix ships shared libraries next to its binaries. For a managed install,commandantsrecords thatlib/dir and injects it onto the loader path (LD_LIBRARY_PATH/DYLD_LIBRARY_PATH/PATH) automatically at run time. If you instead point at your own elastix via$ELASTIXPATH/PATH, make sure itslib/is discoverable the way the official archive lays it out.
COMMANDANTS_AUTO_INSTALL=1 (or auto_install=True) opts elastix into the same
fetch-on-first-use behavior; commandants install-elastix --version latest,
--asset <name>, and commandants uninstall-elastix round out the CLI.
Usage
from commandants import elastix
reg = elastix.presets.affine("fixed.nii.gz", "moving.nii.gz", "out_dir")
print(reg.to_shell()) # elastix -f ... -m ... -out out_dir -p <param0>
result = reg.run(stream=True) # writes out_dir/result.0.nii + TransformParameters.0.txt
print(result.duration_seconds) # wall-clock time, for benchmarking vs ANTs
# apply the transform to another image:
elastix.Transformix("out_dir/TransformParameters.0.txt", "warp_out", moving="other.nii.gz").run()
The presets are the quick path. For the transparent path — the elastix analogue of
hand-composing antsRegistration stages — work with parameter maps directly:
elastix.ParameterMap (or presets.parameter_map("rigid") as a starting point) is an
ordered, dict-like model of an elastix (Key value) file. Build one from scratch, tweak
a preset, or load and edit an existing .txt — it round-trips the exact text, and a list
of maps becomes sequential -p stages.
from commandants.elastix import ParameterMap, presets
affine = presets.parameter_map("affine") # a curated default map to start from
affine.set("MaximumNumberOfIterations", 512) # tweak any setting
affine["NumberOfResolutions"] = 5 # dict-style works too
bspline = presets.parameter_map("bspline").set("FinalGridSpacingInPhysicalUnits", 12)
reg = elastix.Elastix("fixed.nii.gz", "moving.nii.gz", "out_dir", [affine, bspline]) # affine -> B-spline
Full worked example (all three ways to build a map, multi-stage, inspect, run, and apply):
examples/elastix_parameter_maps.py. A backend
timing comparison: examples/benchmark_elastix_vs_ants.py.
There's also a domain preset, presets.ccf_stpt(...) (and ccf_global), that reproduces
the Allen STPT → CCF template-construction
schedule — rigid → affine Mattes MI (64 bins, center-of-gravity init, coarse-to-fine from
shrink 8) → 3rd-order B-spline NCC over a 4-level grid. (The original deformable step uses a
discrete MRF optimizer, so the B-spline stage matches in spirit, not mechanism.)
Allen STPT / CCF registration
The third backend runs the real Allen algorithm from
AllenInstitute/stpt_registration -- MI rigid
to MI affine to a discrete MRF deformable stage solved symmetrically. The ANTs and elastix
ccf_stpt presets only approximate that last step with continuous optimizers.
from commandants import stpt
reg = stpt.presets.ccf_stpt("fixed.nii.gz", "moving.nii.gz", "out_dir", threads=8)
print(reg.to_shell()) # inspect before running, as with every backend
result = reg.run()
warped = result.load("warped") # -> SimpleITK.Image
affine = result.outputs["affine"] # out_dir/stpt_Affine.txt
SimpleITK images work anywhere a path does, exactly as with the ANTs and elastix wrappers:
previews render them as <sitk:...> placeholders, runs materialize them to temp files, and
result.workspace.inputs tells you where each one went.
Binary. This drives
gridpoint, a minimal ITK-only driver built from a separate, Allen-licensed repository -- the upstream code is BSD-2 plus a non-commercial clause, so it is not vendored into this MIT package; commandants only invokes the binary. Put it onPATHor set$STPTPATH. There is no download, hence noinstall-stpt. The driver is named gridpoint because the discrete MRF labels displacements at B-spline grid points -- and because the upstream Allen namespace,idp, is spelled inside that word.The upstream
idpProjection*modules are not driven directly: they cannot register two 3D volumes at all, assembling a volume slice-by-slice from one 2D file per<sub-image>with the z-extraction pinned to slice 0, on top of needing a LIMS-shaped XML, a structuredmodel_directory, and JPEG2000/Kakadu.
Benchmarking backends against each other
Register the same image pair with several backends and compare timings:
from commandants import benchmark
report = benchmark.compare(
"fixed.nii.gz",
"moving.nii.gz",
"bench_out",
backends=("ants", "elastix"),
preset="affine",
threads=8,
repeats=3,
warmup=1,
)
print(report.to_table())
report.to_csv("bench.csv")
backend runs best(s) median(s) mean(s)
------------------------------------------------
ants 3 0.54 0.58 0.57
elastix 3 0.98 0.99 1.02
Timing is already apples-to-apples — every backend subclasses AntsCommand and shares one
run() path that times only the subprocess (image materialization and output bookkeeping
happen outside the timed window). The harness adds the fairness around it: threads are pinned
identically, streaming is forced off (it would penalize the chattier tool), the warped-image
format is equalized so compression cost matches, failures are isolated per backend, and
warmup/repeats absorb page-cache effects.
It also normalizes the output shapes, which genuinely differ — ANTs takes a transform
prefix and exposes transform names only via expected_transforms(), while elastix takes an
output directory and declares everything. Each trial gives you warped + transforms at
predictable paths, so you can compute your own accuracy metrics. Adding a backend is one
benchmark.register_backend(...) call. Worked example:
examples/benchmark_elastix_vs_ants.py.
If you want the comparison without the harness,
examples/ants_vs_gridpoint.py does the same thing by
hand — build, inspect, run, score — as # %% cells you can open as a notebook or run as a
script.
Design
commandants/
core/ binary resolution, the AntsCommand base, result objects
registration/ AntsRegistration, metrics (incl. PSE/ICP/JHCT), transforms, stages, apply
elastix/ Elastix, Transformix, ParameterMap, presets (elastix backend)
stpt/ Allen STPT/CCF backend (StptRegistration, presets)
preprocessing/ N4BiasFieldCorrection, ThresholdImage, ImageMath, ResampleImage
io/ point-set CSV + SimpleITK in-memory support
benchmark.py cross-backend comparison harness (Backend adapters + compare())
install.py download/manage prebuilt ANTs + elastix binaries (ToolSpec table)
__main__.py the `commandants` CLI
Every builder subclasses AntsCommand, so they all share .build_command(),
.to_shell(), .run(...), .extra_args(...), and a CompletedAnts result with
declared output paths and an optional lazy .load().
Status
v1 covers registration + core preprocessing. Segmentation (Atropos,
KellyKapowski) and motion correction (antsMotionCorr) are natural next
additions — the layered core makes them straightforward.
License
MIT
Metadata
Release files for commandants 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| commandants-0.4.0.tar.gz | 155.4 kB | Without provenance | Details for commandants-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| commandants-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for commandants-0.4.0-py3-none-any.whl |
Total release size: 244.2 kB
Release files / commandants-0.4.0.tar.gz
| Download URL | commandants-0.4.0.tar.gz |
|---|---|
| Size | 155.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
89585b638b32dd10678d07e3ebde2195693e33619c800c340681f2666e2e3741
|
|
BLAKE2b-256 checksum How to use checksums |
5c355129e537317d64ef022b8cd90d392497dfc8d1b46c0ec4bad5000a12121d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / commandants-0.4.0-py3-none-any.whl
| Download URL | commandants-0.4.0-py3-none-any.whl |
|---|---|
| Size | 88.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
18839400ce752f2e00d4f96ddfc42072afd2ab514de16bd6181ad8c290c7ca0a
|
|
BLAKE2b-256 checksum How to use checksums |
48cb29e0aacdd46a111b686cddb8cd833beee4e045feec796cfc7f8c3b5df5a3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for commandants 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.