dicom2, Usage (1)

Usage (1)

Conversion formats

Conversion context

Input files

Frame selection

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. I'm trying to provide an accurate dictionary, but new tags are steadily introduced, as well as private clusters which are not publicly described: if you know some tags that should be recognized, please send me their descriptions and I will add them as soon as possible.

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

                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.

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

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 2 head win 2
head 3 head 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.

Medical Imaging / Sébastien Barré / Jan. 1998