.TH "xml2dcm" 1 "Thu Nov 29 2018" "Version 3.6.4" "OFFIS DCMTK" \" -*- nroff -*-
.nh
.SH NAME
xml2dcm \- Convert XML document to DICOM file or data set
.SH "SYNOPSIS"
.PP
.PP
.nf
xml2dcm [options] xmlfile-in dcmfile-out
.fi
.PP
.SH "DESCRIPTION"
.PP
The \fBxml2dcm\fP utility converts the contents of an XML (Extensible Markup Language) document to DICOM file or data set\&. The XML document is expected to validate against the DTD (Document Type Definition) which is described in file \fIdcm2xml\&.dtd\fP\&. An appropriate XML file can be created using the \fBdcm2xml\fP tool (option \fI+Wb\fP recommended to include binary data)\&.
.SH "PARAMETERS"
.PP
.PP
.nf
xmlfile-in XML input filename to be converted (stdin: "-")
dcmfile-out DICOM output filename
.fi
.PP
.SH "OPTIONS"
.PP
.SS "general options"
.PP
.nf
-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
.fi
.PP
.SS "input options"
.PP
.nf
input file format:
+f --read-meta-info
read meta information if present (default)
-f --ignore-meta-info
ignore file meta information
.fi
.PP
.SS "processing options"
.PP
.nf
validation:
+Vd --validate-document
validate XML document against DTD
+Vn --check-namespace
check XML namespace in document root
unique identifiers:
+Ug --generate-new-uids
generate new Study/Series/SOP Instance UID
-Uo --dont-overwrite-uids
do not overwrite existing UIDs (default)
+Uo --overwrite-uids
overwrite existing UIDs
.fi
.PP
.SS "output options"
.PP
.nf
output file format:
+F --write-file
write file format (default)
-F --write-dataset
write data set without file meta information
+Fu --update-meta-info
update particular file meta information
output transfer syntax:
+t= --write-xfer-same
write with same TS as input (default)
+te --write-xfer-little
write with explicit VR little endian TS
+tb --write-xfer-big
write with explicit VR big endian TS
+ti --write-xfer-implicit
write with implicit VR little endian TS
+td --write-xfer-deflated
write with deflated explicit VR little endian TS
post-1993 value representations:
+u --enable-new-vr
enable support for new VRs (UN/UT) (default)
-u --disable-new-vr
disable support for new VRs, convert to OB
group length encoding:
+g= --group-length-recalc
recalculate group lengths if present (default)
+g --group-length-create
always write with group length elements
-g --group-length-remove
always write without group length elements
length encoding in sequences and items:
+e --length-explicit
write with explicit lengths (default)
-e --length-undefined
write with undefined lengths
data set trailing padding (not with --write-dataset):
-p= --padding-retain
do not change padding (default if not --write-dataset)
-p --padding-off
no padding (implicit if --write-dataset)
+p --padding-create [f]ile-pad [i]tem-pad: integer
align file on multiple of f bytes and items on
multiple of i bytes
deflate compression level (only with --write-xfer-deflated):
+cl --compression-level [l]evel: integer (default: 6)
0=uncompressed, 1=fastest, 9=best compression
.fi
.PP
.SH "NOTES"
.PP
The basic structure of the XML input expected looks like the following:
.PP
.PP
.nf
166
...
OFFIS_DCMTK_353
ISO_IR 100
...
-
256\\0\\8
...
...
...
.fi
.PP
.PP
The 'file-format' and 'meta-header' tags may be absent for DICOM data sets\&.
.SS "Character Encoding"
The DICOM character encoding is determined automatically from the element with tag '0008,0005' (Specific Character Set) - if present\&. The following character sets are currently supported (requires \fBlibxml\fP to include \fBiconv\fP support, see \fI--version\fP output):
.PP
.PP
.nf
ASCII (ISO_IR 6) (UTF-8)
UTF-8 "ISO_IR 192" (UTF-8)
ISO Latin 1 "ISO_IR 100" (ISO-8859-1)
ISO Latin 2 "ISO_IR 101" (ISO-8859-2)
ISO Latin 3 "ISO_IR 109" (ISO-8859-3)
ISO Latin 4 "ISO_IR 110" (ISO-8859-4)
ISO Latin 5 "ISO_IR 148" (ISO-8859-9)
Cyrillic "ISO_IR 144" (ISO-8859-5)
Arabic "ISO_IR 127" (ISO-8859-6)
Greek "ISO_IR 126" (ISO-8859-7)
Hebrew "ISO_IR 138" (ISO-8859-8)
.fi
.PP
.PP
Multiple character sets are not supported (only the first value of the 'Specific Character Set' is used for the character encoding in case of value multiplicity)\&.
.PP
See \fBdcm2xml\fP documentation for more details on the XML structure\&.
.SS "Binary Data"
Binary data can be encoded either as a sequence of hex numbers separated by a backslash '\\' or in Base64 format (binary='base64')\&. In addition, binary data can also be read from file (binary='file')\&. In this case, the filename has to be specified as the element value, e\&.g\&.
.PP
.PP
.nf
subdir/pixeldata.raw
.fi
.PP
.PP
Please note that the contents of the file will be read as is\&. OW data is expected to be little endian ordered and will be swapped if necessary\&. No checks will be made to ensure that the amount of data is reasonable in terms of other attributes such as Rows or Columns\&.
.SS "Compression"
If libxml is compiled with zlib support, the input file (\fIxmlfile-in\fP) can also be compressed with ZIP, which usually results in much smaller files\&. See output of option \fI--version\fP in order to check whether zlib support is available\&.
.SS "Limitations"
Different versions of libxml might have different limits for the maximum length of an XML element value\&. Therefore, it should be avoided to use very long element values (e\&.g\&. for pixel data)\&.
.PP
Please note that \fBxml2dcm\fP currently does not fully support DICOMDIR files\&. Specifically, the value of the various offset data elements is not updated automatically by this tool\&.
.SH "LOGGING"
.PP
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 \fI--verbose\fP also informational messages like processing details are reported\&. Option \fI--debug\fP can be used to get more details on the internal activity, e\&.g\&. for debugging purposes\&. Other logging levels can be selected using option \fI--log-level\fP\&. In \fI--quiet\fP 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'\&.
.PP
In case the logging output should be written to file (optionally with logfile rotation), to syslog (Unix) or the event log (Windows) option \fI--log-config\fP 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 \fI/logger\&.cfg\fP\&.
.SH "COMMAND LINE"
.PP
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\&.
.PP
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 behavior conforms to the standard evaluation rules of common Unix shells\&.
.PP
In addition, one or more command files can be specified using an '@' sign as a prefix to the filename (e\&.g\&. \fI@command\&.txt\fP)\&. 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 one to summarize common combinations of options/parameters and avoids longish and confusing command lines (an example is provided in file \fI/dumppat\&.txt\fP)\&.
.SH "ENVIRONMENT"
.PP
The \fBxml2dcm\fP utility will attempt to load DICOM data dictionaries specified in the \fIDCMDICTPATH\fP environment variable\&. By default, i\&.e\&. if the \fIDCMDICTPATH\fP environment variable is not set, the file \fI/dicom\&.dic\fP will be loaded unless the dictionary is built into the application (default for Windows)\&.
.PP
The default behavior should be preferred and the \fIDCMDICTPATH\fP environment variable only used when alternative data dictionaries are required\&. The \fIDCMDICTPATH\fP environment variable has the same format as the Unix shell \fIPATH\fP 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 \fIDCMDICTPATH\fP environment variable\&. It is an error if no data dictionary can be loaded\&.
.SH "FILES"
.PP
\fI/dcm2xml\&.dtd\fP - Document Type Definition (DTD) file
.SH "SEE ALSO"
.PP
\fBdcm2xml\fP(1)
.SH "COPYRIGHT"
.PP
Copyright (C) 2003-2014 by OFFIS e\&.V\&., Escherweg 2, 26121 Oldenburg, Germany\&.