dicom2 logo
 
Download | Install | Usage (1) (2) | How to | Problems | Limitations | Performances 
TOCUsage (1)How to 
Usage (2)
      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 
Top Control output
Renaming pattern
  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.

Control output Renaming pattern
Image processing
  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 

Renaming pattern Image processing
Bottom
  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] 
 
 
Download | Install | Usage (1) (2) | How to | Problems | Limitations | Performances  TOCUsage (1)How to 
 
Medical Imaging / Sébastien Barré / Jan. 1998