MRI: Improve definition of bvec file (#1811)

* MRI: Improve definition of bvec file

* MRI: bvec file: Tweaks to description

* Schema: Update .bvec extension to match specification

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Glossary: Fix compilation for #1811

Co-authored-by: Christopher J. Markiewicz <effigies@gmail.com>

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Christopher J. Markiewicz <effigies@gmail.com>
Co-authored-by: Chris Markiewicz <markiewicz@stanford.edu>

src/modality-specific-files/magnetic-resonance-imaging-data.md

@@ -721,37 +721,46 @@ within the `[*_]dwi.bval` and `[*_]dwi.bvec` files) MAY change across DWI runs.
 
 **Gradient orientation file formats**.
 The `[*_]dwi.bval` and `[*_]dwi.bvec` files MUST follow the
-[FSL format](https://fsl.fmrib.ox.ac.uk/fsl/docs/#/diffusion/index?id=diffusion-data-in-fsl):
-The `[*_]dwi.bvec` file contains 3 rows with *N* space-delimited floating-point numbers
-(corresponding to the *N* volumes in the corresponding NIfTI file.)
-The first row contains the *x* elements, the second row contains the *y* elements and
-the third row contains the *z* elements of a unit vector in the direction of the applied
-diffusion gradient, where the *i*-th elements in each row correspond together to
-the *i*-th volume, with `[0,0,0]` for *non-diffusion-weighted* (also called *b*=0 or *low-b*)
-volumes.
-Following the FSL format for the `[*_]dwi.bvec` specification, the coordinate system of
-the *b* vectors MUST be defined with respect to the coordinate system defined by
-the header of the corresponding `_dwi` NIfTI file and not the scanner's device
-coordinate system (see [Coordinate systems](../appendices/coordinate-systems.md)).
-The most relevant limitation imposed by this choice is that the gradient information cannot
-be directly stored in this format if the scanner generates *b*-vectors in *scanner coordinates*.
-
-Example of `[*_]dwi.bvec` file, with *N*=6, with two *b*=0 volumes in the beginning:
-
-```Text
-0 0 0.021828 -0.015425 -0.70918 -0.2465
-0 0 0.80242 0.22098 -0.00063106 0.1043
-0 0 -0.59636 0.97516 -0.70503 -0.96351
-```
-
-The `[*_]dwi.bval` file contains the *b*-values (in s/mm<sup>2</sup>) corresponding to the
-volumes in the relevant NIfTI file), with 0 designating *b*=0 volumes, space-delimited.
-
-Example of `[*_]dwi.bval` file, corresponding to the previous `[*_]dwi.bvec` example:
-
-```Text
-0 0 2000 2000 1000 1000
-```
+[FSL format](https://fsl.fmrib.ox.ac.uk/fsl/docs/#/diffusion/index?id=diffusion-data-in-fsl).
+
+The `[*_]dwi.bvec` file contains 3 rows with *N* space-delimited floating-point numbers,
+corresponding to the *N* volumes in the corresponding NIfTI file.
+Across these three rows,
+each column encodes three elements of a 3-vector for the corresponding image volume;
+each vector MUST be either of unit norm,
+or optionally the vector `[0.0,0.0,0.0]`
+for *non-diffusion-weighted* (also called *b*=0 or *low-b*) volumes.
+These values are to be interpreted as cosine values with respect to the image axis orientations
+as defined by the corresponding NIfTI image header transformation;
+*unless* the image axes defined in the corresponding NIfTI image header
+form a right-handed coordinate system
+(that is, the 3x3 matrix of direction cosines has a positive determinant),
+in which case the sign of the first element of each 3-vector must be inverted
+for this interpretation to be valid.
+Note that this definition of orientations with respect to the NIfTI image axes
+is *not* equivalent to the DICOM convention,
+where orientations are instead defined with respect to the scanner device's coordinate system
+(see [Coordinate systems](../appendices/coordinate-systems.md)).
+
+The `[*_]dwi.bval` file contains the *b*-values (in s/mm<sup>2</sup>)
+corresponding to the volumes in the relevant NIfTI file,
+with 0 designating *b*=0 volumes; space-delimited.
+
+Examples of `[*_]dwi.bvec` and `[*_]dwi.bval` files,
+corresponding to a NIfTI image with 6 volumes
+with the first two volumes having no diffusion sensitization:
+
+-   `[*_]dwi.bvec`:
+    ```Text
+    0 0 0.021828 -0.015425 -0.70918 -0.2465
+    0 0 0.80242 0.22098 -0.00063106 0.1043
+    0 0 -0.59636 0.97516 -0.70503 -0.96351
+    ```
+
+-   `[_]dwi.bval`:
+    ```Text
+    0 0 2000 2000 1000 1000
+    ```
 
 ### Multipart (split) DWI schemes
 

src/schema/objects/extensions.yaml

@@ -30,21 +30,26 @@ bvec:
   description: |
     A space-delimited file containing gradient directions (b-vectors) of diffusion measurement.
 
-    This file contains 3 rows with *N* space-delimited floating-point numbers,
+    The `bvec` file contains 3 rows with *N* space-delimited floating-point numbers,
     corresponding to the *N* volumes in the corresponding NIfTI file.
 
-    The first row contains the *x* elements, the second row contains the *y* elements and
-    the third row contains the *z* elements of a unit vector in the direction of the applied
-    diffusion gradient, where the *i*-th elements in each row correspond together to
-    the *i*-th volume, with `[0,0,0]` for *non-diffusion-weighted* (also called *b*=0 or *low-b*)
-    volumes.
+    Across these three rows,
+    each column encodes three elements of a 3-vector for the corresponding image volume;
+    each vector MUST be either of unit norm,
+    or optionally the vector `[0.0,0.0,0.0]`
+    for *non-diffusion-weighted* (also called *b*=0 or *low-b*) volumes.
+    These values are to be interpreted as cosine values with respect to the image axis orientations
+    as defined by the corresponding NIfTI image header transformation;
+    *unless* the image axes defined in the corresponding NIfTI image header
+    form a right-handed coordinate system
+    (that is, the 3x3 matrix of direction cosines has a positive determinant),
+    in which case the sign of the first element of each 3-vector must be inverted
+    for this interpretation to be valid.
 
-    Following the FSL format for the `bvec` specification, the coordinate system of
-    the *b* vectors MUST be defined with respect to the coordinate system defined by
-    the header of the corresponding `_dwi` NIfTI file and not the scanner's device
-    coordinate system (see [Coordinate systems](SPEC_ROOT/appendices/coordinate-systems.md)).
-    The most relevant limitation imposed by this choice is that the gradient information cannot
-    be directly stored in this format if the scanner generates *b*-vectors in *scanner coordinates*.
+    Note that this definition of orientations with respect to the NIfTI image axes
+    is *not* equivalent to the DICOM convention,
+    where orientations are instead defined with respect to the scanner device's coordinate system
+    (see [Coordinate systems](SPEC_ROOT/appendices/coordinate-systems.md)).
 chn:
   value: .chn
   display_name: KRISS CHN