🔧 Loaders and util for H5 and NIfTI transforms (propagation of contributions by @sgiavasis)

[jmarabotto]

(Propagation of @sgiavasis 's PR to @jmarabotto 's fork. Original PR message copied below)

Started at the NiPreps hackathon at MIT in May 2024. Thanks again to @jmarabotto and @oesteban + @effigies for catching me up to speed and helping orient me on the nitransforms latest.

✅ This PR:

Adds loaders for .h5 and NIfTI (.nii or .nii.gz) transform files. Adds a function for .x5 reading which only calls the H5 loader for now; set to be expanded as needed. Adds an xfm_util level to the CLI which will read in a transform file and internally represent it as an instance of the TransformBase class, forming the X5 structure. For now, this simply prints out some information, which can be used to verify the transform was read in properly. Moves all I/O and I/O-related package/API calls to nitransforms/io/base.py Starts the process of keeping the internal logic of the X5 transform structures and functions clean so that it can be unit tested without any actual transform files. ⚠️ Needs attention:

Functions exist to write out the X5 structure/transform information to either HDF5 and X5 files, but these need to be updated and completed. More cleanup of dependencies on the lower-level details from the higher-level logic. ❓ Questions:

I don't think the internal structure of the X5 hierarchy is complete or accurate. I started with @jmarabotto 's great flowchart as a guide, but I know this might have been in flux. In keeping with the flat namespace of the HDF5/X5 structure, the key levels remain flat (i.e. TransformGroup/0/Transform but I'm not sure if some of the final levels, like /Transform, should be a new sub-level/sub-dictionary or if they should directly contain the NumPy array defining the actual transform, etc. ▶️ Next steps (that I have in mind but I defer to the nitransforms contributors):

Completion of the write-out functions. Some validation showing that converting any transform to an .x5 transform and applying it produces the exact same result as using the original (ex. ANTs, FSL etc.) transform with its appropriate application tool.

EDIT (OE, 08/02/2024) Just to keep these around:

• BEP014
• X5 Draft