dicom2 logo
 
 
 
      dicom2
      dicom2 is a free command-line driven program which allows you to convert medical images and DICOM files to various other formats, while optionally performing some rudimentary image processing tasks... 
 
reads DICOM file, or raw data-sets (ACR/NEMA). 
converts non-encapsulated (native) syntax to PNG, BMP, TARGA, raw, DICOM (any syntax). 
lists DICOM tags in a human-readable form. 
allows batch conversion. 
extracts multiple-frame files. 
renames destination files using user-defined pattern based on DICOM tags. 
accumulates set of files into one image (to generate masks). 
provides some image processing functions: mask, crop, halve, flip, window. 
is small
 
available for: 
 win95 logo Windows 95/NT (x86)
 linux logo Linux (x86)
 
      Table of contents
 
   

Download

Install

Usage

How to

Problems

Limitations

Performance

 
      Changelog
 
  Version 1.9n, 19 February 2007
newThis release fixes a minor bug that would occur when reading a few specific instances of Siemens NM files.
 
Version 1.9m, 12 February 2007
newThis release fixes a few bugs people reported recently. Thank you for your feedback. Binaries are also about 13% smaller (not that they were really big, mind you).
 
Version 1.9l, 7 March 2005
newWow, no update in a long time. This new release just fixes some bug people reported in the last few years (fortunately not too many). thank you guys. The only major change is that, at last, the DICOM dictionary file (dicom.din) is not needed anymore, it is bundled within the binary: no need to install it in awkward locations anymore, you can safely remove your old dictionary.
 
Version 1.9h, 14 Jul. 2000
newI wish I had some time to document the changes and update this site :( Maybe later in 2001. I'm still maintaining this software from time to time, removing bugs and adding some functions.
 
Version 1.8, 21 Jan. 1998
newPNG format supported (new -p option). 
newNew DICOM2 environment variable to set default options. 
newNew --compression option to control the compression method used by some destination formats. 
newNew --resample option to control the resampling process (to 8 or 16 bits). 
newNew --get=[max][:min][:mean] option to get maximum/minimum/mean pixel values in frame. 
newNew --timer option to time each call to dicom2 (returns elapsed time).  
 
updatedI/Os have been optimized. Expect 30% to 100% speed-up in some cases. Check performance tests. 
updatedNew parameters [=il|el|eb] added to -d, allowing DICOM conversion to new syntax. 
updatedNew parameter [=n] added to --halve, allowing to halve many times in a single call. 
updatedNew parameters [=center:width] added to --win, allowing user-specified windowing arguments. 
updatedNew optional [y|n] parameters added to --name, --rank, --reverse, --sort. 
updatedOption --nowarn has been replaced by option --warn[=y|n], but remains for backward compatibility. 
updatedThe resampling process has been slightly modified when dealing with monochrome images (no min). 
updatedWin 95/NT users: the Borland Redistributable Run Time DLL is no more needed :) (see Download page) 
updatedFixed some very nice bugs and potential memory leaks (and introduced new one :). 
  
Version 1.7, 18 Dec. 1997
newIndependent version number added to the DICOM dictionary (displayed at start-up). Update it. 
newWindows NT support (tested and updated to check dictionary in winnt/ directories).  
newNew accumulating mode --acc=min 
newNew NT and Linux performancetests using a Pentium II @ 300 mhz, 96 meg RAM. 

updatedCorrected a small bug preventing Linux version to find the dictionary in some cases. 
  
Version 1.6, 14 Oct. 1997


updatedA minor bug corrupting MONOCHROME1conversion to TARGA has been fixed. 
updatedSmall changes in the DICOM dictionary. Update it. 
  
Version 1.5, 1 Oct. 1997
newFiles have been moved to a new location !  
newPlanar configuration 1 (color-by-plane) is now supported. 
newConversion to true DICOM format is now supported. See -d. 
newNew "How to..." section describing how to extract frames from multiple-frame files. 
newConverting a single frame from a multiple-frame file to DICOM is now supported. 
newNew renaming pattern fields: cur_fr and cur_fr0, related to the current frame number. 
newA new --step=n option allows the user to process every n-th file only. 

updatedThe --frame option has been enhanced, allowing the specification of ranges. 
updatedThe --rank option now displays the rank of the current file AND frame.  
updatedThe renaming pattern aliases have been changed. 
updatedRGB components are resampled to 8 bits when converting to TARGA or BMP. 
updatedThe structure of pixels resulting from a RAW conversion has been clarified (diagrams). 
updatedThe --acc, --mask options have been clarified too (diagrams). 
updatedThis site has grown. The Usage page has been split into pages (1) and (2). 
  
Version 1.0, Sept. 1997


newConversion from RGB (color-by-pixel) is now supported, as well as samples/pixel > 1. 
newAccess to a particular frame in a multiple frames file is now allowed. See --frame. 
newImages stored as a stream of bytes (VR = OB) are now handled correctly. 
newSequences Item (VR = SQ) are now stored correctly. 
 
updatedBMP format is now better supported (an alignment bug has been fixed). 
updatedTEXT conversion is now performed before any image processing functions. 
updatedA VR =DA and VR=TM bug has been fixed. 
updateddicom2 performs a bit faster. 
      Download
     

The dicom2 tool is a single executable file. Windows users can download this binary file directly. Linux users can download a gzip'ed compressed archive and decompress it accordingly. Note: there is no separate DICOM dictionary file anymore, it is bundled within the binary. You can safely remove your old DICOM dictionary (dicom.din).

Executable
O.S. / Processor
File
Version / Date
Archive size Uncompressed size
 win95 logo
 Windows (Intel x86)
dicom2.exe
1.9n
19 February 2007
208 896
 linux logo
 Linux (Intel x86)
dicom2.gz
1.9n
19 February 2007
582 927
591 660

WARNING: FireFox users (and others), please do check that the size in bytes of the file you downloaded is the same as the size reported above. If it is not, it is likely the transfer failed, the file got corrupted, or your browser is doing something tricky on your behalf.

      Install
   

Just uncompress the executable if needed (Linux), and off you go. Unix users can run: gzip -d *.gz 

Note that dicom2 is a command line tool, you need to run it from a Windows command prompt or a Linux shell

      Usage
      Conversion formats
Conversion context
Input files
Frame selection
Control output 
Renaming pattern 
Image processing 
 

Usage: dicom2 --help --config--acc=max|min[:file] --compression=no|default|fast|best --crop=x:y:w:h --fliph--flipv --frame=first[:last[:step]]|all[:step] --get=[max][:min][:mean] --halve[=n] --mask=zero[:file] --name[=y|n] --rank[=y|n] --rename=alias|field[:field...] --resample=no|shift|near|linear --reverse[=y|n] --sort[=y|n] --step=n --syntax=il|ib|el|eb --timer --to=path --warn[=y|n] --win[=center:width] -a -d[=il|ib|el|eb] -p[0|1] -r[0|1] -t[0|1] -w file(s) to convert

      Conversion formats
 
  You may convert a file to many destination formats in the same time. 
 
-a TARGA  .tga
-d[=il|ib|el|eb] DICOM, optionally using  (i)mplicit|(e)xplicit, (l)ittle|(b)ig endian syntax .dcm
-p[0|1] PNG (0: include tags as tEXt chunks (default), 1: do not) .png
-r[0|1] RAW (0: little endian (default), 1: big endian)  .raw
-t[0|1] TEXT (0: write to file (default), 1: dump to stdout)  .txt
-w BMP .bmp
 
-a -w: TARGA and BMP conversions provide good ways to illustrate your documents and import medical images to your favorite publishing softwares. Nevertheless, you shall not forget that both formats do not support more than 8 bits per sample or per color-component, which is not sufficient to achieve the precision commonly encountered in standard medical image formats. 
  • MONOCHROME (grayscale) files are resampled to 8 bits/sample, using the resampling method defined by the current conversion context.
  • RGB files are handled in the same way, but the red, green and blue components are resampled to 8 bits/component using bit shifting only (the resampling method specified by the conversion context has no influence). 
  • PALETTE COLOR files are dumped as is, and the RGB components of the Color Look-Up Table are resampled to 8 bits each. 

  •  
-d[=il|ib|el|eb]: it might seem stupid to provide conversion to the DICOM format when the original files already use that format, but it becomes quite practical when you start performing some image processing functions on the original files, try to extract particuliar frames within multiple-frame files, or just want to change the internal syntax of the files. Working continuously with the DICOM format allows you to share the benefits of a simple tool like dicom2 with other medical imaging softwares, while keeping most of the informations described by this complex format. 
  • dicom2 respects the type and the syntax of the original files: raw files are converted to raw files, and true DICOM files are converted to true DICOM files (where the elements are preceded by a File Meta Information header made of a File Preamble, a DICOM prefix and File Meta Elements). Raw files are stored using the standard DICOM default syntax (Implicit VR Little Endian Syntax), and true DICOM files use the syntax provided by the corresponding File Meta Elements (0002,0010). The File Meta Information header itself is ALWAYS stored using the standard DICOM Explicit VR Little Endian Syntax. 
  • you may optionally specify a new syntax (il|ib|el|eb, where each letter stands for (i)mplicit|(e)xplicit VR, (l)ittle|(b)ig endian), which will be used to store raw or true DICOM files. This is NOT advised for raw files, as they do not provide any information regarding their internal syntax and you will have to remember that they were stored using this new syntax instead of the standard one (or you may use the --syntax option to specify this new syntax when reading these files). This is safe for true DICOM files, where the corresponding File Meta Elements (0002,0010) will be changed according to the new syntax. DO NOT convert encapsulated (i.e. syntax other than il|el|eb) to a new syntax. Be aware that the the ib parameter (Implicit Big Endian syntax) was provided for backward compatibility only, and shall NOT be used (this syntax has no meaning regarding the DICOM standard).
  • "Group Length" elements (xxxx,0000) are automatically computed. 
  • as dicom2 is frame-oriented, it is not possible to convert multiple-frame files to new multiple-frame files: a single frame shall be chosen
  • when the structure (planar configuration, number of frames) or the size (rows, columns, pixel spacing) of an image is modified (see --crop and --halve), the corresponding tags are updated accordingly to produce the best DICOM file.
  • be aware that reading DICOM files and converting them to another DICOM files might not produce the same files. Nevertheless, this may only happen if the original files use an Implicit VR syntax, which needs a "dictionary" to be decoded: these tags that are not recognized by my DICOM dictionary (as well as these VR that are not yet supported) will not be saved, and will therefore disappear in the resulting files.

  •  
-p[0|1] : The PNG format (which stands for Portable Network Graphics) was designed to be the successor to the popular GIF format, by providing a free, loss-less and much-improved replacement framework. It provides very interesting features: file integrity checking (through CRCs), better compression than GIF, two-dimensional interlacing scheme, 1-, 2-, 4- and 8-bit palette support, 1-, 2-, 4-, 8- and 16-bit grayscale support, 8- and 16-bit-per-channel (that is, 24- and 48-bit) truecolor support, full alpha blending in 8- and 16-bit modes, gamma correction for cross-platform "brightness" control. The PNG format is supported by a growing number of platforms and softwares, including word-processors and web browsers (MSIE 4 and Navigator 4), so I strongly recommend you to have a look at its interesting capabilities. 

This format also solves much of the problems raised by the TARGA and BMP formats: it particularly supports more than 8 bits per sample or per color-component. Therefore, it seems to be the right choice when dealing with medical images which most of the time use more than 8 bits per sample. 

  • MONOCHROME (grayscale) files are resampled to 8 bits/sample when the current bit depth is <= 8, or resampled to 16 bits when > 8 (the precision is extended, up-sampled, not lost), using the resampling method defined by the current conversion context.

  • MONOCHROME1 files, where 0 is associated to white and the maximum value to black, are inverted first, so that 0 will be associated to black and the maximum value to white.
  • RGB files are handled in the same way, but the red, green and blue components are resampled to 8 or 16 bits/component using bit shifting only (the resampling method specified by the conversion context has no influence).
  • PALETTE COLOR files are dumped as is, and the RGB components of the Color Look-Up Table are resampled to 8 bits each.
Furthermore, like DICOM and TIFF, the PNG format is also tag-based: it provides simple ways to include some useful informations related to the image. 
  • every DICOM data-element found in the original file is included in the destination file as a PNG tEXt chunk (a textual pair made of a keyword associated to a text): the data-element description (or the tag if the description was not found in the DICOM dictionary) is used as keyword, and its value as text

  • For example, the following tags: 

                    Study Date (0008,0020)  1    DA [1995.06.26]
                Patient's Name (0010,0010)  1    PN [Doe John]
               Slice Thickness (0018,0050)  1    DS [10.00]

    are dumped into the following tEXt chunks (pair keyword/text): 

                    Study Date/1995.06.26
                Patient's Name/Doe John
               Slice Thickness/10.00
     
    As there might be a LOT of DICOM data-elements within a file, you might choose not to include these elements in the corresponding PNG file by providing the optional 1 parameter to the -p option (i.e. -p1). 

  • the following PNG tEXt chunk is always included: Software/dicom2.
  • if the current DICOM bit-depth (bits stored in every sample) is different from 8 or 16, a PNG sBIT chunk is included and will provide this information (but you might also check the data-elements converted as tEXt chunk for the PNG tEXt chunk associated to the "Bits Stored" keyword).
  • if the aspect ratio of the image is known (DICOM data-element (0028, 0030)), it is included in a PNG pHYs chunk (but once again you might also check the data-elements converted as tEXt chunk for the PNG tEXt chunk associated to the "Pixel Spacing" keyword).
Unlike the previously described TARGA and BMP format, the PNG format might be compressed. Therefore, it understands the global compression parameter defined by the current conversion context. The default behaviour (when no compression method is specified), is to compress the file (a compromiss between best and fastest compression using the zlib library). 
-r[0|1]: the DICOM format provides a great flexibility regarding the organization and the structure of the pixel data: every pixel is made of one or more samples, each one of them is described by a given number of bits ("Bits Stored"), and is packed in a cell that can use an even greater number of bits ("Bits Allocated"), allowing the user to include overlay data within each sample or simply pad each sample in a multiple of 8 bits. 
pixel cell A pixel cell
Bits Allocated = 16 
Bits Stored = 12 
High Bit = 12
So far, this flexibility also means to deal with the complexity of all possible combinations of allocated, stored and high bits, and this task is not obvious. Therefore, a lot of imaging or visualization softwares rely on the user to "reorganize" the pixel data and provide them with raw files, which do not include any informations except the "cleaned" and "padded" pixel data. This is what dicom2 tries to do for you when using the RAW conversion (see examples in the "How to..." section). 
raw pixel cell A raw pixel cell
Bits Allocated = 16 
Bits Stored = 12 
High Bit = 11
  • data other than pixels are not stored. 
  • samples made of more than 8 bits are stored ("padded") in a word (2 bytes) otherwise in a byte, so that each sample starts at the beginning of a word (respectively a byte). 
  • the structure of every sample is "cleaned", so that the least significant bit starts at bit 0 (High Bit = Bits Stored - 1). 
  • unused bits are set to 0 (unused bits are found according to the value of Bits Stored and Bits Allocated). Overlay data are lost.
  • the binary syntax may be chosen (Little (-r0)or Big (-r1) Endian) when samples are stored in a word (2 bytes).
  • the raw conversion performs faster when the pixel cell and the pixel sample have the same size and is a multiple of 8 bits.

  •  
-t[0|1]: the DICOM offline format is not just a way to store medical images, it is a very complete and opened format where hundreds of item and values may be stored. Nevertheless, writing a DICOM decoder is not a simple task. The TEXT conversion will therefore become quickly useful to explore the contents and understand the complexity of DICOM files by providing a textual representation of every element in a human-readable form.It is also helpful for these that are just interested in the Pixel Data or a simple description of the image: these items, as well as offsets to the pixel data (7FE0,0010) are easily recognizable, for every element appears as : 
  • description,
  • tag, as a (group,element) pair),
  • VM, Value Multiplicity, the number of intended values,
  • VR, Value Representation, i.e. the type fo the value, 
  • [value]. 
Here is an excerpt: 

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

  • this listing may be redirected (and filtered) to the standard output stream stdout (-t1) instead of a file (-t0), allowing dicom2 to act as a DICOM text viewer (see examples in the "How to..." section).
  • you might extract a single element by using the grep filter (see examples in the "How to..." section). 
  • be aware that the TEXT conversion is performed before any image processing functions: the listing corresponds to the original files, and not to the converted files.
  •       Conversion context
     
      Each conversion format might define its own optional parameters (ex: -p[0|1] for a PNG conversion, where 0 or 1 are optional), but most of them share common behaviours, which might be controlled using global parameters. This set of global parameters is called the conversion context, and it is applied to all destination formats when converting to different formats in a single call to dicom2

    You might use these parameters in the DICOM2 environment variable to set new default options
     

    --compression=type compression type (no|default|fast|best)
    --resample=method resampling method (no|shift|near|linear(default))
    --to=path destination path (fully expanded, ex: --to=/tmp)
    --win[=center:width] apply windowing (using optional center & width)
     
    --compression=no|default|fast|best: some of the destination formats are compressed, but the compression process might be very time-consumming. Therefore, you may control the compression scheme by providing one of these parameters to the --compression option: 
    • no: no compression at all,
    • default: default compression method (depends on the format),
    • fast: fastest compression method,
    • best: best compression method. 
    Be aware that this option is just an advice regarding the heuristic to be used: it has no influence on destination formats which do not handle compression, or do not provide compression control. 

    When the --compression option is not used, or used in combination with the default parameter, the compression method will depend on the destination format (which implements its own default compression behaviour). 

    The PNG format is for the moment the sole format that understands the --compression option through the well-known zlib compression library. 

    --resample=no|shift|near|linear: most of the destination formats use a fixed bit-length to store monochrome files (8 or 16 bits/sample). Therefore, when a DICOM sample is defined by a bit-length different from 8 or 16, it has to be resampled. You might control the resampling method by providing one of these parameters to the --resample option: 
    • no: no resampling, the original sample is copied directly to the destination sample. It seems obvious that if the bit-length of the destination sample is smaller than the original bit-length, the destination value will be corrupted.
    • linear: the maximum value of the original image is searched, and is used to perform linear scaling to map the data from 0..max to 0..255 (or 0..65535 for 16 bits monochrome file). The major drawback is that the maximum value might not be the real "white" point, but it will nevertheless be mapped to 255 or 65535, which is "white". This might be very noticeable when converting a dark cropped portion of an image, which will appear much lighter than it should be (use the following resampling method instead). 
    • shift: the original sample is resampled to the destination bit-depth using the usual binary shift operators (<< or >>). This ensures that the white point is always the same (if the original sample is stored in 12 bits, the white point is (2^12)-1 = 4095, and black is 0).
    • near: this method use the same binary shift operators, but the original bit-depth is checked first. Many images are stored using a bit depth which seems to be not appropriate with the real values (they do not cover the full range). In this case, the maximum value of the original image is searched and used to guess the real bit-depth (the nearest bit-depth able to accommodate the maximum value). For example, if the original values were stored using 12 bits, but ranged from 0 to 230, there might be a chance that the real bit-depth should be 8 (0..255). This new bit-depth will be used. 
    The linear method is the default when --resample is not used. But is also the slowest. 

    This option has no influence on images other than monochrome, or on formats which are able to store a sample with any bit-length (raw or DICOM). It is also overriden by the --win option, which is a remapping method by itself. 

    --to=path: the default behavior of dicom2 is to use the current directory to save the converted files, but you may specify another destination directory, as long as it is fully expanded (don't use ~ or $HOME). 
    --win[=center:width]: enhance a particular range of values when resampling grayscale files to 8 or 16 bits/sample (PNG, BMP or TARGA). Windowing informations are usually defined by the radiologist to enhance a particular part of the image (a tissue) by remapping a range of values (defined by the window center and the window width) through a color look-up table (using linear scaling, therefore it overrides the --resample option). Specify that option if you want dicom2 to use the settings saved within the file (as HU elements (0028,1050) and (0028,1051)). You may also provide your own center and width, but these have to be expressed as SV (stored values) instead of the usual HU (Hounsfield unit) : you may get a rough idea of the current SV range using the --get option (tell me if you'd prefer specifying that kind of informations using HU, and I will change that behaviour in the next version and add two parameters, the rescale slope and rescale intercept). 
    • a warning is sent if windowing informations are not available.
    • samples per pixel greater than 1 are not supported.


    head 2head win 2
    head 3head win 3
    original and windowed slices
    (center 40, width 300, = bones)

    dicom2 -t1 file1 | grep -i window
        Window Center (0028,1050)  1-n  DS [000040]
         Window Width (0028,1051)  1-n  DS [000300]

    And here is another example for a different and imaginary file2, where the previous elements (0028, 105x) were not found. Let's specify our own window width and center:

    dicom2 --get=max:min file2
    [max: 4000] [min: 0]
    dicom2 -w --win=2000:4000 file2
    (no change) 
    dicom2 -w --win=2000:1000 file2
    (enhance contrast) 

          Input files
     
        The default behavior of dicom2 is to process each file one after the other, but you are free to reverse that standard order or sort the filenames by alphabetical order. 

    You can even restrict dicom2 to a sub-set of these files by providing a step n that will be used to read every n-th file only. This might be useful for testing purposes: suppose you plan to work on a set of 200 slices... by providing a step n = 20 you will get a rough idea of the final outcome by looking at these 10 resulting files. 

    True DICOM files are preceded by a File Meta Information header made of a File Preamble, a DICOM prefix and File Meta Elements. This header shall be read using the standard DICOM Explicit VR Little Endian Syntax. One of the File Meta Elements found in that header provides the syntax to use for the following elements. On the other hand,  raw data-sets do not have any header, and hence do not provide any syntax directive: the entire file shall be read using the standard DICOM default syntax (Implicit VR Little Endian Syntax). Nevertheless, both of these choices may be overridden by the user, allowing raw data-sets or the File Meta Information header of a true DICOM file (only the header, NOT the data-elements of the file) to be read using a different syntax. This might help you to avoid seldom cases where dicom2 may report an error while reading an old DICOM standard. Be aware that the the ib parameter (Implicit Big Endian syntax) was provided for backward compatibility only, and shall NOT be used (this syntax has no meaning regarding the DICOM standard). 

    You might use these parameters in the DICOM2 environment variable to set new default options
     

    --reverse[=y|n] reverse processing order (start with last), yes|no(default)
    --sort[=y|n] sort files to process (before --reverse), yes|no(default)
    --step=n process every n-th file
    --syntax=il|ib|el|eb read the files using (i)mplicit|(e)xplicit, (l)ittle|(b)ig endian syntax

    dicom2 head.dcm stomach.dcm limb.dcm
    would read: head.dcm, stomach.dcm, limb.dcm

    dicom2 --sort=y head.dcm stomach.dcm limb.dcm
    would read: head.dcm, limb.dcm, stomach.dcm

    dicom2 --reverse=y head.dcm stomach.dcm limb.dcm
    would read: limb.dcm, stomach.dcm, head.dcm

    dicom2 --reverse=y --sort=y head.dcm stomach.dcm limb.dcm
    would read: stomach.dcm, limb.dcm, head.dcm

    dicom2 --step=2 file-1 file-2 file-3 file-4 file-5 file-6
    would read: file-1 file-3 file-5

    dicom2 --step=3 file-1 file-2 file-3 file-4 file-5 file-6
    would read: file-1 file-4

    dicom2 --step=3 --reverse=y file-1 file-2 file-3 file-4 file-5 file-6
    would read: file-6 file-3

    dicom2 --step=10 file-1 file-2 file-3 file-4 file-5 file-6
    would read: file-1

          Frame selection
      Although dicom2 is able to read multi-frame files, its output is always made of single-frame files... Therefore, it is up to the user to specify the frame(s) he wants to work with. 

    The default behavior of dicom2 is to process all frames: hence, by converting one multiple-frame file, you will probably get many single-frame files. As dicom2 uses the name of the original file to compute the name of the destination one, this might lead to overwriting problems: in that case, when no other renaming pattern is given, dicom2 adds a frame number to each resulting filename. Note that specifying a renaming pattern overrides this behavior: do not forget to use frame-related fields (cur_fr, cur_fr0) in the pattern if you want to be sure that you will save all frames. 

    You are free to specify  the frame(s) you want to process by providing the index of a particular frame, or a range of frames starting from index i to index j (where i do not have to be < j). You can even provide a step n that will be used to read every n-th frame only. 
     

    --frame=first[:last[:step]]|all[:step] select frame(s)

    Note that the "all" keyword means "all frames". 

    Let's have a look at some examples, using the file mframe, which stores 10 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 [10]

    dicom2 mframe
    will read the 10 frames and process them successively. 

    dicom2 --frame=3 mframe
    will read frame 3

    dicom2 --frame=6:2 mframe
    will read the frames: 6, 5, 4, 3, 2

    dicom2 --frame=6:1:-2 mframe
    will read the frames: 6, 4, 2

    dicom2 --frame=all mframe
    will read the 10 frames and process them successively. 

    dicom2 --frame=all:2 mframe
    will read the frames: 1, 3, 5, 7, 9

    dicom2 --frame=all:-2 mframe
    will read the frames: 10, 8, 6, 4, 2

          Control output
     
      The default behavior of dicom2 is to display nothing but warnings and errors, but processing hundreds of files may take some time... Therefore, one may want to display the rank or the name of the file that is currently processed, which will convey a rough evaluation of the remaining operations. The name of the file may also be helpful to locate the one that produced an error. 
     
    Warnings do not stop the conversion process, but it may be annoying to get the same messages hundreds of times. Hence, it is possible to prevent these warnings (prefixed with [W]) from being displayed. Errors (prefixed with [E]) will always be shown. 
     
    For these willing to time each call to dicom2, the corresponding --timer option may be used. 
     
    You might use these parameters in the DICOM2 environment variable to set new default options
     
    --help display usage
    --config display configuration (for my own debugging purposes :)
    --name[=y|n]  display name of file being processed, yes|no(default)
    --rank[=y|n] display rank of file/frame being processed, yes|no(default)
    --timer time session (returns elapsed time)
    --warn[=y|n] display warnings, yes(default)|no 
    updatedthe --warn option has replaced the --nowarn option since version 1.8, but --nowarn remains for backward compatibility (although not listed).
     
    Let's have a look at some examples, where mframe is a multi-frame file, which stores 5 frames: 
     
    dicom2 --rank=y head.dcm stomach.dcm limb.dcm 
    [1] [2] [3] 

    dicom2 --rank=y head.dcm mframe stomach.dcm limb.dcm 
    [1] [2] 1 2 3 4 5 [3] [4] 

    dicom2 --name=y head.dcm mframe stomach.dcm limb.dcm 
    head.dcm  
    mframe 
    stomach.dcm  
    limb.dcm 

    dicom2 --name=y --rank=y head.dcm mframe stomach.dcm limb.dcm 
    [1] head.dcm 
    [2] stomach.dcm 
    [3] mframe 1 2 3 4 5 
    [4] limb.dcm 

    dicom2 warn_err.dcm 
    >> [W] [14:13:25] 
       bool SbMedicalFrame::UpdateFrom( const SbDicomDataElementSet&, ... ) 
       missing tag: (0028,0004) Photometric Interpretation... 
    >> [E] [14:13:26] 
       bool SbMedicalFrame::UpdateFrom( const SbDicomDataElementSet&, ... ) 
       encapsulated syntax 1.2.840.10008.1.2.4.70 is not supported! 

    dicom2 --warn=n warn_err.dcm 
    >> [E] [14:13:26] 
       bool SbMedicalFrame::UpdateFrom( const SbDicomDataElementSet&, ... ) 
       encapsulated syntax 1.2.840.10008.1.2.4.70 is not supported! 
     
    dicom2 --timer *.dcm 
    Elapsed time: 0.941 s.

          Renaming pattern
     
      The default behavior of dicom2 is to use the name of the file being processed to build the destination filename. The extension of the destination format is added to that name (for example, .bmp, .tga, .txt, etc., see conversion formats). An optional frame number is added also if the file is a multi-frame file

    Unfortunately, filenames automatically created by acquisition software's are most of the time hard to manage, and convey no special meanings in a human-readable form. It would be interesting to implement a simple mechanism able to rename the destination file depending on its contents (its DICOM tags) or its rank. 

    This may be achieved by specifying a renaming pattern made of fields separated by semi-colons (':'). A field is related to a unit of information that may be found in the file: it is similar to a DICOM data-element, although more meaningful. 
     

    --rename=alias|field[:field...] build destination file name
     
    Every field is processed one after the other, from the left to the right. If the field is found in the field-dictionary and if the information is available in the file, its value is used to build a part of the destination filename. Otherwise, it is copied as is in the name, allowing the user to include strings too. In both cases, fields are concatenated and separated by minus signs ('-') in the destination filename. 
     
    Field dictionary:
    cur_nm name of the current file
    cur_we cur_nm without extension
    cur_rk rank of the current file (ex: 1)
    cur_rk0 cur_rk padded to 4 digits (ex: 0001)
    cur_fr rank of the current frame
    cur_fr0 cur_fr padded to 3 digits (ex: 001)
    pat_nm patient name
    xxx_da date of xxx
    xxx_tm time of xxx
    xxx_nb xxx number
     
    xxx is one of:
    stu study u
    ser series s
    acq acquisition a
    img image i
     
    The value of every of these xxx fields will be prefixed with a single character in the destination name (u, s, a, or i). stu_nb is not implemented. Date's format is dd.mm.yy (day, month, year), Time's format is hh.mm.ss.ffffff (hour, minute, second, millionth). 
     
    The frame-related fields (cur_fr, cur_fr0) have no influence on single-frame files. It is also safe to use them in any cases, as dicom2 do not output anything but single-frame files. Therefore, DO NOT forget to use these fields in the pattern if you want to be sure that you will save the frames stored in a multiple-frame file. If not, there won't be any difference between the filenames of each resulting frame, as they are computed from the name of the original multi-frame file:  you will most probably overwrite all frames within the same single-frame file. 
     
    Several aliases are available to specify the most usual combinations of fields. If the first field of the whole renaming pattern is a digit (0..9), the corresponding alias is used: 
     
    0 cur_nm:cur_rk
    1 cur_nm:cur_fr0
    2 pat_nm:cur_rk
    3 pat_nm:cur_rk0
    4 pat_nm:ser_nb:img_da:img_tm
    5 pat_nm:ser_nb:acq_nb:acq_tm
    6 pat_nm:acq_tm:cur_rk
     
    Do not be afraid about this syntax, and feel free to experiment, it is worth it :) Although the field dictionary may be hard to remember, all fields have been chosen to sound like their counterparts. 

    Let's have a look at some examples, where mframe is a multi-frame file, which stores 5 frames. The -w conversion (BMP) adds .bmp to the filename. 

    dicom2 -w --rename=frame:cur_fr mframe 
    result names: frame-1.bmp frame-2.bmp frame-3.bmp frame-4.bmp frame-5.bmp 

    test.dcm contains these elements (description, tag, VM, VR, value): 

                Study Date (0008,0020)  1    DA [1997.05.29] 
          Acquisition Date (0008,0022)  1    DA [1997.05.29] 
                Image Date (0008,0023)  1    DA [1997.05.29] 
                Study Time (0008,0030)  1    TM [16:30:39] 
          Acquisition Time (0008,0032)  1    TM [16:41:41] 
                Image Time (0008,0033)  1    TM [16:58:41.571000] 
            Patient's Name (0010,0010)  1    PN [FOOBAR] 
             Series Number (0020,0011)  1    IS [000001] 
        Acquisition Number (0020,0012)  1    IS [000005] 
              Image Number (0020,0013)  1    IS [000136] 

    dicom2 -w --rename=pat_nm:ser_nb:acq_nb:img_da:img_tm test.dcm 
    result name: FOOBAR-s000001-a000005-i29.05.97-i16.58.41.571000.bmp 

    dicom2 -w --rename=pat_nm:ser_da:stu_tm:img_nb test.dcm 
    result name: FOOBAR-u16.30.39-i000136.bmp (Series Date not in file) 

    dicom2 -w --rename=cur_we:acq_tm test.dcm 
    result name: test-a16.41.41.bmp 

    dicom2 --rename=result:cur_rk0 test.dcm test2.dcm test3.dcm 
    result names: result-0001.bmp result-0002.bmp result-0003.bmp 

          Image processing
     
      Some very rudimentary image processing tasks may be performed on the pixels before converting them to another format. Multiple tasks may be applied during the same pass, allowing you to save a lot of time... be aware that they are performed in the following order: 
     
    --acc=max|min[:file] save accumulated (default file: acc-mode.dcm)
    --mask=zero[:file] mask frame (default file: mask-mode.bmp)
    --crop=x:y:w:h crop frame at x:y (width w, height h)
    --halve[=n] halve frame in both dimensions (n times)
    --fliph --flipv flip frame horizontally/vertically
    --get=val[:val...] get pixel values in frame, where val is max|min|mean
     
    --acc=max|min[:file]: create a unique single-frame file during the call to dicom2, and save it as a DICOM file when all files have been processed. The contents of the resulting file is computed from the accumulated contents of all files, and vary depending on the mode. You can specify the name of the resulting file, or dicom2 will use acc-mode.dcm as default (where mode is actually replaced by the chosen mode). Multi-frame files are of-course supported, and you can even build an accumulated file only based on the frames of one multi-frame file.
     

    Note that the resulting DICOM file is not a logic file in that it does not relate to any existing study or patient: it just contains the mandatory tags necessary to describe an image.  

    Be aware that most modes do not support samples per pixel greater than 1, as they have to compare or order pixels based on their value. Therefore, do not forget that a pixel with a value = 0 is NOT always darker than a pixel with a value = 255, 1024, or higher. It depends on the Photometric Interpretation: it is true for MONOCHROME2, where 0 is black and higher values are lighter, but false for MONOCHROME1, where 0 is white and higher values are darker. 

    • max: by using the 'max' mode, you can build a kind of accumulation buffer which describes approximately the points that are used (grayscale) or unused (black) in a whole series. Samples per pixel greater than 1 are not supported. Every point of that buffer (originally set to 0) gets the maximum value of the corresponding point in all images given as operands. This will roughly compute the union of these files. Using that mode, you may be able to recognize these structures that might be useful (body parts) from these that might not (artefacts, head of the bed, ...).

    •    
      This buffer might be useful to create a mask by attributing a zero to the points that you want to save (using a painting program). Check the corresponding real-life examples in the "How to" section. 
       
      Use the 'min' mode to achieve the same effect on MONOCHROME1 images.
     
    accumulate max (a) and accumulate max (b) = accumulate max (result)
    accumulate max real (a) and accumulate max real (b) = accumulate max real (result)
     
    • min: the 'min' mode works exactly like the 'max' mode, except that every point of the resulting buffer (originally set to 0xFFFF) gets the minimum value of the corresponding point in all images given as operands. This will roughly compute the intersection of these files.

    •   
      Use the 'max' mode to achieve the same effect on MONOCHROME1 images. 
     
    accumulate max real (a) and accumulate max real (b) = accumulate max real (result)
     
    --mask=zero[:file]: mask every image (or frames). The contents of the resulting file is computed from the combination of the original file and the mask, and vary depending on the mode. You can specify the name of the mask, or dicom2 will use mask-mode.bmp as default (where mode is actually replaced by the chosen mode). The mask has to be stored in Window's BMP format, 8 bits/sample, 1 sample/pixel, which corresponds to a 256 indexed-color picture (the color lookup table is ignored). 
    • zero: by using the 'zero' mode, every point of the resulting frame gets the value of the original point if the value of the corresponding mask's point is zero, or zero if the value of the mask's point is non-zero! Think about a stencil :) It might be useful to remove artefacts or undesired structures. Be aware that this mode relies on the zero values of  the mask: there is no color consideration, as zero might not always be associated to "black" in BMP indexed-color picture. 

    •    
      A 'zero' mask might have been created from an accumulation buffer after attributing a zero to the points that you wanted to save (using a painting program). Check the corresponding real-life examples in the "How to" section.
     
    head and mask = head masked
     
    --crop=x:y:w:h: build a destination frame that is a sub-part of the original frame. It starts at pixel x:y and its width and height are w:h (upper-left corner at 0:0). 

    Using accumulating, masking and cropping together might become a very common way to clean images. Check the corresponding real-life examples in the "How to" section. 
     

    --halve[=n]: halve the original frame. Both dimensions (width, height) must be even, but you still can crop the frame a little to achieve the right size. You may also provide a parameter n to halve the frame n times instead of 1 (ex: --halve=3 will halve a 512x512 image to 64x64). 
    • MONOCHROME images are sub-sampled: each destination sample is the mean of 4 original samples.
    • RGB and PALETTE COLOR images are shrinked: every 2 pixels is taken to build the destination pixel. 
    Halving huge sets of images might become a good way to generate subsets and quickly perform some tests before using the real data. Check the corresponding examples in the "How to" section. 
     
    --fliph --flipv: flip frame horizontally or vertically. 
     
    --get=[max][:min][:mean]: get maximum/minimum/mean pixel values in the frame. Parameters are optional and may be specified in any order. This option can not be used on image where pixels are made of more than 1 sample (anything different from MONOCHROME). 
     
    dicom2 --get=max:min file 
    [max: 4000] [min: 0] 
     
    dicom2 --get=mean:min file 
    [mean: 1273] [min: 0] 
     
          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 
     
          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 
    ... 
     
    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 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). 
     
    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()).
          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 (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] 

    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)  1    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. 
     
    head 1head 2head 3head 4
    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 * 
     
    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 
     

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

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

    Summary

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

          Problems
          Too many messages 
    Missing tags 
    Unable to write... 
    Error while reading File Meta Elements 
     
    If dicom2 exhibits a really strange behavior, you might consider checking if it is really working right with your implementation. Have a look at the medical image samples page and the Performance section to download some files and compare your results with these expected. 
          Too many messages
     
        You might be surprised by the number of messages output by dicom2 while it is doing its work. Don't worry, most of them are harmless... Warnings (prefixed with [W]) do not stop the conversion process, whereas errors (prefixed with [E]) do. 
     
    >> [W] [14:13:25] 
       bool SbMedicalFrame::UpdateFrom( const SbDicomDataElementSet&, ... ) 
       missing tag: (0028,0004) Photometric Interpretation... 
    >> [E] [14:13:26] 
       bool SbMedicalFrame::UpdateFrom( const SbDicomDataElementSet&, ... ) 
       encapsulated syntax 1.2.840.10008.1.2.4.70 is not supported! 
     
    Don't forget that you can hide these annoying warning messages by using the  --warn option !
          Missing tags
     
      Some missing tags may be assumed (as they should be there), and therefore introduce nothing but warnings. This kind of warning is usual when reading old ACR/NEMA files. You should use --warn to prevent your screen from being flooded while converting hundreds of these files. 
     
    >> [W] [14:13:25] 
       bool SbMedicalFrame::UpdateFrom( const SbDicomDataElementSet&, ... ) 
       missing tag: (0028,0004) Photometric Interpretation. Assuming MONOCHROME2! 
    >> [W] [14:13:25] 
       bool SbMedicalFrame::UpdateFrom( const SbDicomDataElementSet&, ... ) 
       missing tag: (0028,0002) Samples per Pixel. Assuming 1! 
     
    Some other tags are mandatory for a given conversion task. These missing tags will produce an error, and stop the program. 
     
    >> [E] [14:21:50] 
       bool SbMedicalFrame::UpdateFrom( const SbDicomDataElementSet&, ... ) 
       missing image mandatory tags in set! 
    >> [E] [14:21:50] 
       bool SbMedicalFrame::UpdateFrom( const SbDicomDataElementSet&, ... ) 
       missing CLUT mandatory tags in set! 
    >> [E] [14:21:50] 
       bool SbMedicalFrame::UpdateFrom( const SbDicomDataElementSet&, ... ) 
       missing Windowing mandatory tags in set! 
          Unable to write...
     
      If you encounter that kind of message ("unable to write data..."), check that you are not trying to write the converted files to a protected directory or to any place where you are not allowed to store data (in multi-user systems). You should also check if your hard disk is full, or your quota exhausted :) 
     
    If you are using the --to option, you might also check that you specified a fully expanded directory (don't use ~ or $HOME). 
          Error while reading File Meta Elements
     
      If you ever read that kind of message, you are probably trying to load a true DICOM file (i.e. with a File Preamble) written according to an old DICOM standard which stated that File Meta Elements stored at the beginning of the file should be saved using the DICOM Implicit VR Little Endian Syntax. This is no more the case: these elements have to be written using the DICOM Explicit VR Little Endian Syntax. Nevertheless, you can force dicom2 to conform to that old behavior by specifying the desired syntax with the --syntax option. 
     
    dicom2 mr.d3i 
    >> [E] [00:19:47] 
       VR TranslateVR( const char, const char ) 
       unknown VR token  
    >> [E] [00:19:47] 
       ULONG SbDicomDataElementValue::ReadButValue( ifbstream& ) 
       explicit VR of value is unknown! (0x8a) 
    >> [E] [00:19:47] 
       ifbstream& SbDicomDataElementValue::Read( ifbstream& ) 
       while reading (optional) explicit VR and length of value! (0x8a) 
    >> [E] [00:19:47] 
       ifbstream& SbDicomDataElementSet::ReadFiltered( ifbstream&, const ...) 
       while getting value of element (0002,0000)! (0x8a) 
    >> [E] [00:19:48] 
       bool SbDicomDataElementSet::Load( const SbFileName&, const ...) 
       while reading File Meta Elements of file mr.d3i! (check syntax) 
    >> [E] [00:19:48] 
       int main(const int, const char**) 
       while reading file mr.d3i! 

    dicom2 mr.d3i --syntax=il 
    OK (il = implicit little endian) 

          Limitations
          Encapsulated syntax 
    Unsupported VR 
    Photometric interpretation 
    Planar configuration 
    Bits allocated 
    Color Lookup Tables 
    Multiple-frame files 
     

    Some of these limitations will also remain as long as I won't get samples containing the unsupported topics. If you own such samples, I would really appreciate working on them and maybe adding them to my medical image samples page.

          Encapsulated syntax
     
      No encapsulated (compressed) syntax is supported. Sorry ;) 
     
    >> [E] [21:32:56] 
       bool SbMedicalFrame::UpdateFrom( const SbDicomDataElementSet&, ... ) 
       encapsulated syntax 1.2.840.10008.1.2.4.70 is not supported!
          Unsupported VR
     
        Some Value Representation are not supported. The corresponding DICOM data-elements are skipped: 
      FD (floating point double) 
      FL (floating point single) 
    Multiple valued elements (VM > 1) are not supported too: the first value is read, the others are skipped. You may want to use --warn to prevent these warnings from being displayed. 
     
    >> [W] [20:36:00] 
       ifbstream& SbDicomDataElementValue::Read( ifbstream& ) 
       AT length = 4, current = 12, multiple values not implemented :( 
          Photometric interpretation
     
      Conversions from photometric interpretations (0x0028, 0x0004) other than MONOCHROME1, MONOCHROME2, PALETTE COLOR and RGB are not supported. Be aware that some image processing options support all photometric interpretation, as other do only support a restricted set ot them  (--acc will ignore RGB images for example).  
          Planar configuration
     
      The planar configuration item is required when "Samples per Pixel" has a value greater than 1 (RGB files for example). Planar configuration values 0 (color-by-pixel) and 1 (color-by-plane) are supported, but color-by-plane data are automatically converted and reorganized to color-by-pixel (this might be important to say if you are converting back to DICOM).
          Bits allocated
     
      Bits allocated (0x0028, 0x0100) > 16 are not fully supported (this number of bits is the size of the cell that is used to store a pixel sample and optionally additional bits, see option -r for diagrams). Nevertheless,  I don't know if a such big size has been ever used. 
     
    >> [E] [14:21:50] 
       bool SbMedicalFrame::UpdateFrom( const SbDicomDataElementSet&, ... ) 
       bits allocated 18 > 16 are not fully supported... (email me)
          Color Lookup Tables
     
      When using PALETTE COLOR images, the color lookup table descriptors (red (0x0028,0x1101), green (0x0028, 0x1102), blue (0x0028, 0x1103)) must have the same structure (size, number of entries and depth), so that the whole clut could be rebuilt (red/green/blue). CLUT entries (red (0x0028,0x1201), green (0x0028, 0x1202), blue (0x0028, 0x1203)) shall be "upsampled" to 16 bits (i.e. 0xFF => 0xFF00).
     
    >> [E] [14:21:50] 
       bool SbMedicalFrame::UpdateFrom( const SbDicomDataElementSet&, ... ) 
       different clut descriptors are not allowed!
          Multiple-frame files
     
      dicom2 is unfortunately not able to read all types of multiple-frame files: to be honnest, it is not even able to read the recommended DICOM organization (!), which states (see DICOM Part 5, section A.4c) that value representations OB or OW of files made of multiple fragments shall meet some specific requirements (more or less a SQ organization): 
    • [...] every fragment (within the pixel data stream) shall be  encapsulated as a DICOM Item with a specific Data Element Tag of Value (FFFE, 0000), [...] 
    • [...] all fragments shall be made of an even number of bytes [...] 
    • [...] the first Item before the Encoded Pixel Data Stream shall be a (nice) Basic Offset Table item (not required), which contains concatenated 32-bit unsigned integer values that are bytes offsets leading to the beginning of each frame [...]
    Nevertheless, I have been unable to get any multiple-frame file following that standard, except one or two which used an encapsulated syntax that dicom2 did not support... 

    But I have found a lot of multiple-frame files structured in a much simpler manner: the OB or OW value is made of the raw concatenation of each frame, one after the another, and that's what dicom2 is actually supporting. I you want to have a look at one of these multiple-frame files, check out my medical image samples page.

          Performance
         

    WARNING: this page is old. I mean, really. Like 2000 or so. So take it with a pinch of salt. Or just skip it actually :)

    Although dicom2 should handle most combinations of different size, bit structures and photometric interpretation, you can check at the medical image samples page if a particular type of file has already been successfully tested... 
     
    All tests have been conducted on the following platforms: 
     

    O.S. Processor Mhz Byte Order RAM HD Compiler
    Windows NT Pentium II 300 Little Endian 96 SCSI 2 Borland C++ 5.02
    Linux 2.0.31 Pentium II 300 Little Endian 96 EIDE egcs 1.0.2
     sun logo  Solaris 2.5.1 UltraSparc 170 Big Endian 128 SCSI 2 Sun CC 4.2
     
    I recently removed the Windows 95 and Linux tests performed on a Pentium 120 : this configuration is no more available :) Moreover, these results would not be accurate enough regarding the new I/O optimizations implemented since version 1.8. 
     
    Each test was run using a set of 100 files of different size, bit structures (where "[x, y | z]" means "x bits stored, y bits allocated and high bit z"), photometric interpretation and syntax. The following tables report the results, in second (the smaller, the faster), of each call to dicom2 with a different set of options and tasks. Numbers in brackets at the bottom of some tables report the results previously computed with version 1.7, when the difference with version 1.8 is noteworthy (the comparison is made between the total of each call, except these using -p or --get, which where not available in version 1.7). 
    100 files, 
    Explicit VR Little Endian syntax 
    -w --win
    -w
    -a
    -p --compression=no
    -d
    -r
    -t
    -w -a -d -r -t
    -d --halve
    -d --crop=10:10:100:100
    -d --fliph --flipv
    --get=min:max
    TOTAL (without -p --get)
    version 1.7
     
    256x256 
    [12, 16 | 11] 
    MONOCHROME2
    sun logo
    5.5
    2.5
    4.8
    5.3
    2.9
    5.1
    5.2
    2.8
    5.4
    8.5
    6.4
    9.4
    3.6
    0.8
    5.2
    3.8
    1
    5.3
    1
    0.6
    2
    19
    4.5
    14.2
    2.5
    0.8
    3.9
    2.3
    0.6
    3
    3.5
    0.9
    5.5
    2.5
    0.9
    3.1
    51.7
    17.4
    54.4
       
    108.8
     
    256x256 
    [12, 12 | 11] 
    MONOCHROME2
    sun logo
    5.6
    3.2
    5.5
    5.1
    4.2
    6.9
    5.3
    4.1
    7.2
    8.6
    7.4
    11.1
    3.1
    0.5
    4
    3.5
    1.2
    5.8
    0.7
    0.4
    1.1
    19
    5.9
    15.9
    2.4
    1.2
    4.8
    1.8
    0.6
    2.7
    4
    2.5
    10.5
    1.8
    1.8
    5
    50.5
    23.8
    64.4
     
     
    105.3
     
    320x240 
    [8, 8 | 7] 
    RGB
    sun logo
    -
    -
    -
    6.8
    1.8
    6.8
    7
    1.7
    7.7
    8.9
    6.3
    11.7
    6.6
    1.1
    6.9
    7
    1
    6.7
    0.7
    0.4
    1
    44
    4
    19.6
    6.5
    0.9
    4.7
    3.2
    0.7
    3.7
    7
    2
    8
    -
    -
    -
    88.8
    13.6
    65.1
         
     
     
    100 files, 
    Explicit VR Big Endian syntax 
    -w --win
    -w
    -a
    -p --compression=no
    -d
    -r
    -t
    -w -a -d -r -t
    -d --halve
    -d --crop=10:10:100:100
    -d --fliph --flipv
    --get=min:max
    TOTAL (without -p --get)
    version 1.7
     
    256x256 
    [12, 16 | 11] 
    MONOCHROME2
    sun logo
    5.5
    2.7
    4.6
    5.3
    3
    4.8
    5.7
    2.9
    5.1
    8.5
    6.7
    9.3
    3.7
    0.8
    5.1
    3.9
    1.1
    5.3
    1
    0.6
    2
    20
    4.6
    14
    2.6
    0.8
    3.8
    2.3
    0.6
    2.8
    3.6
    1
    5.3
    2.5
    1
    2.9
    53.6
    18.2
    52.8
    73.1
    27.5
     
     
    256x256 
    [12, 12 | 11] 
    MONOCHROME2
    sun logo
    5.5
    3.3
    5.4
    5.2
    4.3
    6.7
    5.4
    4.1
    7
    8.6
    7.4
    11
    2.8
    0.6
    3.8
    3.5
    1.3
    5.7
    0.7
    0.4
    1.3
    18
    6
    15.4
    2.6
    1.3
    4.7
    1.9
    0.6
    2.7
    4
    2.7
    10.3
    2.9
    1.9
    4.8
    49.6 24.6
    63
    63.7 32.1  
     
    320x240 
    [8, 8 | 7] 
    RGB
    sun logo
    -
    -
    -
    6.9
    1.8
    6.8
    6.5
    1.7
    7.7
    8.9
    6.3
    11.7
    6.6
    1.1
    6.9
    7
    1
    6.7
    0.7
    0.4
    1
    44
    4
    19.6
    6.5
    0.9
    4.7
    3.2
    0.7
    3.7
    7
    2
    8
    -
    -
    -
    88.8 13.6
    65.1
         
     
     
          A few observations
     
        The Linux system is a killer: it is definitely a good choice in this context. 
     
    The Windows NT results are very disappointing: 2 to 5 times slower than the Linux measures, on the same hardware, a Pentium II @ 300 mhz. I guess that the really low performances of the I/O functions or drivers may be the main cause. The quality of the code generated by the Borland C++ might be involved too. This is not a multi-tasking problem, as Windows 95 (which is not a true multi-tasking system) was performing poorly too. It is so bad that even the UltraSparc @ 170 mhz is running faster :( And do not ask me why the RGB files are processed 80% slower than MONOCHROME files :) Anyway, all NT results were mostly unstable: 10% to 30% difference between each benchmark session. 
     
    The I/O functions have been enhanced since version 1.8. The algorithms used to read or write little-endian files on big-endian machine (and vice-versa) were not optimized, resulting in unnecessary slow latency. This is no more the case, and you might not notice any performance penalty resulting from byte-swapping. Have a look at the two set of tables (one is coded using Little Endian syntax, the other with Big Endian) : the difference, which ran from 40% to 100% with version 1.7, shall not exceed 5% with version 1.8 ! 
     
    Although the first two sets have the same size (256x256), the same photometric interpretation (MONOCHROME2) and quite the same structure ([12 in 16 | 11] and [12 in 16 | 11]), dicom2 performs  quicker on the first set: do not worry about this ! It has been optimized to work faster (10% to 90%) on samples stored in a multiple of 8 bits (i.e. when each cell starts at the beginning of a word or a byte). This optimization seems to have no effect with any Windows system ! 
     
    It is obvious that converting the same file to many destination formats during a single call to dicom2 is more efficient than calling dicom2 for each destination format. Look at the table, and compare the -w -a -d -r -t test to the sum of the -w, -a, -d, -r, and -t tests.
     
       
     
    Medical Imaging / Sebastien Barre / Jan. 1998