DICOM Utilities

Johns Hopkins, MR Research and 

Kennedy Krieger Institute, F.M. Kirby Research Center

Table of Contents

Local tools

dicom3tools - toolkit from David Clunie

dcmtk - toolkit from OFFIS

CTN - software package from RSNA/Mallinckrodt Institute

Local tools

dcm_convert - Convert standard DICOM image files into Analyze or AFNI formats

Usage: dcm_convert [-o output-rootname] [-a|-n] [-d] [-f format] [-dyn #]

dcm_convert -h

Input Files:

Using the Series Menu

If the optional -f switch (see below) is not used on the command line, the DICOM images must be in the current directory, or in a subdirectory of the current directory named MR or named any number 1 through 99. MR is the default name used by simple_storage when images are not redirected or when they are redirected using "#-#". Numbered directories are generated by simple_storage when images are redirected using "#a#" or "#s#" or when dcm_move is used to rename dicom files.

A series menu will be presented showing all dicom series found in the current, the MR and the numbered directories below the current working directory. Each line in the menu is numbered in the left column. You are prompted to enter the number of one series to be converted. After conversion, the menu is shown again and you can select another series. Any series you convert will appear in subsequent menus with an asterisk (*) below the selection number (like #1 in the example below). Enter just return when you are done to exit dcm_convert.

Example menu

Studies found:
  --------------------------------------------------------------------------------  
  # |Physician |Identity  |Name      |Date      |Time        |Cols|Rows|Slic|Dyn |
    |Description                                                                 |
  --------------------------------------------------------------------------------  
   1|          |1232      |Hartford,J|04/26/2000|09:45:31.800| 256| 256|  12|   2|  
   *|MOSER      se no filter TRA    SE    504       25     90                    |  
  --------------------------------------------------------------------------------
   2|          |1232      |Hartford,J|04/26/2000|09:31:39.790| 256| 256|  12|   2|
    |Stability  T1W/SE/no    TRA    SE    504       25     90                    |
  --------------------------------------------------------------------------------
   3|          |1232      |Hartford,J|04/26/2000|09:38:52.580| 256| 256|  12|   2|
    |Stability  T1W/SE/yes   TRA    SE    504       25     90                    |
  --------------------------------------------------------------------------------
  Number (1-3) [done] ->

Using the Format Switch

This method is faster than the above since all images in the directory do not have to be read to determine their series and image numbers. But most UIDs do not contain the needed information anymore - old Philips ACS/NT UID's did when this was written. This method can be used for images renamed using dcm_move.

A single series of DICOM images can be selected for conversion on the command line. The names must fit a pattern that can be defined using a C programming language "sprintf" format. You can see more about sprintf formats in the sprintf manpage (use "man sprintf" in a terminal window).

This format contains the parts of the image names that are constant for all slices and all dynamics and a conversion specifier where the changing numbers appear that represent the slice and dynamic numbers. The usual conversion specifier is %d which converts an integer into it's decimal representation without leading blanks or zeroes. The format specifier is used in dcm_convert with two integer arguments: i and j where i is a slice number and j is a dynamic number to step through all your DICOM images.

The format can include a path as well if the DICOM files are not in the current directory.

example (using Philips ACS/NT UID named images):

-f 1.3.46.670589.11.5406.9.955073100000002870201.%d.1.1.%d.0.41

example (using images renamed by dcm_move -f) note: the conversion specifier %03d means 3 digit long decimal integer padded with leading zeroes:

-f 01284.003.%03d.%03d

slice 1 dyn 1,2,3: 01284.003.001.001 01284.003.001.002 01284.003.001.003
slice 2 dyn 1,2,3: 01284.003.002.001 01284.003.002.002 01284.003.002.003

Input switches:

Output:

4D Analyze

A Mayo Clinic Analyze compatible header file is made describing the data.  It has a .hdr file extension. Info from the DICOM header is put into all appropriate fields of the Analyze header (specifications).

Additionally a file is created with file extension .dcm containing all image DICOM headers concatenated together (specifications). This file along with the .img and .hdr files permits the original DICOM images files to be recreated using the dcm_unconvert program. This allows users to safely delete the original DICOM files. You can also feed this file to dcm_dump_file or dcm_dump_element to display DICOM header elements from the first (slice 1, dynamic 1) header.

3D Analyze

A single Mayo Clinic Analyze compatible header file is made describing the data named with extension .001.hdr. Links are made to this file for all other time points with names .002.hdr, .003.hdr, etc. This header file therefore consumes only the space of the single original file but has multiple names.

The concatenated DICOM header file (.dcm) is also created. The -n switch cannot be combined with -a.

AFNI

A Mayo Clinic Analyze compatible header file (.hdr) and concatenated DICOM header file (.dcm) are also made. These would be needed if the original DICOM images were to be recreated using dcm_unconvert. The -a switch cannot be combined with -n.

Output switches:

Binary: Solaris2

dcm_unconvert - Recreate DICOM image files

Usage: dcm_unconvert [-a|n] [-d x:y:z:t] <input-rootname>

dcm_unconvert -h

The Analyze .hdr file is needed only to determine the dimensions of the image data. If the dimensions are specified on the command line using the -d switch, unconversion can proceed without the .hdr file.

Switches:

Binary: included with dcm_convert

dcm_move or dcm_movegui - Rename and move DICOM image files

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

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

dcm_movegui

dcm_move will read DICOM imagesthen 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:

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 dcm_dump_file from the CTN 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):

• images are stored in the destination directory
• in a directory named using the exam number
• in a directory named using the 3 digit series number
• in a file named using the 3 digit slice number
• example: /g1/smith/subj1/17543/002/001

images are stored in the destination directory

in a directory named using the exam number

in a directory named using the 3 digit series number

in a file using <3 digit slice>.<4 digit dynamic number>

example: /g1/smith/subj1/17543/002/001.0124

• images are stored in the destination directory
• in a file named <exam>.<3 digit series>.<3 digit image>
• example: /g1/smith/subj1/17543.002.001

• images are stored in the destination directory
• in a file named <exam>.<3 digit series>.<3 digit slice>.<4 digit dynamic>
• example: /g1/smith/subj1/17543.002.001.0124

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.

WARNING

Example

csh Script

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>...

This script will send the specified DICOM images to a DICOM server. The local AE Title is usedin the DICOM association. The remote system's AE Title, port and host name or IP address must be specified.

If multiple images are beiing sent a delay is 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 retired 3 times. At the end of all transfers the script will list how many images were successful and failed.

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.

• send_mr1 - send to Kirby MR1 3T scanner
• send_mr2 - send to Kirby MR2 3T scanner
• send_mr3 - send to Kirby MR3 7T scanner
• send_emageon - send to the Emageon (now Ultravisual) PACS system
• send_ews - send the the Philips workstation

The script will use either CTN send_image for standard DICOM files or DCMtk storescu for enhanced DICOM images. Do not mix standard and enhanced files in one command since this detection is done only once.

Binaries: Solaris2   NT  gzipped test image    zipped test image

dcmls

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.

dcminfo

Usage: dcminfo [-r] [-t tag] [-w <width>] [-f] 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). The selected files can optionally be renamed using their series number.

Second form lists all dicom fields names for one file sorted by the numeric tag. Adding -k will sort by the key name. Either the key name or numeric tag can be used with -t in first form. For numeric tags specify tow four digit number separated by comma (e.g. 0008,0031).

Third form will list all fields from one file in a cleaner format than provided by dcmdump. Field name is first, indented 2 spaces for each sequence or item key. Private field name are preceeded by dot . to make it clear they are vendor private fields. The field nasme is followed by 2 colons to make parsing easy, followed by the value in the original format used by dcmdump. Strings are surrounded by square barckets [], sequence and item delimiters are surrounded by braces (), integer and floats are bare, array elements are separated by backslash \. For long items like Pixel Data, the first few elements are shown with ... at then end to indicate the value is truncated.

Pre-defined tags for the first form are:

• InstitutionName
• InstitutionalDepartmentName
• StationName
• SeriesDate
• SeriesTime
• PatientName
• PatientID
• StudyID
• SeriesNumber
• AcquisitionNumber
• StudyDescription
• SeriesDescription
• ReferringPhysicianName
• PerformedProcedureStepDescription
• StudyComments
  

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>

dicom3tools

dcmtk

CTN Utility Programs

dcm_dump_file - Display contents of DICOM image header

Usage: dcm_dump_file [-b] [-g] [-l] [-t] [-v] [-z] file [file ...]

Binaries: Solaris2  NT  Linux

dcm_dump_element - Display a DICOM image header element

Usage: dcm_dump_element [-b] [-t] [-v] group element filein fileout

Binaries: Solaris2  NT

dcm_x_disp / dcm_w_disp - Quick display of DICOM image

Usage: dcm_x_disp [-b] [-t] [-w display_width -h display_height] [-W width] [-C center] <dicom image file>

Binaries: (dcm_x_disp) Solaris2   (dcm_w_disp) NT

simple_storage - DICOM server daemon

Usage: simple_storage [-a] [-c title]  [-d FAC] [-i] [-j] [-k] [-l log-file][-m maxPDU] [-n naming] [-p] [-s] [-t trips] [-u uid] [-v] [-w] [-x dir] [-z sec] port

Image Storage Redirection (JHU addition)

• The fields checked are Series Description, Study Description, Physician Name and Patient History. They are checked in the order shown above; the first field found with a flag will be used.
• One of the three flags, #-# or #s# or #a#, in these fields followed by a valid directory path, will cause the images to be moved or copied to that path.
• This destination directory must be an absolute path. ~username can be used and will be expanded.
• The named directory or it's parent directory must already exist and be owned by a user (i.e. not by root).
• If the named directory does not exist, but the parent does, simple_storage will create this last directory in the path for you. This created directory will be given the owner of the parent. This allows you to file your images in your directory areas on the fly, without pre-creating directories for each study.
• Images moved or copied into this directory will be owned by the owner of the directory.
• If the flag is #-# all images will be placed in a directory named MR in the specified directory.  (Actually, the SOPClass from the image header is used: MR, CT, CR, NM, US, XRF, XRA, etc.).
• If the flag is #s# a separate directory will be created for each series in the named directory. The series directories will be named with the series number from the DICOM header. If the series number is padded with blanks, the blanks will be converted to zeros so the directory name will be easier to deal with. This is best used with DICOM images from General Electric Signa scanners.
• If the flag is #a# a separate directory will be created for each acquisition in the named directory. The acquisition directories will be named with the acquisition number from the DICOM header. If the acquisition number is padded with blanks, the blanks will be converted to zeros so the directory name will be easier to deal with. This is best used with DICOM images from Philips scanners.
• Any error encountered during redirection will cause the image to be left in the default simple_storage directory.
• Remember! An extra network transfer via NFS is needed if the redirection directory is on a different host than the host simple_storage is running on. A copy of the image file and delete of the original is required if the redirection directory is on a different disk volume than the default simple_storage directory. The best case of just a rename (mv) occurs if the redirection directory is on the same disk volume as the default simple_storage directory.
• simple_storage must run as root or as another user with setuid user to use this option.

runDicom - Daemon to keep simple_storage running

Usage: runDicom [-help|-kill|-restart] [any simple_storage switches...]

If command line switches are provided, they are used when starting simple_storage, unless the first switch is one of the following:

-help	prints this message
-kill	kills runDicom and simple_storage
-restart	kills runDicom and simple_storage, then restarts both

The kill and restart switches will work for any user if runDicom is owned by root and set uid user bit is set. Otherwise the currently running runDicom process must be owned by the user performing the kill or restart.

If no command line switches for simple_storage are given on the command line, runDicom looks for the file /usr/local/sbin/runDicom.<hostname>, where <hostname> is the name returned by the gethostname system call.  That file must contain valid switches and switch parameters for simple_storage, one switch or parameter to a line. For example:

-l
/tmp/simple_storage.log
-s
-c
DICOM_STORAGE
-u
600
-f
-x
/g1/dicom
3010

-l /tmp/simple_storage.log -s -f -c DICOM_STORAGE -u 0 3010

Source & Binary: Solaris2

Full Downloads

Solaris 2.x binaries and shell scripts in a gzipped tar file

Windows NT binaries in a zip file

libctn.so CTN dynamic library