1dcmodify(1) OFFIS DCMTK dcmodify(1)
2
6 dcmodify - Modify DICOM files
7
9 dcmodify [options] dcmfile-in...
10
12 dcmodify is a tool that allows to modify, insert and delete tags and
13 items in DICOM files. Sequences and tags with a value multiplicity > 1
14 are also supported. Metaheader information and the tag's VR can not be
15 modified directly by dcmodify at this time. In addition to tag
16 modifications, dcmodify makes available some input options - forcing
17 dcmodify to handle its input files as the user specifies - and output
18 options to control the output format of the resulting files.
19 In case multiple modifications have to be performed, dcmodify does the
21 modifications in the same order as they appear on the command line.
22 Please note that dcmodify does not check whether a given value matches
23 its value representation (VR). Usually, an error message is printed but
24 generally the user should take care of the right VR usage.
25 If dcmodify doesn't know the tag it should insert, then the tag's VR is
27 set to UN and the value provided on commandline is interpreted as being
28 a series of hexadecimal numbers (like they are provided for VR=OB).
29 Please insert these tags into the dictionary to avoid this behaviour.
30 Also, specifying the -iun option, it is possible to force dcmodify to
31 leave UN values untouched. Using option -u lets dcmodify saving all
32 VR=UN attributes as OB.
33 dcmodify is able to work with so-called tag paths to access tags in
35 sequences. The (pseudo-formalized) syntax is
36 {sequence[item-no].}*element
38 where 'sequence' is a sequence tag like (0008,1111) or a dictionary
40 name for a tag. 'item-no' describes the item number to be accessed
41 (counting from zero). 'element' defines the target tag to work on. A
42 tag can either be specified directly as (0010,0010) or through the
43 corresponding dictionary name 'PatientName'. The '*' denotes that you
44 can repeat sequence statements to access deeper levels in DICOM files
45 (see EXAMPLES section). For 'item-no', also a wildcard character '*'
46 can be used selecting all items in surrounding sequence (see section
47 WILDCARDS below).
48 When inserting tag paths consisting of multiple nodes (i.e. not a
50 single element) using the -i option, any missing path elements (items,
51 sequences, leaf elements) are inserted automatically when missing. That
52 does not work for item wildcards: When no single item exists in the
53 surrounding sequence dcmodify of course can't decide, how many items
54 should be generated. However, if specifying an item number like '5',
55 all 6 items (counted from zero) can be (and are) automatically
56 generated in insert mode. If already 2 items would exist, the rest (4)
57 would be inserted.
58 Please note that there are some issues concerning the modification of
60 private tags (see PRIVATE TAGS section) and for changing UIDs (CHANGING
61 UIDs section).
62
64 dcmfile-in DICOM input filename(s) to be modified
65
67 general options
68 -h --help
69 print this help text and exit
70 --version
72 print version information and exit
73 --arguments
75 print expanded command line arguments
76 -q --quiet
78 quiet mode, print no warnings and errors
79 -v --verbose
81 verbose mode, print processing details
82 -d --debug
84 debug mode, print debug information
85 -ll --log-level [l]evel: string constant
87 (fatal, error, warn, info, debug, trace)
88 use level l for the logger
89 -lc --log-config [f]ilename: string
91 use config file f for the logger
92 -ie --ignore-errors
94 continue with file, if modify error occurs
95 -nb --no-backup
97 don't backup files (DANGEROUS)
98 input options
100 input file format:
101 +f --read-file
103 read file format or data set (default)
104 +fo --read-file-only
106 read file format only
107 -f --read-dataset
109 read data set without file meta information
110 input transfer syntax:
112 -t= --read-xfer-auto
114 use TS recognition (default)
115 -td --read-xfer-detect
117 ignore TS specified in the file meta header
118 -te --read-xfer-little
120 read with explicit VR little endian TS
121 -tb --read-xfer-big
123 read with explicit VR big endian TS
124 -ti --read-xfer-implicit
126 read with implicit VR little endian TS
127 parsing of odd-length attributes:
129 +ao --accept-odd-length
131 accept odd length attributes (default)
132 +ae --assume-even-length
134 assume real length is one byte larger
135 automatic data correction:
137 +dc --enable-correction
139 enable automatic data correction (default)
140 -dc --disable-correction
142 disable automatic data correction
143 bitstream format of deflated input:
145 +bd --bitstream-deflated
147 expect deflated bitstream (default)
148 +bz --bitstream-zlib
150 expect deflated zlib bitstream
151 processing options
153 insert mode:
154 -i --insert "[t]ag-path=[v]alue"
156 insert (or overwrite) path at position t with value v
157 -if --insert-from-file "[t]ag-path=[f]ilename"
159 insert (or overwrite) path at position t with value from file f
160 -nrc --no-reserv-check
162 do not check private reservations
163 modify mode:
165 -m --modify "[t]ag-path=[v]alue"
167 modify tag at position t to value v
168 -mf --modify-from-file "[t]ag-path=[f]ilename"
170 modify tag at position t to value from file f
171 -ma --modify-all "[t]ag=[v]alue"
173 modify ALL matching tags t in file to value v
174 erase mode:
176 -e --erase "[t]ag-path"
178 erase tag/item at position t
179 -ea --erase-all "[t]ag"
181 erase ALL matching tags t in file
182 -ep --erase-private
184 erase ALL private data from file
185 unique identifier:
187 -gst --gen-stud-uid
189 generate new Study Instance UID
190 -gse --gen-ser-uid
192 generate new Series Instance UID
193 -gin --gen-inst-uid
195 generate new SOP Instance UID
196 -nmu --no-meta-uid
198 do not update metaheader UIDs if related
199 UIDs in the dataset are modified
200 other processing options:
202 -imt --ignore-missing-tags
204 treat 'tag not found' as success
205 when modifying or erasing in files
206 -iun --ignore-un-values
208 do not try writing any values to
209 elements having VR of UN
210 output options
212 output file format:
213 +F --write-file
215 write file format (default)
216 -F --write-dataset
218 write data set without file meta information
219 output transfer syntax:
221 +t= --write-xfer-same
223 write with same TS as input (default)
224 +te --write-xfer-little
226 write with explicit VR little endian TS
227 +tb --write-xfer-big
229 write with explicit VR big endian TS
230 +ti --write-xfer-implicit
232 write with implicit VR little endian TS
233 post-1993 value representations:
235 +u --enable-new-vr
237 enable support for new VRs (UN/UT) (default)
238 -u --disable-new-vr
240 disable support for new VRs, convert to OB
241 group length encoding:
243 +g= --group-length-recalc
245 recalculate group lengths if present (default)
246 +g --group-length-create
248 always write with group length elements
249 -g --group-length-remove
251 always write without group length elements
252 length encoding in sequences and items:
254 +le --length-explicit
256 write with explicit lengths (default)
257 -le --length-undefined
259 write with undefined lengths
260 data set trailing padding (not with --write-dataset):
262 -p= --padding-retain
264 do not change padding (default if not --write-dataset)
265 -p --padding-off
267 no padding (implicit if --write-dataset)
268 +p --padding-create [f]ile-pad [i]tem-pad: integer
270 align file on multiple of f bytes and items on
271 multiple of i bytes
272
274 There are some issues you have to consider when working with private
275 tags. However, the insertion or modification of a reservation tag
276 (gggg,00xx) should always work.
277 Insertions
279 If you wish to insert a private tag (not a reservation with gggg,00xx),
280 be sure, that you've listed it in your dictionary (see
281 <docdir>/datadict.txt for details). If it's not listed, dcmodify will
282 insert it with VR=UN. Also, for some cases insertion may even fail for
283 some values.
284 If you've got your private tag in the dictionary, dcmodify acts as
286 follows: When it finds a reservation in the tag's enclosing dataset,
287 whose private creator matches, insertion is done with the VR found in
288 the dictionary and the value given on command line. But if the private
289 creator doesn't match or none is set, dcmodify will return with an
290 error. If a private tag should be inserted regardless whether a
291 reservation does not exist, the option -nrc can be used, forcing an
292 insertion. However, the VR is set to UN then, because the tag then
293 cannot be found in the dictionary.
294 See description above how inserting values into elements with unknown
296 VR are handled.
297 Modifications
299 If you modify a private tags value, dcmodify won't check its VR against
300 the dictionary. So please be careful to enter only values that match
301 the tag's VR.
302 If you wish to change a private tags value and VR, because you just
304 added this tag to your dictionary, you can delete it with dcmodify and
305 re-insert it. Then dcmodify uses your dicitionary entry to determine
306 the right VR (also see subsection insertions).
307 Also, see description above how inserting values into elements with
309 unknown VR are handled.
310 Deletions
312 When you use dcmodify to delete a private reservation tag, please note
313 that dcmodify won't touch the private tags that are under this
314 reservation. The user is forced to handle the consistency between
315 reservations and their pending private tags.
316 For the deletion of private non-reservation tags there are no special
318 issues.
319
321 dcmodify will automatically correct 'Media Storage SOP Class UID' and
322 'Media Storage SOP Instance UID' in the metaheader, if you make changes
323 to the related tags in the dataset ('SOP Class UID' and 'SOP Instance
324 UID') via insert or modify mode options. You can disable this behaviour
325 by using the -nmu option.
326 If you generate new UID's with -gst, -gse or -gin, this will only
328 affect the UID you choosed to generate. So if you use -gst to generate
329 a new 'Study Instance UID', then 'Series Instance UID' and 'SOP
330 Instance UID' will not be affected! This gives you the possibility to
331 generate each value separately. Normally, you would also modify the
332 'underlying' UIDs. As a disadvantage of this flexibility, the user has
333 to assure, that when creating 'new' DICOM files with new UIDs with
334 dcmodify, other UIDs have to be updated by the user as necessary.
335 When choosing the -gin option, the related metaheader tag ('Media
337 Storage SOP Instance UID') is updated automatically. This behaviour
338 cannot be disabled.
339
341 In order to read the element value from a file instead of specifying it
342 on the command line, option -mf and -if can be used. Please note that
343 for OW elements, the data is expected to be little endian ordered and
344 will be swapped if necessary. The file size should always be an even
345 number of bytes, i.e. no automatic padding is performed.
346
348 dcmodify also permits the usage of a wildcard character '*' for item
349 numbers in path expressions, e.g. 'ContentSequence[*].CodeValue'
350 selects all 'Code Value' attributes in all items of the
351 ContentSequence. Using a wildcard is possible for all basic operations,
352 i.e. modifying -m, inserting -i and -e options which makes it, together
353 with the automatic creation of intermediate path nodes a powerful tool
354 for construction and processing complex datasets.
355 The options -ma and -ea for modifying or deleting all occurences of a
357 DICOM element based on its tag do not accept any wildcards but only
358 work on single elements (i.e. a single dictionary name or tag key).
359
361 -i --insert:
362 dcmodify -i "(0010,0010)=A Name" file.dcm
363 Inserts the PatientName tag into 'file.dcm' at 1st level.
364 If tag already exists, -i will overwrite it! If you want to
365 insert an element with value multiplicity > 1 (e.g. 4) you
366 can do this with: dcmodify -i "(0018,1310)=1\2\3\4"
367 dcmodify -i "(0008,1111)[0].PatientName=Another Name" *.dcm
369 Inserts PatientName tag into the first item of sequence
370 (0008,1111). Note that the use of wildcards for files is
371 possible. You can specify longer tag paths, too (e.g.
372 "(0008,1111)[0].(0008,1111)[1].(0010,0010)=A Third One").
373 If any part of the path, e.g. the sequence or the item "0"
374 does not exist, it is automatically inserted by dcmodify.
375 dcmodify -i "(0008,1111)[*].PatientName=Another Name" *.dcm
377 Inserts PatientName tag into _every_ item of sequence
378 (0008,1111). Note that the use of wildcards for files is
379 possible. You can specify longer tag paths, too (e.g.
380 "(0008,1111)[*].(0008,1111)[*].(0010,0010)=A Third One").
381 -if --insert-from-file:
383 dcmodify -if "PixelData=pixel.raw" file.dcm
384 Inserts the content of file 'pixel.raw' into the PixelData element
385 of 'file.dcm'. The contents of the file will be read as is.
386 OW data is expected to be little endian ordered and will be
387 swapped if necessary. No checks will be made to ensure that the
388 amount of data is reasonable in terms of other attributes such as
389 Rows or Columns.
390 -m --modify:
392 dcmodify -m "(0010,0010)=A Name" file.dcm
393 Changes tag (0010,0010) on 1st level to "A Name".
394 This option also permits longer tag paths as demonstrated
396 above for -i. If the leaf element or any intermediate
397 part of the path does not exist, it is not inserted as it
398 would be if using the '-i' option.
399 dcmodify -m "(0010,0010)=A Name" -imt file.dcm
401 Changes tag (0010,0010) on 1st level to "A Name". Due to the
402 given option '-imt', success is returned instead of "tag not found",
403 if the element/item (or any intermediate node in a longer path) does
404 not exist.
405 Note that for the '-m' option the last node in the path must be
407 a leaf element, i.e. not a sequence or an item.
408 -mf --modify-from-file:
410 dcmodify -mf "PixelData=pixel.raw" file.dcm
411 Does the same as -if in case there was already a PixelData element
412 in 'file.dcm'. Otherwise nothing is changed.
413 -ma --modify-all:
415 dcmodify -ma "(0010,0010)=New Name" file.dcm
416 Does the same as -m but works on all matching tags found in
417 'file.dcm'. Therefore, it searches the whole dataset including
418 sequences for tag (0010,0010) and changes them to "New Name"
419 -e --erase:
421 dcmodify -e "(0010,0010)" *.dcm
422 Erases tag (0010,0010) in all *.dcm files at 1st level.
423 This option also allows longer tag paths as demonstrated
425 above for -i.
426 dcmodify -e "(0010,0010)" -imt *.dcm
428 Erases tag (0010,0010) in all *.dcm files at 1st level. Due to the
429 given option '-imt', success is returned instead of "tag not found",
430 if the element/item (or any intermediate node in a longer path) does
431 not exist.
432 -ea --erase-all:
434 dcmodify -ea "(0010,0010)" *.dcm
435 Same as -e, but also searches in sequences and items.
436 -ep --erase-private:
438 dcmodify -ep *.dcm
439 Deletes all private tags (i.e. tags having an odd group number) from
440 all files matching *.dcm in the current directory.
441 -gst --gen-stud-uid:
443 dcmodify -gst file.dcm
444 This generates a new value for the StudyInstanceUID
445 (0020,000d). Other UIDs are not modified!
446 -gse --gen-ser-uid:
448 dcmodify -gse file.dcm
449 This generates a new value for the SeriesInstanceUID
450 (0020,000e). Other UIDs are not modified!
451 -gin --gen-inst-uid:
453 dcmodify -gin file.dcm
454 This command generates a new value for the SOPInstanceUID
455 (0008,0018). The corresponding MediaStorageSOPInstanceUID
456 (0002,0003) is adjusted to the new value automatically.
457 Please note that it's not possible to avoid this metaheader
458 update via the -nmu option.
459 -nmu --no-meta-uid:
461 dcmodify -m "SOPInstanceUID=[UID]" -nmu *.dcm
462 This will modify the SOPInstanceUID to the given [UID],
463 but -nmu avoids, that dcmodify adjusts the
464 MediaStorageSOPInstanceUID in the metaheader, too.
465
467 dcmodify tries executing each modify operation given on command line:
468 If one returns an error, the others are being performed anyway. However
469 in case of any error, the modified file is not saved, unless the
470 --ignore-errors option is specified. If that option is selected,
471 dcmodify also continues modifying further files specified on
472 commandline; otherwise dcmodify exits after the first file that had
473 modification errors.
474 If the --ignore-missing-tags option is enabled, any modify or erase
476 operations (i.e. not --insert) that fails because of a non-existing tag
477 is treated as being successful. That does make sense if someone wants
478 to be sure that specific tags are not present in the file or that - if
479 they exist - that they are set to a specific value.
480
482 The level of logging output of the various command line tools and
483 underlying libraries can be specified by the user. By default, only
484 errors and warnings are written to the standard error stream. Using
485 option --verbose also informational messages like processing details
486 are reported. Option --debug can be used to get more details on the
487 internal activity, e.g. for debugging purposes. Other logging levels
488 can be selected using option --log-level. In --quiet mode only fatal
489 errors are reported. In such very severe error events, the application
490 will usually terminate. For more details on the different logging
491 levels, see documentation of module 'oflog'.
492 In case the logging output should be written to file (optionally with
494 logfile rotation), to syslog (Unix) or the event log (Windows) option
495 --log-config can be used. This configuration file also allows for
496 directing only certain messages to a particular output stream and for
497 filtering certain messages based on the module or application where
498 they are generated. An example configuration file is provided in
499 <etcdir>/logger.cfg).
500
502 All command line tools use the following notation for parameters:
503 square brackets enclose optional values (0-1), three trailing dots
504 indicate that multiple values are allowed (1-n), a combination of both
505 means 0 to n values.
506 Command line options are distinguished from parameters by a leading '+'
508 or '-' sign, respectively. Usually, order and position of command line
509 options are arbitrary (i.e. they can appear anywhere). However, if
510 options are mutually exclusive the rightmost appearance is used. This
511 behaviour conforms to the standard evaluation rules of common Unix
512 shells.
513 In addition, one or more command files can be specified using an '@'
515 sign as a prefix to the filename (e.g. @command.txt). Such a command
516 argument is replaced by the content of the corresponding text file
517 (multiple whitespaces are treated as a single separator unless they
518 appear between two quotation marks) prior to any further evaluation.
519 Please note that a command file cannot contain another command file.
520 This simple but effective approach allows to summarize common
521 combinations of options/parameters and avoids longish and confusing
522 command lines (an example is provided in file <datadir>/dumppat.txt).
523
525 The dcmodify utility will attempt to load DICOM data dictionaries
526 specified in the DCMDICTPATH environment variable. By default, i.e. if
527 the DCMDICTPATH environment variable is not set, the file
528 <datadir>/dicom.dic will be loaded unless the dictionary is built into
529 the application (default for Windows).
530 The default behaviour should be preferred and the DCMDICTPATH
532 environment variable only used when alternative data dictionaries are
533 required. The DCMDICTPATH environment variable has the same format as
534 the Unix shell PATH variable in that a colon (':') separates entries.
535 On Windows systems, a semicolon (';') is used as a separator. The data
536 dictionary code will attempt to load each file specified in the
537 DCMDICTPATH environment variable. It is an error if no data dictionary
538 can be loaded.
539
541 Copyright (C) 2003-2010 by OFFIS e.V., Escherweg 2, 26121 Oldenburg,
542 Germany.
543Version 3.6.0 6 Jan 2011 dcmodify(1)