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