1xml2dcm(1) OFFIS DCMTK xml2dcm(1)
2
6 xml2dcm - Convert XML document to DICOM file or data set
7
10 xml2dcm [options] xmlfile-in dcmfile-out
11
13 The xml2dcm utility converts the contents of an XML (Extensible Markup
14 Language) document to DICOM file or data set. The XML document is
15 expected to validate against the DTD (Document Type Definition) which
16 is described in file dcm2xml.dtd. An appropriate XML file can be
17 created using the dcm2xml tool (option +Wb recommended to include
18 binary data).
19
21 xmlfile-in XML input filename to be converted (stdin: "-")
22 dcmfile-out DICOM output filename
24
26 general options
27 -h --help
28 print this help text and exit
29 --version
31 print version information and exit
32 --arguments
34 print expanded command line arguments
35 -q --quiet
37 quiet mode, print no warnings and errors
38 -v --verbose
40 verbose mode, print processing details
41 -d --debug
43 debug mode, print debug information
44 -ll --log-level [l]evel: string constant
46 (fatal, error, warn, info, debug, trace)
47 use level l for the logger
48 -lc --log-config [f]ilename: string
50 use config file f for the logger
51 input options
53 input file format:
54 +f --read-meta-info
56 read meta information if present (default)
57 -f --ignore-meta-info
59 ignore file meta information
60 processing options
62 validation:
63 +Vd --validate-document
65 validate XML document against DTD
66 +Vn --check-namespace
68 check XML namespace in document root
69 unique identifiers:
71 +Ug --generate-new-uids
73 generate new Study/Series/SOP Instance UID
74 -Uo --dont-overwrite-uids
76 do not overwrite existing UIDs (default)
77 +Uo --overwrite-uids
79 overwrite existing UIDs
80 output options
82 output file format:
83 +F --write-file
85 write file format (default)
86 -F --write-dataset
88 write data set without file meta information
89 +Fu --update-meta-info
91 update particular file meta information
92 output transfer syntax:
94 +t= --write-xfer-same
96 write with same TS as input (default)
97 +te --write-xfer-little
99 write with explicit VR little endian TS
100 +tb --write-xfer-big
102 write with explicit VR big endian TS
103 +ti --write-xfer-implicit
105 write with implicit VR little endian TS
106 +td --write-xfer-deflated
108 write with deflated explicit VR little endian TS
109 error handling:
111 -E --stop-on-error
113 do not write if document is invalid (default)
114 +E --ignore-errors
116 attempt to write even if document is invalid
117 post-1993 value representations:
119 +u --enable-new-vr
121 enable support for new VRs (UN/UT) (default)
122 -u --disable-new-vr
124 disable support for new VRs, convert to OB
125 group length encoding:
127 +g= --group-length-recalc
129 recalculate group lengths if present (default)
130 +g --group-length-create
132 always write with group length elements
133 -g --group-length-remove
135 always write without group length elements
136 length encoding in sequences and items:
138 +e --length-explicit
140 write with explicit lengths (default)
141 -e --length-undefined
143 write with undefined lengths
144 data set trailing padding (not with --write-dataset):
146 -p= --padding-retain
148 do not change padding (default if not --write-dataset)
149 -p --padding-off
151 no padding (implicit if --write-dataset)
152 +p --padding-create [f]ile-pad [i]tem-pad: integer
154 align file on multiple of f bytes and items on
155 multiple of i bytes
156 deflate compression level (only with --write-xfer-deflated):
158 +cl --compression-level [l]evel: integer (default: 6)
160 0=uncompressed, 1=fastest, 9=best compression
161
163 The basic structure of the XML input expected looks like the following:
164 <?xml version="1.0" encoding="ISO-8859-1"?>
166 <!DOCTYPE file-format SYSTEM "dcm2xml.dtd">
167 <file-format xmlns="http://dicom.offis.de/dcmtk">
168 <meta-header xfer="1.2.840.10008.1.2.1" name="Little Endian Explicit">
169 <element tag="0002,0000" vr="UL" vm="1" len="4"
170 name="MetaElementGroupLength">
171 166
172 </element>
173 ...
174 <element tag="0002,0013" vr="SH" vm="1" len="16"
175 name="ImplementationVersionName">
176 OFFIS_DCMTK_353
177 </element>
178 </meta-header>
179 <data-set xfer="1.2.840.10008.1.2" name="Little Endian Implicit">
180 <element tag="0008,0005" vr="CS" vm="1" len="10"
181 name="SpecificCharacterSet">
182 ISO_IR 100
183 </element>
184 ...
185 <sequence tag="0028,3010" vr="SQ" card="2" name="VOILUTSequence">
186 <item card="3">
187 <element tag="0028,3002" vr="xs" vm="3" len="6"
188 name="LUTDescriptor">
189 256 8
190 </element>
191 ...
192 </item>
193 ...
194 </sequence>
195 ...
196 <element tag="7fe0,0010" vr="OW" vm="1" len="262144"
197 name="PixelData" loaded="no" binary="hidden">
198 </element>
199 </data-set>
200 </file-format>
201 The 'file-format' and 'meta-header' tags may be absent for DICOM data
203 sets.
204 Character Encoding
206 The DICOM character encoding is determined automatically from the
207 element with tag '0008,0005' (Specific Character Set) - if present. The
208 following character sets are currently supported (requires libxml to
209 include iconv support, see --version output):
210 ASCII (ISO_IR 6) (UTF-8)
212 UTF-8 "ISO_IR 192" (UTF-8)
213 ISO Latin 1 "ISO_IR 100" (ISO-8859-1)
214 ISO Latin 2 "ISO_IR 101" (ISO-8859-2)
215 ISO Latin 3 "ISO_IR 109" (ISO-8859-3)
216 ISO Latin 4 "ISO_IR 110" (ISO-8859-4)
217 ISO Latin 5 "ISO_IR 148" (ISO-8859-9)
218 Cyrillic "ISO_IR 144" (ISO-8859-5)
219 Arabic "ISO_IR 127" (ISO-8859-6)
220 Greek "ISO_IR 126" (ISO-8859-7)
221 Hebrew "ISO_IR 138" (ISO-8859-8)
222 Multiple character sets are not supported (only the first value of the
224 'Specific Character Set' is used for the character encoding in case of
225 value multiplicity).
226 See dcm2xml documentation for more details on the XML structure.
228 Binary Data
230 Binary data (*) can be encoded either as a sequence of hex numbers
231 separated by a backslash '\' or in Base64 format (binary='base64'). In
232 addition, binary data can also be read from file (binary='file'). In
233 this case, the filename has to be specified as the element value, e.g.
234 <element tag="7fe0,0010" vr="OW" ... binary="file">subdir/pixeldata.raw</element>
236 Please note that the contents of the file will be read as is. OW data
238 is expected to be little endian ordered and will be swapped if
239 necessary. No checks will be made to ensure that the amount of data is
240 reasonable in terms of other attributes such as Rows or Columns.
241 (*) Please note that currently only OB and OW data is supported, i.e.
243 element values with a VR of OD, OF, OL and OV are not regarded as
244 'binary data' and treated as all other VRs.
245 Compression
247 If libxml is compiled with zlib support, the input file (xmlfile-in)
248 can also be compressed with ZIP, which usually results in much smaller
249 files. See output of option --version in order to check whether zlib
250 support is available.
251 Limitations
253 Different versions of libxml might have different limits for the
254 maximum length of an XML element value. Therefore, it should be avoided
255 to use very long element values (e.g. for pixel data).
256 Please note that xml2dcm currently does not fully support DICOMDIR
258 files. Specifically, the value of the various offset data elements is
259 not updated automatically by this tool.
260
262 The level of logging output of the various command line tools and
263 underlying libraries can be specified by the user. By default, only
264 errors and warnings are written to the standard error stream. Using
265 option --verbose also informational messages like processing details
266 are reported. Option --debug can be used to get more details on the
267 internal activity, e.g. for debugging purposes. Other logging levels
268 can be selected using option --log-level. In --quiet mode only fatal
269 errors are reported. In such very severe error events, the application
270 will usually terminate. For more details on the different logging
271 levels, see documentation of module 'oflog'.
272 In case the logging output should be written to file (optionally with
274 logfile rotation), to syslog (Unix) or the event log (Windows) option
275 --log-config can be used. This configuration file also allows for
276 directing only certain messages to a particular output stream and for
277 filtering certain messages based on the module or application where
278 they are generated. An example configuration file is provided in
279 <etcdir>/logger.cfg.
280
282 All command line tools use the following notation for parameters:
283 square brackets enclose optional values (0-1), three trailing dots
284 indicate that multiple values are allowed (1-n), a combination of both
285 means 0 to n values.
286 Command line options are distinguished from parameters by a leading '+'
288 or '-' sign, respectively. Usually, order and position of command line
289 options are arbitrary (i.e. they can appear anywhere). However, if
290 options are mutually exclusive the rightmost appearance is used. This
291 behavior conforms to the standard evaluation rules of common Unix
292 shells.
293 In addition, one or more command files can be specified using an '@'
295 sign as a prefix to the filename (e.g. @command.txt). Such a command
296 argument is replaced by the content of the corresponding text file
297 (multiple whitespaces are treated as a single separator unless they
298 appear between two quotation marks) prior to any further evaluation.
299 Please note that a command file cannot contain another command file.
300 This simple but effective approach allows one to summarize common
301 combinations of options/parameters and avoids longish and confusing
302 command lines (an example is provided in file <datadir>/dumppat.txt).
303
305 The xml2dcm utility will attempt to load DICOM data dictionaries
306 specified in the DCMDICTPATH environment variable. By default, i.e. if
307 the DCMDICTPATH environment variable is not set, the file
308 <datadir>/dicom.dic will be loaded unless the dictionary is built into
309 the application (default for Windows).
310 The default behavior should be preferred and the DCMDICTPATH
312 environment variable only used when alternative data dictionaries are
313 required. The DCMDICTPATH environment variable has the same format as
314 the Unix shell PATH variable in that a colon (':') separates entries.
315 On Windows systems, a semicolon (';') is used as a separator. The data
316 dictionary code will attempt to load each file specified in the
317 DCMDICTPATH environment variable. It is an error if no data dictionary
318 can be loaded.
319
321 <datadir>/dcm2xml.dtd - Document Type Definition (DTD) file
322
324 dcm2xml(1)
325
327 Copyright (C) 2003-2022 by OFFIS e.V., Escherweg 2, 26121 Oldenburg,
328 Germany.
329Version 3.6.7 Fri Apr 22 2022 xml2dcm(1)