Fix ITK displacement field metadata for EasyReg and SynthMorph

[Mojackhak]

Summary

Fix ITK displacement-field metadata written during EasyReg and SynthMorph FreeSurfer-to-ITK h5 conversion.

This adds a shared helper for deriving ITK fixed parameters from the actual NIfTI displacement-field grid, and uses it in both EasyReg and SynthMorph conversion paths. EasyReg also keeps the load_untouch_nii handling needed for affected oblique fields.

Background

EasyReg and SynthMorph produce FreeSurfer-style displacement fields that Lead-DBS converts to ITK/Slicer-compatible .h5 transforms. During this conversion, the h5 TransformFixedParameters must describe the physical grid on which the displacement vectors live: image size, origin, spacing, and direction matrix.

The previous implementation built these fixed parameters inline in both EasyReg and SynthMorph. The direction part was assembled from NIfTI affine rows and voxel sizes.

Problem

The old direction-matrix construction is correct for simple cases such as isotropic grids or axis-aligned grids, but can be wrong when the displacement field reference grid is both anisotropic and oblique.

Lead-DBS usually reduces this risk by reslicing the pre-op anchor to an isotropic 0.7^3 mm grid, but this is not guaranteed. Two relevant cases are:

• If preprocessing first runs with pre-op images only, ea_autocoord skips the anchor reslice step. If post-op CT is added later, the existing preprocessed anchor can remain on its native anisotropic oblique grid.
• ea_resliceanat only resamples when at least one voxel dimension is larger than 0.7 mm. High-resolution anisotropic anchors, for example 0.5 x 0.5 x 0.6 mm, are therefore not resampled to 0.7^3 mm.

For anisotropic oblique grids, normalizing affine rows by one spacing component per row does not produce the ITK direction matrix. The direction should be derived from voxel-axis columns, normalized by the corresponding spacing, and converted from RAS to LPS. If the wrong direction is written into the h5 transform, ITK/Slicer/ANTs can interpret the displacement field on the wrong physical grid, causing mm-scale mismatch between normalized anatomy, CT artifacts, and reconstructed electrode coordinates.

In EasyReg, affected fields may also fail earlier because load_nii rejects non-orthogonal or sheared NIfTI affines. These displacement-field files should be read without applying affine reorientation, while preserving standard NIfTI scl_slope/scl_inter scaling before displacement values are used.

Changes

• Add ea_field_ref2itk(reference_image) to construct the 18-value ITK displacement-field fixed-parameter vector from a NIfTI grid:
  • image size
  • LPS origin
  • voxel spacing
  • row-major ITK/SimpleITK direction matrix
• Replace duplicated inline TransformFixedParameters construction in:
  • EasyReg
  • SynthMorph
• In EasyReg, use load_untouch_nii for FreeSurfer displacement fields and preserve standard NIfTI scl_slope/scl_inter scaling before computing field - voxel_mm.

Validation

Local validation performed before opening this draft:

• MATLAB self-test with synthetic isotropic and oblique anisotropic NIfTI grids:
  • isotropic grids match the old behavior
  • anisotropic oblique grids differ from the old row/spacing bug
  • direction rows are unit-length and orthonormal
  • direction serialization follows ITK/SimpleITK row-major matrix convention
• EasyReg was tested on an anisotropic coregistered T1 in a temporary workspace and passed manual review.