Merge pull request #624 from rordenlab/development

New stable release
rordenlab · Aug 4, 2022 · bb3a6c3 · bb3a6c3
2 parents 002ebcd + f2ceab6
commit bb3a6c3
Show file tree

Hide file tree

Showing 29 changed files with 5,051 additions and 251 deletions.
diff --git a/BATCH.md b/BATCH.md
@@ -10,9 +10,9 @@ The configuration file should be in yaml format as shown in example `batch_confi
 ```yaml
 Options:
   isGz:             false
-  isFlipY:          true
+  isFlipY:          false
   isVerbose:        false
-  isCreateBIDS:     true
+  isCreateBIDS:     false
   isOnlySingleFile: false
 Files:
     -

diff --git a/BIDS/README.md b/BIDS/README.md
@@ -35,6 +35,7 @@ The Defined By column uses:
 
 The Unit column uses:
 
+- b : boolean
 - deg : degrees
 - f : fraction
 - kg : Kilogram
@@ -214,15 +215,19 @@ Data unique to [GE](https://github.com/rordenlab/dcm2niix/tree/master/GE). Deter
 | PulseSequenceName              |      | `epi` or `epiRT`         | D          |
 | InternalPulseSequenceName      |      | `EPI` or `EPI2`          | D          |
 | PhaseEncodingPolarityGE        |      | `Unflipped` or `Flipped` | D          |
-| ASLContrastTechnique           |      | DICOM tag 0043,10A3      | D          |
-| ASLLabelingTechnique           |      | DICOM tag 0043,10A4      | D          |
-| LabelingDuration               | s    | DICOM tag 0043,10A5      | B          |
-| MultibandAccelerationFactor    |      | DICOM tag 0043,1083      | B          |
+| PostLabelingDelay              | s    | DICOM tag 0018,0082 (TI) | B          |
 | NumberOfPointsPerArm           |      | DICOM tag 0027,1060      | D          |
 | NumberOfArms                   |      | DICOM tag 0027,1061      | D          |
 | NumberOfExcitations            |      | DICOM tag 0027,1062      | D          |
+| ShimSetting[0]                 |      | DICOM tag 0043,1002      | D          |
+| ShimSetting[1]                 |      | DICOM tag 0043,1003      | D          |
+| ShimSetting[2]                 |      | DICOM tag 0043,1004      | D          |
 | ParallelReductionFactorInPlane |      | DICOM tag 0043,1083      | B          |
-| PostLabelingDelay              | s    | DICOM tag 0018,0082 (TI) | B          |
+| PrescanReuseString             |      | DICOM tag 0043,1095      | D          |
+| MultibandAccelerationFactor    |      | DICOM tag 0043,1083      | B          |
+| ASLContrastTechnique           |      | DICOM tag 0043,10A3      | D          |
+| ASLLabelingTechnique           |      | DICOM tag 0043,10A4      | D          |
+| LabelingDuration               | s    | DICOM tag 0043,10A5      | B          |
 
 ### Manufacturer Philips
 
@@ -312,15 +317,19 @@ Fields specific to Siemens V*-series (e.g. VB, VE) MRI systems (e.g. Verio, Trio
 | DwellTime                      |                                                 | DICOM tag 0019,1018                                                                                                                                                                                                                                                                                                                                                                                    | B          |
 | BandwidthPerPixelPhaseEncode   | Hz                                              | DICOM tag 0019,1028                                                                                                                                                                                                                                                                                                                                                                                    | D          |
 | ImageOrientationText           |                                                 | DICOM tag 0051,100E                                                                                                                                                                                                                                                                                                                                                                                    | D          |
+| NonlinearGradientCorrection    | b                                               | DICOM tag 0008,0008                                                                                                                                                                                                                                                                                                                                                                                    | B          |
 
 ### Manufacturer Siemens Magnetic Resonance Imaging (XA)
 
 Fields specific to Siemens XA-series MRI systems (Sola, Vida).
 
-| Field                        | Unit | Comments            | Defined By |
-|------------------------------|------|---------------------|------------|
-| ReceiveCoilActiveElements    |      | DICOM tag 0021,114F | B          |
-| BandwidthPerPixelPhaseEncode | Hz   | DICOM tag 0021,1153 | D          |
+| Field                        | Unit | Comments               | Defined By |
+|------------------------------|------|------------------------|------------|
+| ReceiveCoilActiveElements    |      | DICOM tag 0021,114F    | B          |
+| BandwidthPerPixelPhaseEncode | Hz   | DICOM tag 0021,1153    | D          |
+| ScanningSequence             |      | DICOM tag 0021,105a    | D          |
+| PostLabelDelay               | s    | DICOM tag 0018,9258    | D          |
+| NonlinearGradientCorrection  | b    | 0008,0008 or 0021,1175 | B          |
 
 ### Manufacturer UIH
 

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 2.8.11)
+cmake_minimum_required(VERSION 2.8.12)
 
 if(COMMAND CMAKE_POLICY)
     CMAKE_POLICY(SET CMP0003 NEW)

diff --git a/Canon/README.md b/Canon/README.md
@@ -6,18 +6,26 @@ dcm2niix can convert Canon (né Toshiba) DICOM format images to NIfTI. This page
 
 Users of Canon MRI equipment are strongly advised to export data from their scanners as enhanced DICOM (with all images from the series stored as a single file) rather than classic DICOM (each 2D slice stored as a separate file). Limitations of the Canon classic DICOMs are described [here](https://github.com/rordenlab/dcm2niix/issues/495) and [here](https://github.com/neurolabusc/dcm_qa_canon).
 
+## Avoid Enhanced DICOM
+
+Users of Canon MRI equipment are strongly advised to export data from their scanners as classic DICOM (with each slice from the series stored as a separate files) rather than enhanced DICOM. The enhanced 4D sequences such as fMRI incorrectly sets the public tag TemporalPositionIndex (0020,9128) as 1 for all volumes: both (0020,9157) and (0020,9128). This is a violation of the DICOM standard and interferes with attempts to sort data into the correct temporal order. Any software or user who assumes these tags are truthful will fail.
+
+## The Enhanced versus Classic DICOM dilemma
+
+The prior two sections provide conflicting advice, due to limitations in both the classic and enhanced datasets generated by Canon instruments. Users of Canon equipment should lobby the manufacturer to honor their DICOM conformance statement. DICOM data from Canon instruments may not be handled correctly by any software tool including dcm2niix. This reflects a limitation in the source DICOM data, not dcm2niix.
+
 ## Diffusion Weighted Imaging Notes
 
 In contrast to several other vendors, Toshiba used public tags to report diffusion properties. Specifically, [DiffusionBValue (0018,9087)](http://dicomlookup.com/lookup.asp?sw=Tnumber&q=(0018,9087)) and [DiffusionGradientOrientation (0018,9089)](http://dicomlookup.com/lookup.asp?sw=Tnumber&q=(0018,9089)). Be aware that these tags are only populated for images where a diffusion gradient is applied. Consider a typical diffusion series where some volumes are acquired with B=0 while others have B=1000. In this case, only the volumes with B>0 will report a DiffusionBValue. These coordinates are with respect to the scanner bore, not image space.
 
-Since the acquisition by Canon, these public tags are no longer populated for images saved in classic 2D DICOM format. The diffusion gradient directions are now stored in the ASCII Image Comments tag. Like GE (but unlike [Siemens, GE and Toshiba](https://www.na-mic.org/wiki/NAMIC_Wiki:DTI:DICOM_for_DWI_and_DTI)), these directions are with respect to the image space, not the scanner bore. Further, gradient direction is not adjusted for phase encoding polarity, and it is impossible to determine phase encoding polarity. For detailed discussion and a validation dataset that exhibits these attributes please see [dcm_qa_canon](https://github.com/neurolabusc/dcm_qa_canon). A Canon classic DICOM DWI image may report:
+Be aware that Canon software V6.0 stored diffusion directions in the ASCII Image Comments tag when exporting to classic DICOM. For detailed discussion and a validation dataset that exhibits these attributes please see [dcm_qa_canon](https://github.com/neurolabusc/dcm_qa_canon). A Canon classic DICOM DWI image may report:
 
 ```
  (0018,9087) FD 1500                                     #   8, 1 DiffusionBValue
  (0020,4000) LT [b=1500(0.445,0.000,0.895)]              #  26, 1 ImageComments
 ```
 
-In contrast, when exporting images as enhanced (4D) DICOM, information is stored in public tags and does appear to compensate for phase encode polarity. These coordinates are with respect to the scanner bore, not image space. A Canon classic DICOM DWI image may report:
+In contrast, Canon software [V6.1](https://github.com/neurolabusc/dcm_qa_canon_61) uses pulbic tags for both classic and enhanced DICOMs. A Canon V6.1 DICOM DWI image may report:
 
 ```
 (0018,9087) FD 1500                                     #   8, 1 DiffusionBValue

diff --git a/Philips/README.md b/Philips/README.md
@@ -148,7 +148,7 @@ The BIDS tag [PartialFourier](https://bids-specification.readthedocs.io/en/stabl
 
 Philips DICOMs do not allow one to determine the temporal order of volumes for diffusion (DWI, DTI) and arterial spin labelling (ASL) sequences. This can hinder tools that attempt to model motion motion or T1 effects. For ASL data, dcm2niix will attempt to store volumes in the order phase < control/label < repeat. [For ASL examples and a table describing the ordering hierarchy, see this dataset](https://github.com/neurolabusc/dcm_qa_philips_asl). For diffusion images, dcm2niix may order Philips volumes differently depending on if the data is stored as classic or enhanced DICOM. For enhanced DICOM, dcm2niix follows the hierarchy specified by DimensionIndexValues (0020,9157). On the other hand, for classic DICOMs, volumes with identical b-value index (2005,1412) will be stored sequentially, with ties sorted based on gradient direction number (2005,1413). [For diffusion examples, see series 22 and 23 from this dataset](https://github.com/neurolabusc/dcm_qa_philips_enh). These two different sorting methods may not necessarily sort data identically.
 
-[Slice timing correction](https://www.mccauslandcenter.sc.edu/crnl/tools/stc) can account for some variability in fMRI datasets. Unfortunately, Philips DICOM data [does not encode slice timing information](https://neurostars.org/t/heudiconv-no-extraction-of-slice-timing-data-based-on-philips-dicoms/2201/4). Therefore, dcm2niix is unable to populate the "SliceTiming" BIDS field. However, one can typically infer slice timing by recording the [mode and number of packages](https://en.wikibooks.org/w/index.php?title=SPM/Slice_Timing&stable=0#Philips_scanners) reported for the sequence on the scanner console or the [sequence PDF](http://adni.loni.usc.edu/wp-content/uploads/2017/09/ADNI-3-Basic-Philips-R5.pdf). For precise timing, it is also worth knowing if equidistant "temporal slice spacing" is set and whether "prospect. motion corr." is on or off (if on, a short delay occurs between volumes).
+[Slice timing correction](https://www.mccauslandcenter.sc.edu/crnl/tools/stc) can account for some variability in fMRI datasets. Unfortunately, Philips DICOM data [does not explicitly encode slice timing information](https://neurostars.org/t/heudiconv-no-extraction-of-slice-timing-data-based-on-philips-dicoms/2201/4). Therefore, dcm2niix is unable to populate the "SliceTiming" BIDS field. Note, the [philips_order.py script](https://neurostars.org/t/how-dcm2niix-handles-different-imaging-types/22697/7) may be able to determine slice timing using an undocumented and unverified technique that works in some instances but certainly fails with others. Additionally, one can typically infer slice timing by recording the [mode and number of packages](https://en.wikibooks.org/w/index.php?title=SPM/Slice_Timing&stable=0#Philips_scanners) reported for the sequence on the scanner console or the [sequence PDF](http://adni.loni.usc.edu/wp-content/uploads/2017/09/ADNI-3-Basic-Philips-R5.pdf). For precise timing, it is also worth knowing if equidistant "temporal slice spacing" is set and whether "prospect. motion corr." is on or off (if on, a short delay occurs between volumes).
 
 Likewise, the BIDS tag "PhaseEncodingDirection" allows tools like [eddy](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy) and [TOPUP](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/topup) to undistort images. While the Philips DICOM header distinguishes the phase encoding axis (e.g. anterior-posterior vs left-right) it does not encode the polarity (A->P vs P->A).