dicom2 logo
Download | Install | Usage (1) (2) | How to | Problems | Limitations | Performances 
TOCUsage (2)Problems 
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.
Top Understand output
Set default options
  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.
Understand output Set default options
Convert to PNG, BMP, TARGA
  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 
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" 

Set default options Convert to PNG, BMP, TARGA
Convert to raw (vtk)
  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 PNG, BMP, TARGA Convert to raw (vtk)
List DICOM tags
    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). 
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)  1    US [8] 
               Bits Stored (0028,0101)  1    US [8] 
                  High Bit (0028,0102)  1    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.
  • 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()).
Convert to raw (vtk) List DICOM tags
Generate subsets
  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 (0002,0010)  1    UI [1.2.840.10008.1.2.1] 
                Image Type (0008,0008)  1-n  CS [ORIGINAL\PRIMARY] 
                Study Date (0008,0020)  1    DA [1995.06.26] 
                Image Date (0008,0023)  1    DA [1995.06.26] 
                Study Time (0008,0030)  1    TM [11:20:00] 
                  Modality (0008,0060)  1    CS [MR] 
              Manufacturer (0008,0070)  1    LO [Philips] 
            Patient's Name (0010,0010)  1    PN [Doe John] 
           Slice Thickness (0018,0050)  1    DS [10.00] 
             Series Number (0020,0011)  1    IS [1] 
              Image Number (0020,0013)  1    IS [103] 
         Samples per Pixel (0028,0002)  1    US [1] 
Photometric Interpretation (0028,0004)  1    CS [MONOCHROME2] 
          Number of Frames (0028,0008)  1    IS [16] 
   Frame Increment Pointer (0028,0009)  1-n  AT [(0018,1063)] 
                      Rows (0028,0010)  1    US [256] 
                   Columns (0028,0011)  1    US [256] 
            Bits Allocated (0028,0100)  1    US [8] 
               Bits Stored (0028,0101)  1    US [8] 
                  High Bit (0028,0102)  1    US [7] 
      Pixel Representation (0028,0103)  1    US [0] 
                Pixel Data (7FE0,0010)  1    OB [1048576 bytes at offset 1022 (0x3fe)] 

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

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

dicom2 -t0 test.an2
grep (0028,0100) test.txt
            Bits Allocated (0028,0100)  1    US [8]

List DICOM tags Generate subsets
Clean images
  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.

Generate subsets Clean images (accumulate, mask, crop)
Extract frames
  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. 
head 1head 2head 3head 4
4 images from a series of 250 axial slices
(check the headbed and the left and right "pillows")


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 * 
accumulate maxaccumulate max all
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 


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. 
mask zero
a mask (zero is black)
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 * 
head 1head 2head 3head 4
the 4 original slices
head masked 1head masked 2head masked 3head masked 4
the 4 original slices, now masked


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 * 
head 3head crop 3
original slice (512x512), now masked and cropped (400x400)


dicom2 --acc=max * 
dicom2 -w acc-max.dcm 
... create the mask using acc-max.bmp... 
mkdir masked 
dicom2 --mask=zero:acc-max.bmp --crop=44:70:400:400 --to=masked -d * 
Clean images 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)  1    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  TOCUsage (2)Problems 
Medical Imaging / Sébastien Barré / Jan. 1998