LinuxForHealth DICOM rules engine

The LinuxForHealth DICOM rules engine is a Java based library that enables writing filtering rules for DICOM using standard DICOM tags. The rules for the engine cane be defined in a YAML or JSON format.

Development Quickstart

The DICOM rules engine has the following dependencies:

• JDK 11 or later
• Gradle

Note: The DICOM rules engine includes a Gradle Wrapper, so a local Gradle install is not required.

Clone and build the project:

git clone git@github.com:LinuxForHealth/dicom-rules-engine.git
cd dicom-rules-engine
./gradlew build

Using The DICOM Rules Engine In A Java Application

The DICOM rules engine library is available as a maven dependency.

Library Coordinates

groupId = io.github.linuxforhealth
artifactId = dicom-rules-engine
version = 1.0.2

Maven dependency

<dependency>
  <groupId>io.github.linuxforhealth</groupId>
  <artifactId>dicom-rules-engine</artifactId>
  <version>1.0.2</version>
</dependency>

Gradle dependency:

    implementation 'io.github.linuxforhealth:dicom-rules-engine:1.0.2'

Introduction:

The purpose of the rule engine is to provide mechanism to specify conditions to identify /filter DICOM studies for conditional processing based on pre-configured rules. The rule will evaluate a DICOM file and return the evaluation result. There are different types of rules evaluator for different types of DICOM data.

• BasicRulesEvaluator -- can be used if provided DICOM data is as List of attributes (check DicomAttributeFact)
• DicomFileRulesEvaluator -- can be used if provided DICOM data is DCM file (check FileFact)
• DicomJsonRulesEvaluator-- can be used if provided DICOM data is in JSON format (check DicomJsonFact)
• DicomStreamRulesEvaluator-- can be used if provided DICOM data is inputstream from DCM file (check InputStreamFact)

DICOM rules have following concepts

• Rule Definition: is a collection of rules and conditions.
• Rule Group Id: unique label for group of rules using common conditions.
• Condition - Condition evaluates a single DICOM tag against a predefined predicate.
• Rule – Rule is collection of conditions joined with AND/ORs.
• RuleEvaluationResult: This object holds the results of the rules evaluation. The rules evaluator evaluates all rules defined in the rules definition file.

How to create and configure rules

• Rules for the engine can be defined in a JSON or YAML file.
• Each rule has the following attributes.

Structure of a DICOM Rule

* groupid: (REQUIRED) unique label (no spaces allowed)
* attribute_name_delimiter: (OPTIONAL) character used to split nested attributes, example 000982335.000982333
* conditions: Map of conditions. <Unique name>:<condition>
   - Condition: Condition can be of two types, BiCondition or SimpleCondition. BiCondition has variable, predicate and constant value for maatching.
       Variable always starts with a '$'. Simple condition only has a variable and predicate.
* rules:  this is map of rules. <unique ruleIdentifier>:<rule>
  - Rule: Each rule is defined using conditions, where conditions are joined using &&/|| and can be nested using ().   

Structure of a DICOM Condition

Condition

* variable: DICOM tag example: 00081030,    * 
* operator: condition operator to use for this condition, details below.
* match_value: value/values for matching

Supported DICOM Data element value type, for match_value/match_values.

• String
• Integer
• List

List of supported String type tag operators

* EQUALS - DICOM string tag value is equal to  the value provided in the rule.
* STRING_IS_NULL - DICOM string tag value is null.
* NOT_EQUALS - DICOM string tag value is not equal to  the value provided in the rule.
* STARTS_WITH - DICOM string tag value starts with to  the prefix value provided in the rule.
* NOT_STARTS_WITH - DICOM string tag value does not starts with the prefix value provided in the rule.
* ENDS_WITH - DICOM string tag value ends with the suffix value provided in the rule.
* NOT_ENDS_WITH - DICOM string tag value does not ends with the suffix value provided in the rule.
* CONTAINS - DICOM string tag value contains the value provided in the rule.
* NOT_CONTAINS - DICOM string tag value does not contains  the value provided in the rule.
* IN_EQUALS - DICOM string tag value is equal to (ignore case) any of the values provided in the rule.
* IN_CONTAINS - DICOM string tag value contains (ignore case) any of the values provided in the rule.
* NOT_IN_EQUALS - DICOM string tag value is not equal to (ignore case) any of the values provided in the rule.
* NOT_IN_CONTAINS - DICOM string tag value does not contains (ignore case) any of the values provided in the rule.

List of supported Integer type tag operators

* EQUAL_TO - DICOM integer tag value is equal to the values provided in the rule.
* GREATER_THAN  - DICOM integer tag value is greater than the values provided in the rule.
* LESS_THAN - DICOM integer tag value is less than the values provided in the rule.
* GREATER_OR_EQUAL - DICOM integer tag value is greater than or equal to the values provided in the rule.
* LESS_OR_EQUAL - DICOM integer tag value is less than or equal the values provided in the rule.

List of supported List type tag operators

* EMPTY - DICOM tag value of list type is empty.
* NOT_EMPTY - DICOM tag value of list type is not empty.
* ANY_CONTAINS -  Any of the list of values for a DICOM tag contains value provided in the rule.
* ANY_NOT_CONTAINS- None of the list of values for a DICOM tag contains value provided in the rule.
* ANY_EQUALS- Any of the list of values for a DICOM tag is equal to the value provided in the rule.
* ANY_NOT_EQUALS - None of the list of values for a DICOM tag contains value provided in the rule.
* ANY_IN_EQUALS - Any of the list of values for a DICOM tag is equal to (ignore case) any of the values provided in the rule.
* ANY_NOT_IN_EQUALS - None of the list of values for a DICOM tag is equal to (ignore case) any of the values provided in the rule.
* ANY_IN_CONTAINS -Any of the list of values for a DICOM tag contains (ignore case) any of the values provided in the rule.
* ANY_NOT_IN_CONTAINS- Any of the list of values for a DICOM tag not contains (ignore case) any of the values provided in the rule.
* LIST_SIZE_EQUAL- DICOM tag value list size is equal to the value provided in the rule.
* LIST_SIZE_GREATER_THAN- DICOM tag value list size is greater than the value provided in the rule.
* LIST_SIZE_LESS_THAN- DICOM tag value list size is less than the value provided in the rule.
* NOT_CONTAINS_ALL- List of values for a DICOM tag not contain (ignore case) all the values provided in the rule.
* CONTAINS_ALL- List of values for a DICOM tag contain (match is case sensitive) all the values provided in the rule.

Usage

Example sample rule file:

{
  "ruleDefinitions": [
    {
      "groupid": "queue1rules",
      "conditions": {
        "condition1": "$00080018 EQUALS 1.2.826.0.1.3680043.8.1055.1.20111102150800481.27482048.30798145",
        "condition2": "$0020000E EQUALS 1.2.826.0.1.3680043.8.1055.1.20111102150758591.96842950.07877442"
            },
      "rules": {
        "relevance_rule": "condition1 && condition2"
      }
    }
  ]
}

If rules are stored in rules file, example:rules.json

    File ruleFile = new File(<path to rules.json>);
    DicomFileRulesEvaluator eval = new DicomFileRulesEvaluator(ruleFile);
    RulesEvaluationResult results = eval.apply(new FileFact(dcm)); // provide path to DICOM File 
    assertThat(results.getResultOfRule("relevance_rule").isSuccess()).isTrue();
    
    

If JSON representation of rules are read and stored in String object rulesDefination

   
    DicomFileRulesEvaluator eval = new DicomFileRulesEvaluator(rulesDefination, Format.JSON);
    RulesEvaluationResult results = eval.apply(new FileFact(dcm)); // provide path to DICOM File 
    assertThat(results.getResultOfRule("relevance_rule").isSuccess()).isTrue();