Skip to content

Latest commit

 

History

History
208 lines (168 loc) · 22.7 KB

README.md

File metadata and controls

208 lines (168 loc) · 22.7 KB
Raw

Build status

About

dcm2niix is designed to convert neuroimaging data from the DICOM format to the NIfTI format. This web page hosts the developmental source code - a compiled version for Linux, MacOS, and Windows of the most recent stable release is included with MRIcroGL. A full manual for this software is available in the form of a NITRC wiki.

The DICOM format is the standard image format generated by modern medical imaging devices. However, DICOM is very complicated and has been interpreted differently by different vendors. The NIfTI format is popular with scientists, it is very simple and explicit. However, this simplicity also imposes limitations (e.g. it demands equidistant slices). dcm2niix is also able to generate a BIDS JSON format sidecar which includes relevant information for brain scientists in a vendor agnostic and human readable form. The Neuroimaging DICOM and NIfTI Primer provides details.

License

This software is open source. The bulk of the code is covered by the BSD license. Some units are either public domain (nifti*.*, miniz.c) or use the MIT license (ujpeg.cpp). See the license.txt file for more details.

Dependencies

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 installed. You can get a version of both dcm2niix and pigz compiled for your operating system by downloading MRIcroGL.

Image Conversion and Compression

DICOM provides many ways to store/compress image data, known as transfer syntaxes. The COMPILE.md file describes details on how to enable different options to provide support for more formats.

  • The base code includes support for raw, run-length encoded, and classic JPEG lossless decoding.
  • Lossy JPEG is handled by the included NanoJPEG. This support is modular: you can compile for libjpeg-turbo or disable it altogether.
  • JPEG-LS lossless support is optional, and can be provided by using CharLS.
  • JPEG2000 lossy and lossless support is optional, and can be provided using OpenJPEG or Jasper.
  • GZ compression (e.g. creating .nii.gz images) is optional, and can be provided using either the included miniz or the popular zlib. Of particular note, the Cloudflare zlib exploits modern hardware (available since 2008) for very rapid compression. Alternatively, you can compile dcm2niix without a gzip compressor. Regardless of how you compile dcm2niix, it can use the external program pigz for parallel compression.

Versions

See releases for recent release notes. See the VERSIONS.md file for details on earlier releases.

Contribute

dcm2niix is developed by the community for the community and everybody can become a part of the community.

Running

Command line usage is described in the NITRC wiki. 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/output /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.

See the BATCH.md file for instructions on using the batch processing version.

Install

There are a couple ways to install dcm2niix

  • Github Releases provides the latest compiled executables. This is an excellent option for MacOS and Windows users. However, the provided Linux executable requires a recent version of Linux (e.g. Ubuntu 14.04 or later), so the provided Unix executable is not suitable for very old distributions. Specifically, it requires Glibc 2.19 (from 2014) or later. Users of older systems can compile their own copy of dcm2niix or download the compiled version included with MRIcroGL Glibc 2.12 (from 2011, see below).
  • Run the following command to get the latest release version for Linux, Macintosh or Windows:
    • curl -fLO https://github.com/rordenlab/dcm2niix/releases/latest/download/dcm2niix_lnx.zip
    • curl -fLO https://github.com/rordenlab/dcm2niix/releases/latest/download/macos_dcm2niix.pkg
    • curl -fLO https://github.com/rordenlab/dcm2niix/releases/latest/download/dcm2niix_win.zip
  • Latest development version is available on AppVeyor for Linux, Macintosh or Windows.
  • MRIcroGL (NITRC) or MRIcroGL (GitHub) includes dcm2niix that can be run from the command line or from the graphical user interface (select the Import menu item). The Linux version of dcm2niix is compiled on a holy build box, so it should run on any Linux distribution.
  • If you have a MacOS computer with Homebrew or MacPorts you can run brew install dcm2niix or sudo port install dcm2niix, respectively.
  • If you have Conda, conda install -c conda-forge dcm2niix on Linux, MacOS or Windows.
  • If you have pip, python -m pip install dcm2niix on Linux, MacOS or Windows.
  • On Debian Linux computers you can run sudo apt-get install dcm2niix.

Build from source

It is often easier to download and install a precompiled version. However, you can also build from source.

Build command line version with cmake (Linux, MacOS, Windows)

cmake and pkg-config (optional) can be installed as follows:

Ubuntu: sudo apt-get install cmake pkg-config

MacOS: brew install cmake pkg-config or sudo port install cmake pkgconfig

Once these tools are available, you can compile with cmake:

git clone https://github.com/rordenlab/dcm2niix.git
cd dcm2niix
mkdir build && cd build
cmake -DZLIB_IMPLEMENTATION=Cloudflare -DUSE_JPEGLS=ON -DUSE_OPENJPEG=ON ..
make

dcm2niix will be created in the bin subfolder. To install on the system run make install instead of make - this will copy the executable to your path so you do not have to provide the full path to the executable.

In rare case if cmake fails with the message like "Generator: execution of make failed", it could be fixed by sudo ln -s `which make` /usr/bin/gmake.

Building the command line version without cmake

This is the simplest way to compile dcm2niix on a Linux or MacOS computer. Be warned that this minimal version will not be able to extract DICOM images compressed with the (rarely used) JPEG2000 or JPEG-LS formats.

git clone https://github.com/rordenlab/dcm2niix.git
cd dcm2niix/console
make
./dcm2niix

Referencing

  • Li X, Morgan PS, Ashburner J, Smith J, Rorden C (2016) The first step for neuroimaging data analysis: DICOM to NIfTI conversion. J Neurosci Methods. 264:47-56. doi: 10.1016/j.jneumeth.2016.03.001. PMID: 26945974

Alternatives

  • BIDS-converter hosts Matlab and Python scripts for PET images, supporting DICOM and ECAT (ecat2nii) formats.
  • dcm2nii is the predecessor of dcm2niix. It is deprecated for modern images, but does handle image formats that predate DICOM (proprietary Elscint, GE and Siemens formats).
  • Python dcmstack DICOM to Nifti conversion with meta data preservation.
  • dicm2nii is written in Matlab. The Matlab language makes this very scriptable.
  • dicom2nifti uses the scriptable Python wrapper utilizes the high performance GDCMCONV executables.
  • dicomtonifti leverages VTK.
  • dimon and to3d are included with AFNI.
  • dinifti is focused on conversion of classic Siemens DICOMs.
  • DWIConvert converts DICOM images to NRRD and NIfTI formats.
  • mcverter a great tool for classic DICOMs.
  • mri_convert is part of the popular FreeSurfer package. In my limited experience this tool works well for GE and Siemens data, but fails with Philips 4D datasets.
  • MRtrix mrconvert is a useful general purpose image converter and handles DTI data well. It is an outstanding tool for modern Philips enhanced images.
  • nanconvert uses the ITK library to convert DICOM from GE and proprietary Bruker to standard formats like DICOM.
  • Plastimatch is a Swiss Army knife - it computes registration, image processing, statistics and it has a basic image format converter that can convert some DICOM images to NIfTI or NRRD.
  • Simple Dicom Reader 2 (Sdr2) uses dcmtk to read DICOM images and convert them to the NIfTI format.
  • SlicerHeart extension is specifically designed to help 3D Slicer support ultra sound (US) images stored as DICOM.
  • spec2nii converts MR spectroscopy to NIFTI.
  • SPM12 is one of the most popular tools in the field. It includes DICOM to NIfTI conversion. Being based on Matlab it is easy to script.

Links

The following tools exploit dcm2niix