DicomEdit

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 DicomEdit6 code repository. It depends on the dcm4che2 DICOM Toolkit.

The language is described in detail in the DicomEdit 6.4 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.

DicomEdit can also be packaged to provide a run-able jar providing a stand-alone command-line tool.  See the instructions at DicomEdit6 code repository for instructions.

Release Notes

DicomEdit 6.4 Release Notes

DicomEdit 6.3 Release Notes

• DicomEdit 6.3 is backwards compatible with 6.0, 6.1, and 6.2. All previous 6.x scripts should work unchanged.
• New! Alter Pixels function: Blank PHI burned into pixel data.
• New! Match and IsMatch functions aid in conditional execution or extracting substrings to build values.
• New! Shift date-time by increment function:  Helps obscure dateTimes for privacy but retains the intervals between dates.
• New! Set function:  Enables direct addressing of private tags in non-conforming DICOM.
• New! Assign-if-exists operation '?=':  Assign value to an attribute only if it already exists in the DICOM. This complements the existing assign-always operation ':=' that will create the attribute if it does not exist.

DicomEdit 6.2 Release Notes

• DicomEdit 6.2 is backwards compatible with 6.0 and 6.1. All previous 6.x scripts should work unchanged.
• New! Hash Referenced UIDs function:  Keep references to anonymized objects in sync.
• New! Retain Private Tags function:  Remove all private tags except those specified explicitly.
• New! Shift date by increment function:  Helps obscure dates for privacy but retains the intervals between dates.
• New! Lookup function:  Enable values to be modified based on mappings defined in an external file.

DicomEdit 6.1 Release Notes

• 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

Add the version statement to your 6.0 scripts

// DicomEdit >= 6.1 version "6.1"   // DicomEdit 6.0 script below.......

DicomEdit 6.0 Release Notes

• 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'.

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.