elastix

A parameter-file-driven C++ registration engine on ITK — 23 metrics, 18 transforms and 18 optimisers in any combination — which cannot open a whole-slide image and is worth reading anyway, because its companion tool transformix warps arbitrary held-out points and so supplies the independent acceptance test this wiki’s registration cluster has been missing.

Purpose

Verdict: not adopted as a registration tool, and it is not a competitor to VALIS — it cannot read a slide at all. What it supplies instead is the measurement half of the problem, and that is the half Cross-Stain Registration names as the actual blocker rather than a nicety.

The decisive question for anything in this cluster is not what the tool does but what it does that the indexed stack does not. The stack, per QuPath Tooling, is tiatoolbox’s DFBRegister for a pair and VALIS for a series. Both estimate transforms. Neither can tell you whether the transform it produced is right — VALIS looks like it can, and the reason it cannot is the central finding of its own page: the rTRE it reports is the residual over the very keypoints the transform was fitted to, so a confidently wrong alignment scores well.

elastix closes exactly that hole, and nothing else here does:

  1. transformix -def <pointfile> transforms an arbitrary set of input points through a fitted transform. Points the optimiser never saw. That is the definition of an independent target registration error, and it is the thing cross-stain-registration’s open questions call for in as many words — “a handful of hand-placed fiducial points per case that the fit never sees”.
  2. transformix -jac all writes the determinant of the spatial Jacobian as an image. A deformation field that has folded produces non-positive determinants, which is physically impossible for tissue and is detectable without any ground truth at all. A second quality signal, orthogonal to the first, and again unavailable anywhere else in this stack.

It is also genuinely absent from the stack rather than already present by another name. VALIS was the obvious candidate to be quietly wrapping it — the two live in adjacent problem spaces and SimpleElastix is the usual bridge — but VALIS’s pyproject.toml declares simpleitk and not simpleelastix or itk-elastix. Checked directly rather than assumed, because “we already have this transitively” would have been the cheapest possible reason not to write this page.

Data used

None. It is a registration engine, not a data project, and no cohort or image is involved in evaluating it. What it consumes is whatever ITK can read — and that constraint is the whole of the Methods section below.

Methods

Read at source level on 2026-08-10 from a full clone.

What it actually is: a configuration surface, not a pipeline

elastix is not a tool that registers images. It is a set of interchangeable components that a plain-text parameter file assembles into a registration, and the counts are the point:

Component family Count
Metrics 23
Transforms 18
Optimizers 18
Image samplers 6
Interpolators 6
Fixed / moving image pyramids 5 each
Registration schemes 3

For cross-stain work the relevant metrics are the multi-modal ones — AdvancedMattesMutualInformation, NormalizedMutualInformation, and the unusual KNNGraphAlphaMutualInformation — because two stains of one block are the multi-modal problem in miniature: the same structures, deliberately different intensities. Alongside them sit regularisation penalties that no other tool here offers: BendingEnergyPenalty, RigidityPenalty, DistancePreservingRigidityPenalty. Those constrain a deformable warp towards something physically plausible, which is the standing objection to non-rigid registration of serial sections — that a flexible enough transform will align anything to anything.

CorrespondingPointsEuclideanDistanceMetric is worth naming separately: it drives registration from landmark correspondences. Note the trap, because it is easy to conflate with the finding above — points used through this metric are in the fit and therefore cannot also serve as the independent check. The two uses are mutually exclusive per point set.

The wall: there is no whole-slide image input, at all

This is the fact that settles adoption, and it is not stated as a limitation anywhere in the README — it simply never comes up, because elastix is a medical-imaging tool and whole-slide imaging is not its world.

The CMake requests exactly six ITK IO modules: ITKIOImageBase, ITKIOMeshBase, ITKIOMeshOBJ, ITKIOMeta, ITKIOTransformBase, ITKIOXML. No OpenSlide, no Bio-Formats, no tiled or pyramidal reader. A grep of the whole tree for slide formats returns nothing — and it is worth recording that my first pass appeared to find matches for svs, all of which turned out to be the string MSVS inside // include first to avoid MSVS warning comments. A pattern search that looks like a hit is not a hit, which is the same lesson this wiki records under wiki/index.md gap #8 about opening the file rather than trusting the match.

A second constraint compounds it, and this one is only visible in the build configuration. Core/Install/CMakeLists.txt sets the supported image types at compile time:

ELASTIX_IMAGE_DIMENSIONS    2 3 4
ELASTIX_IMAGE_2D_PIXELTYPES "float"
ELASTIX_IMAGE_3D_PIXELTYPES "short" "float"

So 2D is supported — but 2D is float only, and scalar. An RGB slide plane has to be reduced to one floating-point channel before elastix will accept it, which for cross-stain work means choosing a colour deconvolution or optical-density projection first, and that choice is now part of the registration method rather than a preprocessing detail. The header template says plainly that “elastix, and all its components, must be recompiled after adding a line in this file”, so the supported set is not a runtime option. The prebuilt binaries, the Docker image and the itk-elastix Python wheel ship a fixed selection.

What that means in practice

elastix is intensity-based, with no feature detection or matching anywhere in it. It optimises a similarity metric from a starting position, so it needs a reasonable initialisation and will not recover from the large hand-placement rotations that serial sections routinely arrive with. That is precisely what DFBRegister’s deep features and VALIS’s DISK/LightGlue matching are for.

The honest division of labour, therefore, is not elastix or VALIS. It is: feature-based tools get you aligned; elastix refines under an explicit deformation model and, more importantly, tells you whether the result is acceptable. Nothing about that requires adopting elastix as a pipeline component — transformix operating on a saved transform and a point list is a small, separable step.

Provenance and currency

Checked against primary sources rather than recalled. NOTICE reads “Copyright 2014 University Medical Center Utrecht and contributors”; the README names Stefan Klein and Marius Staring as lead developers and the Image Sciences Institute under Josien Pluim as the origin, and the commit distribution corroborates it (Staring 1,511, Klein 640). The method paper is Klein et al., IEEE TMI 29(1):196–205, 2010 (10.1109/TMI.2009.2035616).

Currency is in the frontmatter and is unusually good for anything evaluated here: 203 commits in the trailing year, a release five months old, 48 contributors with no single point of failure. Compare VALIS, dormant for 13 months and effectively single-author. That difference does not by itself make elastix the better choice — VALIS does the WSI job and elastix does not — but it is the relevant contrast if anything is ever built on top of one of them.

Python access is via itk-elastix (ITKElastix) on PyPI or SimpleElastix; there is an official Docker image, and napari and 3D Slicer plugins exist. None of those was installed or run here, so nothing on this page is a claim about behaviour observed at runtime. [unverified]

Current state / open questions

  • The concrete experiment this makes possible, and it is small. Register two serial slides with whatever tool (VALIS or DFBRegister), export a handful of hand-placed fiducial points from QuPath as GeoJSON, convert to elastix point format, and warp them with transformix -def. The distance between warped and true positions is a real TRE on points no optimiser saw. That is the measurement Cross-Stain Registration has been unable to specify, and it needs two slides and no new data. Unresolved: elastix’s transform-parameter format is its own, so this route works directly only if elastix did the fitting — using it to score a VALIS transform would need the transform converted or the points warped by VALIS’s own warp_xy instead. Which of those is less work is not established here. [unverified]
  • Is a scalar projection of an H&E and an IHC slide a sound input for mutual information? MI is the standard answer for multi-modal registration and cross-stain is arguably that problem, but the reduction from RGB to one float channel is a modelling decision this wiki has never made, and it interacts with Stain Normalisation. Untested. [unverified]
  • Nothing here needs registration today — Cross-Stain Registration says so, and reading this does not change it. This page moves the measurability question, not the priority.
  • Recorded and not investigated, per AGENTS.md §8: Apache-2.0 throughout, consistent between LICENSE, NOTICE and the GitHub API.

How it connects

Cross-Stain Registration — the method page this reading changes. Its standing open question was that no acceptance threshold exists because the only available number is a training residual; transformix -def is the mechanism that produces an independent one, and that page now says so.

VALIS — the complement, not the competitor. VALIS reads slides, orders a series and warps annotations; elastix reads neither slides nor series and offers the deformation model, the regularisation and the validation that VALIS does not. Checked directly that VALIS does not already depend on it.

QuPath Tooling — the hub whose registration entry now has to distinguish estimating a transform from validating one, because until this reading everything in it did only the first.

QuPath Annotation Workflow — the same point-warping machinery that would carry an annotation between stains is what scores the registration; a fiducial and an annotation vertex are the same kind of object, which is why one export format serves both.

HER2 Intratumoral Heterogeneity — the only project here with a serial IHC/ISH series, so the first place a measured registration error would actually be needed rather than interesting.

WSI Quality Control — the Jacobian-determinant check is the same species of idea: a computable signal that something is wrong, available without ground truth, which is what that page argues QC should consist of.

Derived from: repository cloned at full depth 2026-08-10 (318e10ee, 4,359 commits, newest tag 5.3.1) into a scratch directory, never into a local_path; README.md, LICENSE, NOTICE, CMakeLists.txt, Core/Install/CMakeLists.txt, Core/Install/elxSupportedImageTypes.h.in, Core/Main/transformix.cxx, Core/ComponentBaseClasses/elxTransformBase.hxx, and directory inventories of Components/Metrics, Components/Transforms, Components/Optimizers and the remaining component families. Currency, stars, forks and open-issue counts from gh api repos/SuperElastix/elastix on 2026-08-10; commit and contributor figures computed from the clone’s own history. The -def point-transformation claim was verified twice by independent routes — the command-line help text in transformix.cxx, then the implementation in elxTransformBase.hxx, which reads points as image indices or world coordinates, transforms them, and writes the per-point deformation vector — because that claim is what changes a recommendation elsewhere. VALIS’s non-dependence on elastix was checked against its published pyproject.toml, not inferred.

Reuse

Apache-2.0 (LICENSE, NOTICE and the GitHub API agree)