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


Generated on Wed Dec 28 2016 for OFFIS DCMTK Version 3.6.0 by Doxygen 1.8.8