Most medical imaging devices store images in variations of the complicated DICOM format. Many scientific tools expect medical images to be stored in the simpler NIfTI format. My dcm2nii is a popular tool for this. However, dcm2nii was initially developed before the NIfTI format as well as many modern variations of the DICOM format. In response I have created dcm2niix as a modern tool written in the C language. The advantages of the new tool is that it is simple (easier to adapt to vendor extensions to DICOM), easier to specify output file names, and written in a more popular language (C versus Pascal). It is also substantially faster, though image conversion is typically not a major factor in image analysis. The disadvantages of dcm2niix is that it is less heavily tested (and therefore may include bugs) and drops support for legacy image formats (if you are doing a archival study of images collected over a decade ago you should use dcm2nii as it supports ancient proprietary formats that predate DICOM). Both dcm2nii and dcm2niix can also convert proprietary Philips PAR/REC images to NIfTI. There are a lot of alternative tools from other developers. In particular, if you use Matlab I recommend Xiangrui Li's dicm2nii. Another nice alternative is Jolinda Smith's MRIconvert. In general, all these tools will produce similar results for MRI data from the major vendors (Siemens, GE, Philips). However, due to my team's exposure to large clinical datasets I think dcm2nii and dcm2niix may be more suitable for clinical environments (e.g. support for MRI or CT perfusion data where images are stored in color rather than grayscale and one needs to parse non-imaging related DICOM files like patient notes and sound files).
You can download compiled applications as well as the raw source code here:
Source code and compilation instructions (using make or cmake) is available from the GitHub web page.
The only required argument for dcm2niix is the location of the folder with the DICOM files to convert, which is always the final argument provided. For example "dcm2niix ~/dicomdir" will convert all the DICOM files found in the folder "dicomdir". However, you can specify optional arguments that influence conversion. So a typical conversion might look like "dcm2niix -o ~/niftidir -f %p_%s -g y ~/dicomdir". In this example, the software finds DICOM images in dicomdir and saves the converted NIfTI files in niftidir, the output files will be compressed and have file names that include the protocol name (%p) and series number (%s). Here is a list of options (you can also see a list of all the commands by running the command "dcm2niix" without any arguments). Here are notes on the arguments:
The previous section describes how the one can control the name of output files using the '-f' argument. For example, if you use "-f %p_%s" the output file name will be based on the DICOM protocol name and the series number.
However, certain situations will cause dcm2niix to append extra information to the filename to help disambiguate additional dimensions. The Github filenaming page provides a definitive guide to these values. These are briefly described below:
- _c1.._cN coil ID (only seen if saved independently for each coil) - _e2..eN additional echoes (the first echo is implicit) - _ph phase map - _imaginary imaginary component of complex image - _real real component of complex image - _phMag rare case where phase and magnitude are saved as the 4th dimension - _t If the trigger delay time (0020,9153) is non-zero, it will be recorded in the filename. For example, the files "T1_t178.nii" and "T1_t511" suggests that the T1 scan was acquired with two cardiac trigger delays (178 and 511ms after the last R-peak). - _ADC Philips specific case DWI image where derived isotropic, ADC or trace volume was appended to the series. Since this image will disrupt subsequent processing, and because subsequent processing (dwidenoise, topup, eddy) will yield better derived images, dcm2niix will also create an additional image without this volume. Therefore, the _ADC file should typically be discarded. If you want dcm2niix to discard these useless derived images , use the ignore feature ('-i y'). - _Eq is specific to [CT scans](https://www.nitrc.org/plugins/mwiki/index.php/dcm2nii:MainPage#Computed_Tomography_.28CT.2C_CAT.29). These scans can be acquired with variable distance between the slices of a 3D volume. NIfTI asumes all 2D slices that form a 3D stack are equidistant. Therefore, dcm2niix reslices the input data to generate an equidistant volume. - _Tilt is specific to [CT scans](https://www.nitrc.org/plugins/mwiki/index.php/dcm2nii:MainPage#Computed_Tomography_.28CT.2C_CAT.29). These scans can be acquired with a gantry tilt that causes a skew that can not be stored in a NIfTI qForm. Therefore, the slices are resampled to remove the effect of tilt.
To convert images you need to specify the folder you wish to convert. So the minimal command will look like this 'dcm2niix c:\dir'. You can also drag and drop a folder onto the application to convert all the files in your folder. This minimal command will choose the default compression, default file name and the default output folder. To explicitly set these you would run a command that looks like 'dcm2niix -z y -f myMRI%s -o "c:\outdir" "c:\dir with spaces\dir2"'. Here we are specifying that we want to create compressed .nii.gz files (-z y) and that we want the files to have a name that looks like 'myMRI33' (for the 33rd series, -f myMRI%s) and to save converted images to the folder c:\outdir). Note that we need to use double quotes to specify a folder if it has white space in its name. If you omit the -o command the NIfTI images will always be created in the input folder. To edit the default compression and filename values, open the dcm2nii.ini file that is in the same location as the application (if this file does not exist, run dcm2niix and it will be generated for you)
To convert images you need to specify the folder you wish to convert. So the minimal command will look like this 'dcm2niix /users/chris/dir'. You can either provide the name of a folder that includes your DICOM images ('dcm2niix /home/cr/dcm') or the path to a single image 'dcm2niix /home/cr/dcm/img.dcm') and the software will search for all the appropriate images in the parent folder (/home/cr/dcm) and children folders (/home/cr/dcm/dir). However, you should not specifies files with a wild card ('dcm2niix /home/cr/dcm/*.dcm' as some operating systems will automatically expand this list prior to calling dcm2niix and you will get a crash perhaps with a cryptic message like "Argument list too long”. For Linux (but not OSX) you can also drag and drop a folder onto the application to convert all the files in your folder. This minimal command will choose the default compression, default file name and the default output folder. To explicitly set these you would run a command that looks like 'dcm2niix -z y -f myMRI%s -o "users/chris/outdir" /users/chris/dir'. Here we are specifying that we want to create compressed .nii.gz files (-z y) and that we want the files to have a name that looks like 'myMRI33' (for the 33rd series, -f myMRI%s) and to save converted images to the folder users/chris/outdir). If you omit the -o command the NIfTI images will always be created in the input folder (in this example /users/chris/dir). To edit the default compression and filename values, run the command 'open -a textedit ~/.dcm2nii.ini' (on OSX) or 'gedit ~/.dcm2nii.ini &' (on Linux, assuming you have the text editor edit installed). If the hidden file ~/.dcm2nii.ini does not exist, run the program once to create this file.
MRIcroGL includes a simple graphical user interface for controlling dcm2niix. After launching MRIcroGL choose the Import/ConvertDICOMtoNIfTI menu item. The interface is shown in the figure below. The check box sets whether the output will be compressed (creating .nii.gz files) or uncompressed (creating .nii files). You can then specify the desired output filename, using the format described in the "General Usage" section of this web page. When you adjust the desired output name, the software will display an example for how your files will appear. You can also select whether you want to save the output to a specific folder or whether the NIfTI images should be created in the same folder as the input DICOM files. The final step is to drag and drop the folder you wish to convert onto the application. Note that the interface always interactively shows you the command line, so as you interact with the interface by selecting checkboxes you are creating a text command you can copy and paste into your favorite script.
Note that NIfTI and DICOM encode space differently, as shown in the figure. NIfTI follows the Talairach/MNI coordinate system where the X value increases as we move toward the participant's right, the Y increases as we move anteriorly. In contrast, for bipeds DICOM specifies the the X increases as we more toward the participant's left, while the Y increases as we move posteriorly. Both agree that the Z coordinate increases as we move superiorly. For brains, we generally set the origin of the coordinate system to the anterior-commissure, with the brain horizontal along the plane defined by the anterior and posterior commissure. In general DICOM MRI data report the origin as the magnet iso-center, and DICOM CT reports the origin as the table center. Note that DICOM coordinates are different for quadruped brains and that there are several competing coordinate systems for rodent brains. How a system encodes coordinates is separate from how we choose to visualize these coordinates. One should be aware of the competing neurological versus radiological conventions for image display. However, that topic is specific to image display and not image conversion.
By convention, DICOM images are saved to disk in the order we read English: with the first line at the top of the screen and subsequent lines descending. In contrast, the default behavior of NIfTI if for the first line to be at the bottom of the screen and subsequent lines ascending, the way we draw the Y-coordinate of a Cartesian grid. While these are the defaults for image space, the actual relationship of the voxels to world-space are encoded by spatial transforms (e.g. the NIfTI SForm and QForm). Unfortunately, software that is not aware of these conventions may display images unusually. For example, MIPAV assumes the DICOM convention so NIfTI images tend to appear upside down. On the other hand, FSL assumes the NIfTI convention, regardless of orientation. Fortunately, many software tools (MRIcroGL, FSLeyes, SPM) take the spatial transforms into account and show images correctly regardless of the order of voxels as stored on the disk.
The Brain Imaging Data Structure (BIDS) defines a format for the file names, folder structures and file types for neuroimaging data. While dcm2niix does create BIDS-compatible NIfTI and JSON files, it does not replicate the file names and folder hierarchy described by BIDS. The dcm2niix website includes links and details for several scripts that use dcm2niix to create fully BIDS compliant datasets. These include
There are many alternative DICOM to NIfTI converters. Below I list some of the attributes for a few of the most popular converters. It is worth noting that many of these come from centers with Siemens scanners. While GE and Philips make terrific scanners, users need to be particularly vigilant when using these tools.
The speed of conversion is probably the least important reason for choosing a DICOM to NIfTI converter. The time you spend converting data will be only a fraction of the time required to process your data. You should choose a tool that works with your data and that you can integrate with your other tools. However, speed is the easiest to quantify, so the table below shows the time to convert typical datasets (45 minutes of acquisition time) from the three major vendors. The times are shown relative to dcm2niix, which required 0.26, 3.38 an 5.2s to convert GE, Philips and Siemens datasets.
Tool | GE | Philips | Siemens |
dcm2niix | 1.0 | 1.0 | 1.0 |
dinifti | - | - | 1.3 |
dcm2nii | 2.3 | 2.1 | 2.6 |
dicm2nii | 42.4 | 3.0 | 5.1 |
dicom2nifti | 5.4 | 26.3 | 3.1 |
dcmstack | 193.1 | - | 13.8 |
mcverter | 2.3 | 19.7 | 16.1 |
mri_convert | 39.0 | - | 40.1 |
spm12 | - | - | 40.1 |
Conventional fMRI generates a 3D image of the brain by rapidly acquiring a series of 2D slices. The 'echo planar images' see different slices in the brain at different times. For example an ascending axial acquisition would observe an inferior slice slightly before a more superior slice. Correcting for these differences can improve your statistics I discuss slice timing correction in more detail on a dedicated web page, which also explains how you can test the order for your own sequence. My software should correctly detect slice order for data from Siemens scanners. However, it does not attempt to correct slice timing (you can use SPM's 'slice timing' or FSL's slicetimer for that).
In general no personal data is converted. The exception to this is if you specify filenames with the %i, %n, %t parameters, which will store the patient ID, patient name, or scan date/time as part of the filename. The software will create generate a bit of text that is stored in the NIfTI "description" field that will look like this "TE=2.7;Time=134808.242;phase=1" - note that the acquisition time is stored as the as hours, minutes and seconds in HHMMSS.SSSS with leading zeros removed. Time can be helpful for synchronizing your images with physiological measures).
This software should correctly preserve the spatial orientation of your scan using the matrix (SForm) and quaternions (QForm) of the NIfTI header. Tools like SPM, MRIcroGL and MRIcron use this information to reorient your images. However, some software may ignore this information.
Diffusion Tensor Imaging (DTI) allows tractography by acquiring a series of images with different gradient directions (B-vectors). White matter fiber tracts appear bright if they run perpendicular to the gradient direction. Here I discuss how to validate that your DTI images are converted correctly, for general DTI notes see my tutorial and advanced tutorials. The goal of dcm2niix is to create FSL format bvec/bval files for processing. Note that this format has unusual expectations regarding the orientation of the images.
A crucial concern is ensuring that the gradient directions are reported in the frame of reference expected by the software you use to fit your tractography. My software should generate a ".bvec" file that reports the tensors as expected by FSL's dtifit, where vectors are reported relative to image frame of reference (rather than relative to the scanner bore). To check that everything is processed correctly, convert the images from DICOM (or PAR/REC) to NIfTI and then use dtifit to process the data (here is a handy Matlab script that runs eddy current correction, scalp-strips the image, runs dtifit and then launches FSLview). After processing you should be able to load your image into FSLview as shown in the image - I like using the 'lines' function to ensure that the everything looks correct (corpus callosum running left right, pyramidal tract running head-foot and the body of the arcuate fascicles running anterior-posterior). I strongly recommend that users check validate the b-vector directions for their hardware and sequence as described in a dedicated document.
I strongly recommend that you acquire a test sequence using your protocol. Specifically, I suggest acquiring one image oriented with the scanner bore and one where a rotation is applied (as shown in the samples above). There are many possible scanner settings, and it is not clear that all dti fitting software has the same spatial conventions as dtifit. The NAMIC page includes notes for gradient conversion. Siemens and Philips report gradient direction with respect to the scanner bore. These are converted to using an algorithm from Matthew Robson. In contrast, GE reports directions relative to the image plane. For GE data one must adjust for whether the phase encoding direction (0018,1312) was rows or columns. It is also important to ensure that the GE data is stored to disk in spatially ascending order (e.g. first slice closest to the foot): it appears that the order of the image number (0020,0013) is arbitrary depending on how the scan was planned (so on different sessions the same protocol can create images with opposite slice orders). The examples above illustrate these issues, and hopefully my software deals with them for you.
Note that Philips systems often store an average image along with the raw data (this volume looks like an ADC map, and the bvec file reports a vector of 0,0,0 while the bval file reports a non-zero value). This average image can disrupt subsequent processing that expects only the raw data. In these cases, my software will create a second dataset with the prefix 'x' where this average image is removed. This saves you the hassle of running tools like fslsplit and fslmerge to remove these images.
This section provide historical datasets. Both the DICOM standard and the vendor's interpretation of the standard has changed over the years. These datasets help validate that dcm2niix and other tools can handle archival datasets.
This section provides sample DICOM datasets for unusual forms of MRI and comments regarding how dcm2niix handles these files.
Some details from the DICOM PET isotope module attributes (C.8-57) will be stored in BIDS JSON text file. These include RadionuclidePositronFraction, RadionuclideTotalDose, RadionuclideHalfLife, DoseCalibrationFactor, IsotopeHalfLife, and Dosage.
As a rule of thumb, most DICOM images can be viewed by sorting the image instance number (0020,0013). However, this is not required by the DICOM standard. Be aware that some Philips images report the instance number in reverse order of the AcquisitionTime (0008,0032). For these images, dcm2niix will sort based on the PET Image Module's Image Index (0054,1330) or FrameReferenceTime (0054,1300). Therefore, be aware that images converted by dcm2niix may appear differently than other popular visualization tools, such as Horos. This is a feature of dcm2niix, not an issue.
CT scans often pose two challenges for conversion to NIfTI format and scientific analysis. First, the image slices are often skewed relative to each other due to Gantry/DetectorTilt (reported in the DICOM tag 0018,1120). Second, the slices are often not equidistant, typically with many thin slices near the brain stem and a few thicker slices near the top of the brain. This is a problem because the NIfTI format specifies that all slices must be equidistant. The latest versions of dcm2nii (""24Nov2014"" and later) solves this by generating two images - one with the raw slices and the second with the slice thickness and skew corrected through interpolation. In addition, please note that CT scans are typically taken at an oblique angle relative to the MRI convention: the axial slices look like an angle between axial and coronal MRI scans. Therefore, CT scans are usually very far away from the AC-PC horizontal plane used by neuroimaging templates. You may want to manually reorient your image's matrix (using SPM's Display) or use a coregistration routine prior to a conventional normalization.
You should visually inspect the results of these corrections. Some Matlab tools will remove the influence of Gantry Tilt in a DICOM image but do not change the reported Gantry Tilt in the DICOM header. In this case running dcm2nii (or the Matlab script again) will create an image tilted in the wrong direction. Fortunately, dcm2nii will save both the uncorrected and corrected image, so in this case you would simply want to use the uncorrected image. Further, it appears that different manufacturers use this value differently: for GE scanners both positive and negative tilts appear to cause the same skew, while this is not the case for Philips. If dcm2nii does not correctly adjust your images please contact the dcm2nii development team.
If your images have a gantry tilt you should also make sure that the slice thickness converted correctly. Slice thickness is reported in the DICOM header (0018,0050), however vendors have used this tag differently for MRI scans (sometimes not including slice gap in this value). Therefore, most DICOM conversion software uses patient position (0020,0032) between successive slices to compute slice thickness. Yet, when a CT scan has gantry tilt, the image volume is skewed and the slices are not orthogonal to the scanner bed. You can derive the correct answer with trigonometry. For example, patient positions 5.636mm apart with a tilt of 27-degrees have an inter-slice distance of 5mm (in Excel "=5.637*cos(radians(27.5))"). Recent versions of dcm2nii (2015 and later) should correctly deal with this issue.
Some users want slices of their CT scan stacked into 3D volumes regardless of the XRay current, while other users want to keep these separate. The default beavhior of dcm2niix is to keep each exposure as a separate file. If you see the warning while converting images "slices not stacked: X-Ray Exposure varies (exposure 20, 12; number 1, 1). Use 'merge 2D slices' option to force stacking", you can run the software again with the "-m y" parameter to force the exposures to be saved as a single volume.
Here are some sample CT scans in DICOM format. These images provided by Philips Medical and distributed with permission.
The image data can be stored using a many different formats, referred to as Transfer Syntaxes, some of which have been retired. Fortunately, virtually all MRI scans are saved as raw format, but other modalities (CT, ultrasound) sometimes use different formats. Using a DICOM viewer like Horos you can display the DICOM header and read the Transfer Syntax UID (group,element 0002,0010). This table reports supported formats:
Syntax | Format | Supported |
---|---|---|
1.2.840.10008.1.2 | raw litte-endian (implicit) | YES |
1.2.840.10008.1.2.1 | raw litte-endian | YES |
1.2.840.10008.1.2.2 | raw big-endian | YES |
1.2.840.10008.1.2.4.50 | JPEG-lossy | YES |
1.2.840.10008.1.2.4.51 | JPEG-lossy (Processes 2 & 4) | NO |
1.2.840.10008.1.2.4.57 | JPEG-lossless | YES |
1.2.840.10008.1.2.4.70 | JPEG-lossless | YES |
1.2.840.10008.1.2.4.80 | JPEG-LS-lossless | YES+ |
1.2.840.10008.1.2.4.81 | JPEG-LS-lossy | YES+ |
1.2.840.10008.1.2.4.90 | JPEG2000-lossless | YES+ |
1.2.840.10008.1.2.4.91 | JPEG2000-lossy | YES+ |
1.2.840.10008.1.2.4.100 | MPEG2-lossy | NO |
1.2.840.10008.1.2.4.102 | MPEG4-lossy | NO |
1.2.840.10008.1.2.4.103 | MPEG4-lossy | NO |
1.2.840.10008.1.2.1.99 | Deflate | NO |
1.2.840.10008.1.2.4.94 | JPIP | NO |
1.2.840.10008.1.2.4.95 | JPIP-Deflate | NO |
1.2.840.10008.1.2.5 | Run-length encoding | YES |
1.3.46.670589.33.1.4.1 | Philips-private-RLE | YES |
Support for the JPEG-LS and JPEG2000 formats is optional (as noted by the + symbol in the table). The JPEG-LS conversion uses CharLS. Support for JPEG2000 uses OpenJPEG. if your copy of dcm2niix was compiled to support JPEG2000, it will report using the OpenJPEG library, for example "dcm2niiX version v1.0.20170609 (OpenJPEG build)". If your version of dcm2nii is unable to convert your images you will receive a message "Unsupported transfer syntax". You can get a version that supports this format from github.
If your image is not supported by dcm2niix you can usually use dcmtk (see links in table above), gdcmconv, or Horos (File/ExportToDICOMFiles menu item) to convert your compressed DICOM to an uncompressed DICOM. You can then convert the uncompressed data with dcm2niix.
If you use one of these tools to convert your compressed DICOM files to uncompressed DICOMs you should carefully inspect the results. In my experience, some of these tools strip out the vendor proprietary tags that can contain important information (e.g. slice acquisition order, diffusion gradient direction, etc). I have also seen them change the VRs for some of the used for vendor-specific information. My own suggestion is to always store your DICOM files in raw format and use common file compression (e.g. zip format) if you wish to reduce the disk space required for your data. Here are my reasons for avoiding image-based compression:
Philips MRI systems typically save data as DICOM images, however research sites can also export data to Philips' proprietary PAR/REC format, where each dataset is saved as two files: a text file that describes the image properties (.PAR) and a second file (.REC) that stores the raw image data. You can convert these with dcm2niix in two ways: (a) with the graphical user interface press the 'Select files' button and select the PAR file you wish to convert (b) from the command line specify the location of the PAR file ("./dcm2niix ~/dir/img.PAR"). You will get an error if there is not a REC image in the same folder as the PAR header. In general, dcm2niix should handle these conversions without problems. However, this is not a commonly used feature, so use with caution. It should be noted that Philips has deprecated the PAR/REC format, and now provides a direct NIfTI export. Saving your data as DICOM format instead of PAR/REC is a good idea for archival purposes.
For sample PAR/REC images see the Unusual MRI section, the DTI section. You can also find example PAR/REC images at these external locations:
The DICOM standard is very complex, and different vendors have interpreted it differently. Accurate conversion to NIfTI format requires reading the vendor's private tags. Often new software upgrades alter these quasi-proprietary formats. Therefore, DICOM converters are constantly adapting to stay current. It is strongly recommended that you validate your sequences prior to beginning a large study. Ideally, if you can generate a sequence that is not converted correctly you are encouraged to submit it to the Rosetta Bit project so the community can develop a suitable work-around. Here are a couple comments to bear in mind.
dcm2niix uses the the BSD-2-Clause license. The software can be optionally compiled to support different compressed transfer syntaxes using libraries written by others (e.g. OpenJPEG, CharLS, Jasper). Each of these includes its own open source compatible license (BSD or MIT, so without the restriction of GPL). For more details, see the license on Github.
This NITRC web page includes links to many DICOM images in zip format. The page includes attribution to the individuals who provided the data, and all individuals agreed to allow the images to be made public under the BSD-2-Clause. This only refers to the direct downloadable zip files: the Sample DICOM Images contains external links to images that use a variety of licenses.
If you wish to cite this tool or learn more about the challenges of converting DICOM images please see Li et al., 2016, PMID: 26945974
Note several DICOM datasets are linked in previous sections of this web page.