dcm2nii DICOM to NIfTI conversion
  Introduction

Important note: dcm2nii is obsolete. While I hope it is generally robust and useful, active development has moved to dcm2niix. In general, dcm2niix is typically better suited for modern DICOM images. On the other hand, dcm2nii is useful for archival studies with legacy proprietary format that predated DICOM. This software is provided under the BSD 2-Clause license.

DCM2NII attempts to convert images from the proprietary scanner format to the NIfTI format used by FSL, SPM5, MRIcron and many other brain imaging tools. NIfTI is a modern incarnation of the Analyze format, but includes important information like the orientation of the image. DCM2NII is a stand-alone program that is distributed with MRIcron. It is natively compiled for Windows, Linux x86, Mac OSX PPC and Mac OSX x86.


The NIfTI image format standard was designed for scientific analysis of brain images. The format is simple, compact and versatile. The images can be stored as a pair of files (hdr/img, compliant with most Analyze format viewers), or a single file (nii). Programs like FSL and MRIcron can also read compressed (nii.gz) images. One nice feature about NIfTI is that the format attempts to keep spatial orientation information. Therefore, NIfTI software that can read the spatial information (MRIcron and SPM5) should reduce your chance of making left-right errors. Also, software like SPM5 will tend to be more accurate at coregistering images, as all the images from an individual can use the scanner position as a beginning estimate for alignment. For example, here are two scans from the same individual (the sagittal T1 is shown in grayscale, and the coronal FLAIR is shown in reds). Note that the scans were acquired with different orientations (with the FLAIR along the axis of the hippocampus), however MRIcron shows the image orientation correctly. NIfTI image transform

Installation

  1. Follow the instructions to install MRIcron on your hard disk - this should create a program named dcm2nii.exe (Windows) or dcm2nii (Unix).
  2. Double click on dcm2nii.exe - a file named dcm2nii.ini will be created. If you are using Windows, this file is in the same folder as dcm2nii. If you are using Unix (Linux, OSX) then this file is created in your home directory.
  3. (optional) Open dcm2nii.ini with a text editor (double click on the file). You will be able to adjust the settings:
    Text Description
    [BOOL]
    AnonymizeSourceDICOM=0 If '=1' then dcm2nii will create anonymized copies of DICOM images (remove name, DOB, patient ID, sex). No other conversion will occur.
    ManualNIfTIConv=1 If '=1' then dcm2nii will prompt user to describe output subformat for every NIfTI image dragged onto the program. Otherwise, subformat will be based on $D, SingleNIIFile,SPM2 settings.
    4D=1 If '=1' then dcm2nii will generate 4D files (FSL style), otherwise output will be 3D (SPM style).
    Anonymize=1 If '=1' then patient name will not be copied to NIfTI header.
    SingleNIIFile=1 If '=1' then dcm2nii will create .nii files (FSL style), otherwise .hdr/.img pairs will be created (SPM style)
    Gzip=0 If '=1' then dcm2nii will create compressed .nii.gz files (FSL style).
    SPM2=0 If '=1' then dcm2nii will create Analyze images (SPM2 style), otherwise headers will be in NIfTI (SPM5/FSL).
    AppendDate=1 If '=1' then output filename will include date of study.
    AppendAcqSeries=1 If '=1' then output filename will include acquisition number.
    AppendProtocolName=1 If '=1' then output filename will include protocol name.
    AppendPatientName=0 If '=1' then output filename will include patient name.
    AppendFilename=0 If '=1' then output filename will include source filename.
    EveryFile=1 If '=1' then all .par/.rec files in the source folder will be converted, otherwise only the file specified will be converted
    [INT]
    BeginClip=0 Specifies number of volumes to be removed from the beginning of a 4D acquisition (e.g. avoid T1 effects)
    LastClip=0 Specifies number of volumes to be removed from the end of a 4D acquisition (e.g. fMRI scanning continued after behavioral paradigm ended).
    usePigz=0 Only influences .gz files. If 0 then files are compressed using the (single threaded) internal gzip compression routine. If 1 then files will be compressed using the parallel pigz compressor (allowing pigz to select the number of threads). In general, pigz is faster than the inbuilt compressor. You can also specify a value of greater than 1 to explicitly set the number of threads - for example '3' will set pigz to use 3 threads. The software also allows you to specify negative values. These are identical to positive values except that dcm2nii does not wait for pigz to complete before continuing to process files. For example -2 will have pigz compress the current image with 2 threads while simultaneously allowing dcm2nii to convert other images. Not that with negative values pigz may be compressing multiple files simultaneously which may cause 'disk thrashing' or thread contention. Therefore, negative values should be used with caution and a provided for evaluation purposes only.
    MinReorientMatrix=255 Images with a larger matrix size than this value will be reoriented to canonical space (see below).
    OutDirMode=0 Value will be 0, 1 or 2. If 0, output will be saved to same folder as source (this will cause problems if you try to convert a read-only media, such as a CD-ROM). If 1, the user will be prompted to find an output folder. If 2, the data will be saved to the folder "OutDir" (see below).
    [STR]
    OutDir=/home/crlab If OutDirMode is set to 2 (see above), then converted files will be saved to this folder.


  4. With each option listed under the heading [BOOL], add a '1' for yes and a '0' for no. For example, if you want to have images saved as .hdr/.img pairs, set SingleNIIFile to 0. If you want to save images a single .nii files, set this to 1. The append options adjust the output filenames. For example, if you had both AppendDate and AppendProtocolName set to 1, the converted images would have names such as 20060331_123456anat1x1x1.nii if the data session was acquired on 31 March 2006 at 12:34:56 and the protocol was called 'anat1x1x1'. The last two values (listed under the heading [INT]) except integer values - for example if you set 'LastClip=8' then the last 8 volumes of every 4-dimensional dataset will not be saved (e.g. if you had an fMRI dataset with 120 volumes, only the first 111 volumes would be converted). A fuller description of these options is in the gray box below.

Running DCM2NII

There are two ways to run dcm2nii

  1. You can either drag and drop files onto the program - this will convert the images using the values in your dcm2nii.ini file (see above).
  2. You can launch dcm2nii from the command line, specifying specifically the options to use.

To use dcm2nii by dragging and dropping:

  1. Place all the DICOM (or Philips PAR/REC) images you wish to convert into a folder where you have write access.
  2. Drag and drop one of the images onto dcm2nii. 
  3. You can now vew the images with MRIcron, SPM5, FSL, or other Analyze/NIfTI viewers.
To see your options for running dcm2nii from the command line, simply execute the program without specifying any files (e.g. just double click on the program to launch it). The available options will the be written to the screen:
Chris Rorden's dcm2nii :: 12 12 2012
reading preferences file /Users/rorden/.dcm2nii/dcm2nii.ini
Either drag and drop or specify command line options:
dcm2nii
OPTIONS:
-a Anonymize [remove identifying information]: Y,N = Y
-b load settings from specified inifile, e.g. '-b C:\set\t1.ini'
-c Collapse input folders: Y,N = Y
-d Date in filename [filename.dcm -> 20061230122032.nii]: Y,N = Y
-e events (series/acq) in filename [filename.dcm -> s002a003.nii]: Y,N = Y
-f Source filename [e.g. filename.par -> filename.nii]: Y,N = N
-g gzip output, filename.nii.gz [ignored if '-n n']: Y,N = Y
-i ID in filename [filename.dcm -> johndoe.nii]: Y,N = N
-m manually prompt user to specify output format [NIfTI input only]: Y,N = Y
-n output .nii file [if no, create .hdr/.img pair]: Y,N = Y
-o Output Directory, e.g. 'C:\TEMP' (if unspecified, source directory is used)
-p Protocol in filename [filename.dcm -> TFE_T1.nii]: Y,N = Y
-r Reorient image to nearest orthogonal: Y,N
-s SPM2/Analyze not SPM5/NIfTI [ignored if '-n y']: Y,N = N
-v Convert every image in the directory: Y,N = Y
-x Reorient and crop 3D NIfTI images: Y,N = N
You can also set defaults by editing /Users/rorden/.dcm2nii/dcm2nii.ini
EXAMPLE: dcm2nii -a y /Users/Joe/Documents/dcm/IM_0116


Reorienting to canonical space

The NIfTI format stores spatial transforms so that software can determine the oreintation of the image. This means that MRIcron can display the image with an intuitive orientation. However, many programs ignore these transforms, and display the images as they are saved to disk (e.g. FSLview, MRIcro) - this means that a sagittally acquired scan appears very differently from an axially acquired scan. In fact, the three spatial dimensions (left-right, anterior-posterior, superior-inferior) can be saved in 48 different orthogonal orientations. The drawing below shows just three of these possible orientations. Orthogonal orientations
You can set dcm2nii to reorient all images so they are all aligned to the nearest orthogonal direction to 'canonical space' (i.e. as close as possible to the rotation matrix [1 0 0; 0 1 0; 0 0 1]). This means programs like FSLview and MRIcro will display the images in a sensible orientation, regardless of the acquisition. The NIfTI transform codes the residual oblique orientations, so no information is lost in this tranformation. However, you will only want to orient anatomical scans to canonical space - reorienting fMRI data can disrupt slice timing correction (as the software assumes that the slice order of the stored data is correlated with the time of acquisition). Reorienting can also disrupt analysis of the DTI data (as the diffusion directions are not adjusted for the change in image orientation). Therefore, the "MinReorientMatrix" allows you to adjust which images will be reoriented - a value of 255 ensures that T1/T2 scans (typically with a 256x256 matrix) are reoriented, while fMRI (~64x64) and DTI (~128x128) scans are not. If you do not want any scans reoriented, reset this to a very large value (e.g. 5000).

After reorienting, dcm2nii will attempt to 'autocrop' T1-weighted anatomical images (images with a Echo Time [TE] of less than 20ms). A new copy of the image is created with the prefix 'c' that attempts to remove excess air surrounding the individual as well as parts of the neck below the cerebellum. This excess neck can disrupt normalization of images (as the template images do not have similar neck regions). This new image has a slightly different NIfTI transform - the origin is adjusted to compensate for the removed portions of the image. The image below shows a T1-weighted scan before and after cropping.
Orthogonal orientations
As a final note, reorienting images is useful if you want to create masks for an image to use with SPM or FSL. These programs require that the mask image has precisely the same dimensions as the image it is designed to mask. In these cases, you can not apply the precise spatial transforms to an image (as the oblique orientation corrections means that the resulting drawing will have different dimensions than the original image. Therefore, you will want to draw a mask on on a image that has not used the fine spatial transforms. You can use MRIcro or FSLview to do this (as they ignore these transforms). If yu use MRIcron, select Help/Preferences and uncheck the 'Reorient (reslice) images when loading' option - this will ensure that the raw image is loaded. Regardless of which software you use, having a canonically aligned image will mean that the image will be displayed in a sensible manner.

Diffusion data

Diffusion sequences are sensitive to the random spontaneous motion of water molecules. This movement is anisotropic in fiber bundles - in other words it preferentially moves up and down the fibers whereas motion across the fiber is constrained. Diffusion tensor imaging (DTI) use different gradient directions so that different images are sensitive to specific directions. In order to process this data with medINRIA or FSL, you need to extract the diffusion direction information as well as the images. For these images, dcm2nii will attempt to generate .bvec and .bval text files. This information is extracted from the DICOM header (for Siemens data the software attempts to read the "B_value" and "DiffusionGradientDirection" fields from the CSA header).

NIfTI Sub-Formats

SPM5 and FSL both support NIfTI format images. However, by default these programs assume your data is in slightly different formats. Most SPM5 users generate a single 3D volume for each timepoint, and each image is saved as both a .hdr and .img file (separating the header information from the raw image data). On the other hand, by default FSL uses a single 4D dataset, with all the data stored in a single .nii file (this single file contains both the header and raw image data). To save disk space, FSL saved these files as compressed gzipped files (.nii.gz). Therefore, you may want to convert your DICOM data to a different NIfTI sub-format depending on how you want to process and analyze your data. You should adjust dcm2nii's settings depending on which software you will use for post-processing. Here are some general guidelines:
  1. FSL/MRIcron: compressed NIfTI (.nii.gz) - SingleNIIFile=1; Gzip=1; SPM2=0
  2. Recent software (SPM5/Voxbo/FSL/MRIcron): NIfTI (.nii) - SingleNIIFile=1; Gzip=0; SPM2=0
  3. Legacy software (SPM2/Analyze/MRIcro): analyze (.hdr/.img) - SingleNIIFile=0; Gzip=0; SPM2=1

Converting between NIfTI Sub-Formats

FSL includes the avwsplit and avwmerge tools for converting between 3D and 4D NIfTI images. This is useful, as FSL likes 4D images while SPM likes 3D images. The latest versions of dcm2nii (since May 2007) can also help you convert between NIfTI subformats. Specifically, if you drag and drop a NIfTI image (.nii, .nii.gz, or .hdr/.img subformats) onto dcm2nii it will ask how you want the data converted. You can convert these files to SPM2 (analyze 3D hdr/img), SPM5 (3D hdr/img), 3D nii, 4D nii, and FSL (NIfTI 4D nii.gz). If ManualNIfTIConv=1 then the user will be prompted for every file to specify the output format, while if this value is ManualNIfTIConv=0 then the files will be converted automatically using the sub-formant specified in the dcm2nii.ini file. Note that this software will both change subformat and/or convert 4D files to 3D files. However, it does not convert 3D files to 4D files (use avwmerge for this).

Anonymizing DICOM images

This software can also 'anonymize' DICOM data - protecting the participants private information. There are a number of free as well as professional programs that can help anonymize DICOM data. My favorite is the free uniPACS viewer can strip all the private tags from a DICOM file (choose File/BatchFileExport and select 'Anonymize' from the file menu). However, it is worth mentioning that some DICOM images store important data in the 'private' tags - for example, Siemens data includes information about the number of slices in a mosaic as well as DICOM diffusion directions. Therefore, use these 'strong' anonymizers with caution. In contrast, dcm2nii provides a 'weak' anonymization: it only anonymizes the patients name (0010:0010), ID (0010:0020), date of birth (0010:0030), sex (0010:0040), age (0010:1010) and weight (0010:1030). The name is replaced with the number of seconds that elapsed between the study time and January 1, 2000 (ensuring that data from different individuals will not be confused). In theory, the participant can still be identified by study time (if you know when people received scans), and some manufacturers may store personal information in other parts of the DICOM file. To use dcm2nii's DICOM anonymizer, simply edit the dcm2nii file to read "AnonymizeSourceDICOM=1". Then just drag and drop DICOM files on the program - an anonymized file will be created (with the same name as the original image, but with the extension '.dcm' appended at the end). Note that in this mode the software will not convert the DICOM files to the NIfTI format. You may want to keep two copies of dcm2nii with different filenames (and hence different .ini files) - for example you could call one 'dcmanon' and another 'dcm2nii' so that one copy generates anonymized files and the other converts files.

dcm2niiGUI

I find dcm2nii very easy to use - just drop the images that you wish to convert onto the program's icon (for OSX, drop the files onto the dcm2niigui icon in the dock). However, some people prefer programs with a graphical user interface. The Windows distribution of MRIcron includes my dcm2niigui program - which is simply a version of dcm2nii with a graphical interface. Just launch the program, then drag and drop the images you wish to convert. The 'Output format' pulldown menu determines whether the images will be saved in SPM or FSL style NIfTI format. You can also choose help/preferences to more advanced options. In addition, you can use the File/AnonymizeDICOM command to strip personal details from DICOM images. Finally, you can use the File/ModifyNIfTI command to change existing NIfTI images - this command guides you through selecting the images and then choosing how you want to modify the images (remove volumes, changing subformat, reorienting, or changing the order of the 3rd and fourth dimension).
dcm2niigui

Sample Datasets

The dcm2niix page includes sample images and links to repositories of sample DICOM images.

Links

The DICOM standard is very complicted, and different manufacturers interpret it differently. This makes universal data conversion difficult. In contrast, the NIfTI format is simpler and much more explicit, though less flexible and less ambitious.
  1. Word document describing how to validate DTI b-vector orientation.
  2. David Clunie's Medical Image Format FAQ is a great resource.
  3. NA-MIC's DTI web page has information regarding extracting DTI information from different types of scanners.
  4. The official NIfTI web page includes source Code, documentation, example files and further information.
  5. The Dipy manual (Diffusion imaging analysis in python) describes many of the issues.

Alternatives

Each manufacturer has interpretted the DICOM data standard a bit differently. Therefore, you may want to test several programs to see which one is best suited for your data
  1. The links below are obsolete. See the dcm2niix wiki alternatives.
  2. LONI Debabeler is a Java applet that can run on just about any computer. It can also read a number of medical imaging formats. Another nice feature is that it reorients the raw data to be approximately aligned with the nearest orthogonal orientation (i.e. coronal and sagittal scans are resliced along the axial plane).
  3. AFNI to3d/DIMON.
  4. SPM8 includes a DICOM to NIfTI covnerter that works particularly well for Siemens data (requires Matlab).
  5. FreeSurfer unpacksdcmdir
  6. dicom2nifti is a matlab script for converting DICOM to NIfTI (requires Matlab and the Matlab Image Processing Toolbox). [an alternative version is described here.]
  7. xmedcon offers limited NIfTI writing support for many image formats. It uses the niftilib tools, which look very useful.
  8. MRIconvert is a popular converter for Windows and Linux.
  9. dinifti looks useful.
  10. Here is a script that uses dicom2 and FSL to convert DICOM images to NIfTI.
  11. XMedCon includes the ability to convert between Acr/Nema 2.0, Analyze (SPM), Concorde/µPET, DICOM 3.0, CTI ECAT 6/7, NIfTI-1, InterFile3.3 and PNG or Gif87a/89a formats, as well as an elegant image viewer.
  12. r2agui is a Matlab script that can convert Philips PAR/REC images to NIfTI.
  13. dicom-to-nifti-converter-for-siemens-mr is Xiangrui Li's Matlab script that uses the Image Processing Toolbox and Jimmy Shens NIfTI tools to convert Siemens data.
logo