1dcmodify(1)                       OFFIS DCMTK                      dcmodify(1)
2
3
4

NAME

6       dcmodify - Modify DICOM files
7
8

SYNOPSIS

10       dcmodify [options] dcmfile-in...
11

DESCRIPTION

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
21       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
27       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
35       dcmodify  is  able  to  work with so-called tag paths to access tags in
36       sequences. The (pseudo-formalized) syntax is
37
38       {sequence[item-no].}*element
39
40       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
50       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
60       dcmodify does not work on directories, i.e. the parameter dcmfile-in...
61       must not include directory names.
62
63       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

PARAMETERS

68       dcmfile-in  DICOM input filename(s) to be modified
69

OPTIONS

71   general options
72         -h    --help
73                 print this help text and exit
74
75               --version
76                 print version information and exit
77
78               --arguments
79                 print expanded command line arguments
80
81         -q    --quiet
82                 quiet mode, print no warnings and errors
83
84         -v    --verbose
85                 verbose mode, print processing details
86
87         -d    --debug
88                 debug mode, print debug information
89
90         -ll   --log-level  [l]evel: string constant
91                 (fatal, error, warn, info, debug, trace)
92                 use level l for the logger
93
94         -lc   --log-config  [f]ilename: string
95                 use config file f for the logger
96
97   input options
98       input file format:
99
100         +f    --read-file
101                 read file format or data set (default)
102
103         +fo   --read-file-only
104                 read file format only
105
106         -f    --read-dataset
107                 read data set without file meta information
108
109         +fc   --create-file
110                 create file format if file does not exist
111
112       input transfer syntax:
113
114         -t=   --read-xfer-auto
115                 use TS recognition (default)
116
117         -td   --read-xfer-detect
118                 ignore TS specified in the file meta header
119
120         -te   --read-xfer-little
121                 read with explicit VR little endian TS
122
123         -tb   --read-xfer-big
124                 read with explicit VR big endian TS
125
126         -ti   --read-xfer-implicit
127                 read with implicit VR little endian TS
128
129       parsing of odd-length attributes:
130
131         +ao   --accept-odd-length
132                 accept odd length attributes (default)
133
134         +ae   --assume-even-length
135                 assume real length is one byte larger
136
137       automatic data correction:
138
139         +dc   --enable-correction
140                 enable automatic data correction (default)
141
142         -dc   --disable-correction
143                 disable automatic data correction
144
145       bitstream format of deflated input:
146
147         +bd   --bitstream-deflated
148                 expect deflated bitstream (default)
149
150         +bz   --bitstream-zlib
151                 expect deflated zlib bitstream
152
153   processing options
154       backup input files:
155
156               --backup
157                 backup files before modifying (default)
158
159         -nb   --no-backup
160                 don't backup files (DANGEROUS)
161
162       insert mode:
163
164         -i    --insert  "[t]ag-path=[v]alue"
165                 insert (or overwrite) path at position t with value v
166
167         -if   --insert-from-file  "[t]ag-path=[f]ilename"
168                 insert (or overwrite) path at position t with value from file f
169
170         -nrc  --no-reserv-check
171                 do not check private reservations
172
173       modify mode:
174
175         -m    --modify  "[t]ag-path=[v]alue"
176                 modify tag at position t to value v
177
178         -mf   --modify-from-file  "[t]ag-path=[f]ilename"
179                 modify tag at position t to value from file f
180
181         -ma   --modify-all  "[t]ag=[v]alue"
182                 modify ALL matching tags t in file to value v
183
184       erase mode:
185
186         -e    --erase  "[t]ag-path"
187                 erase tag/item at position t
188
189         -ea   --erase-all  "[t]ag"
190                 erase ALL matching tags t in file
191
192         -ep   --erase-private
193                 erase ALL private data from file
194
195       unique identifier:
196
197         -gst  --gen-stud-uid
198                 generate new Study Instance UID
199
200         -gse  --gen-ser-uid
201                 generate new Series Instance UID
202
203         -gin  --gen-inst-uid
204                 generate new SOP Instance UID
205
206         -nmu  --no-meta-uid
207                 do not update metaheader UIDs if related
208                 UIDs in the dataset are modified
209
210       error handling:
211
212         -ie   --ignore-errors
213                 continue with file, if modify error occurs
214
215         -imt  --ignore-missing-tags
216                 treat 'tag not found' as success
217                 when modifying or erasing in files
218
219         -iun  --ignore-un-values
220                 do not try writing any values to elements
221                 having a VR of UN
222
223   output options
224       output file format:
225
226         +F    --write-file
227                 write file format (default)
228
229         -F    --write-dataset
230                 write data set without file meta information
231
232       output transfer syntax:
233
234         +t=   --write-xfer-same
235                 write with same TS as input (default)
236
237         +te   --write-xfer-little
238                 write with explicit VR little endian TS
239
240         +tb   --write-xfer-big
241                 write with explicit VR big endian TS
242
243         +ti   --write-xfer-implicit
244                 write with implicit VR little endian TS
245
246       post-1993 value representations:
247
248         +u    --enable-new-vr
249                 enable support for new VRs (UN/UT) (default)
250
251         -u    --disable-new-vr
252                 disable support for new VRs, convert to OB
253
254       group length encoding:
255
256         +g=   --group-length-recalc
257                 recalculate group lengths if present (default)
258
259         +g    --group-length-create
260                 always write with group length elements
261
262         -g    --group-length-remove
263                 always write without group length elements
264
265       length encoding in sequences and items:
266
267         +le   --length-explicit
268                 write with explicit lengths (default)
269
270         -le   --length-undefined
271                 write with undefined lengths
272
273       data set trailing padding (not with --write-dataset):
274
275         -p=   --padding-retain
276                 do not change padding (default if not --write-dataset)
277
278         -p    --padding-off
279                 no padding (implicit if --write-dataset)
280
281         +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

PRIVATE TAGS

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
290   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
297       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
307       See  description  above how inserting values into elements with unknown
308       VR are handled.
309
310   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
315       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
320       Also,  see  description  above  how inserting values into elements with
321       unknown VR are handled.
322
323   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
329       For  the  deletion of private non-reservation tags there are no special
330       issues.
331

CHANGING UIDS

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
339       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
348       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
352       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

CREATING NEW FILES

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

ELEMENT VALUES FROM FILE

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

WILDCARDS

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
387       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

EXAMPLES

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
399              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
407              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
413       -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
422       -m   --modify:
423              dcmodify -m "(0010,0010)=A Name" file.dcm
424              Changes tag (0010,0010) on 1st level to "A Name".
425
426              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
431              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
437              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
440       -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
445       -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
451       -e   --erase:
452              dcmodify -e "(0010,0010)" *.dcm
453              Erases tag (0010,0010) in all *.dcm files at 1st level.
454
455              This option also allows longer tag paths as demonstrated
456              above for -i.
457
458              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
464       -ea  --erase-all:
465              dcmodify -ea "(0010,0010)" *.dcm
466              Same as -e, but also searches in sequences and items.
467
468       -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
473       -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
478       -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
483       -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
491       -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

ERROR HANDLING

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
506       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

LOGGING

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
524       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

COMMAND LINE

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
538       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
545       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

ENVIRONMENT

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
562       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-2022  by OFFIS e.V., Escherweg 2, 26121 Oldenburg,
573       Germany.
574
575
576
577Version 3.6.7                   Fri Apr 22 2022                    dcmodify(1)
Impressum