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