4 \page dcmgpdir Create a general purpose DICOMDIR
6 \page dcmgpdir dcmgpdir: Create a general purpose DICOMDIR
9 \section synopsis SYNOPSIS
12 dcmgpdir [options] [dcmfile-in...]
15 \section description DESCRIPTION
17 The \b dcmgpdir utility creates a \e DICOMDIR file from the specified
18 referenced DICOM files according to the DICOM Part 11 Media Storage
21 Currently, the following profiles are supported:
23 \li General Purpose CD-R Interchange (STD-GEN-CD)
24 \li General Purpose Interchange on DVD-RAM Media (STD-GEN-DVD-RAM)
26 \b dcmmkdir is an extended version of this tool which also supports other
27 Media Storage Application Profiles than the general purpose one (e.g. both
28 cardio profiles requiring the use of icon images).
30 \section parameters PARAMETERS
33 dcmfile-in referenced DICOM file
36 \section options OPTIONS
38 \subsection general_options general options
41 print this help text and exit
44 print version information and exit
47 print expanded command line arguments
50 quiet mode, print no warnings and errors
53 verbose mode, print processing details
56 debug mode, print debug information
58 -ll --log-level [l]evel: string constant
59 (fatal, error, warn, info, debug, trace)
60 use level l for the logger
62 -lc --log-config [f]ilename: string
63 use config file f for the logger
66 \subsection input_options input options
70 +D --output-file [f]ilename: string
71 generate specific DICOMDIR file
72 (default: DICOMDIR in current directory)
74 +F --fileset-id [i]d: string (default: DCMTK_MEDIA_DEMO)
75 use specific file set ID
77 +R --descriptor [f]ilename: string
78 add a file set descriptor file ID
79 (e.g. README, default: no descriptor)
81 +C --char-set [c]harset: string
82 add a specific character set for descriptor
83 (default: "ISO_IR 100" if descriptor present)
87 +id --input-directory [d]irectory: string
88 read referenced DICOM files from directory d
89 (default for --recurse: current directory)
92 expect filenames to be in DICOM format (default)
95 map to DICOM filenames (lowercase->uppercase,
96 and remove trailing period)
99 do not recurse within directories (default)
102 recurse within filesystem directories
104 +p --pattern [p]attern: string (only with --recurse)
105 pattern for filename matching (wildcards)
107 # possibly not available on all systems
110 \subsection processing_options processing options
114 -W --no-consistency-check
115 do not check files for consistency
117 +W --warn-inconsist-files
118 warn about inconsistent files (default)
120 -a --abort-inconsist-file
121 abort on first inconsistent file
126 exit with error if DICOMDIR type 1 attributes
127 are missing in DICOM file (default)
130 invent DICOMDIR type 1 attributes if missing in DICOM file
132 +Ipi --invent-patient-id
133 invent new PatientID in case of inconsistent
134 PatientName attributes
138 +Nrs --allow-retired-sop
139 allow retired SOP classes defined in previous editions
140 of the DICOM standard
143 do not reject images with non-standard transfer syntax
147 \subsection output_options output options
152 replace existing DICOMDIR (default)
155 append to existing DICOMDIR
158 update existing DICOMDIR
161 do not write out DICOMDIR
164 do not create a backup of existing DICOMDIR
166 post-1993 value representations:
169 enable support for new VRs (UN/UT) (default)
172 disable support for new VRs, convert to OB
174 group length encoding:
176 -g --group-length-remove
177 write without group length elements (default)
179 +g --group-length-create
180 write with group length elements
182 length encoding in sequences and items:
185 write with explicit lengths (default)
187 -e --length-undefined
188 write with undefined lengths
193 All files specified on the command line (or discovered by recursivly examining
194 the contents of directories with the \e +r option) are first evaluated for
195 their compatibility with the General Purpose CD-R Image Interchange Profile
196 (Supplement 19). Only appropriate files encoded using the Explicit VR Little
197 Endian Uncompressed Transfer Syntax will be accepted. Files having invalid
198 filenames will be rejected (the rules can be relaxed via the \e +m option).
199 Files missing required attributes will be rejected (the \e +I option can relax
202 A \e DICOMDIR file will only be constructed if all files have passed initial
205 The \b dcmgpdir utility also allows to append new entries to and to update
206 existing entries in a \e DICOMDIR file. Using option \e +A new entries are
207 only appended to the DICOMDIR, i.e. existing records like the ones for PATIENT
208 information are not updated. Using option \e +U also existing records are
209 updated according to the information found in the referenced DICOM files.
210 Please note that this update process might be slower than just appending new
211 entries. However, it makes sure that additional information that is required
212 for the selected application profile is also added to existing records.
214 \section logging LOGGING
216 The level of logging output of the various command line tools and underlying
217 libraries can be specified by the user. By default, only errors and warnings
218 are written to the standard error stream. Using option \e --verbose also
219 informational messages like processing details are reported. Option
220 \e --debug can be used to get more details on the internal activity, e.g. for
221 debugging purposes. Other logging levels can be selected using option
222 \e --log-level. In \e --quiet mode only fatal errors are reported. In such
223 very severe error events, the application will usually terminate. For more
224 details on the different logging levels, see documentation of module "oflog".
226 In case the logging output should be written to file (optionally with logfile
227 rotation), to syslog (Unix) or the event log (Windows) option \e --log-config
228 can be used. This configuration file also allows for directing only certain
229 messages to a particular output stream and for filtering certain messages
230 based on the module or application where they are generated. An example
231 configuration file is provided in <em><etcdir>/logger.cfg</em>).
233 \section command_line COMMAND LINE
235 All command line tools use the following notation for parameters: square
236 brackets enclose optional values (0-1), three trailing dots indicate that
237 multiple values are allowed (1-n), a combination of both means 0 to n values.
239 Command line options are distinguished from parameters by a leading '+' or '-'
240 sign, respectively. Usually, order and position of command line options are
241 arbitrary (i.e. they can appear anywhere). However, if options are mutually
242 exclusive the rightmost appearance is used. This behaviour conforms to the
243 standard evaluation rules of common Unix shells.
245 In addition, one or more command files can be specified using an '@' sign as a
246 prefix to the filename (e.g. <em>\@command.txt</em>). Such a command argument
247 is replaced by the content of the corresponding text file (multiple
248 whitespaces are treated as a single separator unless they appear between two
249 quotation marks) prior to any further evaluation. Please note that a command
250 file cannot contain another command file. This simple but effective approach
251 allows to summarize common combinations of options/parameters and avoids
252 longish and confusing command lines (an example is provided in file
253 <em><datadir>/dumppat.txt</em>).
255 \section environment ENVIRONMENT
257 The \b dcmgpdir utility will attempt to load DICOM data dictionaries specified
258 in the \e DCMDICTPATH environment variable. By default, i.e. if the
259 \e DCMDICTPATH environment variable is not set, the file
260 <em><datadir>/dicom.dic</em> will be loaded unless the dictionary is built
261 into the application (default for Windows).
263 The default behaviour should be preferred and the \e DCMDICTPATH environment
264 variable only used when alternative data dictionaries are required. The
265 \e DCMDICTPATH environment variable has the same format as the Unix shell
266 \e PATH variable in that a colon (":") separates entries. On Windows systems,
267 a semicolon (";") is used as a separator. The data dictionary code will
268 attempt to load each file specified in the \e DCMDICTPATH environment variable.
269 It is an error if no data dictionary can be loaded.
271 \section see_also SEE ALSO
275 \section copyright COPYRIGHT
277 Copyright (C) 1996-2010 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.