4 \page dcmodify Modify DICOM files
6 \page dcmodify dcmodify: Modify DICOM files
9 \section synopsis SYNOPSIS
12 dcmodify [options] dcmfile-in...
15 \section description DESCRIPTION
17 \b dcmodify is a tool that allows to modify, insert and delete tags and items
18 in DICOM files. Sequences and tags with a value multiplicity > 1 are also
19 supported. Metaheader information and the tag's VR can not be modified
20 directly by \b dcmodify at this time. In addition to tag modifications,
21 \b dcmodify makes available some input options - forcing \b dcmodify to
22 handle its input files as the user specifies - and output options to control
23 the output format of the resulting files.
25 In case multiple modifications have to be performed, \b dcmodify does the
26 modifications in the same order as they appear on the command line. Please
27 note that \b dcmodify does not check whether a given value matches its value
28 representation (VR). Usually, an error message is printed but generally the
29 user should take care of the right VR usage.
31 If \b dcmodify doesn't know the tag it should insert, then the tag's VR is set
32 to UN and the value provided on commandline is interpreted as being a
33 series of hexadecimal numbers (like they are provided for VR=OB). Please
34 insert these tags into the dictionary to avoid this behaviour. Also,
35 specifying the \e -iun option, it is possible to force \b dcmodify to
36 leave UN values untouched. Using option \e -u lets \b dcmodify saving all
37 VR=UN attributes as OB.
39 \b dcmodify is able to work with so-called tag paths to access tags in
40 sequences. The (pseudo-formalized) syntax is
43 {sequence[item-no].}*element
49 where 'sequence' is a sequence tag like (0008,1111) or a dictionary name for a
50 tag. 'item-no' describes the item number to be accessed (counting from zero).
51 'element' defines the target tag to work on. A tag can either be specified
52 directly as (0010,0010) or through the corresponding dictionary name
53 "PatientName". The '*' denotes that you can repeat sequence statements to
54 access deeper levels in DICOM files (see EXAMPLES section). For 'item-no',
55 also a wildcard character '*' can be used selecting all items in surrounding
56 sequence (see section WILDCARDS below).
58 When inserting tag paths consisting of multiple nodes (i.e. not a single
59 element) using the \e -i option, any missing path elements (items, sequences,
60 leaf elements) are inserted automatically when missing. That does not work
61 for item wildcards: When no single item exists in the surrounding sequence
62 \b dcmodify of course can't decide, how many items should be generated.
63 However, if specifying an item number like '5', all 6 items (counted from zero)
64 can be (and are) automatically generated in insert mode. If already 2 items
65 would exist, the rest (4) would be inserted.
67 Please note that there are some issues concerning the modification of private
68 tags (see PRIVATE TAGS section) and for changing UIDs (CHANGING UIDs section).
70 \section parameters PARAMETERS
73 dcmfile-in DICOM input filename(s) to be modified
76 \section options OPTIONS
78 \subsection general_options general options
81 print this help text and exit
84 print version information and exit
87 print expanded command line arguments
90 quiet mode, print no warnings and errors
93 verbose mode, print processing details
96 debug mode, print debug information
98 -ll --log-level [l]evel: string constant
99 (fatal, error, warn, info, debug, trace)
100 use level l for the logger
102 -lc --log-config [f]ilename: string
103 use config file f for the logger
106 continue with file, if modify error occurs
109 don't backup files (DANGEROUS)
112 \subsection input_options input options
117 read file format or data set (default)
120 read file format only
123 read data set without file meta information
125 input transfer syntax:
128 use TS recognition (default)
130 -td --read-xfer-detect
131 ignore TS specified in the file meta header
133 -te --read-xfer-little
134 read with explicit VR little endian TS
137 read with explicit VR big endian TS
139 -ti --read-xfer-implicit
140 read with implicit VR little endian TS
142 parsing of odd-length attributes:
144 +ao --accept-odd-length
145 accept odd length attributes (default)
147 +ae --assume-even-length
148 assume real length is one byte larger
150 automatic data correction:
152 +dc --enable-correction
153 enable automatic data correction (default)
155 -dc --disable-correction
156 disable automatic data correction
158 bitstream format of deflated input:
160 +bd --bitstream-deflated
161 expect deflated bitstream (default)
164 expect deflated zlib bitstream
168 \subsection processing_options processing options
172 -i --insert "[t]ag-path=[v]alue"
173 insert (or overwrite) path at position t with value v
175 -if --insert-from-file "[t]ag-path=[f]ilename"
176 insert (or overwrite) path at position t with value from file f
178 -nrc --no-reserv-check
179 do not check private reservations
183 -m --modify "[t]ag-path=[v]alue"
184 modify tag at position t to value v
186 -mf --modify-from-file "[t]ag-path=[f]ilename"
187 modify tag at position t to value from file f
189 -ma --modify-all "[t]ag=[v]alue"
190 modify ALL matching tags t in file to value v
194 -e --erase "[t]ag-path"
195 erase tag/item at position t
197 -ea --erase-all "[t]ag"
198 erase ALL matching tags t in file
201 erase ALL private data from file
206 generate new Study Instance UID
209 generate new Series Instance UID
212 generate new SOP Instance UID
215 do not update metaheader UIDs if related
216 UIDs in the dataset are modified
218 other processing options:
220 -imt --ignore-missing-tags
221 treat 'tag not found' as success
222 when modifying or erasing in files
224 -iun --ignore-un-values
225 do not try writing any values to
226 elements having VR of UN
229 \subsection output_options output options
234 write file format (default)
237 write data set without file meta information
239 output transfer syntax:
241 +t= --write-xfer-same
242 write with same TS as input (default)
244 +te --write-xfer-little
245 write with explicit VR little endian TS
248 write with explicit VR big endian TS
250 +ti --write-xfer-implicit
251 write with implicit VR little endian TS
253 post-1993 value representations:
256 enable support for new VRs (UN/UT) (default)
259 disable support for new VRs, convert to OB
261 group length encoding:
263 +g= --group-length-recalc
264 recalculate group lengths if present (default)
266 +g --group-length-create
267 always write with group length elements
269 -g --group-length-remove
270 always write without group length elements
272 length encoding in sequences and items:
274 +le --length-explicit
275 write with explicit lengths (default)
277 -le --length-undefined
278 write with undefined lengths
280 data set trailing padding (not with --write-dataset):
283 do not change padding (default if not --write-dataset)
286 no padding (implicit if --write-dataset)
288 +p --padding-create [f]ile-pad [i]tem-pad: integer
289 align file on multiple of f bytes and items on
293 \section private_tags PRIVATE TAGS
295 There are some issues you have to consider when working with private tags.
296 However, the insertion or modification of a reservation tag (gggg,00xx) should
299 \subsection private_insertions Insertions
301 If you wish to insert a private tag (not a reservation with gggg,00xx), be
302 sure, that you've listed it in your dictionary (see
303 <em><docdir>/datadict.txt</em> for details). If it's not listed, \b dcmodify
304 will insert it with VR=UN. Also, for some cases insertion may even fail for
307 If you've got your private tag in the dictionary, \b dcmodify acts as follows:
308 When it finds a reservation in the tag's enclosing dataset, whose private
309 creator matches, insertion is done with the VR found in the dictionary and the
310 value given on command line. But if the private creator doesn't match or none
311 is set, \b dcmodify will return with an error. If a private tag should be
312 inserted regardless whether a reservation does not exist, the option \e -nrc
313 can be used, forcing an insertion. However, the VR is set to UN then, because
314 the tag then cannot be found in the dictionary.
316 See description above how inserting values into elements with unknown VR
319 \subsection private_modifications Modifications
321 If you modify a private tags value, \b dcmodify won't check its VR against the
322 dictionary. So please be careful to enter only values that match the tag's VR.
324 If you wish to change a private tags value \e and VR, because you just added
325 this tag to your dictionary, you can delete it with \b dcmodify and re-insert
326 it. Then \b dcmodify uses your dicitionary entry to determine the right VR
327 (also see subsection insertions).
329 Also, see description above how inserting values into elements with unknown VR
332 \subsection private_deletions Deletions
334 When you use \b dcmodify to delete a private reservation tag, please note that
335 \b dcmodify won't touch the private tags that are under this reservation. The
336 user is forced to handle the consistency between reservations and their
337 pending private tags.
339 For the deletion of private non-reservation tags there are no special issues.
341 \section changing_uids CHANGING UIDS
343 \b dcmodify will automatically correct 'Media Storage SOP Class UID' and
344 'Media Storage SOP Instance UID' in the metaheader, if you make changes to the
345 related tags in the dataset ('SOP Class UID' and 'SOP Instance UID') via
346 insert or modify mode options. You can disable this behaviour by using the
349 If you generate new UID's with \e -gst, \e -gse or \e -gin, this will only
350 affect the UID you choosed to generate. So if you use \e -gst to generate a
351 new 'Study Instance UID', then 'Series Instance UID' and 'SOP Instance UID'
352 will not be affected! This gives you the possibility to generate each value
353 separately. Normally, you would also modify the 'underlying' UIDs. As a
354 disadvantage of this flexibility, the user has to assure, that when creating
355 'new' DICOM files with new UIDs with \b dcmodify, other UIDs have to be updated
356 by the user as necessary.
358 When choosing the \e -gin option, the related metaheader tag ('Media Storage
359 SOP Instance UID') is updated automatically. This behaviour cannot be
362 \section element_values_from_file ELEMENT VALUES FROM FILE
364 In order to read the element value from a file instead of specifying it on the
365 command line, option \e -mf and \e -if can be used. Please note that for OW
366 elements, the data is expected to be little endian ordered and will be swapped
367 if necessary. The file size should always be an even number of bytes, i.e. no
368 automatic padding is performed.
370 \section wildcards WILDCARDS
372 \b dcmodify also permits the usage of a wildcard character "*" for item numbers
373 in path expressions, e.g. "ContentSequence[*].CodeValue" selects all "Code
374 Value" attributes in all items of the ContentSequence. Using a wildcard is
375 possible for all basic operations, i.e. modifying \e -m, inserting \e -i and
376 \e -e options which makes it, together with the automatic creation of
377 intermediate path nodes a powerful tool for construction and processing complex
380 The options \e -ma and \e -ea for modifying or deleting all occurences of a
381 DICOM element based on its tag do not accept any wildcards but only work on
382 single elements (i.e. a single dictionary name or tag key).
384 \section examples EXAMPLES
388 dcmodify -i "(0010,0010)=A Name" file.dcm
389 Inserts the PatientName tag into 'file.dcm' at 1st level.
390 If tag already exists, -i will overwrite it! If you want to
391 insert an element with value multiplicity > 1 (e.g. 4) you
392 can do this with: dcmodify -i "(0018,1310)=1\\2\\3\\4"
394 dcmodify -i "(0008,1111)[0].PatientName=Another Name" *.dcm
395 Inserts PatientName tag into the first item of sequence
396 (0008,1111). Note that the use of wildcards for files is
397 possible. You can specify longer tag paths, too (e.g.
398 "(0008,1111)[0].(0008,1111)[1].(0010,0010)=A Third One").
399 If any part of the path, e.g. the sequence or the item "0"
400 does not exist, it is automatically inserted by dcmodify.
402 dcmodify -i "(0008,1111)[*].PatientName=Another Name" *.dcm
403 Inserts PatientName tag into _every_ item of sequence
404 (0008,1111). Note that the use of wildcards for files is
405 possible. You can specify longer tag paths, too (e.g.
406 "(0008,1111)[*].(0008,1111)[*].(0010,0010)=A Third One").
408 -if --insert-from-file:
409 dcmodify -if "PixelData=pixel.raw" file.dcm
410 Inserts the content of file 'pixel.raw' into the PixelData element
411 of 'file.dcm'. The contents of the file will be read as is.
412 OW data is expected to be little endian ordered and will be
413 swapped if necessary. No checks will be made to ensure that the
414 amount of data is reasonable in terms of other attributes such as
418 dcmodify -m "(0010,0010)=A Name" file.dcm
419 Changes tag (0010,0010) on 1st level to "A Name".
421 This option also permits longer tag paths as demonstrated
422 above for -i. If the leaf element or any intermediate
423 part of the path does not exist, it is not inserted as it
424 would be if using the '-i' option.
426 dcmodify -m "(0010,0010)=A Name" -imt file.dcm
427 Changes tag (0010,0010) on 1st level to "A Name". Due to the
428 given option '-imt', success is returned instead of "tag not found",
429 if the element/item (or any intermediate node in a longer path) does
432 Note that for the '-m' option the last node in the path must be
433 a leaf element, i.e. not a sequence or an item.
435 -mf --modify-from-file:
436 dcmodify -mf "PixelData=pixel.raw" file.dcm
437 Does the same as -if in case there was already a PixelData element
438 in 'file.dcm'. Otherwise nothing is changed.
441 dcmodify -ma "(0010,0010)=New Name" file.dcm
442 Does the same as -m but works on all matching tags found in
443 'file.dcm'. Therefore, it searches the whole dataset including
444 sequences for tag (0010,0010) and changes them to "New Name"
447 dcmodify -e "(0010,0010)" *.dcm
448 Erases tag (0010,0010) in all *.dcm files at 1st level.
450 This option also allows longer tag paths as demonstrated
453 dcmodify -e "(0010,0010)" -imt *.dcm
454 Erases tag (0010,0010) in all *.dcm files at 1st level. Due to the
455 given option '-imt', success is returned instead of "tag not found",
456 if the element/item (or any intermediate node in a longer path) does
460 dcmodify -ea "(0010,0010)" *.dcm
461 Same as -e, but also searches in sequences and items.
465 Deletes all private tags (i.e. tags having an odd group number) from
466 all files matching *.dcm in the current directory.
469 dcmodify -gst file.dcm
470 This generates a new value for the StudyInstanceUID
471 (0020,000d). Other UIDs are not modified!
474 dcmodify -gse file.dcm
475 This generates a new value for the SeriesInstanceUID
476 (0020,000e). Other UIDs are not modified!
479 dcmodify -gin file.dcm
480 This command generates a new value for the SOPInstanceUID
481 (0008,0018). The corresponding MediaStorageSOPInstanceUID
482 (0002,0003) is adjusted to the new value automatically.
483 Please note that it's not possible to avoid this metaheader
484 update via the -nmu option.
487 dcmodify -m "SOPInstanceUID=[UID]" -nmu *.dcm
488 This will modify the SOPInstanceUID to the given [UID],
489 but -nmu avoids, that dcmodify adjusts the
490 MediaStorageSOPInstanceUID in the metaheader, too.
493 \section error_handling ERROR HANDLING
495 \b dcmodify tries executing each modify operation given on command line: If
496 one returns an error, the others are being performed anyway. However in case
497 of any error, the modified file is not saved, unless the \e --ignore-errors
498 option is specified. If that option is selected, \b dcmodify also
499 continues modifying further files specified on commandline; otherwise
500 \b dcmodify exits after the first file that had modification errors.
502 If the \e --ignore-missing-tags option is enabled, any modify or erase
503 operations (i.e. not \e --insert) that fails because of a non-existing tag is
504 treated as being successful. That does make sense if someone wants to be sure
505 that specific tags are not present in the file or that - if they exist - that
506 they are set to a specific value.
508 \section logging LOGGING
510 The level of logging output of the various command line tools and underlying
511 libraries can be specified by the user. By default, only errors and warnings
512 are written to the standard error stream. Using option \e --verbose also
513 informational messages like processing details are reported. Option
514 \e --debug can be used to get more details on the internal activity, e.g. for
515 debugging purposes. Other logging levels can be selected using option
516 \e --log-level. In \e --quiet mode only fatal errors are reported. In such
517 very severe error events, the application will usually terminate. For more
518 details on the different logging levels, see documentation of module "oflog".
520 In case the logging output should be written to file (optionally with logfile
521 rotation), to syslog (Unix) or the event log (Windows) option \e --log-config
522 can be used. This configuration file also allows for directing only certain
523 messages to a particular output stream and for filtering certain messages
524 based on the module or application where they are generated. An example
525 configuration file is provided in <em><etcdir>/logger.cfg</em>).
527 \section command_line COMMAND LINE
529 All command line tools use the following notation for parameters: square
530 brackets enclose optional values (0-1), three trailing dots indicate that
531 multiple values are allowed (1-n), a combination of both means 0 to n values.
533 Command line options are distinguished from parameters by a leading '+' or '-'
534 sign, respectively. Usually, order and position of command line options are
535 arbitrary (i.e. they can appear anywhere). However, if options are mutually
536 exclusive the rightmost appearance is used. This behaviour conforms to the
537 standard evaluation rules of common Unix shells.
539 In addition, one or more command files can be specified using an '@' sign as a
540 prefix to the filename (e.g. <em>\@command.txt</em>). Such a command argument
541 is replaced by the content of the corresponding text file (multiple
542 whitespaces are treated as a single separator unless they appear between two
543 quotation marks) prior to any further evaluation. Please note that a command
544 file cannot contain another command file. This simple but effective approach
545 allows to summarize common combinations of options/parameters and avoids
546 longish and confusing command lines (an example is provided in file
547 <em><datadir>/dumppat.txt</em>).
549 \section environment ENVIRONMENT
551 The \b dcmodify utility will attempt to load DICOM data dictionaries specified
552 in the \e DCMDICTPATH environment variable. By default, i.e. if the
553 \e DCMDICTPATH environment variable is not set, the file
554 <em><datadir>/dicom.dic</em> will be loaded unless the dictionary is built
555 into the application (default for Windows).
557 The default behaviour should be preferred and the \e DCMDICTPATH environment
558 variable only used when alternative data dictionaries are required. The
559 \e DCMDICTPATH environment variable has the same format as the Unix shell
560 \e PATH variable in that a colon (":") separates entries. On Windows systems,
561 a semicolon (";") is used as a separator. The data dictionary code will
562 attempt to load each file specified in the \e DCMDICTPATH environment variable.
563 It is an error if no data dictionary can be loaded.
565 \section copyright COPYRIGHT
567 Copyright (C) 2003-2010 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.