dicom2, How to

http://barre.nom.fr/medical/dicom2/how-to.html

Download | Install | Usage (1) (2) | How to | Problems | Limitations | Performances

How to
Understand output Set default options Convert to PNG, BMP, TARGA Convert to raw (vtk) List DICOM tags Generate subsets Clean images Extract frames Send me an email if you want me to add or create a new "How to" section that might be relevant for you or the other users.

Understand output
The default behavior of dicom2 is to process your files silently and display nothing but warnings and errors... Warnings (prefixed with [W]) are most of the time harmless and do not stop the conversion process, whereas errors (prefixed with [E]) do. It is possible to prevent these warnings from being displayed or even control many other output features by using the corresponding output options.

Set default options

Many default behaviours as well as default option-values are used during the conversion process, but these might not fit your own way to work. It is easy to redefine them, but you might getting tired of always specifying the same destination directory (--to), the same compression scheme (--compression), the same control flags (--warn, --rank), and so on. Put any of your usual options in the DICOM2 environment variable, and they will be used in every subsequent calls:
dicom2 --to=c:\temp --compression=fast --warn=n --rank=y -w *.dcm dicom2 --to=c:\temp --compression=fast --warn=n --rank=y -a test\*.dcm

... might be replaced by:

set DICOM2=--to=c:\temp --compression=fast --warn=n --rank=y dicom2 -w *.dcm dicom2 -a test\*.dcm

...

1 de 8

03/02/2012 10:51 a.m.

dicom2, How to

http://barre.nom.fr/medical/dicom2/how-to.html

No worry, you may still override these options by redefining them on the command-line (the first set of files will be written to c:\temp, the second to c:\temp2):
set DICOM2=--to=c:\temp dicom2 -w *.dcm dicom2 -w --to=c:\temp2 *.dcm

The way you might set and save environment variables depends on your operating system and your shell: win95/NT (command.com): set DICOM2=--warn=n --rank=y SunOS/Solaris (tcsh): setenv DICOM2 "--warn=n --rank=y"

Convert to PNG, BMP, TARGA

Fairly simple. dicom2 is a command-line driven program.Therefore, it shall be called using a set of options and arguments specifying its tasks. See Usage (1) and Usage (2) pages for complete informations regarding these options. Nevertheless, here are small examples:
dicom2 -w knee.dcm

will convert the medical file knee.dcm to Windows's BMP format. The resulting file will be called knee.dcm.bmp.
dicom2 -a -p *.dcm

will convert all files with extension .dcm to TARGA and PNG formats. The .tga extension will be appended to the resulting TARGA files (respectively .png to the PNG files).

Convert to raw (vtk)

The Visualization Toolkit (vtk for short) is a very powerful library that "covers dozens of graphics and visualization techniques". It provides functions to read 16 bits/pixel images (optionally preceeded by a header of fixed length) and automatically swaps and masks 16 bits words if needed. Unfortunately, the organization and the structure of the DICOM format is far from that expected format: there is no fixed-length header, and pixel data shall be "padded" (and optionally "cleaned") first to be usable. This whole stuff may be carried out by the conversion to RAW (have a look at the -r option for more explanations and diagrams regarding the resulting pixel structure). Here is a simple way to create these raw files using dicom2:
mkdir rawdir dicom2 --to=rawdir -r *

The --to=rawdir option is used to store the resulting files in the rawdir directory, although it might not be necessary as the .raw extension will be appended to each file. The --rank option might be useful if you plan to convert hundreds of files: it gives you a visual clue of the remaining files to process (in that situation you might use the --warn option too).

2 de 8

03/02/2012 10:51 a.m.

dicom2, How to

http://barre.nom.fr/medical/dicom2/how-to.html

Be aware that the vtk might be a bit demanding on the syntax of the name of the raw files it uses... In the case where many images should be read in the same time (and treated as a volume), these names must be numbered (ex: ct-raw.1, ct-raw.2, ct-raw.3, and so on). dicom2 may automagically append that kind of number, or even build a much more sophisticated filename (including contents of DICOM tags) by using a renaming pattern (see --rename).
dicom2 -r --rename=test:cur_rk ct1755621 ct23423 ct08234 will produce the files: test-1.raw test-2.raw test-3.raw

You might also need some informations about the image, especially if you are working on series. It is very easy, as you just have to perform a TEXT conversion on the image or one of the element of the series, and look for the corresponding field (see option -t for more explanations, and the "How To: List DICOM tags" section).
dicom2 -t1 test.an2 | grep -i "slice thick" Slice Thickness (0018,0050) 1 DS [10.00]

the value (within square brackets) is 10.0.

dicom2 -t1 test.an2 | grep -i "spacing" Pixel Spacing (0028,0030) 2 DS [8.593750E-01\8.593750E-01]

the pixel size is 0.859 mm in the horizontal dimension (columns), and the same along the vertical dimension (rows).
dicom2 -t1 test.an2 | grep -i "bit" Bits Allocated (0028,0100) Bits Stored (0028,0101) High Bit (0028,0102)

1 1 1

US [8] US [8] US [7]

If you plan to use DICOM files to work on 3D reconstruction, you will surely have to look at the vtkVolume16Reader class. This class inherits the members of the more general vtkVolumeReader class.
vtkVolume16Reader reader reader SetFilePrefix $FILE_PREFIX reader SetFilePattern $FILE_PATTERN reader SetImageRange $START_SLICE $END_SLICE reader SetDataSpacing $PIXEL_SIZE_X $PIXEL_SIZE_Y $Z_SPACING reader SetDataDimensions $COLUMNS $ROWS

The FILE_PREFIX and FILE_PATTERN variables may be set according to the name of the raw files to load (for example, FILE_PREFIX = "test-" and FILE_PATTERN = %s%d.raw to read the files: test-1.raw, test-2.raw, ...). The FILE_PATTERN is based on the C function printf() : the %s field represents the FILE_PREFIX, the %d field will capture the rank of the file. The START_SLICE and END_SLICE variables are used to define a particuliar set of files within a series. It depends on the number of raw files you converted. The data spacing specifiers PIXEL_SIZE_X, PIXEL_SIZE_Y and Z_SPACING (slice thickness) are extracted from one of the files using text conversion. See previous topic. The data dimensions (image size) COLUMNS and ROWS are easy to find, but they may also be extracted from a file using the usual text conversion.
3 de 8 03/02/2012 10:51 a.m.

dicom2, How to

http://barre.nom.fr/medical/dicom2/how-to.html

There are also a HeaderSize() and a DataMask() member, but you do not need to fix them: there is no header in the raw files, and no need to mask data as optional overlaid data were already removed during the conversion. Raw data may be written using Little (-r0) or Big (-r1) Endian syntax, depending on your needs. You will have to specify that order to the vtkVolume16Reader object using one of the corresponding member (SetDataByteOrderToLittleEndian(), or SetDataByteOrderToBigEndian()).

List DICOM tags

It might be interesting to list the contents of the data-set stored in a DICOM file, in order to recover the most useful informations in a human-readable form (the size of the image, the position of the patient, the offset to the pixel data, and so on). Hence, you may use dicom2 to save a textual representation of this file (see option -t for more explanations), where each element will be listed as [description, tag, VM, VR, value]. But it might become a bit frustrating to create that file, display it, and then remove it. Hopefully, this textual representation might be redirected to the standard output:
dicom2 -t1 test.an2 Transfer Syntax UID Image Type Study Date Image Date Study Time Modality Manufacturer Patient's Name Slice Thickness Series Number Image Number Samples per Pixel Photometric Interpretation Number of Frames Frame Increment Pointer Rows Columns Bits Allocated Bits Stored High Bit Pixel Representation Pixel Data (0x3fe)] ..... (0002,0010) (0008,0008) (0008,0020) (0008,0023) (0008,0030) (0008,0060) (0008,0070) (0010,0010) (0018,0050) (0020,0011) (0020,0013) (0028,0002) (0028,0004) (0028,0008) (0028,0009) (0028,0010) (0028,0011) (0028,0100) (0028,0101) (0028,0102) (0028,0103) (7FE0,0010) ..... 1 1-n 1 1 1 1 1 1 1 1 1 1 1 1 1-n 1 1 1 1 1 1 1 UI CS DA DA TM CS LO PN DS IS IS US CS IS AT US US US US US US OB [1.2.840.10008.1.2.1] [ORIGINAL\PRIMARY] [1995.06.26] [1995.06.26] [11:20:00] [MR] [Philips] [Doe John] [10.00] [1] [103] [1] [MONOCHROME2] [16] [(0018,1063)] [256] [256] [8] [8] [7] [0] [1048576 bytes at offset 1022

You can make an alias (depending on your shell) to improve the overall efficiency :)
alias dcm 'dicom2 -t1' dcm test.an2 | more

You might extract a single element by using the grep filter (which is a very common tool in the
4 de 8 03/02/2012 10:51 a.m.

dicom2, How to

http://barre.nom.fr/medical/dicom2/how-to.html

unix world, and is also available for Windows when working on the command prompt). grep will search for an expression in a file or in the data available on the standard input.
dicom2 -t1 test.an2 | grep "Bits Allocated" Bits Allocated (0028,0100) 1 US [8]

or,
dicom2 -t1 test.an2 | grep (0028,0100) Bits Allocated (0028,0100) 1 US [8]

or,
dicom2 -t0 test.an2 grep (0028,0100) test.txt Bits Allocated (0028,0100)

US [8]

Generate subsets
Dealing with hundred of files might become a very time consuming task. Therefore, why not try to work with reduced data before running the real job on full-sized images. Halving will achieve this goal (see option --halve). For example, one could build a 256x256 and a 64x64 set of DICOM files from a 512x512 set of original DICOM files. As most options performs linearly, it is obvious to see that dicom2 will carry out its tasks 4 (64) times quicker on the 256x256 (respectively 64x64) set than on the 512x512 set.
mkdir dir256 dicom2 --halve --to=dir256 -d * mkdir dir64 dicom2 --halve=2 --to=dir64 -d dir256/*

The first call to dicom2 produces the first reduction to 256x256 (stored in the dir256 directory), and the second call creates the second reduction to 64x64 by halving (2 times) the previously converted files located in the dir256 directory. The final set is stored in the dir64 directory.

Clean images (accumulate, mask, crop)

Typical images may exhibit more than the desired body-structures. Artefacts, as well as parts of the bed may be hard to locate and tend to produce undesirable effects (while using 3D reconstruction for example). Moreover, the form and location of these artefacts might change within a series of images, preventing the user from building a hypothetical mask based on a single image of the series. A rudimentary but better approach may be applied with some of the dicom2 functions.

5 de 8

03/02/2012 10:51 a.m.

dicom2, How to

http://barre.nom.fr/medical/dicom2/how-to.html

4 images from a series of 250 axial slices (check the headbed and the left and right "pillows")

Accumulate
First of all, you shall compute which of the pixels are used along all images within the series (which is quite similar to an accumulation buffer representing the maximum occupancy of the structures). See option --acc for more explanations and diagrams.
dicom2 --acc=max *

computed (a) on 4 slices, (b) on 250 slices

The resulting DICOM file (which defaults to acc-max.dcm) shall be converted to BMP, in order to be recognized by any painting program.
dicom2 -w acc-max.dcm

Mask
You are now able to create a mask starting from this image, by attributing zero to the points that you want to save in each frame, and non-zero to these that you want to remove(set to 0). The mask will act like a kind of stencil: the zero-area being a "hole", the non-zero area covering the non-desired pixels. Have a look at the --mask option to get more coverage on the principles.

a mask (zero is black)

6 de 8

03/02/2012 10:51 a.m.

dicom2, How to

http://barre.nom.fr/medical/dicom2/how-to.html

We are quite finished: let's build up the new masked images, which will be stored in the masked directory:
mkdir masked dicom2 --mask=zero:acc-max.bmp --to=masked -d *

the 4 original slices

the 4 original slices, now masked

Crop
The resulting images will exhibit more zeros than the original ones (as pixels from removed structures are set 0). Hence you might consider using the --crop option to save the relevant part of the image only, and speed-up further processes. The coordinates of the cropping-window might be computed from the mask, which explicitly shows which parts of the resulting image will remain, and which won't. The --crop and --mask options may be used in the same time (as --mask occurs first). Forget the previous call to dicom2 and speed up the process with:
mkdir masked dicom2 --mask=zero:acc-max.bmp --crop=44:70:400:400 --to=masked -d *

original slice (512x512), now masked and cropped (400x400)

Summary
dicom2 --acc=max * dicom2 -w acc-max.dcm

7 de 8

03/02/2012 10:51 a.m.

dicom2, How to

http://barre.nom.fr/medical/dicom2/how-to.html

... create the mask using acc-max.bmp...

mkdir masked dicom2 --mask=zero:acc-max.bmp --crop=44:70:400:400 --to=masked -d *

Extract frames
As the --frame option has been enhanced since v1.5, it is now very easy to work on multiple-frame files. Although dicom2 is able to read multi-frame files, you shall not forget that its output is always made of single-frame files. Therefore, you can not build multiple-frame files, but you can extract many single-frame files from one multiple-frame file. See option --frame to learn more about frame selection. Let's have a look at some examples, using the file mframe, which stores 3 frames (you can use the -t1 option to find the number of frames):
dicom2 -t1 mframe | grep -i frame Number of Frames (0028,0008)

IS [3]

dicom2 -w mframe produces 3 files (mframe-1.bmp mframe-2.bmp mframe-3.bmp)

corresponding to each frame

converted to BMP.
dicom2 -d --frame=2:3 --rename=slice:cur_fr mframe

produces 2 files (slice-2.dcm slice-3.dcm) corresponding to frames 2 and 3 converted to DICOM.

Download | Install | Usage (1) (2) | How to | Problems | Limitations | Performances

Medical Imaging / Sbastien Barr / Jan. 1998

8 de 8

03/02/2012 10:51 a.m.