NITRC: dcm2nii: MainPage

NITRC: dcm2nii: MainPage
Skip to main navigation
Skip to user menu
Skip to search
Neuroimaging Resources Registry
Neuroimaging Data Repository
Cloud Computing Environment
Member login
Help
This repository is under review for potential modification in compliance with Administration directives.
dcm2nii:MainPage - NITRC Wiki
Summary
Support
Advanced Search
Documents
Downloads
Forums
MediaWiki
News
PubMed Mentions
Tasks
Tracker
Wiki Search
Views
View
View source
History
Actions
dcm2nii:MainPage
From NITRC Wiki
Jump to:
Contents
Introduction
Building from source
General Usage
File Naming
Microsoft Windows Usage
Apple OSX and Linux Usage
Graphical interface
Spatial Coordinates
10
Brain Imaging Data Structure (BIDS) Support
11
Alternatives
12
Slice timing correction
13
Anonymization
14
Spatial Transforms
15
Diffusion Tensor Imaging
16
Archival MRI
17
Unusual MRI
18
Positron Emission Tomography (PT, PET)
19
Computed Tomography (CT, CAT)
20
DICOM Transfer Syntaxes and Compressed Images
21
Philips PAR/REC Images
22
Caveats
23
License
24
Citations
25
Sample DICOM Images
Introduction
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:
Compiled versions are included with MRIcroGL (which includes a graphical interface)
Download a recent release from Github
Building from source
Source code and compilation instructions (using make or cmake) is available from the
GitHub web page
General Usage
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:
1..9
Compression level (1 is fastest, 9 is slowest but creates smaller files). This option requires compressed output (see
).
BIDS sidecar: (
"-b y"
or
"-b n"
) If this option is "yes" then the software will generate a
Brain Imaging Data Structure
file with the same name as the NIfTI image. This file is in the JSON text format, providing additional information about the scan that can not be saved in the NIfTI header.
ba
BIDS sidecar anonymization: (
"-ba y"
or
"-ba n"
) If this option is "no" then the BIDS file will include personal information about the participant that is encoded in the DICOM file. This identifying information may compromise the
privacy of the participant
. This option only influences the BIDS sidecar (see
).
Output filename: (e.g.
"-f myMR
") dcm2niix allows you to specify how the converted NIfTI files are named. The method may at first seem complex (see the
developer documentation for more details
), but it provides a great deal of flexibility. A simple filename might be "exp03subj09". In this case, the first series from this participant will be called exp03subj09.nii, the next exp03subj09a.nii, then exp03subj09b.nii, etc. However, dcm2niix also allows you to denote the presence and location of relevant information into the filename. Consider you specify "exp03subj09%p%s" - in this case the name of the protocol and the series number (as stored in the DICOM file) will become part of the file name. In this case the output files might be named exp03subj09fmri1.nii, exp03subj09t12.nii and exp03subj09fmri3.nii. You can combine as many modifiers as you want in any order. Here is a list of the special modifiers:
%a
: antenna (coil) number inserted. For example, the output filename "myName%a" would generate "myName1", "myName2", each for each coil. Note that most scans combine data from all coils and in these cases this option is ignored. For example, most scans which combine data from all coils would simply be called "myName".
%d
: series description (0008,103E) inserted. For example, an echo-planar image converted with "myName%d" would yield "myNameEPI"
%e
: echo number inserted. For example, a sequence with two echo times converted with the output filename "myName%e" will yield "myName1" and "myName2". Note that most MRI sequences only use a single echo time, and in these cases you would only get "myName1".
%f
: input folder name inserted. For example, the output filename "myName%f" combined with an input folder "/usr/Subj22" will result in the output file named "myNameSubj22.nii"
%i
: patient ID (DICOM tag 0010,0020) inserted. For example, the output filename "myName%i" would convert an image where the patient ID is named "ID123" to be "myNameID123.nii"
%m
: manufacturer name For example, the output filename "myName%m" would convert an image from a GE scanner to "myNameGE.nii", while an image from a Philips would be "myNamePh.nii", whereas Siemens would be "myNameSi.nii", otherwise the manufacturer is not available ("myNameNA.nii"). (requires dcm2nii versions from 2015 or later).
%n
: subject name (DICOM tag 0010,0010) inserted. For example, the output filename "myName%n" would convert an image from John Doe to be "myNameJohnDoe.nii". This option works best if your participant names use only English letters, for other European languages you may find it makes some basic conversions ("Müller" will become "Muller"). For non-European languages you will find this option unsatisfactory. Perhaps future versions can support DICOM tag
0008,0005
%p
: protocol name (DICOM tag 0018,1030) inserted. For example, the output filename "myName%p" would convert an image where the protocol is named T1 to be "myNameT1.nii"
%q
: sequence name (DICOM tag 0018,1020) inserted. For example, the output filename "myName%q" would convert a Spin Echo sequence to be "myNameSE.nii" (new feature, in versions from 30Aug2015).
%s
: series (DICOM tag 0020,0011) inserted. For example, the output filename "myName%s" would convert the second series to be "myName2.nii". If you want to zero-pad the series number, insert the number of digits desired (0..9). For example applying the filter "m%s" when converting 11 series will create files that will cause problems for a simple alphabetical sort, e.g. "m1.nii,m11.nii,m2.nii...m9.nii". In contrast specifying "m%3s" will help sorting (e.g. "m001.nii,m002.nii...m011.nii").
%t
: session date and time inserted (DICOM tags 0008,0021 and 0008,0030). For example, the output filename "myName%t" would convert an image where the session began at 1:23pm on 13 Jan 2014 as "myName20140113132322.nii"
%z
: Sequence Name (0018,0024) inserted, so a T1 scan converted with "myName%z" might yield "myNameT1".
Shows help screen: (
"-h"
) If this argument is provided, a help screen is displayed with the options available.
Input folder: (e.g.
"/users/chris/dir
") The final value you provide in the dcm2niix command line is the folder that contains your DICOM data. Some scanners store images in nested subfolders, so a single session might be stored in the folders "/usr/subj22/111", "/usr/subj22/112" and "/usr/subj22/123". In this case you should simply provide the parent directly ("/usr/subj22") and dcm2niix will recursively search the sub directories and organize all your images for you.
Merge 2D slices: (
"-m y"
or
"-m n"
). If selected, images from the same series are stacked into a single NIfTI image regardless of study time, echo, coil, orientation, etc. Depending on your vendor, you may want to segment images based on these attributes (
"-m n"
) or combine them
"-m y"
).
Only convert this series Number: (e.g.
"-n 12"
). If selected, only images from the selected series will be converted. For example,
"-n 12"
will only convert the 12th series. This allows you to convert only a single DICOM series. A special feature of this option is unleashed when you provide a negative series number (
"-n -1"
): in this case the software will report the series numbers available in the input folder, but will convert nothing. The
option is useful for display tools like
FSLeyes
, allowing users to view individual files.
Output directory: (e.g.
"-o users/chris/outdir
") you can specify the location where the converted NIfTI images will be stored. By default, the software will save images to the same folder as the original DICOM files. However, you may wish to save these in a specific location (and this is required if your DICOM data are stored on read only media such as a CD-ROM).
Philips precise float (not display) scaling: (
"-p y"
or
"-p n"
). The NIfTI standard requires a single scaling factor to convert the brightness stored on disk to the calibrated brightness. For example, a NIfTI file that stores data as 8-bit integers can only store values in the range 0..255, however one can specify an arbitrary scaling slope and intercept to these (for example, with an intercept of 0 and a slope of 0.1, the calibrated values will have the range 0..25.5). Unfortunately, Philips scanners can provide
two different scaling values
: one "p"recise and one for "d"isplay. This option allows you to select between these. This option only has an effect if your image includes both these scaling factors.
Single file mode: (
"-s y"
or
"-s n"
). If selected, only the single image provided is converted. For example "dcm2niix -s y ~/dir/001.dcm" will only convert the file 001.dcm, while "dcm2niix -s n ~/dir/001.dcm" will convert all the DICOM files in the folder "dir".
Update check: (
"-u"
, UNIX only). This command will cause the software report if there are any newer versions of dcm2niix available online. Note, this command only checks for updates, it does not update the software.
Verbosity: (
"-v 0"
"-v 1"
or
"-v 2"
) influences the amount of comments and hints generated by dcm2niix. At level 0, the software is silent, only reporting serious messages. Level 1 provides numerous hints. Level 2 is logorrheic.
Crop output: (
"-x y"
or
"-x n"
). If selected, dcm2niix will crop 3D sequences (T1 MPRAGE, T2 SPACE), removing excess regions of the neck from brain scans. Tissue in the lower neck can disrupt normalization, so cropping this tissue is often useful.
Output compression: (
"-z y"
or
"-z n"
) dcm2niix will either generate uncompressed (.nii) or compressed (.nii.gz) files. Compressed files require less disk space, but compression takes time and many tools do not read compressed images. Note that
"-z y"
dcm2niix will use the parallel
pigz
(if installed) to compress. Parallel compression is much faster, but if you want to use the internal, single threaded compressor use
"-z i"
. The final option is the 'optimal'
"-z o"
which pipes data directly to pigz (with
"-z y"
dcm2niix creates an temporary uncompressed file that pigz compresses). This optimal method is much faster if you use slow (e.g. networked) storage. However, the piped version requires you to install a pigz version 2.3.4 or later.
File Naming
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](
). 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](
). 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.
Microsoft Windows Usage
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)
Apple OSX and Linux Usage
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.
Graphical interface
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.
Spatial Coordinates
NIfTI versus DICOM coordinates.
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.
Brain Imaging Data Structure (BIDS) Support
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
Dcm2Bids
bidskit
DAC2BIDS
heudiconv
Alternatives
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.
dcm2niix : The topic of this page. Converts diffusion vectors and does a good job with CT scans. It is written in C, so it is very portable, but it is not easy to adapt for your own uses. It attempts to preserve diffusion gradient information.
Valerio Luccio's
dinifti
is written in C, and is focused on conversion of Siemens data
dcm2nii
is the predecessor to dcm2niix. It is deprecated for modern images, but does handle image formats that predate DICOM (proprietary Elscint, GE and Siemens formats).
Xiangrui Li's
dicm2nii
is written in Matlab. Xiangrui has spent considerable time perfecting this tool to detect important but poorly documented features, for example the phase encoding readout direction for GE scans. The Matlab language makes this very scriptable. It attempts to preserve diffusion gradient information.
dicom2nifti
looks promising: the scriptable Python wrapper utilizes the
high performance GDCMCONV executables
for some transfer syntaxes. Be aware that this loads all images into memory during conversion, so you may want to convert one series at a time (or have a computer with more RAM than your entire dataset).
Brendan Moloney's
dcmstack
is written in Python. It has a clever feature that allows you to store/view DICOM meta header data in your NIfTI files.
The MRtrix tool
mrconvert
is a useful general purpose image converter and handles DTI data well.
Jolinda Smith's
mcverter
is written in C++, and has great support for various vendors. It attempts to preserve diffusion gradient information.
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.
The Matlab-based
spm12
includes a DICOM to NIfTI conversion. For Siemens users, SPM provides everything one needs to go from image to inference in a single, well-crafted package. While it does not support some of the advanced features of dicm2nii (e.g. phase encoding and gradient directions, multi-vendor support), the code is elegantly minimal and clear which makes it easy to adapt to ones specific problem.
AFNI's to3D/Dimon
FreeSurfer unpacksdcmdir
LONI Debabeler
Java tool for converting between formats
r2agui
Matlab script for converting Philips PAR/REC to NIfTI
MRIcro
is an OS X application. It uses dcm2niix to convert DICOM images (Import/ConvertDICOMtoNIfTI), but can handle other formats (Import/ConvertOtherToNifti). The other formats include Bio-Rad Pic (.pic), NRRD, Philips (.par/.rec), ITK MetaImage (.mhd, .mha), AFNI (.head/.brik), Freesurfer (.mgh, .mgz) as well as any bitmap format supported natively by OSX (this includes 3D TIFF images, animated GIFs, and PNG format images). For these latter general format images you may need to hand-tune a few NIfTI features (e.g. distance between voxels, to get the appropriate aspect ratio).
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
Slice timing correction
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).
Siemens slice timing samples (8.9mb)
: this includes coronal, axial and sagittal acquisitions each with an odd (35) or even (36) number of slices each with ascending, descending or interleaved acquisition. This set also includes
CMRR multi-band
images. In general, multi-band sequences allow such rapid TRs that slice timing correction is not required, but if you insist on correcting these images please pay special attention to the slice order.
University of Iowa GE Discovery MR750w (114mb)
: sagittal, coronal, and axial fMRI with phase encoding varied between top-down/bottom up as well as interleaved and sequential. 27 LX MR Software release:DV26.0_R02_1810.b. Courtesy of Dr. Vincent Magnotta, Joel Bruss, and Kent James.
NIH GE Discovery MR750w (20mb)
: courtesy of the Interdisciplinary Center for Modern Technologies of the Nicolaus Copernicus University in Toruń. Variations in
phase direction polarity, phase encoding direction, and slice order
. 24\LX\MR Software release:DV24.0_R02_1607.b.
NIH GE Discovery MR750w (20mb)
: variations in phase direction polarity, phase encoding direction, and slice order. 27\LX\MR Software release:DV26.0_R01_1725.a.
Nottingham GE Discovery MR750w (14mb)
: provides ascending and descending slices for both
epi and epiRT sequences
. 24\LX\MR Software release:DV24.0_R02_1607.b.
Anonymization
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
).
Spatial Transforms
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.
Siemens (9mb)
Images acquired on a 3T Siemens Trio at the McCausland Center for Brain Imaging. Sagittal, Coronal and Axial scans are acquired with ascending, descending and interleaved order. Scans were acquired with both 35 and 36 slices per volume and the participant made a dramatic head movement to demonstrate the unusual Siemens interleave pattern which is important for
slice timing correction
. In all cases a left saline bag was placed next to the left temple to ensure that the spatial transforms have been converted correctly.
Diffusion Tensor Imaging
DTI vectors displayed with FSLeyes.
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
GE (153mb)
Images acquired on a 3T GE at Nottingham Medical School courtesy of Paul Morgan.
GE (235mb)
Images acquired on a 3T GE with Sagittal, Coronal and Axial orientations at Nottingham Medical School courtesy of Paul Morgan.
GE (624mb)
Courtesy of Jennifer A. McNab and Christoph Leuze at Stanford University's 3T GE MRI system at the Richard M. Lucas Center for Imaging
Philips (191mb)
:Images acquired on a 3T Philips Achieva (Philips MR 26.2) courtesy of Ed Gronenschild at the Department of Psychiatry and Neuropsychology, School for Mental Health and Neuroscience (MeHNs), Maastricht University Medical Centre (MUMC), Maastricht, The Netherlands. These images were saved to both the DICOM and PAR/REC formats.
Philips (110mb)
: images acquired on a 3T Philips Ingenia (Philips MR 53.1) at the Sir Peter Mansfield Imaging Centre, University of Nottingham, courtesy of Olivier Mougin. Data saved as DICOM as well as XML/PAR/REC.
Siemens (164mb)
from the Georgia State University and Georgia Tech Center for Advanced Brain Imaging
Siemens (11mb)
DTI dataset with sagittal slices (from Xiangrui Li) acquired on a 3T Siemens Trio at the Center for Cognitive and Behavioral Brain Imaging in Columbus, Ohio. For a similar dataset from the
McCausland Center 3T Prisma (37mb)
McCausland Center 3T Prisma (17mb)
DTI dataset with an acquisitions orthogonal to the scanner bore as well as with yaw, pitch and roll applied to the slice angulation.
Vanderbilt University Institute of Imaging Science 3T Philips Achieva dStream enhanced DICOM DTI dataset courtesy of Bennett Landman. This sample is available in
classic DICOM (219mb)
. Finally, this same dataset is provided as
classic DICOM exported with the "Series Split" checkbox selected (222mb)
. Be aware that the "Series Split" option generates very unusual images: a single sequence generates multiple series numbers, while a single sequence also generates images with identical series, acquisition and instance numbers (without Dimension Index Values, only the private tag 2005,1412 distinguishes different images). Note that these "Series Split" images will require manual effort of merging files to recover usable data. Therefore, it is strongly recommended that users do not use Philips "Series Split" option when exporting data. Likewise, the data is available in a
hybrid classic and enhanced format
where one 2D slice from each series is saved as one file, and all other slices are saved as a separate file. This odd structure is unlike the reference enhanced DICOM images, and seems impossible to convert to classic images using any known technique including David Clunie's useful dcuncat tool. These two final datasets are only provided to document the issues surrounding exporting enhanced DICOM. These can be compared to typical (but not DWI) enhanced DICOM datasets provided by Baxter Rogers (listed elsewhere on this page) on the same instrument with the same software. Be aware that many tools can do not recognize enhanced DICOM and simple tasks such as anonymization with unaware tools will render datasets unusable. While enhanced DICOM has terrific features, you must ensure each link in your data handling is able to handle these images. While dcm2niix will handle typical enhanced DICOM images, it can typically will not handle images that have been mangled by other tools.
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.
Archival MRI
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.
3T Philips Intera PAR/REC v3
(2003) MUSC.
3T Philips Intera
(2006, PIIM V2.1.4.1 MIMIT MCS) MUSC
(also as PAR/REC v4)
3T GE SIGNA_HDx
(2007, 14_LX_MR_Software_release:14.0_M4_0629.a via GEMR01) LMU-*Grosshadern.
3T Siemens Trio
(2007, syngo_MR_2006T_4VB12T via OFFIS_DCMTK_354) McCausland Center for Brain Imaging.
3T Siemens Trio
(2007, syngo MR B13 4VB13A via OFFIS_DCMTK_354) McCausland Center for Brain Imaging.
3T Siemens Trio
(2010, syngo MR B15 direct) GSU/GT Center for Advanced Brain Imaging.
3T Siemens Trio
(2010, syngo MR B17 via OFFIS_DCMTK_354) GSU/GT Center for Advanced Brain Imaging.
Unusual MRI
This section provides sample DICOM datasets for unusual forms of MRI and comments regarding how dcm2niix handles these files.
Interpolated Images
McCausland Center 3T Prisma (3mb)
. The Siemens
sequence Resolution tab
includes a checkbox labeled "interpolation". This will save images with double the in-plane resolution as they were acquired. The resulting images will require four times the disk space and can
introduce artifacts and may disrupt traditional methods to attenuate ringing artifacts
. In short, this option should never be used by scientists. However, dcm2niix should convert these images correctly, though it will generate a warning that these images may be incompatible with mrdegibbs and dwidenoise.
Fieldmaps
McCausland Center 3T Prisma (3mb)
are useful for
undistorting EPI images
. This sequence uses two echoes and saves a magnitude image for each as well as a phase difference map.
Multi-echo Sequences
McCausland Center 3T Prisma (141mb)
: MRI sequences with multiple echoes (1) Siemens Product field maps (two magnitude images and one difference phase map), (2)
CMRR T2* fMRI EPI
sequence with two echo times, (3)
MGH Multi-Echo MPRAGE
T1 scan. MRI scanners can acquire multiple echoes. To facilitate processing, each echo is stored as a separate volume. For example, consider an fMRI study where over 200 seconds we acquire scans with two echo time (20ms, 35ms) with a TR of 2 seconds. In this case, dcm2niix will save the first echoes a 4D NIfTI image with 100 volumes ("filename_e1.nii") and a second 4D dataset with the images from the longer echo time ("filename_e2.nii").
Multi-echo Sequences
Vanderbilt Philips 3T Achieva dStream 5.3.0.3 (193mb)
: Fieldmap, T1 and fMRI data demonstrating multiple cardiac phases, multiple echoes, and storage of phase, magnitude, real and imaginary images stored in Philips Enhanced DICOM format. The DICOM images were stored with Philips MR 53.0. PAR/REC and vendor NIfTI images provided where possible. Courtesy of Baxter Rogers.
Diffusion scan from
Vanderbilt Philips 3T Achieva dStream 5.3.0.3 (68mb)
: Philips Enhanced DICOM format where image
intensity is scaled differently for each 2D slice
. Courtesy of Baxter Rogers.
Positron Emission Tomography (PT, PET)
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.
Philips (24mb)
: Images acquired on a Philips GEMINI TF TOF 64 courtesy of Elijah Rockers at Houston Methodist Research. This dataset exhibits the issue with sorting data based on 0020,0013.
Computed Tomography (CT, CAT)
Raw CT scan (left) and after tilt and slice-thickness correction (right).
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.
Viewing a CT scan with MRIcroGL.
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.
Philips Brilliance iCT CTA Carotids Arteries (150mb)
512x512x538 voxels, 0.49x0.49x0.45mm between voxel centers. Note: X-Ray Exposure varies. To convert to NIfTI you should use the 'merge 2D slices' option to force stacking, e.g. "dcm2niix -m y ~/S39210".
Philips Ingenuity CT COW CTA (428mb)
512x512x799 voxels, 0.49x0.49x0.45mm between voxel centers.
Philips Ingenuity CT (103mb)
acquisitions with different gantry tilt. Courtesy of Paul Morgan from the Nottingham Medical School.
DICOM Transfer Syntaxes and Compressed Images
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:
The DICOM standard does not require support for these formats: many compliant tools are unable to read compressed DICOM data. Therefore, choosing a compressed format limits your ability to use many popular DICOM tools.
Some vendors incorrectly store a full JPEG image (header and code stream), while the DICOM standard insists that the data must be the code stream only. This can confuse some software.
The JPEG2000 standard has been interpreted differently by different libraries. For example the Jasper library can exhibit problems with
16-bit images
(verified with version 1.9). Likewise, support for this format in operating systems is not sufficient for medical imaging (for example, with OSX the function 'imageRepsWithContentsOfFile' will correctly load a 16-bit TIFF image, but down samples a 16-bit JPEG2000 to 8-bit precision, as tested with OSX 10.10).
At moderate levels of compression the original JPEG does fine, at extreme levels of compression JPEG2000 is much less blocky than the original JPEG but tends to lose a lot of high frequency information. In my experience the lossless JPEG2000 does not substantially outperform conventional file compression.
Philips PAR/REC Images
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:
Otto von Guericke University examples
Gregory R. Lee's examples
Yaroslav Halchenko's examples
Rosetta Bit project includes PAR/REC examples
Caveats
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.
This software should read data corrupted by GE GEIIS PACS systems. These systems insert a
thumbnail image
that
breaks
DICOM compatibility
(the transfer syntax specifies uncompressed data but the thumbnail is saved compressed in a public pixel data group 7fe0,0010).
This software should be able to read images that have been 'cleaned' with
gdcmconv
. The goal of gdcmconv is to correct some of the bugs introduced by different vendors to create more consistent output. However, be aware that it will modify some of the
value representations
used for vendor specific tags. This can disrupt tools that implicitly assume the VR for these tags.
This software should accurately report slice distances for Philips R3.2.2 where different slice positions are stored for the same slice. However, you should validate that the slice thickness is correct.
License
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.
Citations
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
Sample DICOM Images
Note several DICOM datasets are linked in previous sections of this web page.
dcm_qa
Siemens V*, spatial orientation, total readout time, phase encoding polarity, mosaics, common compressed transfer syntaxes (JPEGLossless:Non-hierarchical-1stOrderPrediction and JPEG2000LosslessOnly].
dcm_qa_agfa
DICOM mangling of data from any vendor touched by an AGFA or dcm4che PACS.
dcm_qa_asl
Siemens V* Arterial Spin Labeling.
dcm_qa_canon
data from Canon.
dcm_qa_ct
computerized axial tomography from GE and Philips showcasing modality specific features like gantry tilt.
dcm_qa_enh
enhanced DICOM from Canon, Philips, Siemens X*.
dcm_qa_fmap
GE, Philips and Siemens field maps. nb Siemens fieldmaps duplicate instance numbers.
dcm_qa_ge
GE slice timing across versions and with hyper band (aka multi band)
dcm_qa_me
multi-echo data from Siemens V*.
dcm_qa_mosaic
examples of image numbering with Siemens V*.
dcm_qa_nih
Siemens V* and GE
dcm_qa_philips
Philips data, diffusion bvec/bval.
dcm_qa_philips_asl
Philips classic DICOM Arterial Spin Labeling.
dcm_qa_philips_asl_enh
Philips enhanced DICOM Arterial Spin Labeling.
dcm_qa_stc
EPI slice timing for GE and Siemens V*, X*.
dcm_qa_toshiba
data from Toshiba (now Canon].
dcm_qa_ts
identical image data stored using various transfer syntaxes.
dcm_qa_uih
UIH data.
Alize medical sample datasets
National Biomedical Imaging Archive
XNAT central
National Alliance for Medical Image Computing (NAMIC) collection
InVesalius
provide nice sample DICOM images.
Curated list of medical data
Curated list from dcmtk
Barré's Sample DICOM images
Links to DICOM datasets
Aycan's Sample DICOM images
I Do Imaging Sample DICOM data
Rosetta Bit
The Cancer Imaging Archive (TCIA)
Plastimatch
provides sample images in DICOM as well as other formats.
Example T1-scan
showing how
gdcmanon
and
nifti2dicom
can be used to create DICOM images with minimal meta data.
morphosource
contains many CT scans of museum specimens. The quality of the images is excellent, but the implementation of the DICOM standard can be problematic.
digimorph
provides CT scans from museum specimens. These are typically provided in TIFF format, rather than DICOM.
The
NEMA FTP server includes many sample DICOM images
. Some are proof-of-concept edge cases that are technically legal DICOMs, but not seen in practice. However, some vendors have provided nice sample datasets, for example
Mediso
Retrieved from "
This page was last edited on 2 January 2025, at 20:46.