Computing Resources

DICOM Utilities

Johns Hopkins, MR Research and 

Kennedy Krieger Institute, F.M. Kirby Research Center

Table of Contents

DICOM Servers running on godzilla

Local tools

dicom3tools - toolkit from David Clunie

dcmtk - toolkit from OFFIS

CTN - software package from RSNA/Mallinckrodt Institute


DICOM Servers

There are two DCMtk storescp servers running on godzilla. The Philips scanners negociate 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:

#-#/g5/kirby/jgillen/scan_20190502/subj1

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, dcm_movegui Rename and move DICOM files
send_dicom Send DICOM images to DICOM server
dcmls List DICOM files with selected header info
dcminfo Show selected DICOM header inof for one or more files
dcm2par Convert Enhanced-MR DICOM to Philips PAR/REC
dicomeread.m MATLAB script to read enhanced MR format DICOM files
dcmexamcard Program to extract binary large objects from Philips DICOM Raw Data Storage SOP files.

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

dcm_movegui

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
-d add .dcm to output filenames, useful for some Windows apps
-n no echo/phase/dynamic breakdown

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.

WARNING

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.

Example


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

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

This script will send the specified DICOM images to a DICOM server. 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 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.

If no file 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 copied 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 program is configured at the beginning of the script.

Zip File


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.

Perl Script

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.

-r

rename scanned dicom files using series number

-t additional tags to display - use colon separated names from dcminfo -l
-w maximum width of displayed data table - default 200
-f
        
full dicom read - without this switch only the first 20k bytes of the dicom file is read. Most parameters of interest are in this part and the time to read is greatly decreased.

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

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

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.

-a

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

dcm2par

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

dicomeread.m

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

dcmexamcard

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

dicom3tools

ancp Copy ACR-NEMA file
ancreate Create dicom file
andiff
andump Describe ACR-NEMA file content
antodc Convert ACR-NEMA to DICOM
binpatch
bmpdump
dcacqmap Create visual map of acquisition pattern
dcarith Arithmetic on DICOM pixels
dcbriggs Create DICOM Briggs pattern
dcburn
dccomb
dccp Copy DICOM file
dcdecmpr
dcdict Extract dictionary elements
dcdirdmp Describe DICOMDIR content
dcdirmk Create DICOMDIR
dcdisp Display file on X window
dcdtchg Change UIDs consistently
dcdump Describe DICOM file content
dcencap Encapsulate compressed stream in a DICOM file
dcfile Describe DICOM file content
dchist DICOM image statistics
dcintro Introduction and options
dciodvfy Describe DICOM objects
dckey Extract attribute values
dclutburn
dclutdmp dump LUT contents
dclutmix
dcmerge Merge DICOM files
dcmkpres Create DICOM presentation state
dcmulti Make multiframe image from single frames
dcortho
dcostosr
dcpatmpl Apply patient and study template
dcposn DICOM locate position
dcpost
dcproj
dcrmmeta Remove meta information header
dcsmpte Create DICOM SMPTE pattern
dcsort Make sorted list of images
dcsqextr Extract Papyrus images
dcsrdump
dcsrmrg
dcstats DICOM image statistics
dcsub
dctable Make tables of attribute values
dctopdf Extract DICOM encapsulated PDF
dctopgm8
dctopgx DICOM image to PGX file
dctopnm DICOM image to PNM file
dctoraw DICOM image to raw file
dcuidchg Change UIDs consistently
dcuncat Split multiframe image into concatenation
dcunmeta Remove DICOM Metaheader
dumptiff
dumpwhat
gawdump GE Advantage Windows to DICOM
gawtodc GE Advantage Windows to DICOM
ge98id GE 9800 dump identifiers
ge98topgm GE 9800 image to PGM file
gendump Genesis dump contents
gentodc Genesis to DICOM
gentopgm Genesis ximg file to PGM file
himrdump himr dump contents
himrtodc himr to DICOM
himrunid
imtndump Imatron dump contents
imtntodc Imatron to DICOM
jpegdump
jpegsplit
pacedump GE PACE dump contents
pacetodc GE PACE to DICOM
pacetopgm GE Pace image to PGM file
paceunid paceunid (1) - PACE remove identification
pbmswbit
pbmtoovl Create DICOM Overlay from PBM file
pdftodc Encapsulate PDF in DICOM
pgmtobmp
pgxtodc Create DICOM from PGX file
pnmpred
pnmtodc Create DICOM from PNM file
pnmtoraw
pqdump pq dump contents
pqsplit
pqtodc pq to DICOM
rawarith
rawdiff
rawftodc Create DICOM from raw float file
rawmask
rawnjl
rawnjl2 JPEG-LS compress/decompress from raw file
rawtodc Create DICOM from raw file
sgndump Signa dump contents
sgntodc Signa to DICOM
shimdump Imatron dump contents
shimtodc Imatron to DICOM
sompdump somp dump contents
somptodc somp to DICOM
syttopgm GE Sytec image to PGM file
toshtodc Convert separate Toshiba ACR-NEMA header and raw pixel data files to DICOM
vsntopgm Vision image to PGM file

dcmtk

dcm2pnm Convert DICOM images to PPM/PGM, PNG, TIFF or BMP
dcm2xml Convert DICOM file and data set to XML
dcmcjpeg Encode DICOM file to JPEG transfer syntax
dcmconv Convert DICOM file encoding
dcmcrle Encode DICOM file to RLE transfer syntax
dcmdjpeg Decode JPEG-compressed DICOM file
dcmdrle Decode RLE-compressed DICOM file
dcmdspfn Export standard display curves to a text file
dcmdump Dump DICOM file and data set
private.dic Private DICOM dictionary locally with added Philips fields
dcmftest Test if file uses DICOM part 10 format
dcmgpdir Create a general purpose DICOMDIR
dcmj2pnm Convert DICOM images to PGM, PPM, BMP, TIFF or JPEG
dcmmkcrv Add 2D curve data to image
dcmmkdir Create a DICOMDIR file
dcmmklut Create DICOM look-up tables
dcmodify Modify DICOM files
dcmp2pgm Read DICOM image and presentation state and render bitmap
dcmprscp DICOM basic grayscale print management SCP
dcmprscu Print spooler for presentation state viewer
dcmpschk Checking tool for presentation states
dcmpsmk Create DICOM grayscale softcopy presentation state
dcmpsprt Read DICOM images and presentation states and render print job
dcmpsrcv Network receive for presentation state viewer
dcmpssnd Network send for presentation state viewer
dcmqridx Register a DICOM image file in an image database index file
dcmqrscp DICOM image archive (central test node)
dcmqrti The Terminal Initiator Telnet Client Program
dcmquant Convert DICOM color images to palette color
dcmscale Scale DICOM images
dcmsign Sign and Verify DICOM Files
dcod2lum Convert hardcopy characteristic curve file to softcopy format
dconvlum Convert VeriLUM files to DCMTK display files
dsr2html Render DICOM SR file and data set to HTML
dsr2xml Convert DICOM SR file and data set to XML
dsrdump Dump DICOM SR file and data set
dump2dcm Convert ASCII dump to DICOM file
echoscu DICOM verification (C-ECHO) SCU
findscu DICOM query (C-FIND) SCU
movescu DICOM retrieve (C-MOVE) SCU
pdf2dcm Convert PDF file to DICOM
storescp DICOM storage (C-STORE) SCP
storescu DICOM storage (C-STORE) SCU
termscu DICOM termination SCU
wlmscpfs DICOM Basic Worklist Management SCP (based on data files)
xml2dcm Convert XML document to DICOM file or data set
xml2dsr Convert DICOM SR file and data set to XML

 


CTN Utility Programs

dcm_dump_file Display contents of DICOM image header
dcm_dump_element Display a DICOM image header element
dcm_x_disp/dcm_w_disp Quick display of DICOM image
dcm_move Rename and move DICOM image files
dcm_count Count number of images in DICOM directory by series
dcm_combine Combine multi NEX series into single series
dcm_study Show study number of DICOM image
send_image Send an image to a DICOM server
simple_storage DICOM server daemon
runDicom Daemon to keep simple_storage running
Full Downloads All programs in gzipped tar file or zip file

dcm_dump_file - Display contents of DICOM image header

This program is part of the RSNA/Mallinckrodt Institute Central Test Node Software package.

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

-b Input files are stored in big-endian byte order
-e Exit on file open error.  Do not process other files
-g Remove group length elements
-l  Use (retired) length-to-end attribute for object length
-t  Part 10 file
-v Place DCM facility in verbose mode
-z Perform format conversion (verification) on data in files

file

One or more information objects to be dumped

dcm_dump_element - Display a DICOM image header element

This program is part of the RSNA/Mallinckrodt Institute Central Test Node Software package.

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

 
-b Read file assuming big endian transfer syntax
-t Read file assuming DICOM Part 10 format
-v Place DCM facility in verbose mode

group element

The tag of the element to be dumped
filein fileout Input and output files

dcm_x_disp / dcm_w_disp - Quick display of DICOM image

This program is part of the RSNA/Mallinckrodt Institute Central Test Node Software package.

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

-b Read file assuming big endian transfer syntax
-t Read file assuming DICOM Part 10 format

simple_storage - DICOM server daemon

This program is part of the RSNA/Mallinckrodt Institute Central Test Node Software package. It has been modified locally to have several additional features.

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

-a Abort Association after receiving one image (debugging tool)
-c Set the AE title of this server
-d Place one facility (DCM, DUL, SRV) in verbose mode
-f Fork a new process for each connection
-i Ignore some incorrect parameters in Association request
-j Use thread model.  Spawn a new thread for each connection
-k Kill (delete) files immediately after they are received
-l Log stdout and stderr to named log file (JHU addition)
-m Set the maximum received PDU in the Association RP to maxPDU
-n <naming> contains naming convention for files stored
-p Dump the Association RQ parameters
-s Silent mode.  Don't dump attributes of received images
-t Execute the main loop trips times (debugging tool)
-u Run as this alternate uid when not running as root (JHU addition)
-v Place DUL and SRV facilities in verbose mode
-w Wait flag.  Wait for 1 second in callback routines (debugging)
-x Set base directory for image creation.  Default is current directory
-z Wait for sec seconds before releasing association
port The TCP/IP port number to use

Image Storage Redirection (JHU addition)

All images are stored in the directory named on the command line using the -x option or in the current working directory where simple_storage is started, if -x is not given. You can redirect images from this default directory using information given in certain DICOM header fields. Binaries: JHU Solaris2    unmodified Solaris2  NT

runDicom - Daemon to keep simple_storage running

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

This program runs in the background. It starts a simple_storage daemon and waits for it to exit (or crash). It then starts another one, so simple_storage is always kept running.

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
If that file does not exist, the following switches are used for starting simple_storage:
-l /tmp/simple_storage.log -s -f -c DICOM_STORAGE -u 0 3010
runDicom logs starts and shutdowns of simple_storage in the file /tmp/simple_storage.log. This same file can be used for simple_storage
log info using the switch "-l /tmp/simple_storage.log".

Source & Binary: Solaris2


Full Downloads

All files described above for each platform in a single compressed file

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

Windows NT binaries in a zip file

libctn.so CTN dynamic library


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