Skip to content

Commit

Permalink
Merge commit 'v1.0.20171017-3-g9ccc4c0' into debian
Browse files Browse the repository at this point in the history
* commit 'v1.0.20171017-3-g9ccc4c0':
  Detect SMS using 0051,1011 if MosaicRefAcqTimes missing rordenlab#141
  Hide NIfTI sliceOrder if protocolSliceNumber1 > 1
  SliceTiming for reversed image numbering https://github.com/neurolabusc/dcm2niix/issues/40
  Update dcm_qa submodule.
  New version (v1.0.20171017)
  Added link rordenlab#138
  Store mulbiband factor in NIfTI descrip field (e.g. "mb=2") https://www.nitrc.org/forum/message.php?msg_id=22593
  Add patient sex, weight, etc, https://www.nitrc.org/forum/message.php?msg_id=22567
  Add ImageOrientationPatientDICOM and InPlanePhaseEncodingDirectionDICOM for 3D undistortion
  Compiling with CentOS 7: rordenlab#137
  BIDS 1.0.2 DelayTime field for sparse fMRI
  Add InstitutionalDepartmentName
  Get ProtocolName from CSA header if it is not in DICOM header nipy/heudiconv#80
  Change name of output tag of two variables to match DICOM
  Group PixelBandwidth with DwellTime in output json
  Vanquish compiler warnings.
  Report lower order shims prior to higher order (requested by mharms)
  Handle Siemens product gradient offsets?
  More Siemens information saved to BIDS
  BIDS: Do not set multiband factor for 3D EPI, report as "MRAcquisitionType": "3D",
  • Loading branch information
yarikoptic committed Nov 3, 2017
2 parents efbfd6a + 9ccc4c0 commit d164ee0
Show file tree
Hide file tree
Showing 10 changed files with 378 additions and 465 deletions.
28 changes: 28 additions & 0 deletions BATCH.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
**Optional batch processing version:**

Perform a batch conversion of multiple dicoms using the configurations specified in a yaml file.
```bash
dcm2niibatch batch_config.yml
```

The configuration file should be in yaml format as shown in example `batch_config.yaml`

```yaml
Options:
isGz: false
isFlipY: false
isVerbose: false
isCreateBIDS: false
isOnlySingleFile: false
Files:
-
in_dir: /path/to/first/folder
out_dir: /path/to/output/folder
filename: dcemri
-
in_dir: /path/to/second/folder
out_dir: /path/to/output/folder
filename: fa3
```
You can add as many files as you want to convert as long as this structure stays consistent. Note that a dash must separate each file.
5 changes: 4 additions & 1 deletion COMPILE.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@ The README.md file describes the typical compilation of the software, using the

The text below generally describes how to build dcm2niix using the [GCC](https://gcc.gnu.org) compiler using the `g++` command. However, the code is portable and you can use different compilers. For [clang/llvm](https://clang.llvm.org) compile using `clang++`. If you have the [Intel C compiler](https://software.intel.com/en-us/c-compilers), you can substitute the `icc` command. For [Microsoft's C compiler](http://landinghub.visualstudio.com/visual-cpp-build-tools) you would use the `cl` command. In theory, the code should support other compilers, but this has not been tested. Be aware that if you do not have gcc installed the `g++` command may use a default to a compiler (e.g. clang). To check what compiler was used, run the dcm2niix software: it always reports the version and the compiler used for the build.


## Building the command line version without cmake

You can also build the software without C-make. The easiest way to do this is to run the function "make" from the "console" folder. Note that this only creates the default version of dcm2niix, not the optional batch version described above. The make command simply calls the g++ compiler, and if you want you can tune this for your build. In essence, the make function simply calls
Expand All @@ -17,6 +16,10 @@ g++ -dead_strip -O3 -I. main_console.cpp nii_dicom.cpp jpg_0XC3.cpp ujpeg.cpp ni

The following sub-sections list how you can modify this basic recipe for your needs.

## Trouble Shooting

Some [Centos/Redhat](https://github.com/rordenlab/dcm2niix/issues/137) may report "/usr/bin/ld: cannot find -lstdc++". This can be resolved by installing static versions of libstd: `yum install libstdc++-static`.

##### ZLIB BUILD
If we have zlib, we can use it (-lz) and disable [miniz](https://code.google.com/p/miniz/) (-myDisableMiniZ)

Expand Down
152 changes: 7 additions & 145 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,153 +11,17 @@ This software is open source. The bulk of the code is covered by the BSD license

## Dependencies

This software should run on macOS, Linux and Windows without requiring any other software. However, if you use dcm2niix to create gz-compressed images it will be faster if you have [pigz](https://github.com/madler/pigz) installed. You can get a version of both dcm2niix and pigz compiled for your operating system by downloading [MRIcroGL](https://www.nitrc.org/projects/mricrogl/).
This software should run on macOS, Linux and Windows typically without requiring any other software. However, if you use dcm2niix to create gz-compressed images it will be faster if you have [pigz](https://github.com/madler/pigz) installed. You can get a version of both dcm2niix and pigz compiled for your operating system by downloading [MRIcroGL](https://www.nitrc.org/projects/mricrogl/).

## Versions

23-Sept-2017
- Swap [phase-encoding direction polarity](https://github.com/rordenlab/dcm2niix/issues/125) for Siemens images where PE is in the Column direction.
- Sort diffusion volumes by [B-value amplitude](https://www.nitrc.org/forum/forum.php?thread_id=8396&forum_id=4703) (use "-d n"/"-d y" to turn the feature off/on).
- BIDS tag [TotalReadoutTime](https://github.com/rordenlab/dcm2niix/issues/130) handles partial fourier, Phase Resolution, etc (Michael Harms).
- Additional [json fields](https://github.com/rordenlab/dcm2niix/issues/127).

18-Aug-2017
- Better BVec extraction for [PAR/REC 4.1](https://www.nitrc.org/forum/forum.php?thread_id=8387&forum_id=4703).
- Support for [Segami Cerescan volumes](https://www.nitrc.org/forum/forum.php?thread_id=8076&forum_id=4703).

24-July-2017
- Compiles with recent releases of [OpenJPEG](https://github.com/neurolabusc/dcm_qa/issues/5#issuecomment-317443179) for JPEG2000 support.

23-June-2017
- [Ensure slice timing always encoded for Siemens EPI](https://github.com/neurolabusc/dcm_qa/issues/4#issuecomment-310707906)
- [Integrates validation](https://github.com/neurolabusc/dcm_qa)
- JSON fix (InstitutionName -> InstitutionAddress)

21-June-2017
- Read DICOM header in 1Mb segments rather than loading whole file : reduces ram usage and [faster for systems with slow io](https://github.com/rordenlab/dcm2niix/issues/104).
- Report [TotalReadoutTime](https://github.com/rordenlab/dcm2niix/issues/98).
- Fix JPEG2000 support in [Superbuild](https://github.com/rordenlab/dcm2niix/issues/105).

28-May-2017
- Remove all derived images from [Philips DTI series](http://www.nitrc.org/forum/message.php?msg_id=21025).
- Provide some [Siemens EPI sequence details](https://github.com/rordenlab/dcm2niix/issues).

28-April-2017
- Experimental [ECAT support](https://github.com/rordenlab/dcm2niix/issues/95).
- Updated cmake to make JPEG2000 support easier with improved Travis and AppVeyor support [Ningfei Li](https://github.com/ningfei).
- Supports Data/Time for images that report Data/Time (0008,002A) but not separate Date and Time (0008,0022 and 0008,0032).
- [BIDS reports morning times correctly](http://www.nitrc.org/forum/message.php?msg_id=20852).
- Options -1..-9 to control [gz compression level](https://github.com/rordenlab/dcm2niix/issues/90).
- Includes some [PET details in the BIDS JSON sidecar](https://github.com/rordenlab/dcm2niix/issues/87).
- Better detection of image order for Philips 4D DICOM (reported by Jason McMorrow and Stephen Wilson).
- [Include StudyInstanceUID and SeriesInstanceUID in filename](https://github.com/rordenlab/dcm2niix/issues/94).

7-Feb-2017
- Can be compiled to use either Philips [Float or Display](http://www.nitrc.org/forum/message.php?msg_id=20213) intensity intercept and slope values.
- Handle 3D Philips DICOM and [PAR/REC](https://www.nitrc.org/forum/forum.php?thread_id=7707&forum_id=4703) files where images are not stored in a spatially contiguous order.
- Handle DICOM violations where icon is uncompressed but image data is compressed.
- Best guess matrix for 2D slices (similar to dcm2nii, SPM and MRIconvert).
- Linux (case sensitive filenames) now handles par/rec as well as PAR/REC.
- Images with unknown phase encoding do not generate [BIDS entry](https://github.com/rordenlab/dcm2niix/issues/79).
- Unified printMessage/printWarning/printError aids embedding in other projects, such as [divest](https://github.com/jonclayden/divest).

1-Nov-2016
- AppVeyor Support (Ningfei Li & Chris Filo Gorgolewski)
- Swap 3rd/4th dimensions for GE sequential multi-phase acquisitions (Niels Janssen).

10-Oct-2016
- Restores/improves building for the Windows operating system using MinGW.

30-Sept-2016
- Save ImageType (0x0008,0x0008) to BIDS.
- Separate CT scans with different exposures.
- Fixed issues where some compilers would generate erratic filenames for zero-padded series (e.g. "-f %3s").

21-Sept-2016
- Reduce verbosity (reduce number of repeated warnings, less scary warnings for derived rather than raw images).
- Re-enable custom output directory "-o" option broken by 30-Apr-2016 version.
- Deal with mis-behaved GE CT images where slice direction across images is not consistent.
- Add new BIDS fields (field strength, manufacturer, etc).
- Philips PAR/REC conversion now reports inconsistent requested vs measured TR (due to prospect. motion corr.?).
- GE: Locations In Acquisition (0054, 0081) is inaccurate if slices are interpolated, use Images In Acquisition (0020,1002) if available.
- New filename options %d Series description (0008,103E), %z Sequence Name (0018,0024).
- New filename options %a antenna (coil) number, %e echo number.
- Initialize unused portions of NIfTI header to zero so multiple runs always produce identical results.
- Supports 3D lossless JPEG saved as [multiple fragments](http://www.nitrc.org/forum/forum.php?thread_id=5872&forum_id=4703).

5-May-2016
- Crop 3D T1 acquisitions (e.g. ./dcm2niix -x y ~/DICOM).

30-Apr-2016
- Convert multiple files/folders with single command line invocation (e.g. ./dcm2niix -b y ~/tst ~/tst2).

22-Apr-2016
- Detect Siemens Phase maps (phase image names end with "_ph").
- Use current working directory if file name not specified.

12-Apr-2016
- Provide override (command line option "-m y") to stack images of the same series even if they differ in study date/time, echo/coil number, or slice orientation. This mechanism allows users to concatenate images that break strict DICOM compliance.

22-Mar-2016
- Experimental support for [DICOM datasets without DICOM file meta information](http://dicom.nema.org/dicom/2013/output/chtml/part10/chapter_7.html).

12-Dec-2015
- Support PAR/REC FP values when possible (see PMC3998685).

11-Nov-2015
- Minor refinements.

12-June-2015
- Uses less memory (helpful for large datasets).

2-Feb-2015
- Support for Visual Studio.
- Remove dependency on zlib (now uses miniz).

1-Jan-2015
- Images separated based on TE (fieldmaps).
- Support for JPEG2000 using OpenJPEG or Jasper libraries.
- Support for JPEG using NanoJPEG library.
- Support for lossless JPEG using custom library.

24-Nov-2014
- Support for CT scans with gantry tilt and varying distance between slices.

11-Oct-2014
- Initial public release.
[See the VERSIONS.md file for details on releases](./VERSIONS.md).

## Running

Command line usage is described in the [NITRC wiki](https://www.nitrc.org/plugins/mwiki/index.php/dcm2nii:MainPage#General_Usage). The minimal command line call would be `dcm2niix /path/to/dicom/folder`. However, you may want to invoke additional options, for example the call `dcm2niix -z y -f %p_%t_%s -o /path/ouput /path/to/dicom/folder` will save data as gzip compressed, with the filename based on the protocol name (%p) acquisition time (%t) and DICOM series number (%s), with all files saved to the folder "output". For more help see help: `dcm2niix -h`.

**Optional batch processing version:**

Perform a batch conversion of multiple dicoms using the configurations specified in a yaml file.
```bash
dcm2niibatch batch_config.yml
```

The configuration file should be in yaml format as shown in example `batch_config.yaml`

```yaml
Options:
isGz: false
isFlipY: false
isVerbose: false
isCreateBIDS: false
isOnlySingleFile: false
Files:
-
in_dir: /path/to/first/folder
out_dir: /path/to/output/folder
filename: dcemri
-
in_dir: /path/to/second/folder
out_dir: /path/to/output/folder
filename: fa3
```
You can add as many files as you want to convert as long as this structure stays consistent. Note that a dash must separate each file.
[See the BATCH.md file for instructions on using the batch processing version](./BATCH.md).

## Build

Expand Down Expand Up @@ -189,14 +53,11 @@ make

**optional batch processing version:**

The batch processing binary `dcm2niibatch` is optional. To build `dcm2niibatch` as well change the cmake command to `cmake -DBATCH_VERSION=ON ..`

This requires a compiler that supports c++11.

The batch processing binary `dcm2niibatch` is optional. To build `dcm2niibatch` as well change the cmake command to `cmake -DBATCH_VERSION=ON ..`. This requires a compiler that supports c++11.

### Building the command line version without cmake

[See the COMPILE.md file for details on manual compilation](./COMPILE.md).
If you have any problems with the cmake build script described above or want to customize the software see the [COMPILE.md file for details on manual compilation](./COMPILE.md).

## Links

Expand All @@ -209,6 +70,7 @@ This requires a compiler that supports c++11.
- [dcm2niir](https://github.com/muschellij2/dcm2niir) R wrapper for dcm2niix/dcm2nii.
- [divest](https://github.com/jonclayden/divest) R interface to dcm2niix.
- [sci-tran dcm2niix](https://github.com/scitran-apps/dcm2niix) docker.
- [neuro_docker](https://github.com/Neurita/neuro_docker) includes dcm2niix.
- [neuro_docker](https://github.com/Neurita/neuro_docker) includes dcm2niix as part of a provides a single, static Dockerfile.
- [neurodocker](https://github.com/kaczmarj/neurodocker) generates [custom](https://github.com/rordenlab/dcm2niix/issues/138) Dockerfiles given specific versions of neuroimaging software.
- [dcm2niix_afni](https://afni.nimh.nih.gov/pub/dist/doc/program_help/dcm2niix_afni.html) is a version of dcm2niix included with the [AFNI](https://afni.nimh.nih.gov/) distribution.
- [MRIcroGL](https://github.com/neurolabusc/MRIcroGL) is available for MacOS, Linux and Windows and provides a graphical interface for dcm2niix. You can get compiled copies from the [MRIcroGL NITRC web site](https://www.nitrc.org/projects/mricrogl/).
112 changes: 112 additions & 0 deletions VERSIONS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
## Versions

17-Oct-2017
- Swap [phase-encoding direction polarity](https://github.com/rordenlab/dcm2niix/issues/125) for Siemens images where PE is in the Column direction.
- Sort diffusion volumes by [B-value amplitude](https://www.nitrc.org/forum/forum.php?thread_id=8396&forum_id=4703) (use "-d n"/"-d y" to turn the feature off/on).
- BIDS tag [TotalReadoutTime](https://github.com/rordenlab/dcm2niix/issues/130) handles partial fourier, Phase Resolution, etc (Michael Harms).
- Additional [json fields](https://github.com/rordenlab/dcm2niix/issues/127).

18-Aug-2017
- Better BVec extraction for [PAR/REC 4.1](https://www.nitrc.org/forum/forum.php?thread_id=8387&forum_id=4703).
- Support for [Segami Cerescan volumes](https://www.nitrc.org/forum/forum.php?thread_id=8076&forum_id=4703).

24-July-2017
- Compiles with recent releases of [OpenJPEG](https://github.com/neurolabusc/dcm_qa/issues/5#issuecomment-317443179) for JPEG2000 support.

23-June-2017
- [Ensure slice timing always reported for Siemens EPI](https://github.com/neurolabusc/dcm_qa/issues/4#issuecomment-310707906)
- [Integrates validation](https://github.com/neurolabusc/dcm_qa)
- JSON fix (InstitutionName -> InstitutionAddress)

21-June-2017
- Read DICOM header in 1Mb segments rather than loading whole file : reduces ram usage and [faster for systems with slow io](https://github.com/rordenlab/dcm2niix/issues/104).
- Report [TotalReadoutTime](https://github.com/rordenlab/dcm2niix/issues/98).
- Fix JPEG2000 support in [Superbuild](https://github.com/rordenlab/dcm2niix/issues/105).

28-May-2017
- Remove all derived images from [Philips DTI series](http://www.nitrc.org/forum/message.php?msg_id=21025).
- Provide some [Siemens EPI sequence details](https://github.com/rordenlab/dcm2niix/issues).

28-April-2017
- Experimental [ECAT support](https://github.com/rordenlab/dcm2niix/issues/95).
- Updated cmake to make JPEG2000 support easier with improved Travis and AppVeyor support [Ningfei Li](https://github.com/ningfei).
- Supports Data/Time for images that report Data/Time (0008,002A) but not separate Date and Time (0008,0022 and 0008,0032).
- [BIDS reports SliceTiming correctly](http://www.nitrc.org/forum/message.php?msg_id=20852).
- Options -1..-9 to control [gz compression level](https://github.com/rordenlab/dcm2niix/issues/90).
- Includes some [PET details in the BIDS JSON sidecar](https://github.com/rordenlab/dcm2niix/issues/87).
- Better detection of image order for Philips 4D DICOM (reported by Jason McMorrow and Stephen Wilson).
- [Include StudyInstanceUID and SeriesInstanceUID in filename](https://github.com/rordenlab/dcm2niix/issues/94).

7-Feb-2017
- Can be compiled to use either Philips [Float or Display](http://www.nitrc.org/forum/message.php?msg_id=20213) intensity intercept and slope values.
- Handle 3D Philips DICOM and [PAR/REC](https://www.nitrc.org/forum/forum.php?thread_id=7707&forum_id=4703) files where images are not stored in a spatially contiguous order.
- Handle DICOM violations where icon is uncompressed but image data is compressed.
- Best guess matrix for 2D slices (similar to dcm2nii, SPM and MRIconvert).
- Linux (case sensitive filenames) now handles par/rec as well as PAR/REC.
- Images with unknown phase encoding do not generate [BIDS entry](https://github.com/rordenlab/dcm2niix/issues/79).
- Unified printMessage/printWarning/printError aids embedding in other projects, such as [divest](https://github.com/jonclayden/divest).

1-Nov-2016
- AppVeyor Support (Ningfei Li & Chris Filo Gorgolewski)
- Swap 3rd/4th dimensions for GE sequential multi-phase acquisitions (Niels Janssen).

10-Oct-2016
- Restores/improves building for the Windows operating system using MinGW.

30-Sept-2016
- Save ImageType (0x0008,0x0008) to BIDS.
- Separate CT scans with different exposures.
- Fixed issues where some compilers would generate erratic filenames for zero-padded series (e.g. "-f %3s").

21-Sept-2016
- Reduce verbosity (reduce number of repeated warnings, less scary warnings for derived rather than raw images).
- Re-enable custom output directory "-o" option broken by 30-Apr-2016 version.
- Deal with mis-behaved GE CT images where slice direction across images is not consistent.
- Add new BIDS fields (field strength, manufacturer, etc).
- Philips PAR/REC conversion now reports inconsistent requested vs measured TR (due to prospect. motion corr.?).
- GE: Locations In Acquisition (0054, 0081) is inaccurate if slices are interpolated, use Images In Acquisition (0020,1002) if available.
- New filename options %d Series description (0008,103E), %z Sequence Name (0018,0024).
- New filename options %a antenna (coil) number, %e echo number.
- Initialize unused portions of NIfTI header to zero so multiple runs always produce identical results.
- Supports 3D lossless JPEG saved as [multiple fragments](http://www.nitrc.org/forum/forum.php?thread_id=5872&forum_id=4703).

5-May-2016
- Crop 3D T1 acquisitions (e.g. ./dcm2niix -x y ~/DICOM).

30-Apr-2016
- Convert multiple files/folders with single command line invocation (e.g. ./dcm2niix -b y ~/tst ~/tst2).

22-Apr-2016
- Detect Siemens Phase maps (phase image names end with "_ph").
- Use current working directory if file name not specified.

12-Apr-2016
- Provide override (command line option "-m y") to stack images of the same series even if they differ in study date/time, echo/coil number, or slice orientation. This mechanism allows users to concatenate images that break strict DICOM compliance.

22-Mar-2016
- Experimental support for [DICOM datasets without DICOM file meta information](http://dicom.nema.org/dicom/2013/output/chtml/part10/chapter_7.html).

12-Dec-2015
- Support PAR/REC FP values when possible (see PMC3998685).

11-Nov-2015
- Minor refinements.

12-June-2015
- Uses less memory (helpful for large datasets).

2-Feb-2015
- Support for Visual Studio.
- Remove dependency on zlib (now uses miniz).

1-Jan-2015
- Images separated based on TE (fieldmaps).
- Support for JPEG2000 using OpenJPEG or Jasper libraries.
- Support for JPEG using NanoJPEG library.
- Support for lossless JPEG using custom library.

24-Nov-2014
- Support for CT scans with gantry tilt and varying distance between slices.

11-Oct-2014
- Initial public release.
Loading

0 comments on commit d164ee0

Please sign in to comment.