Transform files: do they represent affine mappings?

[oesteban]

Clarify how the transform files may be applied and upload the necessary items.

If they are affine transformations, then, a "neat" possibility is to write them in the s-form header of the NIfTI volumes (and set the s-from code to 4 "mni"). That will allow viewers to plot it correctly on top of the corresponding MNI template.

[jdiedrichsen]

I assume you are referring to the _xfm.nii that I included?
These are the Non-linear deformation between atlas spaces, saved as a 5d nifti. 4th dimension is a singleton, 5ths dimension is the coordinate (x,y,z)

For example,
tpl-SUIT_from-MNI152NLin6AsymC_mode-image_xfm.nii
Is an image in SUIT space (with the same affine transformation matrix as the SUIT template), indicating the (x,y,z) location (in mm) in MNI152NLin6Asym space that would correspond. So it is affine + nonlinear transformation combined - thus cannot be simply summarized as an s-form or q-form of the transformation matrix.

I find this way of storing non-linear deformations very handy (and John Ashburners spmdef_ routines are using this format). In SPM these are saved as y* or iy*. For Matlab, we have a version of John's routines so they can be called independently of the batch system:
https://github.com/DiedrichsenLab/spmdefs
In python, these deformations can be applied to an image via a function in our nitools repro:
volume.deform_image(source, deform, interpolation)

I had trouble finding reliable documentation on the _xfm.h5 file format used in templateflow, so I used this more (I think) intuitive and robust way of representing arbitrary non-linear deformations.

In the long run, I'd be happy to decide:

• To translate these into _xfm.h5 files formats if you can point me to a good documentation source
• To provide the deformation as the xfm.nii files and write the appropriate documentation for this.

Let me know which way you want to go for templateflow.... I personally think the deformation images are a very simple, intuitive and robust way of representing non-linear deformations.

Joern

[oesteban]

Is an image in SUIT space (with the same affine transformation matrix as the SUIT template), indicating the (x,y,z) location (in mm) in MNI152NLin6Asym space that would correspond. So it is affine + nonlinear transformation combined - thus cannot be simply summarized as an s-form or q-form of the transformation matrix.

Then, it should be possible to decompose this into the affine and the nonlinear deformation field (and for clarity, this is not a displacement field but a deformation field). I would either encode this in a single h5 file (encapsulating separately the affine and the deformation field) or encode the affine in the s-form field and the deformation as a NIfTI file.

The latter option is perhaps the most appropriate from a theoretical point of view (the s-form is there for exactly this purpose and would allow visualization software to overlay the SUIT template on MNI without resamplings), but at the same time, it is less compatible with the current pipeline development practices. It also has the inconvenience that the s-form goes "from voxel indices to MNI", so we need to modify your affine and prepend the image's affine.

Maybe having more feedback would be useful here - wdyt @effigies, @mgxd, @tsalo?

[jdiedrichsen]

Yes - I could easily decompose the deformation field into an affine part and a displacement field and encode it into an h5 file.
I just could not find a clear documentation on the xfm_h5 files.

Reading a typical _xfm.h5 file (tpl-MNI152NLin6Asym_from-MNI152NLin2009cAsym_mode-image_xfm.h5), I have :

with h5py.File(filename, 'r') as f:
        P1 = np.array(f['TransformGroup']['1']['TranformParameters'])
        P1f = np.array(f['TransformGroup']['1']['TranformFixedParameters'])
        P2 = np.array(f['TransformGroup']['2']['TranformParameters'])
        P2f = np.array(f['TransformGroup']['2']['TranformFixedParameters'])

P1: Looks like a 4x3 Affine transformation matrix between the two spaces. Which direction?
P1f: This is a 3x1 vector. Not sure what this is.
P2: Looks very much like a displacement field in the source (MNI152NLin2009cAsym) space.
P2f: A 18x1 vector which seems like a somewhat awkward encoded Affine transform matrix of the source image?

array([193., 229., 193.,  96., 132., -78.,   1.,   1.,   1.,  -1.,   0.,
         0.,   0.,  -1.,   0.,   0.,   0.,   1.])

Here is my guess:

Source image dimensions  = P2f[:3].astype(int)
Translation  = P2f[3:6]
scale = P2f[6:9] # But why if we have the full 3x3 matrix? Is the rotation contraint to be rigid?  
rotation = P2f[9:18].reshape(3,3)

But all these are just guesses on my part....
Let me know if you know a place of clear documentation, or an example of applying a deformation....