DICOM and REC file Utilities

Johns Hopkins, MR Research and 

Kennedy Krieger Institute, F.M. Kirby Research Center

Table of Contents

rec_convert - Convert REC file into Analyze formats

Usage:  rec_convert [-o <output root>] [-n] [-3] [-q] [-d] [-s] <input-recfile>

The Philips REC data input file's name can have any form but must end with ".REC" or ".rec". There must be a parameter file with root name matching the rec file and ending in ".PAR" or ".par". The PAR file is used for header info and data ordering so no DICOM file is needed as for version 1.x. Since it reads the PAR file ordering information the REC file does not need to be sorted.

It can convert rec files containing magnitude, real, imaginary and/or phase data. Output file name has Philips "type" code appened when not magnitude. (_1 real, _2 imaginary, _3 phase).

Examples:

/g1/jgillen> rec_convert 20070418bsa18_6_1.rec
JHU REC File Conversion Utility v2.3.3 (samfs)
Header Info:
date: 2007.04.18  time: 18:25:25  name: bsa18
iden: none
orig: FM Kirby Research Center
desc: 
nrows: 512  ncols: 512  bits: 16
xspc: 0.449000  yspc: 0.449000  slthk: 5.000000  slspc: 0.000000
FOVap: 230.000000  FOVfh: 5.000000   FOVrh: 186.875000
echos: 1  phases: 1  dynamics: 34  slices: 1   plane: 0  TR: 6000.000000
echo phase dynamic
  1     1     34
done
/g1/jgillen>

The input file is acquistion 6 of a study identified as 20070418bsa18. The output files have the same root as the input and are in the same directory since no output root was given. All 34 dynamics for all slices are in the .img file.

/g1/jgillen> rec_convert -s -3 rl10_7_1.rec
JHU REC File Conversion Utility v2.3.3 (samfs)
Header Info:
date: 2006.04.20  time: 14:57:15  name: xxxxxx xxxxxx
iden: #-#/g2/xxxxx/Emergent2
orig: FM Kirby Research Center
desc: 
nrows: 128  ncols: 128  bits: 16
xspc: 1.875000  yspc: 1.875000  slthk: 3.000000  slspc: 0.000000
FOVap: 216.000000  FOVfh: 150.000000   FOVrh: 240.000000
echos: 1  phases: 1  dynamics: 239  slices: 50   plane: 0  TR: 3000.000000
echo phase dynamic
  1     1    239
done
/g1/jgillen> ls rl10_7_1
rl10_7_1.001.hdr  rl10_7_1.061.hdr  rl10_7_1.121.hdr  rl10_7_1.181.hdr
rl10_7_1.001.img  rl10_7_1.061.img  rl10_7_1.121.img  rl10_7_1.181.img
rl10_7_1.002.hdr  rl10_7_1.062.hdr  rl10_7_1.122.hdr  rl10_7_1.182.hdr
rl10_7_1.002.img  rl10_7_1.062.img  rl10_7_1.122.img  rl10_7_1.182.img
rl10_7_1.003.hdr  rl10_7_1.063.hdr  rl10_7_1.123.hdr  rl10_7_1.183.hdr
.
.
.
rl10_7_1.058.hdr  rl10_7_1.118.hdr  rl10_7_1.178.hdr  rl10_7_1.238.hdr
rl10_7_1.058.img  rl10_7_1.118.img  rl10_7_1.178.img  rl10_7_1.238.img
rl10_7_1.059.hdr  rl10_7_1.119.hdr  rl10_7_1.179.hdr  rl10_7_1.239.hdr
rl10_7_1.059.img  rl10_7_1.119.img  rl10_7_1.179.img  rl10_7_1.239.img
rl10_7_1.060.hdr  rl10_7_1.120.hdr  rl10_7_1.180.hdr
rl10_7_1.060.img  rl10_7_1.120.img  rl10_7_1.180.img
/g1/jgillen> 

Output is to a directory named rl10_7_1. 3D files are selected so the is a header and image file for each of the 239 dynamics containing 1 volume (time point).

dcm_convert - Convert DICOM image files into other formats

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

dcm_convert -h

Input Files:

Philips ACS/NT 6.x naming convention is:
                                      series  slice dynamic
                                         vv   v     v
1.3.46.670589.11.5406.9.955073100000002870301.3.1.1.1.0.44
^--------------^ ^----^ ^-----^^--------^  ^^   ^
   Philips MR   scanner patient study     recon echo

Philips Interra 8.x naming convention is:
                                      series  slice dynamic
                                         vv   v     v
1.3.46.670589.11.5406.9.955073100000002870301.3.1.1.1.0.0.2
^--------------^ ^----^ ^-----^^--------^  ^^   ^
   Philips MR   scanner patient study     recon echo

GE Signa naming convention is:
                     scanner              image*
                   v--------v              v-v
1.2.840.113619.2.5.1762527352.1600.969534116.278
^----------------^            ^------------^
    Signa MR                   study/series**

* this number increments but bears no relation to the image or phase number. It increments through multiple series until reaching 999 then resets to 1 and the field to the left increments by 1.
** this number changes with exam but otherwise increments only when the image number goes over 999.
Because of this GE images can't be identified as to study, series or image from the DICOM filename (which is the UID).

Siemens Magnetom naming convention is:
                        series date          slice
                          v------v           v-v
1.3.12.2.1107.5.2.6.21601.20001003125935000022329
                    ^---^         ^----^  ^^
     system serial number        ser time   series
 

Using the Series Menu

A 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 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 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 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_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

dcm_move - Rename and move DICOM image files

Usage: dcm_move [-s <source-dir>] [-m modality] [-f] [-n] [<directory>]

Images are renamed according to the study, series and image 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 is used to read Dicom header information and must be in a directory in your PATH.

if -f (flat) is not specified for an anatomic series (i.e. no dynamics/multiphase):

• images are stored in the destination directory
• in a directory named using the 5 digit exam number
• in a directory named using the 3 digit series number
• in a file named using the 4 digit image number

images are stored in the destination directory

in a directory named using the 5 digit exam number

in a directory named using the 3 digit series number

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

• images are stored in the destination directory
• in a file named <5 digit exam>.<3 digit series>.<4 digit image>

• images are stored in the destination directory
• in a file named <5 digit exam>.<3 digit series>.<3 digit slice>.<4 digit dynamic>

No Dynamic switch

Patient History Field

WARNING

Example

csh Script

dcm_count - Count number of images in DICOM directory by series

Usage: dcm_count [<directory-path>]

/g1/dave/smith419> dcm_count
Philips  MR/1.3.46.670589.11.5406.9.1067676100000012170901 22 x 1 = 22
Philips  MR/1.3.46.670589.11.5406.9.1067676100000012171101 17 x 60 = 1020
Philips  MR/1.3.46.670589.11.5406.9.1067676100000012171306 12 x 360 = 4320
Philips  MR/1.3.46.670589.11.5406.9.1067676100000012171401 12 x 1 = 12
/g1/dave/smith419>

csh Script

dcm_combine - Combine multi NEX series into single series

Usage: dcm_combine [-n <number-of-recons>] <root-filename>

If -n is not given, 2 recons are assumed. Dynamics are interleaved to make new recon. For example, with 2 recons:
 
 

This      becomes	this
recon1/dyn1	recon3/dyn1
recon2/dyn1	recon3/dyn2
recon1/dyn2	recon3/dyn3
recon2/dyn2	recon3/dyn4
recon1/dyn3	recon3/dyn5
recon2/dyn3	recon3/dyn6

Run from the simple_storage directory (not inside the MR directory). This script expects a directory named MR to exist in the present working directory.

<root-filename> is the image name up to but not including the recon digits (red parts below).

The script assumes consecutive recons are being combined, but they don't necessarily need to start at 1. The usual case is for recons 1 and 2 to be combined to make a new recon 3. If some error occurs starting the first recon, you could have recons 2 and 3 combined to make 4. Output is to a recon numbered one greater than the highest found.

For reference Philips naming convention is:
                                      series  slice dynamic
                                         vv   v     v
1.3.46.670589.11.5406.9.955073100000002870301.3.1.1.1.0.44
^--------------^ ^----^ ^-----^^--------^ ^^   ^
   Philips MR   scanner patient study  recon  echo

csh Script

dcm_study - Show study number of DICOM image

Usage: dcm_study <image-filename>

csh Script

send_image - Send an image to a DICOM server

Usage: send_image [-a application] [-c called] [-m maxPDU] [-p] [-q] [-r] [-s SOPName] [-x FAC] [-v] node port image [image...]

Binaries: Solaris2   NT  gzipped test image    zipped test image

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