1/*!
2
3\if MANPAGES
4\page dump2dcm Convert ASCII dump to DICOM file
5\else
6\page dump2dcm dump2dcm: Convert ASCII dump to DICOM file
7\endif
8
9\section dump2dcm_synopsis SYNOPSIS
10
11\verbatim
12dump2dcm [options] dumpfile-in dcmfile-out
13\endverbatim
14
15\section dump2dcm_description DESCRIPTION
16
17The \b dump2dcm utility converts an ASCII dump file to a DICOM file.  The
18dump file has the same format as the output of \b dcmdump.  Thus it is possible
19to capture the output of \b dcmdump into a file, modify some attributes and
20create a new DICOM file.
21
22\section dump2dcm_parameters PARAMETERS
23
24\verbatim
25dumpfile-in  dump input filename
26
27dcmfile-out  DICOM output filename
28\endverbatim
29
30\section dump2dcm_options OPTIONS
31
32\subsection dump2dcm_general_options general options
33\verbatim
34  -h   --help
35         print this help text and exit
36
37       --version
38         print version information and exit
39
40       --arguments
41         print expanded command line arguments
42
43  -q   --quiet
44         quiet mode, print no warnings and errors
45
46  -v   --verbose
47         verbose mode, print processing details
48
49  -d   --debug
50         debug mode, print debug information
51
52  -ll  --log-level  [l]evel: string constant
53         (fatal, error, warn, info, debug, trace)
54         use level l for the logger
55
56  -lc  --log-config  [f]ilename: string
57         use config file f for the logger
58\endverbatim
59
60\subsection dump2dcm_input_options input options
61\verbatim
62input file format:
63
64  +f   --read-meta-info
65         read meta information if present (default)
66
67  -f   --ignore-meta-info
68         ignore file meta information
69
70file contents byte ordering:
71
72  +rl  --read-file-little
73         read OW data with little endian (default)
74
75  +rb  --read-file-big
76         read OW data from file with big endian
77
78other input options:
79
80  +l   --line  [m]ax-length: integer
81         maximum line length m (default: 4096)
82\endverbatim
83
84\subsection dump2dcm_processing_options processing options
85\verbatim
86unique identifiers:
87
88  +Ug  --generate-new-uids
89         generate new Study/Series/SOP Instance UID
90
91  -Uo  --dont-overwrite-uids
92         do not overwrite existing UIDs (default)
93
94  +Uo  --overwrite-uids
95         overwrite existing UIDs
96\endverbatim
97
98\subsection dump2dcm_output_options output options
99\verbatim
100output file format:
101
102  +F   --write-file
103         write file format (default)
104
105  -F   --write-dataset
106         write data set without file meta information
107
108  +Fu  --update-meta-info
109         update particular file meta information
110
111output transfer syntax:
112
113  +t=  --write-xfer-same
114         write with same TS as input (default)
115
116  +te  --write-xfer-little
117         write with explicit VR little endian
118
119  +tb  --write-xfer-big
120         write with explicit VR big endian TS
121
122  +ti  --write-xfer-implicit
123         write with implicit VR little endian TS
124
125  +td  --write-xfer-deflated
126         write with deflated explicit VR little endian TS
127
128error handling:
129
130  -E   --stop-on-error
131         do not write if dump is damaged (default)
132
133  +E   --ignore-errors
134         attempt to write even if dump is damaged
135
136post-1993 value representations:
137
138  +u   --enable-new-vr
139         enable support for new VRs (UN/UT) (default)
140
141  -u   --disable-new-vr
142         disable support for new VRs, convert to OB
143
144group length encoding:
145
146  +g=  --group-length-recalc
147         recalculate group lengths if present (default)
148
149  +g   --group-length-create
150         always write with group length elements
151
152  -g   --group-length-remove
153         always write without group length elements
154
155length encoding in sequences and items:
156
157  +e   --length-explicit
158         write with explicit lengths (default)
159
160  -e   --length-undefined
161         write with undefined lengths
162
163data set trailing padding (not with --write-dataset):
164
165  -p=  --padding-retain
166         do not change padding (default if not --write-dataset)
167
168  -p   --padding-off
169         no padding (implicit if --write-dataset)
170
171  +p   --padding-create  [f]ile-pad [i]tem-pad: integer
172         align file on multiple of f bytes
173         and items on multiple of i bytes
174
175deflate compression level (only with --write-xfer-deflated):
176
177  +cl  --compression-level  [l]evel: integer (default: 6)
178         0=uncompressed, 1=fastest, 9=best compression
179\endverbatim
180
181\section dump2dcm_notes NOTES
182
183\subsection dump2dcm_notes_description Dump File Description
184
185The input file can be an output of \b dcmdump (default indented format only).
186One element (tag, VR, value) must be written into one line separated by
187arbitrary spaces or tab characters.  A '#' begins a comment that ends at the
188line end.  Empty lines are allowed.
189
190The individual parts of a line have the following syntax:
191
192\verbatim
193Tag:   (gggg,eeee)
194       with gggg and eeee are 4 character hexadecimal values
195       representing group and element tag.  Spaces and tabs can be
196       anywhere in a tag specification.
197VR:    Value Representation must be written as 2 characters as in
198       Part 6 of the DICOM standard.  No spaces or tabs are allowed
199       between the two characters.  If the VR can be determined from
200       the tag, this part of a line is optional.
201Value: There are several rules for writing values:
202       1. US, SS, UL, SL, UV, SV, FD, FL, OD, OF, OL and OV are written
203          as decimal strings that can be read by scanf().
204       2. AT is written as '(gggg,eeee)' with additional spaces
205          stripped off automatically and gggg and eeee being decimal
206          strings that can be read by scanf().
207       3. OB and OW values are written as byte or word hexadecimal
208          values separated by '\' character.  Alternatively, OB or OW
209          values can be read from a separate file by writing the
210          filename prefixed by a '=' character (e.g. '=largepix.dat').
211          The contents of the file will be read as is.  By default, OW
212          data is expected to be little endian ordered and will be
213          swapped if necessary.  No checks will be made to ensure that
214          the amount of data is reasonable in terms of other attributes
215          such as Rows or Columns.
216          In case of compressed pixel data, the line should start with
217          '(7fe0,0010) OB (PixelSequence' in order to distinguish from
218          uncompressed pixel data.
219       4. UI is written as '=Name' in data dictionary or as unique
220          identifier string (see 6.), e.g. '[1.2.840.....]'.
221       5. Strings without () <> [] spaces, tabs and # can be written
222          directly.
223       6. Other strings must be surrounded by '[' and ']'.  No bracket
224          structure is passed.  The value ends at the last ']' in the
225          line.  Anything after the ']' is interpreted as comment.
226       7. '(' and '<' are interpreted special and may not be used when
227          writing an input file by hand as beginning characters of a
228          string.  Multiple Value are separated by '\'.  The lines
229          need not be sorted into ascending tag order.  References in
230          DICOM Directories are not supported.  Semantic errors are
231          not detected.
232\endverbatim
233
234\subsection dump2dcm_notes_examples Examples
235
236The following lines show valid examples of the syntax described above:
237
238\verbatim
239 (0008,0020) DA [19921012]            #  8, 1 StudyDate
240 (0008,0016) UI =MRImageStorage       # 26, 1 SOPClassUID
241 (0002,0012) UI [1.2.276.0.7230010.100.1.1]
242 (0020,0032) DS [0.0\0.0]             #  8, 2 ImagePositionPatient
243 (0028,0009) AT (3004,000c)           #  4, 1 FrameIncrementPointer
244 (0028,0010) US 256                   #  4, 1 Rows
245 (0002,0001) OB 01\00
246\endverbatim
247
248\subsection dump2dcm_limitations Limitations
249
250Please note that \b dump2dcm currently does not fully support DICOMDIR files.
251Specifically, the value of the various offset data elements is not updated
252automatically by this tool.
253
254\section dump2dcm_logging LOGGING
255
256The level of logging output of the various command line tools and underlying
257libraries can be specified by the user.  By default, only errors and warnings
258are written to the standard error stream.  Using option \e --verbose also
259informational messages like processing details are reported.  Option
260\e --debug can be used to get more details on the internal activity, e.g. for
261debugging purposes.  Other logging levels can be selected using option
262\e --log-level.  In \e --quiet mode only fatal errors are reported.  In such
263very severe error events, the application will usually terminate.  For more
264details on the different logging levels, see documentation of module "oflog".
265
266In case the logging output should be written to file (optionally with logfile
267rotation), to syslog (Unix) or the event log (Windows) option \e --log-config
268can be used.  This configuration file also allows for directing only certain
269messages to a particular output stream and for filtering certain messages
270based on the module or application where they are generated.  An example
271configuration file is provided in <em>\<etcdir\>/logger.cfg</em>.
272
273\section dump2dcm_command_line COMMAND LINE
274
275All command line tools use the following notation for parameters: square
276brackets enclose optional values (0-1), three trailing dots indicate that
277multiple values are allowed (1-n), a combination of both means 0 to n values.
278
279Command line options are distinguished from parameters by a leading '+' or '-'
280sign, respectively.  Usually, order and position of command line options are
281arbitrary (i.e. they can appear anywhere).  However, if options are mutually
282exclusive the rightmost appearance is used.  This behavior conforms to the
283standard evaluation rules of common Unix shells.
284
285In addition, one or more command files can be specified using an '@' sign as a
286prefix to the filename (e.g. <em>\@command.txt</em>).  Such a command argument
287is replaced by the content of the corresponding text file (multiple
288whitespaces are treated as a single separator unless they appear between two
289quotation marks) prior to any further evaluation.  Please note that a command
290file cannot contain another command file.  This simple but effective approach
291allows one to summarize common combinations of options/parameters and avoids
292longish and confusing command lines (an example is provided in file
293<em>\<datadir\>/dumppat.txt</em>).
294
295\section dump2dcm_environment ENVIRONMENT
296
297The \b dump2dcm utility will attempt to load DICOM data dictionaries specified
298in the \e DCMDICTPATH environment variable.  By default, i.e. if the
299\e DCMDICTPATH environment variable is not set, the file
300<em>\<datadir\>/dicom.dic</em> will be loaded unless the dictionary is built
301into the application (default for Windows).
302
303The default behavior should be preferred and the \e DCMDICTPATH environment
304variable only used when alternative data dictionaries are required.  The
305\e DCMDICTPATH environment variable has the same format as the Unix shell
306\e PATH variable in that a colon (":") separates entries.  On Windows systems,
307a semicolon (";") is used as a separator.  The data dictionary code will
308attempt to load each file specified in the \e DCMDICTPATH environment variable.
309It is an error if no data dictionary can be loaded.
310
311\section dump2dcm_see_also SEE ALSO
312
313<b>dcmdump</b>(1)
314
315\section dump2dcm_copyright COPYRIGHT
316
317Copyright (C) 1996-2020 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.
318
319*/
320