.TH "xml2dcm" 1 "Thu Jul 9 2026 18:43:40" "Version 3.7.0" "OFFIS DCMTK" \" -*- nroff -*- .nh .SH NAME xml2dcm \- Convert XML document to DICOM file or data set .PP .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 ("-" for stdin) dcmfile-out DICOM output filename ("-" for stdout) .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 error handling: -E --stop-on-error do not write if document is invalid (default) +E --ignore-errors attempt to write even if document is invalid 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) ISO Latin 9 "ISO_IR 203" (ISO-8859-15) 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 datacan also be read from file (binary="file")\&. In this case, the filename has tobe specified as the element value, e\&.g\&.@verbatim subdir/pixeldata\&.raw\\endverbatimPlease note that the contents of the file will be read as is\&. OW data isexpected to be little endian ordered and will be swapped if necessary\&. Nochecks will be made to ensure that the amount of data is reasonable in termsof other attributes such as Rows or Columns\&.(*) Please note that currently only OB and OW data is supported, i\&.e\&. elementvalues with a VR of OD, OF, OL and OV are not regarded as "binary data" andtreated as all other VRs\&.@subsection xml2dcm_compression CompressionIf libxml is compiled with zlib support, the input file (\\e xmlfile-in) canalso be compressed with ZIP, which usually results in much smaller files\&. Seeoutput of option \\e --version in order to check whether zlib support isavailable\&.@subsection xml2dcm_limitations LimitationsDifferent versions of libxml might have different limits for the maximumlength of an XML element value\&. Therefore, it should be avoided to use verylong element values (e\&.g\&. for pixel data)\&.Please note that \\b xml2dcm currently does not fully support DICOMDIR files\&.Specifically, the value of the various offset data elements is not updatedautomatically by this tool\&.@section xml2dcm_logging LOGGINGThe level of logging output of the various command line tools and underlyinglibraries can be specified by the user\&. By default, only errors and warningsare written to the standard error stream\&. Using option \\e --verbose alsoinformational messages like processing details are reported\&. Option\\e --debug can be used to get more details on the internal activity, e\&.g\&. fordebugging purposes\&. Other logging levels can be selected using option\\e --log-level\&. In \\e --quiet mode only fatal errors are reported\&. In suchvery severe error events, the application will usually terminate\&. For moredetails on the different logging levels, see documentation of module "oflog"\&.In case the logging output should be written to file (optionally with logfilerotation), to syslog (Unix) or the event log (Windows) option \\e --log-configcan be used\&. This configuration file also allows for directing only certainmessages to a particular output stream and for filtering certain messagesbased on the module or application where they are generated\&. An exampleconfiguration file is provided in \\/logger\&.cfg\&.@section xml2dcm_command_line COMMAND LINEAll command line tools use the following notation for parameters: squarebrackets enclose optional values (0-1), three trailing dots indicate thatmultiple values are allowed (1-n), a combination of both means 0 to n values\&.Command line options are distinguished from parameters by a leading '+' or '-'sign, respectively\&. Usually, order and position of command line options arearbitrary (i\&.e\&. they can appear anywhere)\&. However, if options are mutuallyexclusive the rightmost appearance is used\&. This behavior conforms to thestandard evaluation rules of common Unix shells\&.In addition, one or more command files can be specified using an '@' sign as aprefix to the filename (e\&.g\&. \\@command\&.txt)\&. Such a command argumentis replaced by the content of the corresponding text file (multiplewhitespaces are treated as a single separator unless they appear between twoquotation marks) prior to any further evaluation\&. Please note that a commandfile cannot contain another command file\&. This simple but effective approachallows one to summarize common combinations of options/parameters and avoidslongish and confusing command lines (an example is provided in file\\/dumppat\&.txt)\&.@section xml2dcm_environment ENVIRONMENTThe \\b xml2dcm utility will attempt to load DICOM data dictionaries specifiedin the \\e DCMDICTPATH environment variable\&. By default, i\&.e\&. if the\\e DCMDICTPATH environment variable is not set, the file\\/dicom\&.dic will be loaded unless the dictionary is builtinto the application (default for Windows)\&.The default behavior should be preferred and the \\e DCMDICTPATH environmentvariable only used when alternative data dictionaries are required\&. The\\e DCMDICTPATH environment variable has the same format as the Unix shell\\e PATH 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-2025 by OFFIS e\&.V\&., Escherweg 2, 26121 Oldenburg, Germany\&.