Applying ANTs transforms to tractograms#
trxrs transform warps streamline vertex coordinates through an ITK Composite .h5 (with embedded warp + affines), an Insight Transform File V1.0 (.txt, affine-only), or an ITK MATLAB v4 binary (.mat, affine-only — what ANTs writes for *0GenericAffine.mat).
The “opposite-named h5” rule (cartoon BIDS)#
Tractograms warp in the opposite spatial direction from images. Concretely, with paired BIDS h5 files for subject sub-01:
You have |
You want |
Pass to |
|---|---|---|
|
tracts in |
|
|
tracts in |
|
|
tracts in |
|
If you are coming from antsApplyTransforms for images: pass the same h5 you would use to warp an image of the destination space into the source space. (That’s the same convention as antsApplyTransformsToPoints.)
Why opposite-named?#
Image warping with antsApplyTransforms is pull-based: the chain inside from-X_to-Y_xfm.h5 (the file that warps an X-image onto a Y-grid, per BIDS) internally maps target Y voxels back to source X coordinates. Applied to a point, that same chain sends a Y-point to an X-point. So to warp a streamline FROM space A TO space B, you need a chain that maps A → B — which lives in the opposite-named file from-B_to-A_xfm.h5.
Library usage#
use trx_rs::{TrxFile, apply_transform};
let mut trx = TrxFile::<f32>::load("tractogram.trx")?;
let transform = load_transform_from_file("warp.h5")?;
apply_transform_in_place(&mut trx, &transform)?;
CLI usage#
trxrs transform \
sub-01_space-ACPC_tracts.trx \
sub-01_space-MNI152NLin2009cAsym_tracts.trx \
--transform sub-01_from-MNI152NLin2009cAsym_to-ACPC_xfm.h5 \
--reference sub-01_space-MNI152NLin2009cAsym_T1w.nii.gz
The --reference flag is optional — if given, the output TRX header’s voxel_to_rasmm and dimensions are taken from it. The streamline coordinates themselves are warped regardless.
Affine-only chains#
For an affine-only .txt or .mat, --invert numerically flips the chain so you can use a single file in either direction. Warps cannot be numerically inverted; for those, use the paired from-Y_to-X_xfm.h5 instead.