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 tag's 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 doesn't know the tag it should insert, then the tag's 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 can't 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
don't backup files (DANGEROUS)
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
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 you've listed it in your dictionary (see
<docdir>/datadict.txt for details). If it's not listed,
dcmodify will insert it with VR=UN. Also, for some cases insertion may
even fail for some values.
If you've got your private tag in the dictionary,
dcmodify acts as
follows: When it finds a reservation in the tag's 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 doesn't 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 won't check its VR against
the dictionary. So please be careful to enter only values that match the tag's
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 won't 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 UID's 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 it's 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.