Merge pull request #444 from rordenlab/development

version 2-November-2020 (v1.0.20201102)

COMPILE.md

@@ -137,34 +137,26 @@ lipo -create dcm2niix32 dcm2niix64 -o dcm2niix
 file ./dcm2niix
 ```
 
-##### OSX GRAPHICAL INTERFACE BUILD
-
-You can building the OSX graphical user interface using Xcode. First, Copy contents of "console" folder to /xcode/dcm2/core. Next, open and compile the project "dcm2.xcodeproj" with Xcode 4.6 or later
-
-##### THE QT AND wxWIDGETS GUIs ARE NOT YET SUPPORTED - FOLLOWING LINES FOR FUTURE VERSIONS
-
-Building QT graphical user interface:
-  Open "dcm2.pro" with QTCreator. This should work on OSX and Linux. On Windows the printf information is not redirected to the user interface
-  If compile gives you grief look at the .pro file which has notes for different operating systems.
-
-Building using wxWidgets
-wxWdigets makefiles are pretty complex and specific for your operating system. For simplicity, we will build the "clipboard" example that comes with wxwidgets and then substitute our own code. The process goes something like this.
- a.) Install wxwdigets
- b.) successfully "make" the samples/clipboard program
- c.) DELETE console/makefile. WE DO NOT WANT TO OVERWRITE the WX MAKEFILE
- d.) with the exception of "makefile", copy the contents of console to /samples/clipboard
- e.) overwrite the original /samples/clipboard.cpp with the dcm2niix file of the same name
- f.) Older Xcodes have problems with .cpp files, whereas wxWidgets's makefiles do not compile with "-x cpp". So the core files are called '.c' but we will rename them to .cpp for wxWidgets:
- rename 's/\.c$/\.cpp/' *
- g.) edit the /samples/clipboard makefile: Add "nii_dicom.o nifti1_io_core.o nii_ortho.o nii_dicom_batch.o \" to CLIPBOARD_OBJECTS:
-CLIPBOARD_OBJECTS =  \
-  nii_dicom.o nifti1_io_core.o nii_ortho.o nii_dicom_batch.o \
-  $(__clipboard___win32rc) \
-  $(__clipboard_os2_lib_res) \
-  clipboard_clipboard.o
- h.) edit the /samples/clipboard makefile: With wxWidgets we will capture std::cout comments, not printf, so we need to add "-DDmyUseCOut" to CXXFLAGS:
-CXXFLAGS = -DmyUseCOut -DWX_PRECOMP ....
- i.) For a full refresh
-rm clipboard
-rm *.o
-make
+##### CMAKE INSTALLATION
+
+While most of this page describes  how to use `make` to compile dcm2niix, `cmake` can automatically aid complex builds. The [home page](https://github.com/rordenlab/dcm2niix) describes typical cmake options. The cmake command will attempt to pull additional code from git as needed for zlib, OpenJPEG etc.  If you get the following error:
+
+```
+fatal: unable to connect to github.com:
+github.com[0: 140.82.121.4]: errno=Connection timed out
+```
+
+This suggests git is unable to connect using ssh. You have two options, first you can disable the cmake option USE_GIT_PROTOCOL (which is on by default). Alternatively, to use https instead using the following lines prior to running cmake:
+
+```
+git config --global url."https://github.com/".insteadOf git@github.com:
+git config --global url."https://".insteadOf git://
+```
+
+Once the installation is completed, you can revert these changes:
+
+```
+git config --global --unset-all url.https://github.com/.insteadof
+git config --global --unset-all url.https://.insteadof
+```
+

Toshiba/README.md → Canon/README.md

@@ -1,14 +1,22 @@
 ## About
 
-dcm2niix attempts to convert Toshiba DICOM format images to NIfTI. This page notes vendor specific conversion details.
+dcm2niix can convert Canon (né Toshiba) DICOM format images to NIfTI. This page notes vendor specific conversion details.
 
 ## Diffusion Weighted Imaging Notes
 
-In contrast to several other vendors, Toshiba uses 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.
+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.
+
+Since the acquisition by Canon, these public tags are no longer populated. 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. For empirical data see the Sample Datasets section.
+
+```
+ (0018,9087) FD 1500                                     #   8, 1 DiffusionBValue
+ (0020,4000) LT [b=1500(0.445,0.000,0.895)]              #  26, 1 ImageComments
+```
+
 
 ## Unknown Properties
 
-The (BIDS format)[https://bids.neuroimaging.io] can record several sequence properties that are useful for processing MRI data. The DICOM headers created by Toshiba scanners are very clean and minimalistic, and do not report several of these advanced properties. Therefore, dcm2niix is unable to populate these properties of the JSON file. This reflects a limitation of the DICOM images, not of dcm2niix.
+The [BIDS format](https://bids.neuroimaging.io) can record several sequence properties that are useful for processing MRI data. The DICOM headers created by Toshiba scanners are very clean and minimalistic, and do not report several of these advanced properties. Therefore, dcm2niix is unable to populate these properties of the JSON file. This reflects a limitation of the DICOM images, not of dcm2niix.
 
  - SliceTiming is not recorded. This can be useful for slice time correction.
  - Phase encoding polarity is not record. This is useful for undistortion with [TOPUP](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/topup).
@@ -18,3 +26,4 @@ The (BIDS format)[https://bids.neuroimaging.io] can record several sequence prop
 
  - [Toshiba Aquilion](https://www.aliza-dicom-viewer.com/download/datasets).
  - [Toshiba 3T Galan Diffusion Dataset](https://github.com/neurolabusc/dcm_qa_toshiba).
+ - [Canon 3T Galan Diffusion Dataset](https://github.com/neurolabusc/dcm_qa_canon).

ERRORS.md

@@ -0,0 +1,29 @@
+## About
+
+dcm2niix will return an exit status to allow scripts to determine if a conversion was successful. Following Unix convention, the value value 0 is used for [EXIT_SUCCESS](https://www.gnu.org/software/libc/manual/html_node/Exit-Status.html). In contrast, any non-zero result suggests an error. In the Unix terminal and with shell scripts, the variable `$?` reports the most recent exit status. Here is an example of a successful conversion:
+
+```
+>dcm2niix ~/dcm
+Chris Rorden's dcm2niiX version v1.0.20200331 Clang11.0.0 (64-bit MacOS)
+Found 2 DICOM file(s)
+Convert 2 DICOM as ~/dcm/dcm_ax_asc_6 (64x64x35x2)
+Conversion required 0.015866 seconds (0.012676 for core code).
+>echo $?
+0
+```
+
+Below is a list of possible return values from running dcm2niix. 
+
+| Exit Status | Meaning                                                     |
+| ----------- | ----------------------------------------------------------- |
+| 0           | Success                                                     |
+| 1           | Unspecified error (see console output for details)          |
+| 2           | No DICOM images found in input folder                       |
+| 3           | Exit from report version (result of `dcm2niix -v`)          |
+| 4           | Corrupt DICOM file (Irrecoverable error during conversion)  |
+| 5           | Input folder invalid                                        |
+| 6           | Output folder invalid                                       |
+| 7           | Unable to write to output folder (check file permissions)   |
+| 8           | Converted some but not all of the input DICOMs              |
+| 9           | Unable to rename files (result of `dcm2niix -r y ~/in`)     |
+

FILENAMING.md

@@ -19,7 +19,7 @@ You request the output file name with the `-f` argument. For example, consider y
  - %m=manufacturer short name (from 0008,0070: GE, Ph, Si, To, UI, NA)
  - %n=name of patient (from 0010,0010)
  - %o=mediaObjectInstanceUID (0002,0003)*
- - %p=protocol name (from 0018,1030)
+ - %p=protocol name (from 0018,1030). If 0018,1030 is empty, or if the Manufacturer (0008,0070) is GE with Modality (0008,0060) of MR, then the SequenceName (0018,0024) is used if it is not empty.
  - %r=instance number (from 0020,0013)*
  - %s=series number (from 0020,0011)
  - %t=time of study (from 0008,0020 and 0008,0030)
@@ -54,6 +54,10 @@ Some post-fixes are specific to Philips DICOMs
 
 If you do not want post-fixes, run dcm2niix in the terse mode (`--terse`). In this mode, most post-fixes will be omitted. Beware that this mode can have name clashes, and images from a series may over write each other.  
 
+## Overlays
+
+DICOM images can have up to [16](https://www.medicalconnections.co.uk/kb/Number-Of-Overlays-In-Image/) binary (black or white) overlays as described by the [Overlay Plane Module](http://dicom.nema.org/dicom/2013/output/chtml/part03/sect_C.9.html). dcm2niix will save these regions of interest with the post-fix "_ROIn" where N is the overlay number (1..16). 
+
 ## File Name Conflicts
 
 dcm2niix will attempt to write your image using the naming scheme you specify with the '-f' parameter. However, if an image already exists with the specified output name, dcm2niix will append a letter (e.g. 'a') to the end of a file name to avoid overwriting existing images. Consider a situation where dcm2niix is run with '-f %t'. This will name images based on the study time. If a single study has multiple series (for example, a T1 sequence and a fMRI scan, the reulting file names will conflict with each other. In order to avoid overwriting images, dcm2niix will resort to adding the post fix 'a', 'b', etc. There are a few solutions to avoiding these situations. You may want to consider using both of these:
@@ -78,4 +82,6 @@ dcm2niix will attempt to write your image using the naming scheme you specify wi
 * (asterisk)
 ```
 
+[Control characters](https://en.wikipedia.org/wiki/ASCII#Control_characters) like backspace and tab are also forbidden.
+
 Be warned that dcm2niix will copy all allowed characters verbatim, which can cause problems for some other tools. Consider this [sample dataset](https://github.com/neurolabusc/dcm_qa_nih/tree/master/In/20180918GE/mr_0004) where the DICOM Protocol Name (0018,1030) is 'Axial_EPI-FMRI_(Interleaved_I_to_S)'. The parentheses ("round brackets") may cause other tools issues. Consider converting this series with the command 'dcm2niix -f %s_%p ~/DICOM' to create the file '4_Axial_EPI-FMRI_(Interleaved_I_to_S).nii'.If you now run the command 'fslhd 4_Axial_EPI-FMRI_(Interleaved_I_to_S).nii' you will get the error '-bash: syntax error near unexpected token `(''. Therefore, it is often a good idea to use double quotes to specify the names of files. In this example 'fslhd "4_Axial_EPI-FMRI_(Interleaved_I_to_S).nii"' will work correctly.