|
DCMTK
Version 3.6.9
OFFIS DICOM Toolkit
|
dcm2avi [options] [dcmfile-in...] [avifile-out]
The dcm2avi utility converts DICOM images to Windows AVI files using the optionally specified video compressor. It supports both uncompressed and compressed (JPEG and RLE) DICOM images in monochrome and color format.
dcmfile-in DICOM input filename to be converted
("-" for stdin)
avifile-out AVI output filename
-h --help
print this help text and exit
--version
print version information and exit
--arguments
print expanded command line arguments
-q --quiet
quiet mode, print no warnings and errors
-v --verbose
verbose mode, print processing details
-d --debug
debug mode, print debug information
-ll --log-level [l]evel: string constant
(fatal, error, warn, info, debug, trace)
use level l for the logger
-lc --log-config [f]ilename: string
use config file f for the logger
-li --license-info
print license information
input file format:
+f --read-file
read file format or data set (default)
+fo --read-file-only
read file format only
-f --read-dataset
read data set without file meta information
input transfer syntax:
-t= --read-xfer-auto
use TS recognition (default)
-td --read-xfer-detect
ignore TS specified in the file meta header
-te --read-xfer-little
read with explicit VR little endian TS
-tb --read-xfer-big
read with explicit VR big endian TS
-ti --read-xfer-implicit
read with implicit VR little endian TS
input image format:
+mf --multiframe-only
convert multi-frame images only
input mode:
-bm --batch-mode
batch mode, convert multiple input files
(output filenames created automatically)
-rd --read-from-dicomdir [f]ilename: string
read image filenames from DICOMDIR file f
(implies --batch-mode)
compressor:
-Cl --list-compressors
list installed video compressors
-Ci --compressor-info [f]our-character code: string
print details of video compressor f
-C --no-compression
do not compress output file (default)
+C --use-compressor [f]our-character code: string
use specified codec f for compression
+Cq --compr-quality [q]uality: float (0..100)
quality value for compression (in percent)
+Cd --compr-data-rate [d]ata rate: float
data rate for compression (in kbit/s)
+Ck --compr-key-frames [k]ey frames: integer
maximum period between video key frames
+Cf --compr-frame-rate [f]rame rate: float
value overrides DICOM 'FrameTime' (fps)
+Cs --compr-show-dialog
show compression options dialog
pixel aspect ratio:
+a --recognize-aspect
recognize pixel aspect ratio
-a --ignore-aspect
ignore pixel aspect ratio (default)
+i --interpolate [n]umber of algorithm: integer
use interpolation when scaling (1..4, default: 1)
-i --no-interpolation
no interpolation when scaling
color space conversion (compressed images only):
+cp --conv-photometric
convert if YCbCr photometric interpretation (default)
+cl --conv-lossy
convert YCbCr to RGB if lossy JPEG
+cg --conv-guess
convert to RGB if YCbCr is guessed by library
+cgl --conv-guess-lossy
convert to RGB if lossy JPEG and YCbCr is
guessed by the underlying JPEG library
+ca --conv-always
always convert YCbCr to RGB
+cn --conv-never
never convert color space
VOI LUT transformation:
-W --no-windowing
no VOI windowing (default)
+Wm --min-max-window
compute VOI window using min-max algorithm
+Wn --min-max-window-n
compute VOI window using min-max algorithm,
ignoring extreme values
overlay:
+O --display-overlays
display overlays (default)
-O --no-overlays
do not display overlays
memory handling:
-fm --frames-in-memory [f]rame count: integer
number of frames in memory (default: all)
error handling:
-ab --abort-on-error
abort on error (default: skip to next file)
other:
+tc --always-truecolor
always create and pass truecolor bitmaps to the codec
(required for some compressors)
-lp --no-line-padding
do not align scanlines to a 32-bit address
(required for some compressors)
-owh --no-odd-width-height
add 1-pixel border in case width or height is odd
(required for some compressors)
general:
-im --image-info
info mode, print image details
-o --no-output
do not create any output file
(useful with --image-info)
+od --output-directory [d]irectory: string (default: ".")
output directory for the created AVI files
(not with parameter 'avifile-out')
+Os --skip-existing-files
skip if AVI or overview image file already exists
(default: overwrite)
filename generation:
+On --create-new-filename
automatically create a new filename using modality and
a counter (e.g. XA000001.avi)
+Op --create-from-pathname
create filename from DICOM image path
(e.g. st1\\se1\\im1 -> st1_se1_im1.avi)
+Opn --create-from-patient
create filename from DICOM patient's name
(e.g. Doe_John_01.avi)
additional files:
+ov --overview-image
create overview image (128x128 pixels) of the
representative frame
+ob --overview-image-bmp
use BMP format for the overview image (default)
+oj --overview-image-jpeg
use JPEG format for the overview image
+si --single-frame-image
create JPEG image (90% quality) instead of AVI file
for single-frame input images
+sd --write-study-data
[i]nput [o]utput filename: string
write DICOM attributes specified in i to o
In the following five typical use cases are described:
1. Get information on available compressors and options
> dcm2avi -Cl
lists all video compressors installed using the following format:
MSVC Microsoft Video 1
MRLE Microsoft RLE
IV32 Intel Indeo(R) Video R3.2
M263 Microsoft H.263 Video Codec
M261 Microsoft H.261 Video Codec
MPG4 MPEG-4-Highspeed-Videokomprimierung (MT)
: :
where the first column shows the four-character code (FCC) of the
compressor. This code can be used to retrieve detailed information
on a particular compressor, e.g.
> dcm2avi -Ci MSVC
prints the details on the 'Microsoft Video 1' compressor:
4 char code : MSVC
Version : 65536
Version ICM : 260
Name : MS-CRAM
Description : Microsoft Video 1
Driver : C:\\Windows\\System32\\msvidc32.dll
Flags : VIDCF_QUALITY VIDCF_TEMPORAL
Defaults
- Quality : 75%
- Keyframes : 15
2. Get information on a given DICOM image
To get some basic information on a DICOM image prior to
conversion enter the following command:
> dcm2avi -im -o image.dcm
The output might look like this (for an ultrasound image):
Filename : image.dcm
Xfer Syntax : JPEG Baseline
SOP Class : UltrasoundMultiframeImageStorage
Color Model : YBR_FULL_422
Width : 768
Height : 576
Depth : 8
Frames : 25
Frame Time : 40.000000
To print the image details for more than one image use
the "batch mode" (by adding '-bm' to the command line):
> dcm2avi -im -o -bm image1.dcm image2.dcm image3.dcm
or use wildcards
> dcm2avi -im -o -bm image?.dcm images\\*.dcm
3. Convert a given DICOM image to an AVI file
To convert a DICOM image to AVI format just specify
input and output filename:
> dcm2avi image.dcm image.avi
Switch to verbose mode by adding '-v' to see the processing
details during the conversion. Since no compressor is
specified the created AVI file contains uncompressed image
data. Use the '+C' option to select the desired video
compressor, e.g.:
> dcm2avi -v image.dcm image.avi +C MSVC
Further compressor parameters can be set using the '+C..'
options as listed above. '+Cs' shows the compressor dialog
which might allow to modify further settings.
4. Convert a number of DICOM images
The batch mode can also be used to convert multiple DICOM
images in one step. In this case the name of the output file
cannot be specified but is created automatically.
> dcm2avi -v image1.dcm image2.dcm -bm +C MSVC
converts the two given DICOM images to AVI format and stores
the result as "image1.dcm.avi" and "image2.dcm.avi" in the current
directory. The output directory can be changed using the '+od'
option:
> dcm2avi -v image1.dcm image2.dcm -bm +C MSVC +od c:\\temp
5. Convert all images referenced in a DICOMDIR
DICOM media usually contain a central directory file, called
DICOMDIR, referencing all DICOM images stored on it. The
following command converts all images referenced in the DICOMDIR
of a CD (in this case drive "E:"):
> dcm2avi -rd e:\\DICOMDIR +od c:\\temp -v
To avoid single frame images (e.g. secondary capture overview
images) to be converted to an AVI file, add the option '+mf'.
When the DICOM images are stored with identical names in different
subdirectories another option should be added to avoid that
already converted files are overwritten. '+Op' uses the relative
pathname as stored in the DICOMDIR for the AVI filename (and
replaces the path separator characters by an underscore):
e.g. "st1\\se1\\im1" becomes "st1_se1_im1.avi".
Alternatively, option '+On' can be used to create the output
filenames from the modality symbol and a counter:
e.g. XA000001.avi, SC000002.avi, ...
Please note that an AVI file created with a certain video compressor requires the same compressor to be installed on the system which is used to display the AVI file (e.g. DICOM image is converted on a desktop PC but AVI file is played on a notebook).
By default, dcm2avi loads the complete DICOM image into memory. Especially, when processing compressed pixel data this approach might require more main memory than available on the particular system or to a single process (e.g. there is 2 GB limitation on many versions of the Windows operating systems). Therefore, option –frames-in-memory allows for specifying the maximum number of frames to be loaded and converted in a single step; the subsequent frames are processed in further iterations. Using this step-by-step processing, the overall memory consumption can be reduced significantly, especially for large compressed multi-frame images. However, as a drawback, the processing of embedded overlay planes is disabled.
The option –no-line-padding is required for some compressors (e.g. DIV3) when converting images with a number of columns which cannot be divided by 4. If the AVI file looks strange and the image width is for instance odd, try this option first. Option –always-truecolor might be required when converting monochrome images with a compressor which does not accept palette color bitmaps (e.g. DIVX 5).
The following preferred interpolation algorithms can be selected using the –interpolate option:
The option –write-study-data allows to write user defined attributes from the DICOM dataset to a text file. The input text file contains the DICOM tag names (according to the data dictionary, e.g. "PatientName") or group and element numbers ("gggg,eeee"). Multiple tags are to be separated by whitespaces, see <datadir>/study.txt for an example. The specified output file is used for all images converted in a single step. Descriptions of multiple DICOM files are separated by a blank line. The name of the DICOM ("InputFilename"), AVI/JPEG ("OutputFilename") and BMP/JPEG ("OverviewImage") file is always listed at the beginning of the output file, followed by the user defined DICOM attributes. Each line in the output file contains the field or tag name followed by ": " and the actual value (which might be empty/absent).
The option –create-from-patient creates for each written file a filename that corresponds to the first and last name of the patient as stored in the attribute "PatientName" in the DICOM file. If one of these two name components is not available, dcm2avi uses the word "Anonymous" as a replacement. In order to handle multiple files belonging to the same patient (i.e. having the same patient's name) dcm2avi adds a counter that is incremented for each file belonging to the same patient. Here are some examples for a patient named "John Doe":
For two DICOM files containing a complete attribute "PatientName": Doe_John_00.avi Doe_John_01.avi If one of the files has no last name set: Anonymous_John_00.avi Doe_John_00.avi If both files contain neither a first nor a last name: Anonymous_Anonymous_00.avi Anonymous_Anonymous_01.avi
Many file systems only allow parts of the full 8-bit character set for naming files (e.g. 0-9, A-Z, a-z, '-' and '_'). Therefore, dcm2avi substitutes every other occurrence of a character in a patient's name with an "equivalent" character. E.g. the German umlaut "Ä" is translated to "Ae". If no mapping is possible, the underscore "_" character is used as a placeholder. Please note that currently only ASCII characaters and the ISO Latin 1 character set are supported. For other character sets the behaviour of this option is undefined.
The level of logging output of the various command line tools and underlying libraries can be specified by the user. By default, only errors and warnings are written to the standard error stream. Using option –verbose also informational messages like processing details are reported. Option –debug can be used to get more details on the internal activity, e.g. for debugging purposes. Other logging levels can be selected using option –log-level. In –quiet mode only fatal errors are reported. In such very severe error events, the application will usually terminate. For more details on the different logging levels, see documentation of module "oflog".
In case the logging output should be written to file (optionally with logfile rotation), to syslog (Unix) or the event log (Windows) option –log-config can be used. This configuration file also allows for directing only certain messages to a particular output stream and for filtering certain messages based on the module or application where they are generated. An example configuration file is provided in <etcdir>/logger.cfg).
All command line tools use the following notation for parameters: square brackets enclose optional values (0-1), three trailing dots indicate that multiple values are allowed (1-n), a combination of both means 0 to n values.
Command line options are distinguished from parameters by a leading '+' or '-' sign, respectively. Usually, order and position of command line options are arbitrary (i.e. they can appear anywhere). However, if options are mutually exclusive the rightmost appearance is used. This behaviour conforms to the standard evaluation rules of common Unix shells.
In addition, one or more command files can be specified using an '@' sign as a prefix to the filename (e.g. @command.txt). Such a command argument is replaced by the content of the corresponding text file (multiple whitespaces are treated as a single separator unless they appear between two quotation marks) prior to any further evaluation. Please note that a command file cannot contain another command file. This simple but effective approach allows to summarize common combinations of options/parameters and avoids longish and confusing command lines (an example is provided in file <datadir>/dumppat.txt).
The dcm2avi utility requires the Microsoft 'Video for Windows 1.1' (or later) package to be installed. This should be the case for most Windows systems today. A list of available compressors can be retrieved using the '-Cl' option as described above.
The dcm2avi utility will attempt to load DICOM data dictionaries specified in the DCMDICTPATH environment variable. By default, i.e. if the DCMDICTPATH environment variable is not set, the file <datadir>/dicom.dic will be loaded unless the dictionary is built into the application (default for Windows).
The default behaviour should be preferred and the DCMDICTPATH environment variable only used when alternative data dictionaries are required. The DCMDICTPATH environment variable has the same format as the Unix shell PATH variable in that a colon (":") separates entries. On Windows systems, a semicolon (";") is used as a separator. The data dictionary code will attempt to load each file specified in the DCMDICTPATH environment variable. It is an error if no data dictionary can be loaded.
<datadir>/study.txt - Sample input file for –write-study-data option
Copyright (C) 2001-2024 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.
Enter 'dcm2avi -li' to get more information on the type of license and the details on how to get a registered copy.
Do not distribute the license file 'dcm2avi.lic'!