# DicomEdit

XNAT versions 1.7.0, 1.7.1, and 1.7.2 support DicomEdit 6.0 only.

XNAT 1.7.3 and greater supports scripts in both DicomEdit 6.1 format, and DicomEdit 4.2 format.

DicomEdit is a software library that provides the ability to read DICOM objects, transform their contents based on a scripted list of commands, and to output the transformed DICOM. Scripts are created by users in the small custom language defined by DicomEdit. Scripts can be general purpose, providing a general anonymization, or they can be customized to handle unique requirements posed by a specific project and its unique data sources.

DicomEdit 6.x is written in ANTLR and Java and is open source (BSD license). The source code is available in the XNAT DICOM DicomEdit4 code repository. It depends on the dcm4che2 DICOM Toolkit.

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

DicomEdit version 6.0 introduced some changes to the scripting language that are not backward compatible with previous versions of DicomEdit.  See the section 'Migration to version 6.0 scripts' below for details.

## Release Notes, version 6.1

New! Scripts starting with 6.1 must be versioned. A statement of the form ' version "6.1" ' must be the first statement in the script. Versions of scripts prior to 6.1 do not have this statement.

DicomEdit 6.1 is backwards compatible with 6.0 except that scripts must now be versioned.  Everyone is encouraged to migrate to 6.1.  However, there may be circumstances where moving to 6.1 is prohibited or too costly.  XNAT 1.7.3 is able to support both the legacy version 4.2 and new version 6 because it can now distinguish versions.

### Migration to version 6.1 scripts

// DicomEdit >= 6.1
version "6.1"

// DicomEdit 6.0 script below.......

## Release Notes, version 6.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.1 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 first statement must be 'version "6.0"'.
2. 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.
3. 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.
4. 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.

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