1/*!
2
3\if MANPAGES
4\page dcmgpdir Create a general purpose DICOMDIR
5\else
6\page dcmgpdir dcmgpdir: Create a general purpose DICOMDIR
7\endif
8
9\section dcmgpdir_synopsis SYNOPSIS
10
11\verbatim
12dcmgpdir [options] [dcmfile-in...]
13\endverbatim
14
15\section dcmgpdir_description DESCRIPTION
16
17The \b dcmgpdir utility creates a \e DICOMDIR file from the specified
18referenced DICOM files according to the DICOM Part 11 Media Storage
19Application Profiles.
20
21Currently, the following profiles are supported:
22
23\li General Purpose CD-R Interchange (STD-GEN-CD)
24\li General Purpose Interchange on DVD-RAM Media (STD-GEN-DVD-RAM)
25
26\b dcmmkdir is an extended version of this tool which also supports other
27Media Storage Application Profiles than the general purpose one (e.g. the
28cardio profiles require the use of icon images).
29
30\section dcmgpdir_parameters PARAMETERS
31
32\verbatim
33dcmfile-in  referenced DICOM file (or directory to be scanned)
34\endverbatim
35
36\section dcmgpdir_options OPTIONS
37
38\subsection dcmgpdir_general_options general options
39\verbatim
40  -h    --help
41          print this help text and exit
42
43        --version
44          print version information and exit
45
46        --arguments
47          print expanded command line arguments
48
49  -q    --quiet
50          quiet mode, print no warnings and errors
51
52  -v    --verbose
53          verbose mode, print processing details
54
55  -d    --debug
56          debug mode, print debug information
57
58  -ll   --log-level  [l]evel: string constant
59          (fatal, error, warn, info, debug, trace)
60          use level l for the logger
61
62  -lc   --log-config  [f]ilename: string
63          use config file f for the logger
64\endverbatim
65
66\subsection dcmgpdir_input_options input options
67\verbatim
68DICOMDIR identifiers:
69
70  +F    --fileset-id  [i]d: string
71          use specific file-set ID
72          (default: DCMTK_MEDIA_DEMO, "" for none)
73
74  +R    --descriptor  [f]ilename: string
75          add a file-set descriptor file ID
76          (e.g. README, default: no descriptor)
77
78  +C    --char-set  [c]harset: string
79          add a specific character set for descriptor
80          (default: "ISO_IR 100" if descriptor present)
81
82reading:
83
84  +id   --input-directory  [d]irectory: string
85          read referenced DICOM files from directory d
86          (default for --recurse: current directory)
87
88  -m    --keep-filenames
89          expect filenames to be in DICOM format (default)
90
91  +m    --map-filenames
92          map to DICOM filenames (lowercase->uppercase,
93          and remove trailing period)
94
95  -r    --no-recurse
96          do not recurse within directories (default)
97
98  +r    --recurse
99          recurse within filesystem directories
100
101  +p    --pattern  [p]attern: string (only with --recurse)
102          pattern for filename matching (wildcards)
103
104          # possibly not available on all systems
105\endverbatim
106
107\subsection dcmgpdir_processing_options processing options
108\verbatim
109consistency check:
110
111  -W    --no-consistency-check
112          do not check files for consistency
113
114  +W    --warn-inconsist-files
115          warn about inconsistent files (default)
116
117  -a    --abort-inconsist-file
118          abort on first inconsistent file
119
120type 1 attributes:
121
122  -I    --strict
123          exit with error if DICOMDIR type 1 attributes
124          are missing in DICOM file (default)
125
126  +I    --invent
127          invent DICOMDIR type 1 attributes if missing in DICOM file
128
129  +Ipi  --invent-patient-id
130          invent new PatientID in case of inconsistent
131          PatientName attributes
132
133other checks:
134
135  +Nrs  --allow-retired-sop
136          allow retired SOP classes defined in previous editions
137          of the DICOM standard
138
139  -Nxc  --no-xfer-check
140          do not reject images with non-standard transfer syntax
141          (just warn)
142\endverbatim
143
144\subsection dcmgpdir_output_options output options
145\verbatim
146DICOMDIR file:
147
148  +D    --output-file  [f]ilename: string
149          generate specific DICOMDIR file
150          (default: DICOMDIR in current directory)
151
152writing:
153
154  -A    --replace
155          replace existing DICOMDIR (default)
156
157  +A    --append
158          append to existing DICOMDIR
159
160  +U    --update
161          update existing DICOMDIR
162
163  -w    --discard
164          do not write out DICOMDIR
165
166backup:
167
168        --create-backup
169          create a backup of existing DICOMDIR (default)
170
171  -nb   --no-backup
172          do not create a backup of existing DICOMDIR
173
174post-1993 value representations:
175
176  +u    --enable-new-vr
177          enable support for new VRs (UN/UT) (default)
178
179  -u    --disable-new-vr
180          disable support for new VRs, convert to OB
181
182group length encoding:
183
184  -g    --group-length-remove
185          write without group length elements (default)
186
187  +g    --group-length-create
188          write with group length elements
189
190length encoding in sequences and items:
191
192  +e    --length-explicit
193          write with explicit lengths (default)
194
195  -e    --length-undefined
196          write with undefined lengths
197\endverbatim
198
199\section dcmgpdir_notes NOTES
200
201All files specified on the command line (or discovered by recursively examining
202the contents of directories with the \e +r option) are first evaluated for
203their compatibility with the General Purpose CD-R Image Interchange Profile
204(Supplement 19).  Only appropriate files encoded using the Explicit VR Little
205Endian Uncompressed Transfer Syntax will be accepted.  Files having invalid
206filenames will be rejected (the rules can be relaxed via the \e +m option).
207Files missing required attributes will be rejected (the \e +I option can relax
208this behavior).
209
210A \e DICOMDIR file will only be constructed if all files have passed initial
211tests.
212
213The \b dcmgpdir utility also allows one to append new entries to and to update
214existing entries in a \e DICOMDIR file.  Using option \e +A new entries are
215only appended to the DICOMDIR, i.e. existing records like the ones for PATIENT
216information are not updated.  Using option \e +U also existing records are
217updated according to the information found in the referenced DICOM files.
218Please note that this update process might be slower than just appending new
219entries.  However, it makes sure that additional information that is required
220for the selected application profile is also added to existing records.
221
222\subsection dcmgpdir_scanning_directories Scanning Directories
223
224Adding files from directories is possible by using option \e --recurse.  If no
225further command line parameters are given, the directory specified by option
226\e --input-directory (default: current directory) is scanned for files.  If
227parameters are given, they can either specify a file or directory name; the
228input directory is always prepended.  If the files in the provided directories
229should be selected according to a specific name pattern (e.g. using wildcard
230matching), option \e --pattern has to be used.  Please note that this file
231pattern only applies to the files within the scanned directories, and, if any
232other patterns are specified on the command line outside the
233\e --input-directory option (e.g. in order to select further files), these do
234not apply to the specified directories.
235
236\section dcmgpdir_logging LOGGING
237
238The level of logging output of the various command line tools and underlying
239libraries can be specified by the user.  By default, only errors and warnings
240are written to the standard error stream.  Using option \e --verbose also
241informational messages like processing details are reported.  Option
242\e --debug can be used to get more details on the internal activity, e.g. for
243debugging purposes.  Other logging levels can be selected using option
244\e --log-level.  In \e --quiet mode only fatal errors are reported.  In such
245very severe error events, the application will usually terminate.  For more
246details on the different logging levels, see documentation of module "oflog".
247
248In case the logging output should be written to file (optionally with logfile
249rotation), to syslog (Unix) or the event log (Windows) option \e --log-config
250can be used.  This configuration file also allows for directing only certain
251messages to a particular output stream and for filtering certain messages
252based on the module or application where they are generated.  An example
253configuration file is provided in <em>\<etcdir\>/logger.cfg</em>.
254
255\section dcmgpdir_command_line COMMAND LINE
256
257All command line tools use the following notation for parameters: square
258brackets enclose optional values (0-1), three trailing dots indicate that
259multiple values are allowed (1-n), a combination of both means 0 to n values.
260
261Command line options are distinguished from parameters by a leading '+' or '-'
262sign, respectively.  Usually, order and position of command line options are
263arbitrary (i.e. they can appear anywhere).  However, if options are mutually
264exclusive the rightmost appearance is used.  This behavior conforms to the
265standard evaluation rules of common Unix shells.
266
267In addition, one or more command files can be specified using an '@' sign as a
268prefix to the filename (e.g. <em>\@command.txt</em>).  Such a command argument
269is replaced by the content of the corresponding text file (multiple
270whitespaces are treated as a single separator unless they appear between two
271quotation marks) prior to any further evaluation.  Please note that a command
272file cannot contain another command file.  This simple but effective approach
273allows one to summarize common combinations of options/parameters and avoids
274longish and confusing command lines (an example is provided in file
275<em>\<datadir\>/dumppat.txt</em>).
276
277\section dcmgpdir_environment ENVIRONMENT
278
279The \b dcmgpdir utility will attempt to load DICOM data dictionaries specified
280in the \e DCMDICTPATH environment variable.  By default, i.e. if the
281\e DCMDICTPATH environment variable is not set, the file
282<em>\<datadir\>/dicom.dic</em> will be loaded unless the dictionary is built
283into the application (default for Windows).
284
285The default behavior should be preferred and the \e DCMDICTPATH environment
286variable only used when alternative data dictionaries are required.  The
287\e DCMDICTPATH environment variable has the same format as the Unix shell
288\e PATH variable in that a colon (":") separates entries.  On Windows systems,
289a semicolon (";") is used as a separator.  The data dictionary code will
290attempt to load each file specified in the \e DCMDICTPATH environment variable.
291It is an error if no data dictionary can be loaded.
292
293\section dcmgpdir_see_also SEE ALSO
294
295<b>dcmmkdir</b>(1)
296
297\section dcmgpdir_copyright COPYRIGHT
298
299Copyright (C) 1996-2016 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.
300
301*/
302