4 \page dcmdump Dump DICOM file and data set
6 \page dcmdump dcmdump: Dump DICOM file and data set
9 \section synopsis SYNOPSIS
12 dcmdump [options] dcmfile-in...
15 \section description DESCRIPTION
17 The \b dcmdump utility dumps the contents of a DICOM file (file format or raw
18 data set) to stdout in textual form. Attributes with very large value fields
19 (e.g. pixel data) can be described as "(not loaded)". String value fields
20 will be delimited with square brackets ([]). Known UIDs will be displayed by
21 their names prefixed by an equals sign (e.g. "=MRImageStorage") unless this
22 mapping would be explicitly switched off. Empty value fields are described as
23 "(no value available)".
25 If \b dcmdump reads a raw data set (DICOM data without a file format
26 meta-header) it will attempt to guess the transfer syntax by examining the
27 first few bytes of the file. It is not always possible to correctly guess the
28 transfer syntax and it is better to convert a data set to a file format
29 whenever possible (using the \b dcmconv utility). It is also possible to use
30 the \e -f and <em>-t[ieb]</em> options to force \b dcmdump to read a dataset
31 with a particular transfer syntax.
33 \section parameters PARAMETERS
36 dcmfile-in DICOM input file or directory to be dumped
39 \section options OPTIONS
41 \subsection general_options general options
44 print this help text and exit
47 print version information and exit
50 print expanded command line arguments
53 quiet mode, print no warnings and errors
56 verbose mode, print processing details
59 debug mode, print debug information
61 -ll --log-level [l]evel: string constant
62 (fatal, error, warn, info, debug, trace)
63 use level l for the logger
65 -lc --log-config [f]ilename: string
66 use config file f for the logger
69 \subsection input_options input options
74 read file format or data set (default)
80 read data set without file meta information
82 input transfer syntax:
85 use TS recognition (default)
87 -td --read-xfer-detect
88 ignore TS specified in the file meta header
90 -te --read-xfer-little
91 read with explicit VR little endian TS
94 read with explicit VR big endian TS
96 -ti --read-xfer-implicit
97 read with implicit VR little endian TS
101 +sd --scan-directories
102 scan directories for input files (dcmfile-in)
104 +sp --scan-pattern [p]attern: string (only with --scan-directories)
105 pattern for filename matching (wildcards)
107 # possibly not available on all systems
110 do not recurse within directories (default)
113 recurse within specified directories
115 parsing of file meta information:
117 +ml --use-meta-length
118 use file meta information group length (default)
120 -ml --ignore-meta-length
121 ignore file meta information group length
123 parsing of odd-length attributes:
125 +ao --accept-odd-length
126 accept odd length attributes (default)
128 +ae --assume-even-length
129 assume real length is one byte larger
131 handling of non-standard VR:
133 +vr --treat-as-unknown
134 treat non-standard VR as unknown (default)
136 -vr --assume-implicit
137 try to read with implicit VR little endian TS
139 handling of undefined length UN elements:
142 read undefined len UN as implicit VR (default)
145 read undefined len UN as explicit VR
147 handling of defined length UN elements:
150 retain elements as UN (default)
153 convert to real VR if known
155 handling of private max-length elements (implicit VR):
158 read as defined in dictionary (default)
161 read as sequence with undefined length
163 automatic data correction:
165 +dc --enable-correction
166 enable automatic data correction (default)
168 -dc --disable-correction
169 disable automatic data correction
171 general handling of parser errors:
173 +Ep --ignore-parse-errors
174 try to recover from parse errors
176 -Ep --handle-parse-errors
177 handle parse errors and stop parsing (default)
179 other parsing options:
181 +st --stop-after-elem [t]ag: "gggg,eeee" or dictionary name
182 stop parsing after element specified by t
184 bitstream format of deflated input:
186 +bd --bitstream-deflated
187 expect deflated bitstream (default)
190 expect deflated zlib bitstream
193 \subsection output_options output options
198 load very long tag values (default)
201 do not load very long values (e.g. pixel data)
203 +R --max-read-length [k]bytes: integer (4..4194302, default: 4)
204 set threshold for long values to k kbytes
209 print long tag values completely
212 print long tag values shortened (default)
215 print hierarchical structure as a simple tree
218 print hierarchical structure indented (default)
221 print header with filename for each input file
223 +Fs --print-file-search
224 print header with filename only for those input files
225 that contain one of the searched tags
228 map well-known UID numbers to names (default)
231 do not map well-known UID numbers to names
234 quote non-ASCII and control chars as XML markup
237 print non-ASCII and control chars (default)
240 use ANSI escape codes for colored output
242 # not available on Windows systems
247 do not print if file is damaged (default)
250 attempt to print even if file is damaged
254 +P --search [t]ag: "gggg,eeee" or dictionary name
255 print the value of tag t this option can be specified
256 multiple times (default: the complete file is printed)
259 print all instances of searched tags (default)
262 only print first instance of searched tags
265 prepend sequence hierarchy to printed tag,
266 denoted by: (gggg,eeee).(gggg,eeee).*
267 (only with --search-all or --search-first)
270 do not prepend hierarchy to tag (default)
274 +W --write-pixel [d]irectory: string
275 write pixel data to a .raw file stored in d
276 (little endian, filename created automatically)
279 \section logging LOGGING
281 The level of logging output of the various command line tools and underlying
282 libraries can be specified by the user. By default, only errors and warnings
283 are written to the standard error stream. Using option \e --verbose also
284 informational messages like processing details are reported. Option
285 \e --debug can be used to get more details on the internal activity, e.g. for
286 debugging purposes. Other logging levels can be selected using option
287 \e --log-level. In \e --quiet mode only fatal errors are reported. In such
288 very severe error events, the application will usually terminate. For more
289 details on the different logging levels, see documentation of module "oflog".
291 In case the logging output should be written to file (optionally with logfile
292 rotation), to syslog (Unix) or the event log (Windows) option \e --log-config
293 can be used. This configuration file also allows for directing only certain
294 messages to a particular output stream and for filtering certain messages
295 based on the module or application where they are generated. An example
296 configuration file is provided in <em><etcdir>/logger.cfg</em>).
298 \section command_line COMMAND LINE
300 All command line tools use the following notation for parameters: square
301 brackets enclose optional values (0-1), three trailing dots indicate that
302 multiple values are allowed (1-n), a combination of both means 0 to n values.
304 Command line options are distinguished from parameters by a leading '+' or '-'
305 sign, respectively. Usually, order and position of command line options are
306 arbitrary (i.e. they can appear anywhere). However, if options are mutually
307 exclusive the rightmost appearance is used. This behaviour conforms to the
308 standard evaluation rules of common Unix shells.
310 In addition, one or more command files can be specified using an '@' sign as a
311 prefix to the filename (e.g. <em>\@command.txt</em>). Such a command argument
312 is replaced by the content of the corresponding text file (multiple
313 whitespaces are treated as a single separator unless they appear between two
314 quotation marks) prior to any further evaluation. Please note that a command
315 file cannot contain another command file. This simple but effective approach
316 allows to summarize common combinations of options/parameters and avoids
317 longish and confusing command lines (an example is provided in file
318 <em><datadir>/dumppat.txt</em>).
320 \section environment ENVIRONMENT
322 The \b dcmdump utility will attempt to load DICOM data dictionaries specified
323 in the \e DCMDICTPATH environment variable. By default, i.e. if the
324 \e DCMDICTPATH environment variable is not set, the file
325 <em><datadir>/dicom.dic</em> will be loaded unless the dictionary is built
326 into the application (default for Windows).
328 The default behaviour should be preferred and the \e DCMDICTPATH environment
329 variable only used when alternative data dictionaries are required. The
330 \e DCMDICTPATH environment variable has the same format as the Unix shell
331 \e PATH variable in that a colon (":") separates entries. On Windows systems,
332 a semicolon (";") is used as a separator. The data dictionary code will
333 attempt to load each file specified in the \e DCMDICTPATH environment variable.
334 It is an error if no data dictionary can be loaded.
336 \section see_also SEE ALSO
338 <b>dump2dcm</b>(1), <b>dcmconv</b>(1)
340 \section copyright COPYRIGHT
342 Copyright (C) 1994-2010 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.