dcmodify(1)                       OFFIS DCMTK                      dcmodify(1)



NAME
       dcmodify - Modify DICOM files

SYNOPSIS
       dcmodify [options] dcmfile-in...


DESCRIPTION
       dcmodify  is  a  tool that allows to modify, insert and delete tags and
       items in DICOM files. Sequences and tags with a value multiplicity >  1
       are  also supported. Metaheader information and the tags VR can not be
       modified directly  by  dcmodify  at  this  time.  In  addition  to  tag
       modifications,  dcmodify  makes  available some input options - forcing
       dcmodify to handle its input files as the user specifies -  and  output
       options to control the output format of the resulting files.

       In  case multiple modifications have to be performed, dcmodify does the
       modifications in the same order as they appear  on  the  command  line.
       Please  note that dcmodify does not check whether a given value matches
       its value representation (VR). Usually, an error message is printed but
       generally the user should take care of the right VR usage.

       If dcmodify doesnt know the tag it should insert, then the tags VR is
       set to UN and the value provided on commandline is interpreted as being
       a  series  of  hexadecimal  numbers (like they are provided for VR=OB).
       Please insert these tags into the dictionary to avoid  this  behaviour.
       Also,  specifying  the -iun option, it is possible to force dcmodify to
       leave UN values untouched. Using option -u  lets  dcmodify  saving  all
       VR=UN attributes as OB.

       dcmodify  is  able  to  work with so-called tag paths to access tags in
       sequences. The (pseudo-formalized) syntax is



         {sequence[item-no].}*element



       where sequence is a sequence tag like  (0008,1111)  or  a  dictionary
       name  for  a  tag.  item-no  describes the item number to be accessed
       (counting from zero). element defines the target tag to  work  on.  A
       tag  can  either  be  specified  directly as (0010,0010) or through the
       corresponding dictionary name PatientName. The * denotes  that  you
       can  repeat  sequence statements to access deeper levels in DICOM files
       (see EXAMPLES section). For item-no, also a  wildcard  character  *
       can  be  used  selecting all items in surrounding sequence (see section
       WILDCARDS below).

       When inserting tag paths consisting  of  multiple  nodes  (i.e.  not  a
       single  element) using the -i option, any missing path elements (items,
       sequences, leaf elements) are inserted automatically when missing. That
       does  not  work  for  item wildcards: When no single item exists in the
       surrounding sequence dcmodify of course cant decide,  how  many  items
       should  be  generated.  However, if specifying an item number like 5,
       all 6  items  (counted  from  zero)  can  be  (and  are)  automatically
       generated  in insert mode. If already 2 items would exist, the rest (4)
       would be inserted.

       Please note that there are some issues concerning the  modification  of
       private tags (see PRIVATE TAGS section) and for changing UIDs (CHANGING
       UIDs section).

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


OPTIONS
   general options
         -h    --help
                 print this help text and exit

               --version
                 print version information and exit

               --arguments
                 print expanded command line arguments

         -q    --quiet
                 quiet mode, print no warnings and errors

         -v    --verbose
                 verbose mode, print processing details

         -d    --debug
                 debug mode, print debug information

         -ll   --log-level  [l]evel: string constant
                 (fatal, error, warn, info, debug, trace)
                 use level l for the logger

         -lc   --log-config  [f]ilename: string
                 use config file f for the logger

         -ie   --ignore-errors
                 continue with file, if modify error occurs

         -nb   --no-backup
                 dont backup files (DANGEROUS)


   input options
       input file format:

         +f    --read-file
                 read file format or data set (default)

         +fo   --read-file-only
                 read file format only

         -f    --read-dataset
                 read data set without file meta information

       input transfer syntax:

         -t=   --read-xfer-auto
                 use TS recognition (default)

         -td   --read-xfer-detect
                 ignore TS specified in the file meta header

         -te   --read-xfer-little
                 read with explicit VR little endian TS

         -tb   --read-xfer-big
                 read with explicit VR big endian TS

         -ti   --read-xfer-implicit
                 read with implicit VR little endian TS

       parsing of odd-length attributes:

         +ao   --accept-odd-length
                 accept odd length attributes (default)

         +ae   --assume-even-length
                 assume real length is one byte larger

       automatic data correction:

         +dc   --enable-correction
                 enable automatic data correction (default)

         -dc   --disable-correction
                 disable automatic data correction

       bitstream format of deflated input:

         +bd   --bitstream-deflated
                 expect deflated bitstream (default)

         +bz   --bitstream-zlib
                 expect deflated zlib bitstream


   processing options
       insert mode:

         -i    --insert  "[t]ag-path=[v]alue"
                 insert (or overwrite) path at position t with value v

         -if   --insert-from-file  "[t]ag-path=[f]ilename"
                 insert (or overwrite) path at position t with value from file f

         -nrc  --no-reserv-check
                 do not check private reservations

       modify mode:

         -m    --modify  "[t]ag-path=[v]alue"
                 modify tag at position t to value v

         -mf   --modify-from-file  "[t]ag-path=[f]ilename"
                 modify tag at position t to value from file f

         -ma   --modify-all  "[t]ag=[v]alue"
                 modify ALL matching tags t in file to value v

       erase mode:

         -e    --erase  "[t]ag-path"
                 erase tag/item at position t

         -ea   --erase-all  "[t]ag"
                 erase ALL matching tags t in file

         -ep   --erase-private
                 erase ALL private data from file

       unique identifier:

         -gst  --gen-stud-uid
                 generate new Study Instance UID

         -gse  --gen-ser-uid
                 generate new Series Instance UID

         -gin  --gen-inst-uid
                 generate new SOP Instance UID

         -nmu  --no-meta-uid
                 do not update metaheader UIDs if related
                 UIDs in the dataset are modified

       other processing options:

         -imt  --ignore-missing-tags
                 treat tag not found as success
                 when modifying or erasing in files

         -iun  --ignore-un-values
                 do not try writing any values to
                 elements having VR of UN


   output options
       output file format:

         +F    --write-file
                 write file format (default)

         -F    --write-dataset
                 write data set without file meta information

       output transfer syntax:

         +t=   --write-xfer-same
                 write with same TS as input (default)

         +te   --write-xfer-little
                 write with explicit VR little endian TS

         +tb   --write-xfer-big
                 write with explicit VR big endian TS

         +ti   --write-xfer-implicit
                 write with implicit VR little endian TS

       post-1993 value representations:

         +u    --enable-new-vr
                 enable support for new VRs (UN/UT) (default)

         -u    --disable-new-vr
                 disable support for new VRs, convert to OB

       group length encoding:

         +g=   --group-length-recalc
                 recalculate group lengths if present (default)

         +g    --group-length-create
                 always write with group length elements

         -g    --group-length-remove
                 always write without group length elements

       length encoding in sequences and items:

         +le   --length-explicit
                 write with explicit lengths (default)

         -le   --length-undefined
                 write with undefined lengths

       data set trailing padding (not with --write-dataset):

         -p=   --padding-retain
                 do not change padding (default if not --write-dataset)

         -p    --padding-off
                 no padding (implicit if --write-dataset)

         +p    --padding-create  [f]ile-pad [i]tem-pad: integer
                 align file on multiple of f bytes and items on
                 multiple of i bytes


PRIVATE TAGS
       There are some issues you have to consider when  working  with  private
       tags.  However,  the  insertion  or  modification  of a reservation tag
       (gggg,00xx) should always work.

   Insertions
       If you wish to insert a private tag (not a reservation with gggg,00xx),
       be   sure,   that   youve   listed   it   in   your   dictionary  (see
       <docdir>/datadict.txt for details). If its not listed,  dcmodify  will
       insert  it with VR=UN. Also, for some cases insertion may even fail for
       some values.

       If youve got your private tag in  the  dictionary,  dcmodify  acts  as
       follows:  When  it  finds a reservation in the tags enclosing dataset,
       whose private creator matches, insertion is done with the VR  found  in
       the  dictionary and the value given on command line. But if the private
       creator doesnt match or none is set,  dcmodify  will  return  with  an
       error.  If  a  private  tag  should  be  inserted  regardless whether a
       reservation does not exist, the option -nrc can  be  used,  forcing  an
       insertion.  However,  the  VR  is  set to UN then, because the tag then
       cannot be found in the dictionary.

       See description above how inserting values into elements  with  unknown
       VR are handled.

   Modifications
       If you modify a private tags value, dcmodify wont check its VR against
       the dictionary. So please be careful to enter only  values  that  match
       the tags VR.

       If  you  wish  to  change a private tags value and VR, because you just
       added this tag to your dictionary, you can delete it with dcmodify  and
       re-insert  it.  Then  dcmodify uses your dicitionary entry to determine
       the right VR (also see subsection insertions).

       Also, see description above how inserting  values  into  elements  with
       unknown VR are handled.

   Deletions
       When  you use dcmodify to delete a private reservation tag, please note
       that dcmodify  wont  touch  the  private  tags  that  are  under  this
       reservation.  The  user  is  forced  to  handle the consistency between
       reservations and their pending private tags.

       For the deletion of private non-reservation tags there are  no  special
       issues.

CHANGING UIDS
       dcmodify  will  automatically correct Media Storage SOP Class UID and
       Media Storage SOP Instance UID in the metaheader, if you make changes
       to  the  related tags in the dataset (SOP Class UID and SOP Instance
       UID) via insert or modify mode options. You can disable this behaviour
       by using the -nmu option.

       If  you  generate  new  UIDs  with  -gst, -gse or -gin, this will only
       affect the UID you choosed to generate. So if you use -gst to  generate
       a  new  Study  Instance  UID,  then  Series  Instance  UID and SOP
       Instance UID will not be affected! This gives you the  possibility  to
       generate  each  value  separately.  Normally, you would also modify the
       underlying UIDs. As a disadvantage of this flexibility, the user  has
       to  assure,  that  when  creating  new DICOM files with new UIDs with
       dcmodify, other UIDs have to be updated by the user as necessary.

       When choosing the -gin  option,  the  related  metaheader  tag  (Media
       Storage  SOP  Instance  UID)  is updated automatically. This behaviour
       cannot be disabled.

ELEMENT VALUES FROM FILE
       In order to read the element value from a file instead of specifying it
       on  the  command line, option -mf and -if can be used. Please note that
       for OW elements, the data is expected to be little endian  ordered  and
       will  be  swapped  if necessary. The file size should always be an even
       number of bytes, i.e. no automatic padding is performed.

WILDCARDS
       dcmodify also permits the usage of a wildcard character  *  for  item
       numbers   in   path  expressions,  e.g.  ContentSequence[*].CodeValue
       selects  all  Code   Value   attributes   in   all   items   of   the
       ContentSequence. Using a wildcard is possible for all basic operations,
       i.e. modifying -m, inserting -i and -e options which makes it, together
       with  the automatic creation of intermediate path nodes a powerful tool
       for construction and processing complex datasets.

       The options -ma and -ea for modifying or deleting all occurences  of  a
       DICOM  element  based  on  its tag do not accept any wildcards but only
       work on single elements (i.e. a single dictionary name or tag key).

EXAMPLES
       -i   --insert:
              dcmodify -i "(0010,0010)=A Name" file.dcm
              Inserts the PatientName tag into file.dcm at 1st level.
              If tag already exists, -i will overwrite it!  If you want to
              insert an element with value multiplicity > 1 (e.g. 4) you
              can do this with: dcmodify -i "(0018,1310)=1\2\3\4"

              dcmodify -i "(0008,1111)[0].PatientName=Another Name" *.dcm
              Inserts PatientName tag into the first item of sequence
              (0008,1111).  Note that the use of wildcards for files is
              possible.  You can specify longer tag paths, too (e.g.
              "(0008,1111)[0].(0008,1111)[1].(0010,0010)=A Third One").
              If any part of the path, e.g. the sequence or the item "0"
              does not exist, it is automatically inserted by dcmodify.

              dcmodify -i "(0008,1111)[*].PatientName=Another Name" *.dcm
              Inserts PatientName tag into _every_ item of sequence
              (0008,1111).  Note that the use of wildcards for files is
              possible.  You can specify longer tag paths, too (e.g.
              "(0008,1111)[*].(0008,1111)[*].(0010,0010)=A Third One").

       -if  --insert-from-file:
              dcmodify -if "PixelData=pixel.raw" file.dcm
              Inserts the content of file pixel.raw into the PixelData element
              of file.dcm.  The contents of the file will be read as is.
              OW data is expected to be little endian ordered and will be
              swapped if necessary.  No checks will be made to ensure that the
              amount of data is reasonable in terms of other attributes such as
              Rows or Columns.

       -m   --modify:
              dcmodify -m "(0010,0010)=A Name" file.dcm
              Changes tag (0010,0010) on 1st level to "A Name".

              This option also permits longer tag paths as demonstrated
              above for -i. If the leaf element or any intermediate
              part of the path does not exist, it is not inserted as it
              would be if using the -i option.

              dcmodify -m "(0010,0010)=A Name" -imt file.dcm
              Changes tag (0010,0010) on 1st level to "A Name". Due to the
              given option -imt, success is returned instead of "tag not found",
              if the element/item (or any intermediate node in a longer path) does
              not exist.

              Note that for the -m option the last node in the path must be
              a leaf element, i.e. not a sequence or an item.

       -mf  --modify-from-file:
              dcmodify -mf "PixelData=pixel.raw" file.dcm
              Does the same as -if in case there was already a PixelData element
              in file.dcm.  Otherwise nothing is changed.

       -ma  --modify-all:
              dcmodify -ma "(0010,0010)=New Name" file.dcm
              Does the same as -m but works on all matching tags found in
              file.dcm.  Therefore, it searches the whole dataset including
              sequences for tag (0010,0010) and changes them to "New Name"

       -e   --erase:
              dcmodify -e "(0010,0010)" *.dcm
              Erases tag (0010,0010) in all *.dcm files at 1st level.

              This option also allows longer tag paths as demonstrated
              above for -i.

              dcmodify -e "(0010,0010)" -imt *.dcm
              Erases tag (0010,0010) in all *.dcm files at 1st level. Due to the
              given option -imt, success is returned instead of "tag not found",
              if the element/item (or any intermediate node in a longer path) does
              not exist.

       -ea  --erase-all:
              dcmodify -ea "(0010,0010)" *.dcm
              Same as -e, but also searches in sequences and items.

       -ep  --erase-private:
              dcmodify -ep *.dcm
              Deletes all private tags (i.e. tags having an odd group number) from
              all files matching *.dcm in the current directory.

       -gst --gen-stud-uid:
              dcmodify -gst file.dcm
              This generates a new value for the StudyInstanceUID
              (0020,000d).  Other UIDs are not modified!

       -gse --gen-ser-uid:
              dcmodify -gse file.dcm
              This generates a new value for the SeriesInstanceUID
              (0020,000e).  Other UIDs are not modified!

       -gin --gen-inst-uid:
              dcmodify -gin file.dcm
              This command generates a new value for the SOPInstanceUID
              (0008,0018).  The corresponding MediaStorageSOPInstanceUID
              (0002,0003) is adjusted to the new value automatically.
              Please note that its not possible to avoid this metaheader
              update via the -nmu option.

       -nmu --no-meta-uid:
              dcmodify -m "SOPInstanceUID=[UID]" -nmu *.dcm
              This will modify the SOPInstanceUID to the given [UID],
              but -nmu avoids, that dcmodify adjusts the
              MediaStorageSOPInstanceUID in the metaheader, too.


ERROR HANDLING
       dcmodify tries executing each modify operation given on  command  line:
       If one returns an error, the others are being performed anyway. However
       in case of any error, the  modified  file  is  not  saved,  unless  the
       --ignore-errors  option  is  specified.  If  that  option  is selected,
       dcmodify  also  continues  modifying   further   files   specified   on
       commandline;  otherwise  dcmodify  exits  after the first file that had
       modification errors.

       If the --ignore-missing-tags option is enabled,  any  modify  or  erase
       operations (i.e. not --insert) that fails because of a non-existing tag
       is treated as being successful. That does make sense if  someone  wants
       to  be sure that specific tags are not present in the file or that - if
       they exist - that they are set to a specific value.

LOGGING
       The level of logging output of  the  various  command  line  tools  and
       underlying  libraries  can  be  specified by the user. By default, only
       errors and warnings are written to the  standard  error  stream.  Using
       option  --verbose  also  informational messages like processing details
       are reported. Option --debug can be used to get  more  details  on  the
       internal  activity,  e.g.  for debugging purposes. Other logging levels
       can be selected using option --log-level. In --quiet  mode  only  fatal
       errors  are reported. In such very severe error events, the application
       will usually terminate. For  more  details  on  the  different  logging
       levels, see documentation of module oflog.

       In  case  the logging output should be written to file (optionally with
       logfile rotation), to syslog (Unix) or the event log  (Windows)  option
       --log-config  can  be  used.  This  configuration  file also allows for
       directing only certain messages to a particular output stream  and  for
       filtering  certain  messages  based  on the module or application where
       they are generated.  An  example  configuration  file  is  provided  in
       <etcdir>/logger.cfg).

COMMAND LINE
       All  command  line  tools  use  the  following notation for parameters:
       square brackets enclose optional  values  (0-1),  three  trailing  dots
       indicate  that multiple values are allowed (1-n), a combination of both
       means 0 to n values.

       Command line options are distinguished from parameters by a leading +
       or  - sign, respectively. Usually, order and position of command line
       options are arbitrary (i.e. they  can  appear  anywhere).  However,  if
       options  are  mutually exclusive the rightmost appearance is used. This
       behaviour conforms to the standard  evaluation  rules  of  common  Unix
       shells.

       In  addition,  one  or more command files can be specified using an @
       sign as a prefix to the filename (e.g. @command.txt).  Such  a  command
       argument  is  replaced  by  the  content of the corresponding text file
       (multiple whitespaces are treated as a  single  separator  unless  they
       appear  between  two  quotation marks) prior to any further evaluation.
       Please note that a command file cannot contain  another  command  file.
       This   simple   but  effective  approach  allows  to  summarize  common
       combinations of options/parameters and  avoids  longish  and  confusing
       command lines (an example is provided in file <datadir>/dumppat.txt).

ENVIRONMENT
       The  dcmodify  utility  will  attempt  to  load DICOM data dictionaries
       specified in the DCMDICTPATH environment variable. By default, i.e.  if
       the   DCMDICTPATH   environment   variable   is   not   set,  the  file
       <datadir>/dicom.dic will be loaded unless the dictionary is built  into
       the application (default for Windows).

       The   default   behaviour  should  be  preferred  and  the  DCMDICTPATH
       environment variable only used when alternative data  dictionaries  are
       required.  The  DCMDICTPATH environment variable has the same format as
       the Unix shell PATH variable in that a colon (:)  separates  entries.
       On  Windows systems, a semicolon (;) is used as a separator. The data
       dictionary code will  attempt  to  load  each  file  specified  in  the
       DCMDICTPATH  environment variable. It is an error if no data dictionary
       can be loaded.

COPYRIGHT
       Copyright (C) 2003-2010 by OFFIS e.V., Escherweg  2,  26121  Oldenburg,
       Germany.



Version 3.6.0                     6 Jan 2011                       dcmodify(1)
