This documentation describes DicomEdit 6.0, which is used in XNAT 1.7. Documentation for DicomEdit 4.2, which was used in XNAT 1.6.5 and earlier, can be found here: DicomEdit 4.2 Language Reference

DicomEdit defines a small language for specifying modifications to DICOM metadata. It is used by both DicomBrowser and XNAT for scripted metadata modification.

The reference implementation is written in ANTLR and Java and is open source (BSD license). Source code is available here. It depends on the dcm4che2 DICOM Toolkit.

The language is described in detail in the DicomEdit 6.0 Language Reference. The previous version is documented here. A FAQ will grow here.

Release Notes, version 6.0.0

Version 6.0 introduces new capabilities and major changes in its underlying implementation that should simplify support and future modifications. (In some cases, 'new' functionality existed in versions prior to 6.0 but is now documented.)

New! Support for private tags.  Private tags can be specified anywhere that public tags can be. The general syntax for private tags is (gggg,{<private-creator-id>}ee). The group is specified by the four hex digits gggg and the last digit will be odd. The <private-creator-id> is the string value that is used in the Private Creator Data Element (gggg,nn00) to reserve a block of tags nn for private use.  Thus, (0019,{SIEMENS MR HEADER}0F) will resolve to the correct tag, regardless of which values of nn that are used.

New! Individual elements in arbitrarily-deep sequences, public or private, can be addressed. For example, (0008,1155)[0]/(0008,0018) addresses the (0008,0018) tag within the first DICOM object within the (0008,1155) sequence.

New! An element can be addressed regardless of where in a sequence it appears, e.g. + / (0010, 0010) addresses Patient Name anywhere in a sequence except at the top level.

New! Conditional statements have been enhanced. Syntax now mirrors Java's ternary if-then-else operator.  Conditional statements have the form 'condition ? if-true-action : if-false-action', where ': if-false-action' is optional.

New! Two new conditional operators have been added: '!=' not equal, and '!~' does not match.

New! Syntax for removing all private tags. 'removeAllPrivateTags'.

Refer to the DicomEdit 6.0 Language Reference for in-depth documentation.

Migration to version 6.0 scripts

DicomEdit's implementation has been reworked to leverage advances in the underlying technologies. The grammar is now generated using ANTLR4. This has brought simplifications to how the scripting language's grammar is coded and the ability to simplify DicomEdit's implementation by extending a parse-tree visitor that is automatically generated by ANTLR4. Also, DicomEdit's interaction with DICOM objects has been abstracted behind an interface. This will ease the migration of DicomEdit from its use of the dcm4che2 DICOM library to dcm4ch3.

The downside of this rewrite is that some changes in the scripting language are not compatible with previous versions. This is the list of changes that you need to be aware of.

  1. The previously deprecated "new UID" 'generator' has been removed. (0002,0003) := new UID has been replaced with (0002,0003) := newUID[].  'newUID[]' is implemented in the same manner as all the other functions in DicomEdit. However, it is likely that the hashUID function is likely to be more useful.
  2. The syntax for conditional statements has changed. Prior to version 6.0, conditional statements have syntax 'condition : action'.  The operator ':' is binary, separating the condition from the action that occurs if the condition is true. With version 6.0, the conditional operator is '?' and ':' becomes an optional operator that specifies an action that is taken if the condition is false.
  3. The precedence of statement order has changed. It is now true that all statements are executed in the order they are encoded in the script. It used to be true that the first operation on a tag took effect and all subsequent modifications would be ignored. Now, "last one wins". A consequence of this is illustrated below.

    // DicomEdit version < 6.0
    project = "Unassigned" : (0008,1030) := (0008,1030)
    (0008,1030) := project

    This code functions like this. If the value of the variable named 'project' is "Unassigned", assign the value of (0008,1030), StudyDescription, to itself. A modification to (0008,1030) has occurred so the second statement will be ignored.  If project = "Unassigned" is not true, the first assignment does not occur so the second statement is not ignored and StudyDescription will receive the value of the 'project' variable.  This is more easily expressed as "change the value of StudyDescription only if the value of variable 'project' is not "Unassigned".  In DicomEdit >= 6.0, this will not work as coded above. The second assignment will never be ignored and StudyDescription will always get the value of 'project'.  One way to achieve this in DicomEdit >= 6.0 is as follows.

    // DicomEdit >= 6.0
    project != "Unassigned" ? (0008,1030) := project

    Notice that this statement uses the new ternary if-then-else operator and the new not-equal operator in the condition. No action is needed if the condition is false, so the optional if-false action is not used.

  4. All statements must be on a single line.  The backslash '\' no longer allows a statement to continue after a line break.