Evidence · ANTs and ITK
ITK transform files
ANTs and fMRIPrep keep their transforms in ITK’s files: text, MATLAB and HDF5 (.h5), fMRIPrep’s composite .h5 files among them. LARMORX’s port is a replica of ITK 5.4.5’s reading and writing of these files and of the parts of the HDF5 format they use, in pure Rust, with no HDF5 library. Of its record’s 149 cases, 128 agree: the replica reads a file’s datasets as h5py reads them and its transforms as ITK reads them, bit for bit, or writes ITK’s file byte for byte given ITK’s compressed chunks and object times. ITK and the replica refuse 16 files alike; 5 cases are expected divergences. On fMRIPrep’s own composite every dataset reads as the HDF5 library and ITK read it, and ITK reads back the file the replica writes.
- Ports
- replica
larmorxApache-2.0: translated from ITK 5.4.5's transform reading and writing (Apache-2.0) and from the parts of the HDF5 file format they use, as HDF5 1.12.1 (the version ITK bundles, under The HDF Group's BSD-style licence) reads and lays them out; crateslarmorx-hdf5andlarmorx-io
- replica
- Status
- replica validated (marked before the statuses' definition)
- Records
- standard comparison (ITK 5.4.5 on HDF5 1.12.1, h5py, nitransforms) · findings itk-hdf5
- Reference
- API page transforms-hdf5
What is compared
ANTs and fMRIPrep store transforms in ITK’s formats: affine matrices as text or MATLAB files, displacement fields as NIfTI vector images, and chains of them as HDF5 composites (fMRIPrep’s *_xfm.h5). The replica reads and writes them without the HDF5 C library, so they work on every platform the wheels support.
import larmorx as lx
parts = lx.transforms.read("sub-01_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5")
# ITK's class names and parameters:
[(t.name, t.parameters.shape) for t in parts]
lx.transforms.write("copy.h5", parts)On the command line, every ANTs program takes these files, for example larmorx ants antsApplyTransforms ... -t xfm.h5. How to read what follows: how to read the evidence.
Its port
ITK comes under the Apache-2.0 licence, as LARMORX does, and HDF5 under a permissive BSD-style one, so the replica is in larmorx itself. It is translated from ITK’s transform reading and writing and follows HDF5 1.12.1 step by step, so that it reads every dataset as HDF5 does and writes ITK’s file byte for byte given ITK’s compressed chunks and object times (its own compressed chunks are compared by content). A clean room of ANTs’ and ITK’s code is planned after FreeSurfer (roadmap).
The verdicts at a glance
Select a segment to list its cases below.
The files the replica reads are compared with what h5py reads (every dataset, bit for bit), with what ITK reads (ANTs writes back what it read, in double and in single precision) and with nitransforms’ chain. The files it writes are compared with ITK’s own files, byte for byte given ITK’s compressed chunks and object times, and read back by ITK, h5py and nitransforms. The files ITK refuses are refused alike. The expected divergences are files ITK reads through undefined behaviour or from other files, which the replica refuses, and a composite of 38 transforms laid out differently.
A real file, object by object
fMRIPrep 25.2.6’s T1w-to-MNI152NLin2009cAsym composite of OpenNeuro ds000005 sub-01 (PDDL-1.0): the affine of its template registration and the SyN displacement field, 25.6 million values on the 1 mm template grid. Each table is one of the comparisons the record makes for every file.
Every group and dataset of the file, as the replica reads it, against h5py on the HDF5 C library
| Object | Type | Shape | Values (the replica's reading) | SHA-256 of the values | h5py ↔ replica |
|---|---|---|---|---|---|
HDFVersion | string | 1 | “HDF5 library version: 1.14.6” | 2eaa8f202160 | Bit-identical |
ITKVersion | string | 1 | “5.4.4” | 8afaee56f3f3 | Bit-identical |
OSName | string | 1 | “Linux” | 4828e60247c1 | Bit-identical |
OSVersion | string | 1 | “6.8.0-124-generic” | 8b5d04e6519a | Bit-identical |
TransformGroup | group | – | Bit-identical | ||
TransformGroup/0 | group | – | Bit-identical | ||
TransformGroup/0/TransformType | string | 1 | “CompositeTransform_float_3_3” | c654182c8d6e | Bit-identical |
TransformGroup/1 | group | – | Bit-identical | ||
TransformGroup/1/TransformFixedParameters | float, 8 bytes | 3 | 0.235927805, 21.999485, 9.74520111 | 9c41ef3da47c | Bit-identical |
TransformGroup/1/TransformParameters | float, 4 bytes | 12 | 0.950066507, 0.00142755918, 0.00215913029, … (12 values) | 35283160b8ca | Bit-identical |
TransformGroup/1/TransformType | string | 1 | “AffineTransform_float_3_3” | 3b0834b44765 | Bit-identical |
TransformGroup/2 | group | – | Bit-identical | ||
TransformGroup/2/TransformFixedParameters | float, 8 bytes | 18 | 193, 229, 193, … (18 values) | b7024eeef84f | Bit-identical |
TransformGroup/2/TransformParameters | float, 4 bytes | 25590063 | 0, 0, 0, … (25,590,063 values) | 6e541248c3a7 | Bit-identical |
TransformGroup/2/TransformType | string | 1 | “DisplacementFieldTransform_float_3_3” | 86573557f210 | Bit-identical |
Floating-point values compared as numbers (each value bit for bit, read through HDF5’s conversion to double), strings byte for byte. The file has no attributes; neither reader finds any. The SHA-256 (first 12 hex digits) is of the values as float64 or of the strings’ bytes, for a reader to check.
The transforms as ITK reads them, against the replica’s reading
| As ITK reads the file | parameters | fixed parameters | parameters that differ | ITK ↔ replica |
|---|---|---|---|---|
| double: transform 1AffineTransform_double_3_3 | 12 | 3 | 0 | Bit-identicalevery parameter and fixed parameter, bit for bit |
| double: transform 2DisplacementFieldTransform_double_3_3 | 25,590,063 | 18 | 0 | Bit-identicalevery parameter and fixed parameter, bit for bit |
| float: transform 1AffineTransform_float_3_3 | 12 | 3 | 0 | Bit-identicalevery parameter and fixed parameter, bit for bit |
| float: transform 2DisplacementFieldTransform_float_3_3 | 25,590,063 | 18 | 0 | Bit-identicalevery parameter and fixed parameter, bit for bit |
ITK 5.4.5 (ANTs 2.6.5’s antsApplyTransforms) reads the composite and writes back what it read (-o CompositeTransform[...]), in double and with --float 1, where ITK converts the stored floats to its precision and renames the transforms; the replica reads the file in the same precision. The composite’s own entry (CompositeTransform) is a container without parameters.
The file the replica writes, read back by ITK, and its bytes against ITK’s own file
| What | What was compared | Result |
|---|---|---|
| ITK reads the replica’s file | 2 transforms, as ITK reads fMRIPrep’s file | Bit-identicalevery parameter, bit for bit |
| antsApplyTransforms through the replica’s file | fMRIPrep’s T1w on the 2 mm MNI grid, linear: 1,082,035 voxels | Bit-identicalthe same output image as through fMRIPrep’s file |
| The replica writes ITK’s own file again | ITK’s file: 105,141,337 bytes; given ITK’s compressed chunks and object times, the replica’s file is | Bit-identicalthe same bytes |
| … with the replica’s own deflate | 104,598,162 bytes differ: zlib-rs (the replica) and zlib-ng 2.1.6 (ITK’s HDF5) choose other matches, so the compressed chunks, their sizes and the addresses after them differ; the content does not | Bit-identicalthe same datasets (the comparison by content, decided 2026-10-16) |
The replica writes the transforms it read from fMRIPrep’s file (lx.transforms.write). ITK’s own file is the one antsApplyTransforms wrote above; itk_h5_replay rewrites it with the replica’s writer, ITK’s strings and times and, first, ITK’s compressed chunks.
Every case
Each case of the record, with what it tests, its verdict and the reason. Search, filter by category or verdict (or select a segment of the chart above), sort by a column; #case=<name> links to one.
149 cases
| Case | Category | What it tests | Verdict | Checks |
|---|---|---|---|---|
errors/h5py/2d-fixed | files refused | written by h5py, refused by ITK: 2d-fixed | Rejected by both Description: ITK ERROR: HDF5TransformIOTemplate(0x0): Wrong # of dims for TransformType in HDF5 File | 5/5 |
errors/h5py/2d-parameters | files refused | written by h5py, refused by ITK: 2d-parameters | Rejected by both Description: ITK ERROR: HDF5TransformIOTemplate(0x0): Wrong # of dims for TransformType in HDF5 File | 5/5 |
errors/h5py/external-link | files refused | written by h5py, read by ITK, refused by the replica: a transform behind an external link to another HDF5 file | Expected divergence a transform behind an external link to another HDF5 file: ITK’s HDF5 follows it; the replica refuses the file | 5/5 |
errors/h5py/external-storage | files refused | written by h5py, read by ITK, refused by the replica: parameters in an external raw file (H5Pset_external) | Expected divergence parameters in an external raw file (H5Pset_external): ITK’s HDF5 follows it; the replica refuses the file | 5/5 |
errors/h5py/fixed-string | files refused | written by h5py, refused by ITK: fixed-string | Rejected by both Description: ITK ERROR: HDF5TransformIOTemplate(0x0): H5Dread failed for variable length string | 5/5 |
errors/h5py/gap-in-names | files refused | written by h5py, refused by ITK: gap-in-names | Rejected by both Description: ITK ERROR: HDF5TransformIOTemplate(0x0): H5Gopen2 failed | 5/5 |
errors/h5py/int-fixed | files refused | written by h5py, refused by ITK: int-fixed | Rejected by both Description: ITK ERROR: HDF5TransformIOTemplate(0x0): Wrong data type for /TransformGroup/1/TransformFixedParametersin HDF5 File | 5/5 |
errors/h5py/int-parameters | files refused | written by h5py, refused by ITK: int-parameters | Rejected by both Description: ITK ERROR: HDF5TransformIOTemplate(0x0): Wrong data type for /TransformGroup/1/TransformParametersin HDF5 File | 5/5 |
errors/h5py/lzf | files refused | written by h5py, refused by ITK: lzf | Rejected by both Description: ITK ERROR: HDF5TransformIOTemplate(0x0): H5Dread failed | 5/5 |
errors/h5py/missing-parameters | files refused | written by h5py, refused by ITK: missing-parameters | Rejected by both Description: ITK ERROR: HDF5TransformIOTemplate(0x0): H5Dopen2 failed | 5/5 |
errors/h5py/mixed-dimension | files refused | written by h5py, refused by ITK: mixed-dimension | Expected divergence ITK-17: ITK casts the 2-D component to a 3-D transform (undefined behaviour) and antsApplyTransforms exits 0; the replica refuses the file | 3/3 |
errors/h5py/no-precision-in-name | files refused | written by h5py, refused by ITK: no-precision-in-name | Rejected by both basic_string::replace: __pos (which is 18446744073709551615) > this->size() (which is 15) | 5/5 |
errors/h5py/no-transform-group | files refused | written by h5py, refused by ITK: no-transform-group | Rejected by both failed to read file: /tmp/lx-h5-sdd15ydg/no-transform-group.h5 | 5/5 |
errors/h5py/not-hdf5 | files refused | written by h5py, refused by ITK: not-hdf5 | Rejected by both set the suffix to an unsupported type. | 5/5 |
errors/h5py/scalar-parameters | files refused | written by h5py, refused by ITK: scalar-parameters | Rejected by both Description: ITK ERROR: HDF5TransformIOTemplate(0x0): Wrong # of dims for TransformType in HDF5 File | 5/5 |
errors/h5py/superblock3-chunked | files refused | written by h5py, refused by ITK: superblock3-chunked | Rejected by both Description: ITK ERROR: HDF5TransformIOTemplate(0x0): H5Dopen2 failed | 5/5 |
errors/h5py/truncated | files refused | written by h5py, refused by ITK: truncated | Rejected by both set the suffix to an unsupported type. | 5/5 |
errors/h5py/two-strings | files refused | written by h5py, refused by ITK: two-strings | Rejected by both Description: ITK ERROR: HDF5TransformIOTemplate(0x0): H5Dread failed for variable length string | 5/5 |
errors/h5py/unknown-type | files refused | written by h5py, refused by ITK: unknown-type | Rejected by both “VersorTransform_float_3_3” | 5/5 |
errors/h5py/virtual | files refused | written by h5py, read by ITK, refused by the replica: parameters in a virtual dataset (mapping another dataset of the same file) | Expected divergence parameters in a virtual dataset (mapping another dataset of the same file): ITK’s HDF5 follows it; the replica refuses the file | 5/5 |
hdf5/fixture/sb0 | HDF5's storage features | a golden-test fixture (tests/golden/hdf5/sb0.h5.gz) | Bit-identical every dataset as h5py reads it, bit for bit | 2/2 |
hdf5/fixture/sb1 | HDF5's storage features | a golden-test fixture (tests/golden/hdf5/sb1.h5.gz) | Bit-identical every dataset as h5py reads it, bit for bit | 2/2 |
hdf5/fixture/sb3-datasets | HDF5's storage features | a golden-test fixture (tests/golden/hdf5/sb3-datasets.h5.gz) | Bit-identical every dataset as h5py reads it, bit for bit | 2/2 |
hdf5/fixture/sb3-groups | HDF5's storage features | a golden-test fixture (tests/golden/hdf5/sb3-groups.h5.gz) | Bit-identical every dataset as h5py reads it, bit for bit | 2/2 |
hdf5/fixture/sohm | HDF5's storage features | a golden-test fixture (tests/golden/hdf5/sohm.h5.gz) | Bit-identical every dataset as h5py reads it, bit for bit | 4/4 |
hdf5/group/deflate-direct | HDF5's storage features | an HDF5 storage feature written by h5py: group:deflate-direct | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/group/deflate-fletcher32-direct | HDF5's storage features | an HDF5 storage feature written by h5py: group:deflate-fletcher32-direct | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/group/deflate-fletcher32-huge | HDF5's storage features | an HDF5 storage feature written by h5py: group:deflate-fletcher32-huge | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/group/deflate-fletcher32-indirect | HDF5's storage features | an HDF5 storage feature written by h5py: group:deflate-fletcher32-indirect | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/group/deflate-huge | HDF5's storage features | an HDF5 storage feature written by h5py: group:deflate-huge | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/group/deflate-indirect | HDF5's storage features | an HDF5 storage feature written by h5py: group:deflate-indirect | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/group/order-indirect | HDF5's storage features | an HDF5 storage feature written by h5py: group:order-indirect | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/group/plain-direct | HDF5's storage features | an HDF5 storage feature written by h5py: group:plain-direct | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/group/plain-huge | HDF5's storage features | an HDF5 storage feature written by h5py: group:plain-huge | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/group/plain-indirect | HDF5's storage features | an HDF5 storage feature written by h5py: group:plain-indirect | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/index/bt2 | HDF5's storage features | an HDF5 storage feature written by h5py: index:bt2 | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/index/bt2-filtered | HDF5's storage features | an HDF5 storage feature written by h5py: index:bt2-filtered | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/index/earray-2d-swizzled | HDF5's storage features | an HDF5 storage feature written by h5py: index:earray-2d-swizzled | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/index/earray-3d-swizzled | HDF5's storage features | an HDF5 storage feature written by h5py: index:earray-3d-swizzled | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/index/earray-dblocks | HDF5's storage features | an HDF5 storage feature written by h5py: index:earray-dblocks | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/index/earray-filtered | HDF5's storage features | an HDF5 storage feature written by h5py: index:earray-filtered | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/index/earray-paged | HDF5's storage features | an HDF5 storage feature written by h5py: index:earray-paged | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/index/earray-sblocks | HDF5's storage features | an HDF5 storage feature written by h5py: index:earray-sblocks | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/index/earray-small | HDF5's storage features | an HDF5 storage feature written by h5py: index:earray-small | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/index/farray | HDF5's storage features | an HDF5 storage feature written by h5py: index:farray | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/index/farray-paged | HDF5's storage features | an HDF5 storage feature written by h5py: index:farray-paged | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/index/farray-paged-filtered | HDF5's storage features | an HDF5 storage feature written by h5py: index:farray-paged-filtered | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/index/implicit | HDF5's storage features | an HDF5 storage feature written by h5py: index:implicit | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/index/single | HDF5's storage features | an HDF5 storage feature written by h5py: index:single | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/index/single-filtered | HDF5's storage features | an HDF5 storage feature written by h5py: index:single-filtered | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/nbit/float | HDF5's storage features | an HDF5 storage feature written by h5py: nbit:float | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/nbit/int | HDF5's storage features | an HDF5 storage feature written by h5py: nbit:int | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/nbit/int-be | HDF5's storage features | an HDF5 storage feature written by h5py: nbit:int-be | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/scaleoffset/>f8,3, | HDF5's storage features | an HDF5 storage feature written by h5py: scaleoffset:>f8,3, | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/scaleoffset/f4,0, | HDF5's storage features | an HDF5 storage feature written by h5py: scaleoffset:f4,0, | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/scaleoffset/f4,2, | HDF5's storage features | an HDF5 storage feature written by h5py: scaleoffset:f4,2, | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/scaleoffset/f4,2,-7.5 | HDF5's storage features | an HDF5 storage feature written by h5py: scaleoffset:f4,2,-7.5 | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/scaleoffset/f4,6, | HDF5's storage features | an HDF5 storage feature written by h5py: scaleoffset:f4,6, | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/scaleoffset/f8,0, | HDF5's storage features | an HDF5 storage feature written by h5py: scaleoffset:f8,0, | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/scaleoffset/f8,2, | HDF5's storage features | an HDF5 storage feature written by h5py: scaleoffset:f8,2, | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/scaleoffset/f8,6, | HDF5's storage features | an HDF5 storage feature written by h5py: scaleoffset:f8,6, | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/scaleoffset/i1,0, | HDF5's storage features | an HDF5 storage feature written by h5py: scaleoffset:i1,0, | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/scaleoffset/i2,0, | HDF5's storage features | an HDF5 storage feature written by h5py: scaleoffset:i2,0, | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/scaleoffset/i4,0, | HDF5's storage features | an HDF5 storage feature written by h5py: scaleoffset:i4,0, | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/scaleoffset/i4,0,12345 | HDF5's storage features | an HDF5 storage feature written by h5py: scaleoffset:i4,0,12345 | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/scaleoffset/i8,0, | HDF5's storage features | an HDF5 storage feature written by h5py: scaleoffset:i8,0, | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/scaleoffset/u1,0, | HDF5's storage features | an HDF5 storage feature written by h5py: scaleoffset:u1,0, | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/scaleoffset/u2,0, | HDF5's storage features | an HDF5 storage feature written by h5py: scaleoffset:u2,0, | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/scaleoffset/u4,0, | HDF5's storage features | an HDF5 storage feature written by h5py: scaleoffset:u4,0, | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/scaleoffset/u8,0, | HDF5's storage features | an HDF5 storage feature written by h5py: scaleoffset:u8,0, | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/sohm/btree | HDF5's storage features | an HDF5 storage feature written by h5py: sohm:btree | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/sohm/one-list | HDF5's storage features | an HDF5 storage feature written by h5py: sohm:one-list | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/sohm/superblock2 | HDF5's storage features | an HDF5 storage feature written by h5py: sohm:superblock2 | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
hdf5/sohm/two-lists | HDF5's storage features | an HDF5 storage feature written by h5py: sohm:two-lists | Bit-identical every dataset as h5py reads it, bit for bit | 1/1 |
read/catalog/openneuro-derivatives/ds000005-fmriprep/sub-01/anat/sub-01_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5 | reading: the test data's files | Inverse composite transform MNI152NLin2009cAsym -> T1w (HDF5), used to bring template masks/priors into T1w space. | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/catalog/openneuro-derivatives/ds000005-fmriprep/sub-01/anat/sub-01_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5 | reading: the test data's files | ANTs composite transform (HDF5: affine + SyN displacement field) T1w -> MNI152NLin2009cAsym, as written by antsRegistration: input for reading ITK/ANTs .h5 transforms and for applying normalisation to BOLD. | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/catalog/synthetic/resampling/transforms/composite-affine-warp.h5 | reading: the test data's files | ITK HDF5 composite, as antsApplyTransforms -o CompositeTransform[...] writes it from -t warp-lps-vector.nii.gz -t affine-centered.mat (queue: affine, then field). | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/catalog/synthetic/series-resampling/transforms/anat2std-composite.h5 | reading: the test data's files | Anatomical-to-standard ITK composite in ITK's HDF5 layout: an AffineTransform_double_3_3 (with a centre) then a DisplacementFieldTransform_float_3_3 on a 2 mm grid of 34 × 40 × 30 (smooth displacements up to about 3 mm, LPS), the queue fMRIPrep's *_xfm.h5 files have. | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/fmriprep-25.2.6/ds000005-sub-01-noreconall/sub-01_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5 | reading: fMRIPrep 25.2.6's files | found: sub-01_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5 | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/fmriprep-25.2.6/ds000005-sub-01-noreconall/sub-01_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5 | reading: fMRIPrep 25.2.6's files | found: sub-01_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5 | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/fmriprep-25.2.6/ds001600-sub-1-noreconall/sub-1_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5 | reading: fMRIPrep 25.2.6's files | found: sub-1_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5 | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/fmriprep-25.2.6/ds001600-sub-1-noreconall/sub-1_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5 | reading: fMRIPrep 25.2.6's files | found: sub-1_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5 | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/fmriprep-25.2.6/ds005040-sub-002-noreconall/sub-002_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5 | reading: fMRIPrep 25.2.6's files | found: sub-002_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5 | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/fmriprep-25.2.6/ds005040-sub-002-noreconall/sub-002_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5 | reading: fMRIPrep 25.2.6's files | found: sub-002_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5 | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/fmriprep-25.2.6/ds005454-sub-16-noreconall/sub-16_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5 | reading: fMRIPrep 25.2.6's files | found: sub-16_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5 | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/fmriprep-25.2.6/ds005454-sub-16-noreconall/sub-16_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5 | reading: fMRIPrep 25.2.6's files | found: sub-16_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5 | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/fmriprep-25.2.6/ds005752-sub-ON01016-noreconall/sub-ON01016_ses-01_acq-FSPGR_rec-SCIC_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5 | reading: fMRIPrep 25.2.6's files | found: sub-ON01016_ses-01_acq-FSPGR_rec-SCIC_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5 | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/fmriprep-25.2.6/ds005752-sub-ON01016-noreconall/sub-ON01016_ses-01_acq-FSPGR_rec-SCIC_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5 | reading: fMRIPrep 25.2.6's files | found: sub-ON01016_ses-01_acq-FSPGR_rec-SCIC_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5 | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/big-endian-f4 | reading: files h5py wrote | written by h5py: big-endian-f4 | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/big-endian-f8 | reading: files h5py wrote | written by h5py: big-endian-f8 | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/compact | reading: files h5py wrote | written by h5py: compact | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/composite | reading: files h5py wrote | written by h5py: composite | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/composite-second | reading: files h5py wrote | written by h5py: composite-second | Bit-identical every dataset as h5py reads it, bit for bit | 7/7 |
read/h5py/dense-11 | reading: files h5py wrote | written by h5py: dense-11 | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/dense-11-superblock3 | reading: files h5py wrote | written by h5py: dense-11-superblock3 | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/earray | reading: files h5py wrote | written by h5py: earray | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/empty-composite | reading: files h5py wrote | written by h5py: empty-composite | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/farray | reading: files h5py wrote | written by h5py: farray | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/farray-paged | reading: files h5py wrote | written by h5py: farray-paged | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/float32 | reading: files h5py wrote | written by h5py: float32 | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/half | reading: files h5py wrote | written by h5py: half | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/implicit | reading: files h5py wrote | written by h5py: implicit | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/long-double | reading: files h5py wrote | written by h5py: long-double | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/misspelt-itk4 | reading: files h5py wrote | written by h5py: misspelt-itk4 | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/nbit | reading: files h5py wrote | written by h5py: nbit | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/no-version-strings | reading: files h5py wrote | written by h5py: no-version-strings | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/scalar-type | reading: files h5py wrote | written by h5py: scalar-type | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/scaleoffset | reading: files h5py wrote | written by h5py: scaleoffset | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/shuffle-fletcher32 | reading: files h5py wrote | written by h5py: shuffle-fletcher32 | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/single | reading: files h5py wrote | written by h5py: single | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/single-chunk | reading: files h5py wrote | written by h5py: single-chunk | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/superblock3 | reading: files h5py wrote | written by h5py: superblock3 | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/two-linear | reading: files h5py wrote | written by h5py: two-linear | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/h5py/utf8-strings | reading: files h5py wrote | written by h5py: utf8-strings | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/itk/assemble | reading: files ITK wrote | written by ITK: CompositeTransformUtil --assemble (itk::ants::WriteTransform) | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/itk/assemble-field-first | reading: files ITK wrote | written by ITK: CompositeTransformUtil --assemble: a field, then two linear transforms (objects allocated after the compressed chunk) | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/itk/composite-11-affines | reading: files ITK wrote | written by ITK: -o CompositeTransform[...] of 11 affines: 12 links (dense: a fractal heap and a v2 B-tree) | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/itk/composite-37-affines | reading: files ITK wrote | written by ITK: -o CompositeTransform[...] of 37 affines: 38 links (dense: a fractal heap and a v2 B-tree) | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/itk/composite-38-affines | reading: files ITK wrote | written by ITK: -o CompositeTransform[...] of 38 affines: 39 links (dense: a fractal heap and a v2 B-tree) | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/itk/composite-8-affines | reading: files ITK wrote | written by ITK: -o CompositeTransform[...] of 8 affines: 9 links (dense: a fractal heap and a v2 B-tree) | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/itk/composite-9-affines | reading: files ITK wrote | written by ITK: -o CompositeTransform[...] of 9 affines: 10 links (dense: a fractal heap and a v2 B-tree) | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/itk/composite-affine | reading: files ITK wrote | written by ITK: -o CompositeTransform[...]: one affine | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/itk/composite-float | reading: files ITK wrote | written by ITK: --float 1 -o CompositeTransform[...]: float parameters | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/itk/composite-identity | reading: files ITK wrote | written by ITK: -o CompositeTransform[...] -t identity | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/itk/composite-types | reading: files ITK wrote | written by ITK: -o CompositeTransform[...]: six transform types (seven links, compact) | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/itk/composite-warp-affine | reading: files ITK wrote | written by ITK: -o CompositeTransform[...]: a displacement field and an affine (chunk of 190 KB) | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/itk/displacement-field | reading: files ITK wrote | written by ITK: -o DisplacementField[...]: a collapsed field on the reference grid | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/itk/fmriprep-rewritten | reading: files ITK wrote | written by ITK: fMRIPrep's T1w→MNI composite rewritten by ITK 5.4.5: a field of several 1 Mi-value chunks | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/itk/linear | reading: files ITK wrote | written by ITK: -o Linear[...]: two transforms collapsed into one affine | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/itk/linear-float | reading: files ITK wrote | written by ITK: --float 1 -o Linear[...]: float parameters | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
read/itk/linear-inverse | reading: files ITK wrote | written by ITK: -o Linear[...,1]: the inverse | Bit-identical every dataset as h5py reads it, bit for bit | 5/5 |
write/assemble | writing | CompositeTransformUtil --assemble (itk::ants::WriteTransform) | Bit-identical byte for byte given ITK’s compressed chunks and object times; with the replica’s own deflate: 78899 bytes differ; ITK, h5py and nitransforms read the replica’s file as ITK’s | 7/7 |
write/assemble-field-first | writing | CompositeTransformUtil --assemble: a field, then two linear transforms (objects allocated after the compressed chunk) | Bit-identical byte for byte given ITK’s compressed chunks and object times; with the replica’s own deflate: 79355 bytes differ; ITK, h5py and nitransforms read the replica’s file as ITK’s | 7/7 |
write/composite-11-affines | writing | -o CompositeTransform[...] of 11 affines: 12 links (dense: a fractal heap and a v2 B-tree) | Bit-identical byte for byte given ITK’s compressed chunks and object times; with the replica’s own deflate: identical; ITK, h5py and nitransforms read the replica’s file as ITK’s | 6/6 |
write/composite-37-affines | writing | -o CompositeTransform[...] of 37 affines: 38 links (dense: a fractal heap and a v2 B-tree) | Bit-identical byte for byte given ITK’s compressed chunks and object times; with the replica’s own deflate: identical; ITK, h5py and nitransforms read the replica’s file as ITK’s | 6/6 |
write/composite-38-affines | writing | -o CompositeTransform[...] of 38 affines: 39 links (dense: a fractal heap and a v2 B-tree) | Expected divergence 39 links do not fit the first block of TransformGroup’s fractal heap: HDF5 adds an indirect block, which the replica’s writer does not cover; the replica keeps the links as link messages (a group info storing 39 compact links), a layout HDF5 itself writes for such a … | 6/6 |
write/composite-8-affines | writing | -o CompositeTransform[...] of 8 affines: 9 links (dense: a fractal heap and a v2 B-tree) | Bit-identical byte for byte given ITK’s compressed chunks and object times; with the replica’s own deflate: identical; ITK, h5py and nitransforms read the replica’s file as ITK’s | 6/6 |
write/composite-9-affines | writing | -o CompositeTransform[...] of 9 affines: 10 links (dense: a fractal heap and a v2 B-tree) | Bit-identical byte for byte given ITK’s compressed chunks and object times; with the replica’s own deflate: identical; ITK, h5py and nitransforms read the replica’s file as ITK’s | 6/6 |
write/composite-affine | writing | -o CompositeTransform[...]: one affine | Bit-identical byte for byte given ITK’s compressed chunks and object times; with the replica’s own deflate: identical; ITK, h5py and nitransforms read the replica’s file as ITK’s | 7/7 |
write/composite-float | writing | --float 1 -o CompositeTransform[...]: float parameters | Bit-identical byte for byte given ITK’s compressed chunks and object times; with the replica’s own deflate: identical; ITK, h5py and nitransforms read the replica’s file as ITK’s | 6/6 |
write/composite-identity | writing | -o CompositeTransform[...] -t identity | Bit-identical byte for byte given ITK’s compressed chunks and object times; with the replica’s own deflate: identical; ITK, h5py and nitransforms read the replica’s file as ITK’s | 6/6 |
write/composite-types | writing | -o CompositeTransform[...]: six transform types (seven links, compact) | Bit-identical byte for byte given ITK’s compressed chunks and object times; with the replica’s own deflate: identical; ITK, h5py and nitransforms read the replica’s file as ITK’s | 7/7 |
write/composite-warp-affine | writing | -o CompositeTransform[...]: a displacement field and an affine (chunk of 190 KB) | Bit-identical byte for byte given ITK’s compressed chunks and object times; with the replica’s own deflate: 78899 bytes differ; ITK, h5py and nitransforms read the replica’s file as ITK’s | 7/7 |
write/displacement-field | writing | -o DisplacementField[...]: a collapsed field on the reference grid | Bit-identical byte for byte given ITK’s compressed chunks and object times; with the replica’s own deflate: identical; ITK, h5py and nitransforms read the replica’s file as ITK’s | 6/6 |
write/fmriprep-rewritten | writing | fMRIPrep's T1w→MNI composite rewritten by ITK 5.4.5: a field of several 1 Mi-value chunks | Bit-identical byte for byte given ITK’s compressed chunks and object times; with the replica’s own deflate: 104442002 bytes differ; ITK, h5py and nitransforms read the replica’s file as ITK’s | 6/6 |
write/itk15-identity-compressed | writing | CompositeTransformUtil --assemble with an IdentityTransform: ITK fails (ITK-15) and leaves a partial file | Bit-identical ITK fails (ITK-15) and leaves a partial file; the replica in | 7/7 |
write/linear | writing | -o Linear[...]: two transforms collapsed into one affine | Bit-identical byte for byte given ITK’s compressed chunks and object times; with the replica’s own deflate: identical; ITK, h5py and nitransforms read the replica’s file as ITK’s | 6/6 |
write/linear-float | writing | --float 1 -o Linear[...]: float parameters | Bit-identical byte for byte given ITK’s compressed chunks and object times; with the replica’s own deflate: identical; ITK, h5py and nitransforms read the replica’s file as ITK’s | 6/6 |
write/linear-inverse | writing | -o Linear[...,1]: the inverse | Bit-identical byte for byte given ITK’s compressed chunks and object times; with the replica’s own deflate: identical; ITK, h5py and nitransforms read the replica’s file as ITK’s | 6/6 |
Speed
No benchmark report yet: reading HDF5 against h5py and ANTs is among the planned benchmarks (next steps).
Corrections by default
Where ITK, HDF5 or nitransforms has a deterministic defect that changes a result, the replica corrects it by default, fix, and warns. upstream_defects="reproduce" (on the command line --upstream-defects reproduce from the next release, LARMORX_UPSTREAM_DEFECTS=reproduce in 0.1.0rc1) gives their behaviour, and the record compares with it. In reading: a TransformType stored as a fixed-length string, as h5py writes it, is read (ITK-12); a parameter dataset of the wrong class or rank is named in the message (ITK-13); parameters wider than 8 bytes (long double, quadruple) are read in the reader’s precision, not through float (ITK-14); non-native floats are converted element by element, without the state HDF5 1.12 carries from one to the next (HDF-01); a composite’s transforms are read in numeric order, 2 before 10 (PIPE-04), and a file’s first group is read when it is not a composite (PIPE-17). In writing: a transform without parameters has its empty parameters stored uncompressed, where ITK fails and leaves a file it cannot read (ITK-15). ITK-16 (a null TransformType string, which crashes ITK) and ITK-17 are refused either way. The API page has the table and the register every entry. fMRIPrep’s composites meet none of them; PIPE-04 would from eleven transforms on.
Random testing
Random testing writes random transform files and reads them through ITK, as ANTs’ programs do (an ANTs program writes back what it read, in double and in single precision), and through the replica, h5py and nitransforms, in long runs of several hours. The files come from seeded plain arithmetic: text and MATLAB files holding one to four transforms of every linear type ITK reads (in double and float, 2-D and 3-D) and composites, their numbers spelt in many ways, and HDF5 files from the replica’s writer, with and without compression, that also hold displacement fields (how random testing works). A difference is shrunk to the smallest file that still shows it, then fixed and kept as a comparison case, registered as a defect of the original, or reported. The latest long run:
Random testing, the replica against the original: ITK 5.4.5’s transform files, the long run of 2026-10-25 (seed 20261025, 6.2 h for 21 programs): random valid inputs and option combinations, each run through both
| Program | Random cases | Extreme | Options covered | Agree | glibc | Notices | Undefined | Differ | Heavy | Guard | Unclear |
|---|---|---|---|---|---|---|---|---|---|---|---|
| ITK transform filesreplica | 2,260 | 0 | 21 | 2,244 | · | · | · | 16 | · | · | · |
- fixed in LARMORX ITK transform files (replica), 16 case(s):
ITK's float reading (--float N): ANTs cannot write the transforms back; antsApplyTransforms agrees,ITK's reading: ANTs cannot write the transforms back; antsApplyTransforms agrees: QuaternionRigidTransform, ScaleVersor3DTransform, ScaleSkewVersor3DTransform and ScaleTransform: LARMORX read them but its antsApplyTransforms could not evaluate them (exit 1, ANTs 0); now evaluated as ITK computes them (vnl’s rotation matrix of the conjugate quaternion; the versor’s matrix with scale - 1 and the skews added; ScaleTransform’s own (p - c)·s + c) (larmorx_transform::linear)
Every case is drawn from its tool, the run's seed and its number, and replays anywhere: how random testing works; each difference's triage: validation/difftest/triage.toml.
Known limits
The expected divergences: data stored in other files (external raw files, external links, virtual datasets), which ITK’s HDF5 follows, are refused; a 2-D component in a 3-D composite is refused (ITK-17, an undefined cast in ITK); a composite of 38 or more transforms is written with its links laid out compactly. Compressed chunks are compared by content, not bytes, by design.
History
- 2026-10-16: compressed chunks compared by content, not bytes, decided (the written files’ table and the writing cases say so).
- 2026-10-21: the standard comparison made (its Generated line).
Data credits
The data this page shows or names: each dataset with its version, DOI and licence, from LARMORX's test-data catalog. Public-domain dedications (CC0, PDDL) ask nothing; the datasets are cited all the same.
- Mixed-gambles task (OpenNeuro ds000005, version 00001), Open Data Commons Public Domain Dedication and Licence 1.0.
- Example fieldmaps (OpenNeuro ds001600, version 1.0.0), Creative Commons Attribution-ShareAlike (CC BY-SA; the dataset gives no version). Attribution: Cieslak M., Elliott M., Satterthwaite T. Example Fieldmaps. OpenNeuro ds001600, version 1.0.0 (Siemens Prisma, University of Pennsylvania). The images shown are adapted from it: reoriented to RAS, cropped to the region shown, masked outside it, and shown as the outputs of the programs compared. Share-alike: the images adapted from this dataset are shared under the same licence, CC BY-SA.
- Political Moralization (OpenNeuro ds005040, version 1.2.0, doi:10.18112/openneuro.ds005040.v1.2.0), CC0 1.0 public-domain dedication.
- fMRIPrep boot camp 7T training dataset (OpenNeuro ds005454, version 1.0.0, doi:10.18112/openneuro.ds005454.v1.0.0), Creative Commons Attribution 4.0 (CC BY 4.0). Attribution: Sleight EC, Esteban O, Grouiller F. fMRIPrep boot camp -- 7T training dataset. OpenNeuro ds005454, version 1.0.0. doi:10.18112/openneuro.ds005454.v1.0.0 The images shown are adapted from it: reoriented to RAS, cropped to the region shown, masked outside it, and shown as the outputs of the programs compared.
- NIMH Healthy Research Volunteer Dataset (OpenNeuro ds005752, version 2.1.0, doi:10.18112/openneuro.ds005752.v2.1.0), CC0 1.0 public-domain dedication.
- MNI152NLin2009cAsym template (TemplateFlow, version tpl-MNI152NLin2009cAsym git 15d7c02160f79f5218d2545b4febebeecc11531d), the MNI ICBM 152 copyright notice.