From ace8d7d6c0fe4ea3c8468b227363864e5792ee0b Mon Sep 17 00:00:00 2001 From: Robert Smith Date: Fri, 23 Aug 2024 03:26:27 +0800 Subject: [PATCH] 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 --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Christopher J. Markiewicz Co-authored-by: Chris Markiewicz --- .../magnetic-resonance-imaging-data.md | 71 +++++++++++-------- src/schema/objects/extensions.yaml | 29 ++++---- 2 files changed, 57 insertions(+), 43 deletions(-) diff --git a/src/modality-specific-files/magnetic-resonance-imaging-data.md b/src/modality-specific-files/magnetic-resonance-imaging-data.md index 5e4528aca5..ce58b6446a 100644 --- a/src/modality-specific-files/magnetic-resonance-imaging-data.md +++ b/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/mm2) 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/mm2) +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 diff --git a/src/schema/objects/extensions.yaml b/src/schema/objects/extensions.yaml index db38cf55b2..d482f8849d 100644 --- a/src/schema/objects/extensions.yaml +++ b/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