[ENH] MRI: Improve definition of bvec file

[Lestropie]

Closes #243.

Making an attempt to resolve this issue as ensuring that the definition here is robust and consistent across different softwares will be essential to verifying the definition of orientation encoding for BEP016 MRI diffusion models.

References:

• FSL documentation
• Implementation changes we made to MRtrix3 on load and save
• Announcement on the MRtrix3 community forum regarding how our prior support for this format was flawed and how it was fixed.

I'm listing this as a draft PR as it's entirely possible that the phrasing can be fine-tuned. Pinging @jdtournier; if anyone knows of an appropriate person from FMRIB to ping please do so.

One note here is that I've intentionally avoided the use of "radiological" vs. "neurological" coordinate systems. I've always thought of these as being in reference to two-dimensional projections of image data. There seems to be some confusion about which of these terms apply in reference to three-dimensional coordinate systems. Therefore I chose to stick to "left-handed vs. right-handed" / "positive vs. negative determinant". Not strictly against use of such terms, but the ambiguity would need to be resolved.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 88.22%. Comparing base (0de4c9c) to head (63c82e9).
Report is 44 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1811   +/-   ##
=======================================
  Coverage   88.22%   88.22%           
=======================================
  Files          16       16           
  Lines        1393     1393           
=======================================
  Hits         1229     1229           
  Misses        164      164           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[jdtournier]

Looks good to me. I might suggest a very minor rewording, but it might be more a matter of personal preference than clarity...

This sentence:

Further, if the rotation component of the NIfTI image header transformation possesses a positive determinant (a "right-handed" coordinate system), then the sign of the first element of each 3-vector must be inverted to be interpreted as cosines with respect to the first image axis orientation.

Modify to:

Moreover, if the image axes defined in the corresponding NIfTI image header form a right-handed coordinate system (in other words, the 3×3 matrix of direction cosines has a positive determinant), then the sign of the first element of each 3 vector must be inverted before any further interpretation.

In fact, I'd be tempted to mention this particular aspect before describing the interpretation as relative to the image axes, to ensure that there is no confusion about when the sign flip takes place: it applies to the original entry in the bvec table, not the x-component following transformation into scanner space or something.

I would also have a more upfront statement about the fact that bvecs are relative to some reference image, maybe in the second sentence, with something like:

In this format, the gradient directions are specified relative to a reference image, which must also be provided in order to correctly interpret the information.

As it stands, the fact that the reference image must be supplied is implicit from the later discussion, but in my opinion it's a really important consideration that deserves to be stated very upfront.

[jdtournier]

if anyone knows of an appropriate person from FMRIB to ping please do so

Maybe Mark Jenkinson, @markj789?

[Lestropie]

Had a go at some minor tweaks. The directions being defined with respect to the image axes is stated explicitly twice, and the ordering of statements about flipping of first element / contrast against DICOM convention is hopefully better.

[Lestropie]

Marked as ready for review.

[tsalo]

@mattcieslak and I discussed this and it looks good to us.

[effigies]

Thanks @Lestropie for the PR, and thanks all for the reviews!