1dcmodify(1) OFFIS DCMTK dcmodify(1)
2
6 dcmodify - Modify DICOM files
7
10 dcmodify [options] dcmfile-in...
11
13 dcmodify is a tool that allows one to modify, insert and delete tags
14 and items in DICOM files. Sequences and tags with a value multiplicity
15 > 1 are also supported. Metaheader information and the tag's VR can not
16 be modified directly by dcmodify at this time. In addition to tag
17 modifications, dcmodify makes available some input options - forcing
18 dcmodify to handle its input files as the user specifies - and output
19 options to control the output format of the resulting files.
20 In case multiple modifications have to be performed, dcmodify does the
22 modifications in the same order as they appear on the command line.
23 Please note that dcmodify does not check whether a given value matches
24 its value representation (VR). Usually, an error message is printed but
25 generally the user should take care of the right VR usage.
26 If dcmodify doesn't know the tag it should insert, then the tag's VR is
28 set to UN and the value provided on command line is interpreted as
29 being a series of hexadecimal numbers (like they are provided for
30 VR=OB). Please insert these tags into the dictionary to avoid this
31 behavior. Also, specifying the -iun option, it is possible to force
32 dcmodify to leave UN values untouched. Using option -u lets dcmodify
33 saving all VR=UN attributes as OB.
34 dcmodify is able to work with so-called tag paths to access tags in
36 sequences. The (pseudo-formalized) syntax is
37 {sequence[item-no].}*element
39 where 'sequence' is a sequence tag like (0008,1111) or a dictionary
41 name for a tag. 'item-no' describes the item number to be accessed
42 (counting from zero). 'element' defines the target tag to work on. A
43 tag can either be specified directly as (0010,0010) or through the
44 corresponding dictionary name 'PatientName'. The '*' denotes that you
45 can repeat sequence statements to access deeper levels in DICOM files
46 (see EXAMPLES section). For 'item-no', also a wildcard character '*'
47 can be used selecting all items in surrounding sequence (see section
48 WILDCARDS below).
49 When inserting tag paths consisting of multiple nodes (i.e. not a
51 single element) using the -i option, any missing path elements (items,
52 sequences, leaf elements) are inserted automatically when missing. That
53 does not work for item wildcards: When no single item exists in the
54 surrounding sequence dcmodify of course can't decide, how many items
55 should be generated. However, if specifying an item number like '5',
56 all 6 items (counted from zero) can be (and are) automatically
57 generated in insert mode. If already 2 items would exist, the rest (4)
58 would be inserted.
59 dcmodify does not work on directories, i.e. the parameter dcmfile-in...
61 must not include directory names.
62 Please note that there are some issues concerning the modification of
64 private tags (see PRIVATE TAGS section) and for changing UIDs (CHANGING
65 UIDs section).
66
68 dcmfile-in DICOM input filename(s) to be modified
69
71 general options
72 -h --help
73 print this help text and exit
74 --version
76 print version information and exit
77 --arguments
79 print expanded command line arguments
80 -q --quiet
82 quiet mode, print no warnings and errors
83 -v --verbose
85 verbose mode, print processing details
86 -d --debug
88 debug mode, print debug information
89 -ll --log-level [l]evel: string constant
91 (fatal, error, warn, info, debug, trace)
92 use level l for the logger
93 -lc --log-config [f]ilename: string
95 use config file f for the logger
96 input options
98 input file format:
99 +f --read-file
101 read file format or data set (default)
102 +fo --read-file-only
104 read file format only
105 -f --read-dataset
107 read data set without file meta information
108 +fc --create-file
110 create file format if file does not exist
111 input transfer syntax:
113 -t= --read-xfer-auto
115 use TS recognition (default)
116 -td --read-xfer-detect
118 ignore TS specified in the file meta header
119 -te --read-xfer-little
121 read with explicit VR little endian TS
122 -tb --read-xfer-big
124 read with explicit VR big endian TS
125 -ti --read-xfer-implicit
127 read with implicit VR little endian TS
128 parsing of odd-length attributes:
130 +ao --accept-odd-length
132 accept odd length attributes (default)
133 +ae --assume-even-length
135 assume real length is one byte larger
136 automatic data correction:
138 +dc --enable-correction
140 enable automatic data correction (default)
141 -dc --disable-correction
143 disable automatic data correction
144 bitstream format of deflated input:
146 +bd --bitstream-deflated
148 expect deflated bitstream (default)
149 +bz --bitstream-zlib
151 expect deflated zlib bitstream
152 processing options
154 backup input files:
155 --backup
157 backup files before modifying (default)
158 -nb --no-backup
160 don't backup files (DANGEROUS)
161 insert mode:
163 -i --insert "[t]ag-path=[v]alue"
165 insert (or overwrite) path at position t with value v
166 -if --insert-from-file "[t]ag-path=[f]ilename"
168 insert (or overwrite) path at position t with value from file f
169 -nrc --no-reserv-check
171 do not check private reservations
172 modify mode:
174 -m --modify "[t]ag-path=[v]alue"
176 modify tag at position t to value v
177 -mf --modify-from-file "[t]ag-path=[f]ilename"
179 modify tag at position t to value from file f
180 -ma --modify-all "[t]ag=[v]alue"
182 modify ALL matching tags t in file to value v
183 erase mode:
185 -e --erase "[t]ag-path"
187 erase tag/item at position t
188 -ea --erase-all "[t]ag"
190 erase ALL matching tags t in file
191 -ep --erase-private
193 erase ALL private data from file
194 unique identifier:
196 -gst --gen-stud-uid
198 generate new Study Instance UID
199 -gse --gen-ser-uid
201 generate new Series Instance UID
202 -gin --gen-inst-uid
204 generate new SOP Instance UID
205 -nmu --no-meta-uid
207 do not update metaheader UIDs if related
208 UIDs in the dataset are modified
209 error handling:
211 -ie --ignore-errors
213 continue with file, if modify error occurs
214 -imt --ignore-missing-tags
216 treat 'tag not found' as success
217 when modifying or erasing in files
218 -iun --ignore-un-values
220 do not try writing any values to elements
221 having a VR of UN
222 output options
224 output file format:
225 +F --write-file
227 write file format (default)
228 -F --write-dataset
230 write data set without file meta information
231 output transfer syntax:
233 +t= --write-xfer-same
235 write with same TS as input (default)
236 +te --write-xfer-little
238 write with explicit VR little endian TS
239 +tb --write-xfer-big
241 write with explicit VR big endian TS
242 +ti --write-xfer-implicit
244 write with implicit VR little endian TS
245 post-1993 value representations:
247 +u --enable-new-vr
249 enable support for new VRs (UN/UT) (default)
250 -u --disable-new-vr
252 disable support for new VRs, convert to OB
253 group length encoding:
255 +g= --group-length-recalc
257 recalculate group lengths if present (default)
258 +g --group-length-create
260 always write with group length elements
261 -g --group-length-remove
263 always write without group length elements
264 length encoding in sequences and items:
266 +le --length-explicit
268 write with explicit lengths (default)
269 -le --length-undefined
271 write with undefined lengths
272 data set trailing padding (not with --write-dataset):
274 -p= --padding-retain
276 do not change padding (default if not --write-dataset)
277 -p --padding-off
279 no padding (implicit if --write-dataset)
280 +p --padding-create [f]ile-pad [i]tem-pad: integer
282 align file on multiple of f bytes and items on
283 multiple of i bytes
284
286 There are some issues you have to consider when working with private
287 tags. However, the insertion or modification of a reservation tag
288 (gggg,00xx) should always work.
289 Insertions
291 If you wish to insert a private tag (not a reservation with gggg,00xx),
292 be sure, that you've listed it in your dictionary (see
293 <docdir>/datadict.txt for details). If it's not listed, dcmodify will
294 insert it with VR=UN. Also, for some cases insertion may even fail for
295 some values.
296 If you've got your private tag in the dictionary, dcmodify acts as
298 follows: When it finds a reservation in the tag's enclosing dataset,
299 whose private creator matches, insertion is done with the VR found in
300 the dictionary and the value given on command line. But if the private
301 creator doesn't match or none is set, dcmodify will return with an
302 error. If a private tag should be inserted regardless whether a
303 reservation does not exist, the option -nrc can be used, forcing an
304 insertion. However, the VR is set to UN then, because the tag then
305 cannot be found in the dictionary.
306 See description above how inserting values into elements with unknown
308 VR are handled.
309 Modifications
311 If you modify a private tags value, dcmodify won't check its VR against
312 the dictionary. So please be careful to enter only values that match
313 the tag's VR.
314 If you wish to change a private tags value and VR, because you just
316 added this tag to your dictionary, you can delete it with dcmodify and
317 re-insert it. Then dcmodify uses your dictionary entry to determine the
318 right VR (also see subsection insertions).
319 Also, see description above how inserting values into elements with
321 unknown VR are handled.
322 Deletions
324 When you use dcmodify to delete a private reservation tag, please note
325 that dcmodify won't touch the private tags that are under this
326 reservation. The user is forced to handle the consistency between
327 reservations and their associated private tags.
328 For the deletion of private non-reservation tags there are no special
330 issues.
331
333 dcmodify will automatically correct 'Media Storage SOP Class UID' and
334 'Media Storage SOP Instance UID' in the metaheader, if you make changes
335 to the related tags in the dataset ('SOP Class UID' and 'SOP Instance
336 UID') via insert or modify mode options. You can disable this behavior
337 by using the -nmu option.
338 If you generate new UID's with -gst, -gse or -gin, this will only
340 affect the UID you chose to generate. So if you use -gst to generate a
341 new 'Study Instance UID', then 'Series Instance UID' and 'SOP Instance
342 UID' will not be affected! This gives you the possibility to generate
343 each value separately. Normally, you would also modify the 'underlying'
344 UIDs. As a disadvantage of this flexibility, the user has to assure,
345 that when creating 'new' DICOM files with new UIDs with dcmodify, other
346 UIDs have to be updated by the user as necessary.
347 When choosing the -gin option, the related metaheader tag ('Media
349 Storage SOP Instance UID') is updated automatically. This behavior
350 cannot be disabled.
351 When working on multiple input files, dcmodify processes each file in
353 isolated fashion, i.e. it will generate UIDs for each single file. For
354 example, when using the -gst option, dcmodify will insert a different
355 Study Instance UID into each file instead of generating a single one
356 and writing it to each file that is being processed.
357
359 Option --create-file lets dcmodify create a file if it does not already
360 exist on disk. This can be used in order to create files from scratch
361 by performing consecutive insertions with options like --insert. This
362 might especially become handy when creating query files for tools like
363 findscu or movescu. In case no specific output transfer syntax is
364 defined, dcmodify chooses Little Endian Explicit Uncompressed for
365 output. Files that are newly created are always written as DICOM file
366 format, i.e. option --write-dataset is not permitted together with
367 --create. This way, at least the metaheader is written and no file with
368 zero byte length is created in a case where no insertions are performed
369 in the dcmodify call.
370
372 In order to read the element value from a file instead of specifying it
373 on the command line, option -mf and -if can be used. Please note that
374 for OW elements, the data is expected to be little endian ordered and
375 will be swapped if necessary. The file size should always be an even
376 number of bytes, i.e. no automatic padding is performed.
377
379 dcmodify also permits the usage of a wildcard character '*' for item
380 numbers in path expressions, e.g. 'ContentSequence[*].CodeValue'
381 selects all 'Code Value' attributes in all items of the
382 ContentSequence. Using a wildcard is possible for all basic operations,
383 i.e. modifying -m, inserting -i and -e options which makes it, together
384 with the automatic creation of intermediate path nodes a powerful tool
385 for construction and processing complex datasets.
386 The options -ma and -ea for modifying or deleting all occurrences of a
388 DICOM element based on its tag do not accept any wildcards but only
389 work on single elements (i.e. a single dictionary name or tag key).
390
392 -i --insert:
393 dcmodify -i "(0010,0010)=A Name" file.dcm
394 Inserts the PatientName tag into 'file.dcm' at 1st level.
395 If tag already exists, -i will overwrite it! If you want to
396 insert an element with value multiplicity > 1 (e.g. 4) you
397 can do this with: dcmodify -i "(0018,1310)=1\2\3\4"
398 dcmodify -i "(0008,1111)[0].PatientName=Another Name" *.dcm
400 Inserts PatientName tag into the first item of sequence
401 (0008,1111). Note that the use of wildcards for files is
402 possible. You can specify longer tag paths, too (e.g.
403 "(0008,1111)[0].(0008,1111)[1].(0010,0010)=A Third One").
404 If any part of the path, e.g. the sequence or the item "0"
405 does not exist, it is automatically inserted by dcmodify.
406 dcmodify -i "(0008,1111)[*].PatientName=Another Name" *.dcm
408 Inserts PatientName tag into _every_ item of sequence
409 (0008,1111). Note that the use of wildcards for files is
410 possible. You can specify longer tag paths, too (e.g.
411 "(0008,1111)[*].(0008,1111)[*].(0010,0010)=A Third One").
412 -if --insert-from-file:
414 dcmodify -if "PixelData=pixel.raw" file.dcm
415 Inserts the content of file 'pixel.raw' into the PixelData element
416 of 'file.dcm'. The contents of the file will be read as is.
417 OW data is expected to be little endian ordered and will be
418 swapped if necessary. No checks will be made to ensure that the
419 amount of data is reasonable in terms of other attributes such as
420 Rows or Columns.
421 -m --modify:
423 dcmodify -m "(0010,0010)=A Name" file.dcm
424 Changes tag (0010,0010) on 1st level to "A Name".
425 This option also permits longer tag paths as demonstrated
427 above for -i. If the leaf element or any intermediate
428 part of the path does not exist, it is not inserted as it
429 would be if using the '-i' option.
430 dcmodify -m "(0010,0010)=A Name" -imt file.dcm
432 Changes tag (0010,0010) on 1st level to "A Name". Due to the
433 given option '-imt', success is returned instead of "tag not found",
434 if the element/item (or any intermediate node in a longer path) does
435 not exist.
436 Note that for the '-m' option the last node in the path must be
438 a leaf element, i.e. not a sequence or an item.
439 -mf --modify-from-file:
441 dcmodify -mf "PixelData=pixel.raw" file.dcm
442 Does the same as -if in case there was already a PixelData element
443 in 'file.dcm'. Otherwise nothing is changed.
444 -ma --modify-all:
446 dcmodify -ma "(0010,0010)=New Name" file.dcm
447 Does the same as -m but works on all matching tags found in
448 'file.dcm'. Therefore, it searches the whole dataset including
449 sequences for tag (0010,0010) and changes them to "New Name"
450 -e --erase:
452 dcmodify -e "(0010,0010)" *.dcm
453 Erases tag (0010,0010) in all *.dcm files at 1st level.
454 This option also allows longer tag paths as demonstrated
456 above for -i.
457 dcmodify -e "(0010,0010)" -imt *.dcm
459 Erases tag (0010,0010) in all *.dcm files at 1st level. Due to the
460 given option '-imt', success is returned instead of "tag not found",
461 if the element/item (or any intermediate node in a longer path) does
462 not exist.
463 -ea --erase-all:
465 dcmodify -ea "(0010,0010)" *.dcm
466 Same as -e, but also searches in sequences and items.
467 -ep --erase-private:
469 dcmodify -ep *.dcm
470 Deletes all private tags (i.e. tags having an odd group number) from
471 all files matching *.dcm in the current directory.
472 -gst --gen-stud-uid:
474 dcmodify -gst file.dcm
475 This generates a new value for the StudyInstanceUID
476 (0020,000d). Other UIDs are not modified!
477 -gse --gen-ser-uid:
479 dcmodify -gse file.dcm
480 This generates a new value for the SeriesInstanceUID
481 (0020,000e). Other UIDs are not modified!
482 -gin --gen-inst-uid:
484 dcmodify -gin file.dcm
485 This command generates a new value for the SOPInstanceUID
486 (0008,0018). The corresponding MediaStorageSOPInstanceUID
487 (0002,0003) is adjusted to the new value automatically.
488 Please note that it's not possible to avoid this metaheader
489 update via the -nmu option.
490 -nmu --no-meta-uid:
492 dcmodify -m "SOPInstanceUID=[UID]" -nmu *.dcm
493 This will modify the SOPInstanceUID to the given [UID],
494 but -nmu avoids, that dcmodify adjusts the
495 MediaStorageSOPInstanceUID in the metaheader, too..fi
496
498 dcmodify tries executing each modify operation given on command line:
499 If one returns an error, the others are being performed anyway. However
500 in case of any error, the modified file is not saved, unless the
501 --ignore-errors option is specified. If that option is selected,
502 dcmodify also continues modifying further files specified on command
503 line; otherwise dcmodify exits after the first file that had
504 modification errors.
505 If the --ignore-missing-tags option is enabled, any modify or erase
507 operations (i.e. not --insert) that fails because of a non-existing tag
508 is treated as being successful. That does make sense if someone wants
509 to be sure that specific tags are not present in the file or that - if
510 they exist - that they are set to a specific value.
511
513 The level of logging output of the various command line tools and
514 underlying libraries can be specified by the user. By default, only
515 errors and warnings are written to the standard error stream. Using
516 option --verbose also informational messages like processing details
517 are reported. Option --debug can be used to get more details on the
518 internal activity, e.g. for debugging purposes. Other logging levels
519 can be selected using option --log-level. In --quiet mode only fatal
520 errors are reported. In such very severe error events, the application
521 will usually terminate. For more details on the different logging
522 levels, see documentation of module 'oflog'.
523 In case the logging output should be written to file (optionally with
525 logfile rotation), to syslog (Unix) or the event log (Windows) option
526 --log-config can be used. This configuration file also allows for
527 directing only certain messages to a particular output stream and for
528 filtering certain messages based on the module or application where
529 they are generated. An example configuration file is provided in
530 <etcdir>/logger.cfg.
531
533 All command line tools use the following notation for parameters:
534 square brackets enclose optional values (0-1), three trailing dots
535 indicate that multiple values are allowed (1-n), a combination of both
536 means 0 to n values.
537 Command line options are distinguished from parameters by a leading '+'
539 or '-' sign, respectively. Usually, order and position of command line
540 options are arbitrary (i.e. they can appear anywhere). However, if
541 options are mutually exclusive the rightmost appearance is used. This
542 behavior conforms to the standard evaluation rules of common Unix
543 shells.
544 In addition, one or more command files can be specified using an '@'
546 sign as a prefix to the filename (e.g. @command.txt). Such a command
547 argument is replaced by the content of the corresponding text file
548 (multiple whitespaces are treated as a single separator unless they
549 appear between two quotation marks) prior to any further evaluation.
550 Please note that a command file cannot contain another command file.
551 This simple but effective approach allows one to summarize common
552 combinations of options/parameters and avoids longish and confusing
553 command lines (an example is provided in file <datadir>/dumppat.txt).
554
556 The dcmodify utility will attempt to load DICOM data dictionaries
557 specified in the DCMDICTPATH environment variable. By default, i.e. if
558 the DCMDICTPATH environment variable is not set, the file
559 <datadir>/dicom.dic will be loaded unless the dictionary is built into
560 the application (default for Windows).
561 The default behavior should be preferred and the DCMDICTPATH
563 environment variable only used when alternative data dictionaries are
564 required. The DCMDICTPATH environment variable has the same format as
565 the Unix shell PATH variable in that a colon (':') separates entries.
566 On Windows systems, a semicolon (';') is used as a separator. The data
567 dictionary code will attempt to load each file specified in the
568 DCMDICTPATH environment variable. It is an error if no data dictionary
569 can be loaded.
570
572 Copyright (C) 2003-2014 by OFFIS e.V., Escherweg 2, 26121 Oldenburg,
573 Germany.
574Version 3.6.6 Thu Jan 14 2021 dcmodify(1)