4 \page dump2dcm Convert ASCII dump to DICOM file
6 \page dump2dcm dump2dcm: Convert ASCII dump to DICOM file
9 \section synopsis SYNOPSIS
12 dump2dcm [options] dumpfile-in dcmfile-out
15 \section description DESCRIPTION
17 The \b dump2dcm utility converts an ASCII dump file to a DICOM file. The
18 dump file has the same format as the output of \b dcmdump. Thus it is possible
19 to capture the output of \b dcmdump into a file, modify some attributes and
20 create a new DICOM file.
22 \section parameters PARAMETERS
25 dumpfile-in dump input filename
27 dcmfile-out DICOM output filename
30 \section options OPTIONS
32 \subsection general_options general options
35 print this help text and exit
38 print version information and exit
41 print expanded command line arguments
44 quiet mode, print no warnings and errors
47 verbose mode, print processing details
50 debug mode, print debug information
52 -ll --log-level [l]evel: string constant
53 (fatal, error, warn, info, debug, trace)
54 use level l for the logger
56 -lc --log-config [f]ilename: string
57 use config file f for the logger
60 \subsection input_options input options
65 read meta information if present (default)
68 ignore file meta information
72 +l --line [m]ax-length: integer
73 maximum line length m (default: 4096)
76 \subsection processing_options processing options
80 +Ug --generate-new-uids
81 generate new Study/Series/SOP Instance UID
83 -Uo --dont-overwrite-uids
84 do not overwrite existing UIDs (default)
87 overwrite existing UIDs
90 \subsection output_options output options
95 write file format (default)
98 write data set without file meta information
100 +Fu --update-meta-info
101 update particular file meta information
103 output transfer syntax:
105 +t= --write-xfer-same
106 write with same TS as input (default)
108 +te --write-xfer-little
109 write with explicit VR little endian
112 write with explicit VR big endian TS
114 +ti --write-xfer-implicit
115 write with implicit VR little endian TS
117 +td --write-xfer-deflated
118 write with deflated explicit VR little endian TS
123 do not write if dump is damaged (default)
126 attempt to write even if dump is damaged
128 post-1993 value representations:
131 enable support for new VRs (UN/UT) (default)
134 disable support for new VRs, convert to OB
136 group length encoding:
138 +g= --group-length-recalc
139 recalculate group lengths if present (default)
141 +g --group-length-create
142 always write with group length elements
144 -g --group-length-remove
145 always write without group length elements
147 length encoding in sequences and items:
150 write with explicit lengths (default)
152 -e --length-undefined
153 write with undefined lengths
155 data set trailing padding (not with --write-dataset):
158 do not change padding (default if not --write-dataset)
161 no padding (implicit if --write-dataset)
163 +p --padding-create [f]ile-pad [i]tem-pad: integer
164 align file on multiple of f bytes
165 and items on multiple of i bytes
167 deflate compression level (only with --write-xfer-deflated):
169 +cl --compression-level [l]evel: integer (default: 6)
170 0=uncompressed, 1=fastest, 9=best compression
175 \subsection notes_description Dump File Description
177 The input file can be an output of \b dcmdump (default indented format only).
178 One element (tag, VR, value) must be written into one line separated by
179 arbitrary spaces or tab characters. A '#' begins a comment that ends at the
180 line end. Empty lines are allowed.
182 The individual parts of a line have the following syntax:
186 with gggg and eeee are 4 character hexadecimal values
187 representing group and element tag. Spaces and tabs can be
188 anywhere in a tag specification.
189 VR: Value Representation must be written as 2 characters as in
190 Part 6 of the DICOM standard. No spaces or tabs are allowed
191 between the two characters. If the VR can be determined from
192 the tag, this part of a line is optional.
193 Value: There are several rules for writing values:
194 1. US, SS, SL, UL, FD, FL are written as decimal strings that
195 can be read by scanf().
196 2. AT is written as '(gggg,eeee)' with additional spaces
197 stripped off automatically and gggg and eeee being decimal
198 strings that can be read by scanf().
199 3. OB and OW values are written as byte or word hexadecimal
200 values separated by '\\' character. Alternatively, OB or OW
201 values can be read from a separate file by writing the
202 filename prefixed by a '=' character (e.g. '=largepix.dat').
203 The contents of the file will be read as is. OW data is
204 expected to be little endian ordered and will be swapped if
205 necessary. No checks will be made to ensure that the amount
206 of data is reasonable in terms of other attributes such as
208 In case of compressed pixel data, the line should start with
209 '(7fe0,0010) OB (PixelSequence' in order to distinguish from
210 uncompressed pixel data.
211 4. UI is written as '=Name' in data dictionary or as unique
212 identifier string (see 6.), e.g. '[1.2.840.....]'.
213 5. Strings without () <> [] spaces, tabs and # can be written
215 6. Other strings must be surrounded by '[' and ']'. No bracket
216 structure is passed. The value ends at the last ']' in the
217 line. Anything after the ']' is interpreted as comment.
218 7. '(' and '<' are interpreted special and may not be used when
219 writing an input file by hand as beginning characters of a
220 string. Multiple Value are separated by '\\'. The lines
221 need not be sorted into ascending tag order. References in
222 DICOM Directories are not supported. Semantic errors are
226 \subsection notes_example Example
229 (0008,0020) DA [19921012] # 8, 1 StudyDate
230 (0008,0016) UI =MRImageStorage # 26, 1 SOPClassUID
231 (0002,0012) UI [1.2.276.0.7230010.100.1.1]
232 (0020,0032) DS [0.0\\0.0] # 8, 2 ImagePositionPatient
233 (0028,0009) AT (3004,000c) # 4, 1 FrameIncrementPointer
234 (0028,0010) US 256 # 4, 1 Rows
235 (0002,0001) OB 01\\00
238 \subsection limitations Limitations
240 Please note that \b dump2dcm currently does not fully support DICOMDIR files.
241 Specifically, the value of the various offset data elements is not updated
242 automatically by this tool.
244 \section logging LOGGING
246 The level of logging output of the various command line tools and underlying
247 libraries can be specified by the user. By default, only errors and warnings
248 are written to the standard error stream. Using option \e --verbose also
249 informational messages like processing details are reported. Option
250 \e --debug can be used to get more details on the internal activity, e.g. for
251 debugging purposes. Other logging levels can be selected using option
252 \e --log-level. In \e --quiet mode only fatal errors are reported. In such
253 very severe error events, the application will usually terminate. For more
254 details on the different logging levels, see documentation of module "oflog".
256 In case the logging output should be written to file (optionally with logfile
257 rotation), to syslog (Unix) or the event log (Windows) option \e --log-config
258 can be used. This configuration file also allows for directing only certain
259 messages to a particular output stream and for filtering certain messages
260 based on the module or application where they are generated. An example
261 configuration file is provided in <em><etcdir>/logger.cfg</em>).
263 \section command_line COMMAND LINE
265 All command line tools use the following notation for parameters: square
266 brackets enclose optional values (0-1), three trailing dots indicate that
267 multiple values are allowed (1-n), a combination of both means 0 to n values.
269 Command line options are distinguished from parameters by a leading '+' or '-'
270 sign, respectively. Usually, order and position of command line options are
271 arbitrary (i.e. they can appear anywhere). However, if options are mutually
272 exclusive the rightmost appearance is used. This behaviour conforms to the
273 standard evaluation rules of common Unix shells.
275 In addition, one or more command files can be specified using an '@' sign as a
276 prefix to the filename (e.g. <em>\@command.txt</em>). Such a command argument
277 is replaced by the content of the corresponding text file (multiple
278 whitespaces are treated as a single separator unless they appear between two
279 quotation marks) prior to any further evaluation. Please note that a command
280 file cannot contain another command file. This simple but effective approach
281 allows to summarize common combinations of options/parameters and avoids
282 longish and confusing command lines (an example is provided in file
283 <em><datadir>/dumppat.txt</em>).
285 \section environment ENVIRONMENT
287 The \b dump2dcm utility will attempt to load DICOM data dictionaries specified
288 in the \e DCMDICTPATH environment variable. By default, i.e. if the
289 \e DCMDICTPATH environment variable is not set, the file
290 <em><datadir>/dicom.dic</em> will be loaded unless the dictionary is built
291 into the application (default for Windows).
293 The default behaviour should be preferred and the \e DCMDICTPATH environment
294 variable only used when alternative data dictionaries are required. The
295 \e DCMDICTPATH environment variable has the same format as the Unix shell
296 \e PATH variable in that a colon (":") separates entries. On Windows systems,
297 a semicolon (";") is used as a separator. The data dictionary code will
298 attempt to load each file specified in the \e DCMDICTPATH environment variable.
299 It is an error if no data dictionary can be loaded.
301 \section see_also SEE ALSO
305 \section copyright COPYRIGHT
307 Copyright (C) 1996-2010 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.