MRtrix3 provides a set of tools to perform various advanced diffusion MRI analyses, including constrained spherical deconvolution (CSD), probabilistic tractography, track-density imaging, and apparent fibre density
This one has taken a lot more of my time than I would have liked. But it needed to be properly resolved, not just to fix issues for those disabling internal transform realignment but also because downstream work on BIDS BEP016 Diffusion models is dependent on these format definitions and conversion operations being robust.
The core mistake here was:
There exists a function to indicate, when a saved image is NIfTI, what the axis permutations / flips and eventual transform will be.
This was being erroneously used to indicate what transformations had been performed on load of an image.
I've done a bunch of refactoring to store internally more exhaustive information about what (if anything) was performed at the internal header transform realignment phase. In addition to trivialising transformations between on-disk image header and scanner-space, this will also facilitate tracking exactly what differs between on-disk and interpreted versions of an image; not just transform & strides but potentially also metadata that are defined with respect to image axes.
According to my battery of tests, this all yields the correct results:
For all possible combinations of acquisition slice and phase encoding
For inputs of any format
(DICOM, NIfTI / JSON / bvec / bval, MRtrix w. external metadata / MRtrix w. header metadata)
From mrconvert or dcm2niix
With & without transform realignment in the former case
For outputs of any format
(NIfTI / JSON / bvec / bval, MRtrix w. external metadata / MRtrix w. header metadata)
With & without transform realignment
For any output strides
Questions:
Move core/axes.*?
From memory these used to be much larger; what's left there now is almost exclusively about transform realignment of spatial axes, which isn't really captured by the file name / namespace.
Move much of dwi/gradient.* into core/metadata/?
It made sense for me to move phase_encoding.* out of core/ given I needed something similar for slice encoding and those are naturally grouped. But a gradient table is also "metadata that can be stored in an image header or external file(s) that necessitates advanced handling".
[ ] Back-port to master.
Ultimately these are bug fixes, so should ideally be in 3.0.5.
But maybe I'll try to restrict the scope of it by just making requisite changes and preserving a bit of code duplication that the refactoring removed / was done to hopefully facilitate #2477.
[ ] transformconvert flirt_import:
[x] Use on-disk transform rather than File::NIfTI::axes_on_write()
[ ] Test
[ ] meshconvert -transform fs2real:
[x] Use on-disk transform rather than File::NIfTI::axes_on_write()
[ ] Test
[ ] Check handling of user-specified phase encoding information
Particularly for dwifslpreproc -pe_dir, there needs to be greater care around interpretation depending on whether the user's configuration does or does not include internal transform realignment
[ ] Fix diffusion scheme docs page description of bvec format
Appears to currently omit the left-handed vs. right-handed distinction, and also uses "x, y, z" to refer to image axes.
Closes #2477.
Work toward #2526.
This one has taken a lot more of my time than I would have liked. But it needed to be properly resolved, not just to fix issues for those disabling internal transform realignment but also because downstream work on BIDS BEP016 Diffusion models is dependent on these format definitions and conversion operations being robust.
The core mistake here was:
I've done a bunch of refactoring to store internally more exhaustive information about what (if anything) was performed at the internal header transform realignment phase. In addition to trivialising transformations between on-disk image header and scanner-space, this will also facilitate tracking exactly what differs between on-disk and interpreted versions of an image; not just transform & strides but potentially also metadata that are defined with respect to image axes.
According to my battery of tests, this all yields the correct results:
mrconvertordcm2niixQuestions:
Move
core/axes.*? From memory these used to be much larger; what's left there now is almost exclusively about transform realignment of spatial axes, which isn't really captured by the file name / namespace.Move much of
dwi/gradient.*intocore/metadata/? It made sense for me to movephase_encoding.*out ofcore/given I needed something similar for slice encoding and those are naturally grouped. But a gradient table is also "metadata that can be stored in an image header or external file(s) that necessitates advanced handling".[ ] Back-port to
master. Ultimately these are bug fixes, so should ideally be in3.0.5. But maybe I'll try to restrict the scope of it by just making requisite changes and preserving a bit of code duplication that the refactoring removed / was done to hopefully facilitate #2477.[ ]
transformconvert flirt_import:File::NIfTI::axes_on_write()[ ]
meshconvert -transform fs2real:File::NIfTI::axes_on_write()[ ] Check handling of user-specified phase encoding information Particularly for
dwifslpreproc -pe_dir, there needs to be greater care around interpretation depending on whether the user's configuration does or does not include internal transform realignment[ ] Fix diffusion scheme docs page description of
bvecformat Appears to currently omit the left-handed vs. right-handed distinction, and also uses "x, y, z" to refer to image axes.