OFFIS DCMTK  Version 3.6.0
dcmodify.man
1 /*!
2 
3 \if MANPAGES
4 \page dcmodify Modify DICOM files
5 \else
6 \page dcmodify dcmodify: Modify DICOM files
7 \endif
8 
9 \section synopsis SYNOPSIS
10 
11 \verbatim
12 dcmodify [options] dcmfile-in...
13 \endverbatim
14 
15 \section description DESCRIPTION
16 
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.
24 
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.
30 
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.
38 
39 \b dcmodify is able to work with so-called tag paths to access tags in
40 sequences. The (pseudo-formalized) syntax is
41 
42 \verbatim
43  {sequence[item-no].}*element
44 \endverbatim
45 \if MANPAGES
46 .fi
47 \endif
48 
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).
57 
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.
66 
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).
69 
70 \section parameters PARAMETERS
71 
72 \verbatim
73 dcmfile-in DICOM input filename(s) to be modified
74 \endverbatim
75 
76 \section options OPTIONS
77 
78 \subsection general_options general options
79 \verbatim
80  -h --help
81  print this help text and exit
82 
83  --version
84  print version information and exit
85 
86  --arguments
87  print expanded command line arguments
88 
89  -q --quiet
90  quiet mode, print no warnings and errors
91 
92  -v --verbose
93  verbose mode, print processing details
94 
95  -d --debug
96  debug mode, print debug information
97 
98  -ll --log-level [l]evel: string constant
99  (fatal, error, warn, info, debug, trace)
100  use level l for the logger
101 
102  -lc --log-config [f]ilename: string
103  use config file f for the logger
104 
105  -ie --ignore-errors
106  continue with file, if modify error occurs
107 
108  -nb --no-backup
109  don't backup files (DANGEROUS)
110 \endverbatim
111 
112 \subsection input_options input options
113 \verbatim
114 input file format:
115 
116  +f --read-file
117  read file format or data set (default)
118 
119  +fo --read-file-only
120  read file format only
121 
122  -f --read-dataset
123  read data set without file meta information
124 
125 input transfer syntax:
126 
127  -t= --read-xfer-auto
128  use TS recognition (default)
129 
130  -td --read-xfer-detect
131  ignore TS specified in the file meta header
132 
133  -te --read-xfer-little
134  read with explicit VR little endian TS
135 
136  -tb --read-xfer-big
137  read with explicit VR big endian TS
138 
139  -ti --read-xfer-implicit
140  read with implicit VR little endian TS
141 
142 parsing of odd-length attributes:
143 
144  +ao --accept-odd-length
145  accept odd length attributes (default)
146 
147  +ae --assume-even-length
148  assume real length is one byte larger
149 
150 automatic data correction:
151 
152  +dc --enable-correction
153  enable automatic data correction (default)
154 
155  -dc --disable-correction
156  disable automatic data correction
157 
158 bitstream format of deflated input:
159 
160  +bd --bitstream-deflated
161  expect deflated bitstream (default)
162 
163  +bz --bitstream-zlib
164  expect deflated zlib bitstream
165 \endverbatim
166 
167 
168 \subsection processing_options processing options
169 \verbatim
170 insert mode:
171 
172  -i --insert "[t]ag-path=[v]alue"
173  insert (or overwrite) path at position t with value v
174 
175  -if --insert-from-file "[t]ag-path=[f]ilename"
176  insert (or overwrite) path at position t with value from file f
177 
178  -nrc --no-reserv-check
179  do not check private reservations
180 
181 modify mode:
182 
183  -m --modify "[t]ag-path=[v]alue"
184  modify tag at position t to value v
185 
186  -mf --modify-from-file "[t]ag-path=[f]ilename"
187  modify tag at position t to value from file f
188 
189  -ma --modify-all "[t]ag=[v]alue"
190  modify ALL matching tags t in file to value v
191 
192 erase mode:
193 
194  -e --erase "[t]ag-path"
195  erase tag/item at position t
196 
197  -ea --erase-all "[t]ag"
198  erase ALL matching tags t in file
199 
200  -ep --erase-private
201  erase ALL private data from file
202 
203 unique identifier:
204 
205  -gst --gen-stud-uid
206  generate new Study Instance UID
207 
208  -gse --gen-ser-uid
209  generate new Series Instance UID
210 
211  -gin --gen-inst-uid
212  generate new SOP Instance UID
213 
214  -nmu --no-meta-uid
215  do not update metaheader UIDs if related
216  UIDs in the dataset are modified
217 
218 other processing options:
219 
220  -imt --ignore-missing-tags
221  treat 'tag not found' as success
222  when modifying or erasing in files
223 
224  -iun --ignore-un-values
225  do not try writing any values to
226  elements having VR of UN
227 \endverbatim
228 
229 \subsection output_options output options
230 \verbatim
231 output file format:
232 
233  +F --write-file
234  write file format (default)
235 
236  -F --write-dataset
237  write data set without file meta information
238 
239 output transfer syntax:
240 
241  +t= --write-xfer-same
242  write with same TS as input (default)
243 
244  +te --write-xfer-little
245  write with explicit VR little endian TS
246 
247  +tb --write-xfer-big
248  write with explicit VR big endian TS
249 
250  +ti --write-xfer-implicit
251  write with implicit VR little endian TS
252 
253 post-1993 value representations:
254 
255  +u --enable-new-vr
256  enable support for new VRs (UN/UT) (default)
257 
258  -u --disable-new-vr
259  disable support for new VRs, convert to OB
260 
261 group length encoding:
262 
263  +g= --group-length-recalc
264  recalculate group lengths if present (default)
265 
266  +g --group-length-create
267  always write with group length elements
268 
269  -g --group-length-remove
270  always write without group length elements
271 
272 length encoding in sequences and items:
273 
274  +le --length-explicit
275  write with explicit lengths (default)
276 
277  -le --length-undefined
278  write with undefined lengths
279 
280 data set trailing padding (not with --write-dataset):
281 
282  -p= --padding-retain
283  do not change padding (default if not --write-dataset)
284 
285  -p --padding-off
286  no padding (implicit if --write-dataset)
287 
288  +p --padding-create [f]ile-pad [i]tem-pad: integer
289  align file on multiple of f bytes and items on
290  multiple of i bytes
291 \endverbatim
292 
293 \section private_tags PRIVATE TAGS
294 
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
297 always work.
298 
299 \subsection private_insertions Insertions
300 
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
305 some values.
306 
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.
315 
316 See description above how inserting values into elements with unknown VR
317 are handled.
318 
319 \subsection private_modifications Modifications
320 
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.
323 
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).
328 
329 Also, see description above how inserting values into elements with unknown VR
330 are handled.
331 
332 \subsection private_deletions Deletions
333 
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.
338 
339 For the deletion of private non-reservation tags there are no special issues.
340 
341 \section changing_uids CHANGING UIDS
342 
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
347 \e -nmu option.
348 
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.
357 
358 When choosing the \e -gin option, the related metaheader tag ('Media Storage
359 SOP Instance UID') is updated automatically. This behaviour cannot be
360 disabled.
361 
362 \section element_values_from_file ELEMENT VALUES FROM FILE
363 
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.
369 
370 \section wildcards WILDCARDS
371 
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
378 datasets.
379 
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).
383 
384 \section examples EXAMPLES
385 
386 \verbatim
387 -i --insert:
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"
393 
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.
401 
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").
407 
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
415  Rows or Columns.
416 
417 -m --modify:
418  dcmodify -m "(0010,0010)=A Name" file.dcm
419  Changes tag (0010,0010) on 1st level to "A Name".
420 
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.
425 
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
430  not exist.
431 
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.
434 
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.
439 
440 -ma --modify-all:
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"
445 
446 -e --erase:
447  dcmodify -e "(0010,0010)" *.dcm
448  Erases tag (0010,0010) in all *.dcm files at 1st level.
449 
450  This option also allows longer tag paths as demonstrated
451  above for -i.
452 
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
457  not exist.
458 
459 -ea --erase-all:
460  dcmodify -ea "(0010,0010)" *.dcm
461  Same as -e, but also searches in sequences and items.
462 
463 -ep --erase-private:
464  dcmodify -ep *.dcm
465  Deletes all private tags (i.e. tags having an odd group number) from
466  all files matching *.dcm in the current directory.
467 
468 -gst --gen-stud-uid:
469  dcmodify -gst file.dcm
470  This generates a new value for the StudyInstanceUID
471  (0020,000d). Other UIDs are not modified!
472 
473 -gse --gen-ser-uid:
474  dcmodify -gse file.dcm
475  This generates a new value for the SeriesInstanceUID
476  (0020,000e). Other UIDs are not modified!
477 
478 -gin --gen-inst-uid:
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.
485 
486 -nmu --no-meta-uid:
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.
491 \endverbatim
492 
493 \section error_handling ERROR HANDLING
494 
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.
501 
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.
507 
508 \section logging LOGGING
509 
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".
519 
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>).
526 
527 \section command_line COMMAND LINE
528 
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.
532 
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.
538 
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>).
548 
549 \section environment ENVIRONMENT
550 
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).
556 
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.
564 
565 \section copyright COPYRIGHT
566 
567 Copyright (C) 2003-2010 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.
568 
569 */


Generated on Sun Aug 23 2015 for OFFIS DCMTK Version 3.6.0 by Doxygen 1.8.9.1