Important note: dcm2nii
is still beta software - please carefully monitor the output from this
software. In particular, be aware of potential left-right flipping.
This has only been tested with Philips Intera DICOM, Siemens Trio DICOM
and Philips Intera PAR/REC images. This software is provided under the BSD 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.
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.
- Follow the instructions to install MRIcron on your hard disk - this should create a program named dcm2nii.exe (Windows) or dcm2nii (Unix).
- 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.
- (optional) Open dcm2nii.ini with a text editor (double click on the file). You will be able to adjust the settings:
||If '=1' then dcm2nii will
create anonymized copies of DICOM images (remove name, DOB, patient ID,
sex). No other conversion will occur.
||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,
||If '=1' then dcm2nii will generate 4D files (FSL style), otherwise output will be 3D (SPM style).
|| If '=1' then patient name will not be copied to NIfTI header.
||If '=1' then dcm2nii will create .nii files (FSL style), otherwise .hdr/.img pairs will be created (SPM style)
||If '=1' then dcm2nii will create compressed .nii.gz files (FSL style).
||If '=1' then dcm2nii will create Analyze images (SPM2 style), otherwise headers will be in NIfTI (SPM5/FSL).
||If '=1' then output filename will include date of study.
||If '=1' then output filename will include acquisition number.
|| If '=1' then output filename will include protocol name.
|| If '=1' then output filename will include patient name.
||If '=1' then output filename will include source filename.
||If '=1' then all .par/.rec files in the source folder will be converted, otherwise only the file specified will be converted
|| Specifies number of volumes to be removed from the beginning of a 4D acquisition (e.g. avoid T1 effects)
||Specifies number of volumes
to be removed from the end of a 4D acquisition (e.g. fMRI scanning
continued after behavioral paradigm ended).
||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.
||Images with a larger matrix size than this value will be reoriented to canonical space (see below).
||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).
||If OutDirMode is set to 2 (see above), then converted files will be saved to this folder.
There are two ways to run dcm2nii
- 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).
- You can
launch dcm2nii from the command line, specifying specifically the
options to use.
To use dcm2nii by dragging and dropping:
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:
- Place all the DICOM (or Philips PAR/REC) images you wish to convert into a folder where you have write access.
- Drag and drop one of the images onto dcm2nii.
- You can now vew the images with MRIcron, SPM5, FSL, or other Analyze/NIfTI viewers.
Chris Rorden's dcm2nii :: 12 12 2012
reading preferences file /Users/rorden/.dcm2nii/dcm2nii.ini
Either drag and drop or specify command line 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.
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.
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 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).
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
- FSL/MRIcron: compressed NIfTI (.nii.gz) - SingleNIIFile=1; Gzip=1; SPM2=0
- Recent software (SPM5/Voxbo/FSL/MRIcron): NIfTI (.nii) - SingleNIIFile=1; Gzip=0; SPM2=0
- 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.
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).
Converting DICOM images is fast compared to the other processing stages common to neuroimaging. However, several people have asked me how to improve dcm2nii's performance. I have tried to design this software to be quick - it attempts to minimize the amount of time writing to disk (by using a large amount of RAM). The table below shows the time required to process a standard neuroimaging dataset (the B17 test set from below). This dataset is typical for a one hour scanning session. The table below shows the time (in seconds) for dcm2nii (and SPM8) to convert these images. The 'GZ' cells reflect times for creating FSL style compressed .nii.gz images, while the other cells report times for creating uncompressed NIfTI data. In brief, creating uncompressed images is generally constrained by disk speeds, while creating compressed images is limited by your processing power. Here we see that using pigz on a multicore computer can dramatically accelerate compression. However, note that the inbuilt compressor writes the compressed file only once to the hard disk, whereas when using pigz the uncompressed data is saved to the hard disk and then compressed. Therefore, in theory pigz may be slower than the inbuilt routines if you have a slow (e.g. network) connection to the disk.
||.NII.GZ harddisk pigz
||.NII.GZ ramdisk pigz
|dcm2nii 3.7GHz i7 4 core (8HT)
|SPM8 3.7GHz i7 4 core (8HT)
|dcm2nii 667Mhz G4 Laptop
Here are some sample images that help show whether images are converted with the correct image orientation:
- GE DICOM dataset.
Twelve 4D EPI series, each with five volumes: s26692 axial ascending
sequentia, s26693: axial ascending interleaved, s26694: axial
descending sequentia, s26695: axial descending interleaved, s26696:
sagittal right to left sequential, s26697: sagittal right to left
interleaved, s26698: sagittal left to right sequential, s26699 sagittal
left to right interleaved, s26700: coronal P to A sequential, s26701:
coronal P to A interleaved, s26702: coronal A to P sequential, s26703:
EPI, coronal A to P interleaved. A water filled fiduical marker is
placed over the right temple of the participant. Data were acquired on
a GE-SignaHD-Excite scanner at 3 Tesla using an 8 Channel Brain Array
Coil. The first volume of each series has been marked with a '1' on the
image. (LMU Grosshadern)
- Philips DICOM dataset.
Six 4D EPI volumes, each with two volumes: sagittal, coronal and axial
each with both 'ascending' and 'descending' slice order. The white line
added at the bottom should be shorter on the earlier volumes. (MUSC
Center for Advanced Imaging Research)
- Philips PAR/REC dataset.
Five 4D EPI volumes - same raw data as Philips DICOM dataset, but only
a single axial volume is included.(MUSC Center for Advanced Imaging
- Siemens Trio B12 DICOM dataset.
Six 4D EPI volumes, each with two volumes: sagittal, coronal and axial
each with both 'ascending' and 'descending' slice order. A saline bag
is placed near the participant's left temple. (USC McCausland Center)
- Siemens Trio B13 DICOM DTI dataset.
From May-2007, dcm2nii attempts to generate FSL and medINRIA compatible
descriptions of the B-values (bval) and Diffusion Gradient Directions
(bvec). For instructions on using FSL and medINRIA, see my DTI page.
These sample images were simply designed to validate dcm2nii's
conversion: these protocols are not appropriate for any other use (our standard protocol is described here).
This large (33Mb) file includes four 20 direction EPI datasets: the
first two are true axial (aligned to scanner bore, not the
participant's head) and are identical except that the phase direction
is Anterior-Posterior in the first and Right-Left in second. The third
volume is identical to the second except that the imaging plane has
been rotated: a pitch and yaw have been applied. The final scan is a
coronal scan,also taken in plane with the scanner's bore with pahse
encoding in the right-left direction. The file also includes a matlab
function (dtivecs.m) that illustrates dcm2nii's calculation for
correcting the diffusion directions for the imaging plane, using
suggestions from dicom2ana (see below) and Paul Morgan. (USC McCausland
- Siemens Trio B15 DICOM dataset.
(from GSU/GT Center for Advanced Brain Imaging)
- Siemens Trio B17 DICOM dataset.
From July 2010: this is similar to B15 dataset except collected with B17. Includes DTI images, fMRI dataset, T1 scan and field maps. (from GSU/GT Center for Advanced Brain Imaging)
- With regards to diffusion tensor data (DTI): Considerable confusion concerns whether or not the vectors reported in the DICOM header are stored relative to the scanner bore or relative to the image plane. While errors in the frame of reference probably have little impact on FA, MD, and ADC values, they can impair accurate tractography. dcm2nii attempts to use sensible default values based on my experience (albeit with a limited number of scanners and software patches), but dcm2nii also allows you to customize the conversion options. Please note that with Siemens scanners you can explicitly specify diffusion directions in the DiffusionVectors.txt file in EITHER a Logical (measurement) coordinate system = PRS (phase/read/slice) OR a Physical (gradient) coordinate system = XYZ, however the DICOM files will ALWAYS report directions in a patient coordinate system = Sag/Cor/Tra (as confirmed by Siemens in January 2013). By default, dcm2nii should adjust Siemens data for slice angulation, so the resulting files should work seamlessly with the FSL DTI tools. If you want to conduct tractography, we suggest you collect a sample image with substantial roll applied and examine connectivity across the corpus callosum. This Word document describes this approach, and we provide a sample Siemens Trio B17 DICOM DTI dataset with one scan orthogonal to scanner bore and one scan with a rotation in the roll axis applied.
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.
- David Clunie's Medical Image Format FAQ is a great resource.
- NA-MIC's DTI web page has information regarding extracting DTI information from different types of scanners.
- The official NIfTI web page includes source Code, documentation, example files and further information.
- The Dipy manual (Diffusion imaging analysis in python) describes many of the issues.
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
- 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).
- AFNI to3d/DIMON.
- SPM8 includes a DICOM to NIfTI covnerter that works particularly well for Siemens data (requires Matlab).
- FreeSurfer unpacksdcmdir
- dicom2nifti is a matlab script for converting DICOM to NIfTI (requires Matlab and the Matlab Image Processing Toolbox).
[an alternative version is described here.]
- xmedcon offers limited NIfTI writing support for many image formats. It uses the niftilib tools, which look very useful.
- MRIconvert is a popular converter for Windows and Linux.
- dinifti looks useful.
- Here is a script that uses dicom2 and FSL to convert DICOM images to NIfTI.
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.
- r2agui is a Matlab script that can convert Philips PAR/REC images to NIfTI.
- 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.