Computing Resources

DICOM Utilities

Table of Contents

DICOM Servers

There are two DCMtk storescp servers running on godzilla. The Philips scanners negotiate a transfer protocol with the server, and if enhanced-MR format is available, the scanner will prefer it and transfer in that format. The first server listed supports enhanced-MR so transfers to this server from the Philips scanners will produce enhanced-MR format files.

The second server has been configured not to support enhanced-MR, so files sent there from the scanners will be in classic DICOM format. The first server actually supports both formats so transfers to it from other sources will produce files in whatever format the sender supports.

Enhanced-MR format

Classic DICOM

Note: these ports are not open to the outside. They can be accessed only from inside KKI.

All files are stored by the servers in directory /godzilla2/dicom. A post processor is run after a study completes which checks fields in the DICOM header for a tag and path. If present, it copies the files to the path specified.

for example, in the Study Description put:


The directory /g5/kirby/jgillen/scan_20190502 or /g5/kirby/jgillen/scan_20190502/subj1 must already exist. In the first case, the subj1 directory will be created.

If any error is made in the path specification the files will remain in /godzilla2/dicom. Directories older than 30 days are deleted each night.

Local tools

dcm_move or dcm_movegui - Rename and move DICOM image files

Usage: dcm_move [-s <source-dir>] [-R] [-m modality] [-a] [-S] [-d] [-l] [-f|-r|-c] [-n] [-i] [<destdir>]

dcm_move [-s <source-dir>] [-R] [-m modality] -u [<destdir>]


dcm_move will read DICOM files, then rename and move them based on the stored study number, acquisition number, slice number and possibly dynamic, echo or phase number. There are command line switches to control the source and destination of the image files, and the format of renaming. dcm_movegui has the same features as dcm_move but they are accessed through the graphic user interface shown to the right. There is a direct correspondence between the fields of the GUI and the command-line switches.


Command-line switches:

Input Switches  
-s <source­dir> dicom source directory, default: present working directory
-R recurse into all sub-directories of source-dir, default: source dir only
-a process all source files found, default: prompt for each study
-m <modality> check only the named DICOM modality sub-dir, default is all (MR CT US USMF CR NM SC)
Output Switches  
-c copy files leaving originals, default: move to another dir
-r rename in place (implies flat names -f), default: move to another dir
<destdir> is the writable & searchable destination directory, default is present working directory
-i no info file created
-l ignore location in header, default: move to location in header if found
-f  flat names mode, default: hierarchical
-u unmove - use SOP Instance UID for names
-S use SeriesDescription field in acq dir name
-d add .dcm to output filenames, useful for some Windows apps
-n no echo/phase/dynamic breakdown
-b don't move non-DICOM files to bad directory
-q quiet - less output

Images are renamed according to the study, series and slice number found in the DICOM header.  If images are Philips dynamic images, they are renamed according to the study, series, slice and dynamic number.  If images are GE cardiac multiphase images, they are renamed according to study, series, slice and phase number.  If a file has an invalid DICOM header it is moved to a directory named "bad". The program dcmdump from the DCMtk package is used to read DICOM header information.

Hierarchical or Flat: switch -f

Without the flat switch images are stored in a hierarchy of directories and files, named from top, using a directory with the study number, then directory with series number, then a file with the slice number. If the study has multiple dynamics (echoes or phases) the slice number and dynamic (echo or phase) number will be used in the file name.

No Dynamic: switch -n

When -n is specified, series with multiple dynamics or phases (time points) are treated like anatomic series. The images are numbered using the image number provided in the DICOM header. It increments through time points for each slice (i.e. first all time points for slice 1, then all time points for slice 2, etc.). The highest image number is number of slices * number of time points.

hierarchical (no -f ) for an anatomic series (i.e. no dynamics/multiphase):

hierarchical (no -f ) for a dynamic/multiphase series and -n is not specified:

flat (-f) for anatomic series:

flat (-f) for dynamic/multiphase series and -n is not specified:

Patient History Field: switch -l

If the Patient History field in the header contains #-#<directory> and <directory> exists and is writable and searchable the images will be moved to that <directory> rather than the one named on the command line (or the default). Use -l on the command line to ignore this stored tag.

Info File: switch -i

Without -i, a file named "info" is created in each series directory containing some identifying information about the study, patient and series. Use the -i command line switch to suppress creation of this file. PHI/HIPAA Warning: the info file may contain the patient's name or other private information.


Do not run dcm_move while images are being transferred. Wait until DICOM transfer from the scanner is complete. dcm_move will probably move an incompletely transferred image and cause the simple_storage or other DICOM server to crash.


Zip Archive

send_dicom - Send images to a DICOM server

Usage: send_dicom [-d <max-delay>] [-a <local AET>] [-c destination] [-p port] [-r <remote AE Title>] [<DICOM file or dir> ...]

-d Max delay, default is 0.5 second.
-l Use CTN send_image to transmit the images. Only compatible with Classic DICOM images - no enhanced-MR, -CT or -PET
-a Local host's AE title.
-s Remote host name or IP address of destination.
-p Remote DICOM port.
-r Remote host's DICOM AE title.
<DICOM file or dir> One or more DICOM image files or directories containing DICOM image files to send

This script will send the specified DICOM images to a DICOM server. If a direcotory is specified all files in the directory will be sent. There is no recursion - sub-directories of a named directory are not checked.

The local AE Title is used in the DICOM association. The remote system's AE Title, port and host name or IP address must be specified.

If multiple images are being sent a delay may be used between each send to try to prevent transfer errors. The delay starts at 0 and increases by 0.1 sec each time an error occurs up to the max-delay. Failed transfers will be retried 3 times. At the end of all transfers the script will list how many images were successful and failed and you may try again to send the failed files.

If no file/dir name is supplied, the connection to the remote system is checked (DICOM echo).

Links to this script with the names of our local scanners allow transfer to these systems without supplying the AE Titles, destination port and name or address:

External Programs Required

The script uses DCMtk storescu for sending DICOM images. Classic images can be sent using CTN send_image by adding the -l option. DCMtk's echoscu is used for the test mode and dcmdump to detect Classic vs Enhanced format. There is an option to allow a field to be modified using the pre-defined hosts - used by XNAT to copy the field "Comments on the Performed Procedure Step" to the field "Patient Comments". This requires DCMtk's dcmodify. Location of all external programs and pre-defined destinations are configured at the beginning of the script.

Zip File - includes script and Windows and Solaris versions of CTN send_image. Get DCMtk binaries for your system from the OFFIS website.


Usage: dcmls <file path>

dcmls acts much like the Unix "ls -lR" command, listing files recursively in long format with permissions, owner, group, size, access date and name. If the file is DICOM format, it also lists a selection of DICOM header fields: SeriesDate, SeriesTime, StudyDescription, SeriesDescription, PatientName, PatientID, ProtocolName, SeriesNumber and PerformedProceduresStepDescription.

Perl Script



dcminfo [-t tags [-x]] [-f] [-s] [-w <width>] <dicom-file> [<dicom-file>...]

dcminfo -r tags [-c] [-q] <dicom-file> [<dicom-file>...]

dcminfo -l [-k] <dicom-file>

dcminfo -a <dicom-file>

First form will list selected DICOM tags for one or more DICOM files. If multiple files are specified, the tags with the same value for all files are listed first, then tags which are different in one or more files are listed in a table. Additional tags can be added to the pre-defined list (see below).

-t additional tag(s) to display, colon separated, '*' for all

used with -t, clears the default tags list


search-all - default is search-first

-w maximum width of displayed data table - default 200

Second form will rename DICOM files using one or more header tags (see Tags below). Multiple tags are concatenated using underscores (_). Rename is aborted if any tag is missing for any file or if any generated name is not unique. The extension .dcm is appended. Use -c to check generated names. All files will be listed as in first form as well

-r rename scanned DICOM files using series number
-c check generated names before renaming. No files are renamed.


Either the key name or numeric tag can be used. For numeric tags specify two four-hex numbers separated by comma (e.g. 0008,103e). Use colon to separate multiple key names or numeric tags. Use dcminfo -l on a file to see the list of available key names and tags.

Third form lists all DICOM fields names for one file sorted by the numeric tag. Adding -k will sort by the key name.

-l list all DICOM tags in the <dicom-file>
-k sort by key name rather than by numeric tag

Fourth form will list all fields from one file in a cleaner format than provided by dcmdump. All private field names are preceeded with ".".


list all dicom elements for one file

Pre-defined tags for the first form are:

You can create a ~/.dcminforc file with a set of preferred tags that will override the default pre-defined tags listed above. You can also override the default table width. File format:

Tags <tag1> <tag2> <tag3> ...
MaxWidth <number>
Perl Script


Usage: dcm2par <dicom-file> [<dicom-file>...]

dcm2par is a Perl script that will convert one or more Enhanced-MR DICOM files to Philips proprietary PAR/REC format. This should be used when legacy software requires PAR/REC input files but data is only available in DICOM format. If used on godzilla, delete the converted PAR/REC after processing is finished - do not keep duplicate data online.

The Perl script can be used on Windows, Mac or Linux systems. It requires the Math::Trig and Math::Matrix Perl packages. It also requires the dcmdump program from the DCMTK toolkit. The toolkit is available as pre-compiled binaries from Offis e.V..

The script has been tested using a variety of acquisitions, mostly brain scans, including various anatomical protocols, diffusion, ASL, BOLD fMRI, B0 mapping, B1 mapping, Dixon scans and a few angio protocols. In most cases the converted PAR file is identical to a PAR file generated on the scanner. There are several minor differences in some cases including:

Perl Script



dcms2e <dicom-directory>

dcms2e --diffs

The named <directory> must contain the classic DICOM files for the first dynamic (i.e. volume) of the fMRI acquisition. The number of files in this directory must equal the number of slices acquired.

There must be a PAR/REC pair of files with the same root name as the named <directory>. This PAR/REC must be the same acquisition as the classic DICOM files. This data can be sorted or not. Example: the directory is named "02_Resting" and the PAR/REC is 02_Resting.par and 02_Resting.rec

Using the attributes of the classic DICOM files and the image data in the REC file, this script will create an enhanced MR Image format file named <directory>.dcm. This file is nearly identical to one that would be transferred directly from the scanner. UID's will be different, the sequences describing the reference images are dropped and there are as some trival rounding differences.

This script is only for use with fMRI data files. There must be only multiple dynamics (volumes) of 1 or more slices. The script was not tested with multi-echos, multi phases, diffsion or ASL scans.

This script is useful for producing enhanced MR DICOM for scans with more than 16,384 images. Philips software currently on the scanner cannot send acquisitions as enhanced MR if there are more than 16,384 images.

After conversion and verifying the data, please delete the REC file since these files are very large and the data is now duplicated in the new enhanced DICOM file.

The --diffs option will provide a description of differences between a file transferred from the scanner and one converted using this script.

Output of the --diffs switch

Differences Between a Converted Enhanced MR Image File and One Transferred from the Scanner

DICOM Meta Information header
Instance Creation Time
SOP Instance UID's (for the entire file and for each frame)
These attributes are always newly generated when a DICOM file is created.
Referenced Image Evidence Sequence
Referenced Image Sequence
These sequences provide information about the localizer used to prescribe this acquisition. The standard DICOM file does not provide the information needed to generate these sequences so they are dropped.
Specific Absorption Rate Value
Gradient Output
Pixel Bandwidth
Image Position Patient
Trival rounding differences between values in the standard and enhanced files or in the converted output.
Frame Anatomy Sequence
This is present in the standard DICOM file but values are mostly blank. In a scanner exported Enhanced MR file they are filled in. In the converted file they are the blanks copied from the standard file.
Window Width and Window Center
In an exported file these are calculated by some unknown algorithm. In the converted file they are estimated using empirically determined scale factors and the data max and min. The differences are trivial.
MR Max FP and MR Min FP
In an exported file, these are calculated from the floating point image data before it is scaled down to the short integers stored in the file. For the converted file, the FP values are estimated by scaling up the minimum and maximum of the integer image data - these can never be exact due to the loss of precision in going to integer.

Note: Requires dcmdump, dump2dcm and dcmodify from the DCMTK toolkit. Also the Perl module Math::Matrix. Zip File


  dicomeread  Read enhanced-MR DICOM file with correct order & dimensions
   [imag, info] = dicomeread(file_in)
   [imag, info] = dicomeread(file_in, 'Noscale')
   [imag, info] = dicomeread(file_in, 'Order', [1 2 3 4])
   [imag, info] = dicomeread(file_in, 'Combine', [0 0 0 1])
   imag is a n-dimensional image
   info is the structure returned by dicominfo containing DICOM metadata

   Uses the Frame Content Sequence, Dimension Index Values to read in 
   Enhanced-MR DICOM images with correct dimensions.

   - Adds field MatlabNames to the returned DICOM header containing the
     labels of the image dimensions. First 2 dimensions are labelled
     'Column' and 'Row'; other labels come from the DICOM Dimension 
     Description Label field.
   - Adds field MatlabIndexes to the returned DICOM header containing
     the labels of the indexes of each dimension. First 2 dimensions are
     excluded. Other indexes come from the DICOM field pointed to by the 
     FunctionalGroupPointer and DimensionIndexPointer. For diffusion scans
     the indexes are the b-value and directions, for ASL the
     labeled/unlabelled tag. 
   - Adds field MatlabItems to the returned DICOM header containing the
     PerFrameFunctionalGroup item index for each image. For example to
     access info for slice 9, echo 2, dynamic 7 of a multi-slice, multi-echo,
     multi-volume scan:
      items = fieldnames(info.PerFrameFunctionalGroupsSequence);
      h = info.PerFrameFunctionalGroupsSequence.(item(info.MatlabItems(9,2,7)))
   - Handles diffusion and other scans with incomplete matricies by
     combining dimensions E.g. b-value and gradient orientation in case of
     diffusion, scanning sequence and image type in case of B1 maps.
   - Order property: reorder image dimensions. Arg can be cell string of
     DICOM dimension names, a row of dimension numbers or 'Prompt' to set
   - Combine property: combine dimensions to reduce dimensionality. Arg is
     a row with 0's and 1's, a dimension with 1 is combined with dimension
     to the left. Combine is done after re-order.
   - Noscale Property: don't apply scale slope and intercept to data.
Zip file with script and dictionary


Usage: dcmexamcard <dicom-file>

This program can extract binary large objects (BLOBs) from Philips DICOM Raw Data Storage SOP files. These files are transferred to DICOM servers which support and accept the Raw Data Storage SOP. Using our DCMtk storescp server, the files are stored with names beginning "RAW." rather than the "MRe." or "MR." used for enhanced-MR or classic images respectively. There will be one Raw Data Storage file for each acquisition and one additional file for each study. Note that these files do not contain raw data, i.e. k-space data - the DICOM Raw Data Storage IOD is a datatype that permits vendor specific data of any type to be stored.

They are also saved to the scanner DICOM folder when DICOM Export is selected from Disk Files panel on the Administration page. These files names begin "XX_" rather than the "IM_" used for image data. There will be one Raw Data Storage file for each acquisition and one additional file for each study.

The additional study file contains the ExamCard for the study stored in a single DICOM field. The program extracts the object from the DICOM field, then extracts the ExamCard from the object and stores it in a file using the ExamCard name stored in the BLOB. This ExamCard will reflect the actual scanned protocols, not the stored ExamCard used to initiate the study. Note that if DICOM data is sent before the end of the study, a study file will be stored with the scanned acquisitions completed up to that point. There may end up being multiple study Raw Data files - the last will contain the complete study.

The files for each acquisition contain multiple BLOBS which will be interprepted and printed as text to standard output. The meanings of some fields in some BLOBs are not known and are printed without interpretation.

Not all BLOBS will be present. Pre-R5.2? scans do not have the COILSTATE and HARDWARE_CONFIG BLOBs. RC and CPX are present in studies that save Raw or Complex data.

This program is based on DCMtk's dcmdump and supports the many command-line switches of that program. Additionally the following were added or modified:

Zip file with binaries


Usage: dcmcleanup [<data-directory>...]

This script will cleanup your data directory - the directory where the techs transferred your DICOM and/or PAR/REC data files from the MR scanner. Cleanup consists of renaming files to have names that contain the acquisition number and series description, moving some extraneous files and deleting a few unneeded files.

By default operates on the current working directory. One or more directories can be specified on the command line.

Operations performed:

The script requires: dcminfo, dcmexamcard, ExamCard_to_HTML and dcm_move. dcminfo & dcm_move require dcmdump. Zip file


Usage: dcmshortacq <dicom-file> [<dicom-file>...]

This script will remove a final partial acquisition from an enhanced MR DICOM data file. This occurs when an fMRI acquisition is stopped prior to completion of the series. Having the partial volume in the file prevents processing with some application. A backup file is created which should be deleted once the correction is verified.

This script requires dcmdump and dcmodify.


Usage: dcm2btable <dicom-file> [<dicom-file>...]

Dump b-table from one or more enhanced-MR DICOM DTI acquisition files. The table consists of four space separated numbers: the b-factor, and three angulations, one line for each DTI direction.

This script requires dcmdump.

Supported by NIH Grant P41 EB015909
© 2017 Kennedy Krieger Institute. Baltimore, Maryland.
All rights reserved.
Contact by email
=- 09'8