dicom2, How to

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

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

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

			Many default behaviours as well as default option-values are used during the conversion process, but these might not fit your own way to work. It is easy to redefine them, but you might getting tired of always specifying the same destination directory (`--to`), the same compression scheme (`--compression`), the same control flags (`--warn`, `--rank`), and so on. Put any of your usual options in the `DICOM2` environment variable, and they will be used in every subsequent calls: `dicom2 --to=c:\temp --compression=fast --warn=n --rank=y -w .dcm` `dicom2 --to=c:\temp --compression=fast --warn=n --rank=y -a test\.dcm` ... might be replaced by: `set DICOM2=--to=c:\temp --compression=fast --warn=n --rank=y` `dicom2 -w .dcm` `dicom2 -a test\.dcm` ... No worry, you may still override these options by redefining them on the command-line (the first set of files will be written to `c:\temp`, the second to `c:\temp2)`: `set DICOM2=--to=c:\temp` `dicom2 -w .dcm` `dicom2 -w --to=c:\temp2 .dcm` The way you might set and save environment variables depends on your operating system and your shell: win95/NT (command.com): `set DICOM2=--warn=n --rank=y` SunOS/Solaris (tcsh): `setenv DICOM2 "--warn=n --rank=y"`
			Convert to PNG, BMP, TARGA

			Fairly simple. dicom2 is a command-line driven program.Therefore, it shall be called using a set of options and arguments specifying its tasks. See Usage (1) and Usage (2) pages for complete informations regarding these options. Nevertheless, here are small examples: `dicom2 -w knee.dcm` will convert the medical file `knee.dcm` to Windows's BMP format. The resulting file will be called `knee.dcm.bmp`. `dicom2 -a -p *.dcm` will convert all files with extension `.dcm` to TARGA and PNG formats. The `.tga` extension will be appended to the resulting TARGA files (respectively `.png` to the PNG files).
			*Convert to raw (vtk)*

			The Visualization Toolkit (vtk for short) is a very powerful library that "covers dozens of graphics and visualization techniques". It provides functions to read 16 bits/pixel images (optionally preceeded by a header of fixed length) and automatically swaps and masks 16 bits words if needed. Unfortunately, the organization and the structure of the DICOM format is far from that expected format: there is no fixed-length header, and pixel data shall be "padded" (and optionally "cleaned") first to be usable. This whole stuff may be carried out by the conversion to RAW (have a look at the `-r` option for more explanations and diagrams regarding the resulting pixel structure). Here is a simple way to create these raw files using dicom2: `mkdir rawdir` `dicom2 --to=rawdir -r *` The `--to=rawdir` option is used to store the resulting files in the `rawdir` directory, although it might not be necessary as the `.raw` extension will be appended to each file. The `--rank` option might be useful if you plan to convert hundreds of files: it gives you a visual clue of the remaining files to process (in that situation you might use the `--warn` option too).
			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. `4 images from a series of 250 axial slices` `(check the headbed and the left and right "pillows")`
			Accumulate First of all, you shall compute which of the pixels are used along all images within the series (which is quite similar to an accumulation buffer representing the maximum occupancy of the structures). See option `--acc` for more explanations and diagrams. `dicom2 --acc=max *` `computed (a) on 4 slices, (b) on 250 slices` The resulting DICOM file (which defaults to `acc-max.dcm`) shall be converted to BMP, in order to be recognized by any painting program. `dicom2 -w acc-max.dcm`
			Mask You are now able to create a mask starting from this image, by attributing zero to the points that you want to save in each frame, and non-zero to these that you want to remove(set to 0). The mask will act like a kind of stencil: the zero-area being a "hole", the non-zero area covering the non-desired pixels. Have a look at the `--mask` option to get more coverage on the principles. `a mask (zero is black)` We are quite finished: let's build up the new masked images, which will be stored in the `masked` directory: `mkdir masked` `dicom2 --mask=zero:acc-max.bmp --to=masked -d *` `the 4 original slices` `the 4 original slices, now masked`
			Crop The resulting images will exhibit more zeros than the original ones (as pixels from removed structures are set 0). Hence you might consider using the `--crop` option to save the relevant part of the image only, and speed-up further processes. The coordinates of the cropping-window might be computed from the mask, which explicitly shows which parts of the resulting image will remain, and which won't. The `--crop` and `--mask` options may be used in the same time (as `--mask` occurs first). Forget the previous call to dicom2 and speed up the process with: `mkdir masked` `dicom2 --mask=zero:acc-max.bmp --crop=44:70:400:400 --to=masked -d *` `original slice (512x512), now masked and cropped (400x400)`
			Summary `dicom2 --acc=max ` `dicom2 -w acc-max.dcm` ... 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.

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

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

Accumulate

Mask

Crop

Summary