11.1. DICOM Adapter

The Clara DICOM Adapter is designed for the Clara Deploy SDK. It implements the necessary DICOM services for interoperability between Clara and other medical devices. The Clara DICOM Adapter allows receiving and sending of DICOM objects using standard DICOM protocols and interprets standard DICOM part 10 formats.

11.1.1. Requirements

This container requires Docker 18.09.2 or higher.

11.1.2. Running the Clara DICOM Adapter

Before running the container, remove any existing installation and ensure an up-to-date image is installed.

11.1.2.1. To Run the Clara DICOM Adapter Using the Clara CLI

To configure the DICOM Adapter, update ~/.clara/charts/dicom-adapter/files/dicom-server-config.yaml and then run the following command:

clara dicom start

If the DICOM Adapter is already running, please use the following command to stop the service first:

clara dicom stop

11.1.3. Configuration

The DICOM Adapter configuration (app.yaml) is a YAML formatted configuration file. It contains the following sections:

  • dicom

    • scp: DICOM SCP Service settings

    • scu: DICOM SCU service settings

  • pipeline-mappings: Pipeline mappings - maps a Clara AE Title to a pipeline

The Clara DICOM Adapter allows multiple Clara AE Titles to be configured where each AE Title can be mapped to a pipeline with one DICOM destination.

11.1.3.1. Samples

11.1.3.1.1. Mapping Clara AE Title to a Pipeline

The following sample configuration has two pipelines configured which accepts DICOM associations from a source AE Title DCM4CHEE with IP address 1.2.3.4 (dicom>scp>sources):

11.1.3.1.1.1. ct_ai_pipeline

DICOM files that are sent to Clara AE Title NVIDIADGX100 (dicom>scp>ae-titles) in the association are grouped in one single batch. When the association is closed, the DICOM Adapter triggers the pipeline configured, which is 0fcdcdea-89c6-456f-b20a-bc7379c54ef2. When the pipeline job completes, the results are sent to destinations configured in the pipeline definition.

External DICOM Device C-STORE => NVIDIADGX100 => Pipeline (0fcdcdea-89c6-456f-b20a-bc7379c54ef2) => Results Service => DICOM SCU

11.1.3.1.1.2. mammo_ai_pipeline

External DICOM Device C-STORE => NVIDIADGX101 => Pipeline (3c9d3b93-86d4-4bc2-b89b-7a12de9f7bda) => Results Service => DICOM SCU

dicom:
  scp:
    port: 104
    ae-titles:
      - ae-title: NVIDIADGX100
      - ae-title: NVIDIADGX101
    max-associations: 2
    sources:
      - host-ip: 1.2.3.4
        ae-title: DCM4CHEE
  scu:
    ae-title: ClaraSCU
    max-associations: 2
    destinations:
      - name: MyOrthanc
        host-ip: 1.2.3.5
        port: 104
        ae-title: ORTHANC
      - name: PACS
        host-ip: 1.2.3.6
        port: 104
        ae-title: DCM4CHEE
pipeline-mappings:
  - name: ct_ai_pipeline
    clara-ae-title: NVIDIADGX100
    pipeline-id: 0fcdcdea-89c6-456f-b20a-bc7379c54ef2
  - name: mammo_ai_pipeline
    clara-ae-title: NVIDIADGX101
    pipeline-id: 3c9d3b93-86d4-4bc2-b89b-7a12de9f7bda

11.1.3.1.2. Grouping DICOM Data by Association

In this sample configuration, DICOM files may be pushed to NVIDIADGX100 in multiple associations as long as all the files are received within the configured timeout value, 300 seconds. When the timeout period has elapsed, Clara DICOM Adapter triggers the configured pipeline as shown in the above example.

dicom:
  scp:
    port: 104
    ae-titles:
      - ae-title: NVIDIADGX100
        timeout: 300
        timeout-group: Association
...

11.1.3.1.3. Grouping DICOM Data by Patient ID (0010,0020)

This configuration is similar to the sample configuration above. The difference is that received instances are grouped by the Patient ID (0010,0020). This means multiple timers are created; one timer per each distinct Patient ID. If a Patient ID does not receive any new instances within the configured timeout, 300 seconds, a new job is triggered with the configured pipeline.

dicom:
  scp:
    port: 104
    ae-titles:
      - ae-title: NVIDIADGX100
        timeout: 300
        timeout-group: Patient
...

11.1.3.2. Schema

dicom:
  scp: #DICOM SCP configurations.
    port: #(int, optional) Default 104. DICOM SCP Port number.
    ae-titles: #(string[], optional) Default ClaraSCP.
      - ae-title: ClaraSCP
        timeout: #(int, optional) Default 0 seconds.  Timeout to stop associating incoming DICOM instances to a pipeline job.  If no DICOM instances are received within the specified timeout period, a new pipeline job request is created for all received DICOM instances.  This is useful if multiple DICOM associations are used to transfer the data required for a pipeline job.
        timeout-group: #(enum: Association, Patient, optional) Default Association.   When the timeout value is greater than 0, the SCP service would group instances received based on this setting.  Association: groups all instances received within the timeout period. Patient: groups all instances with the same Patient ID (0010,0020) received within the timeout period.
        overwrite-same-instance: #(bool, optional) Default false. Overwrites existing DICOM instance with the same SOP Instance UID.
        ignored-sop-classes: #(Optional) List of SOP Class UIDs to ignore and not store on disk.
        processors: # (string, optional) List of file processors that are executed after association release or timeout.
          - "Nvidia.Clara.Dicom.Processors.JobProcessor, Nvidia.Clara.DicomAdapter" #Default if none configured. Processor that triggers a job based on the mapped pipeline.
    max-associations: #(int, optional) Default 2. Min: 1, Max:5. Maximum number of simultaneous associations.
    verification: #(Optional)
      enabled: #(bool, optional) Default true, Enable C-ECHO.
      transfer-syntaxes: # (string, optional) List of transfer syntax UIDs supported for Verification SOP class.
        - []
    reject-unknown-sources: #(bool, optional) Default true. Rejects calling AE Titles that are not defined in the source section.
    log-dimse-datasets: #$(bool, optional) Default false. Gets or sets whether or not to write command and data datasets to log.
    sources: #(Optional if reject-unknown-sources is false) List of DICOM sources.
      - host-ip: #(string) IP or host name.
        ae-title: #(string) AE Title.
  scu: #DICOM SCU configuration.
    ae-title: #(string) Clara SCU AE Title.  This is also used as the agent name of the Results Service.
    max-associations: #(int, optional) Default 2. Min: 1, Max:5. Maximum number of simultaneous associations.
    destinations: # (Optional) List of DICOM destinations.
      - name: #(string) Name of DICOM destination.
        host-ip: #(string) IP or host name.
        port: #(int) Port number.
        ae-title: #(string) AE Title.
pipeline-mappings:
  - name: #(string) Name of the pipeline.
    clara-ae-title: #(string) The Clara AE Title to associate a pipeline with.
    pipeline-id: #(string, optional) Name/ID of the pipeline to execute.
storage:
    temporary: ./storage #(string, optional) Path to the temporary storage that is used to store received DICOM instances.  Defaults to ./storage.
services:
    platform-endpoint: localhost:50051 #(string, optional when using Clara Deploy SDK) Endpoint of the Platform API.
    results-service-endpoint: http://localhost:50080  #(string, optional when using Clara Deploy SDK) Endpoint of the Results Service API.

Note: When using the DICOM Adapter, the platform-endpoint and results-service-endpoint are set using the following environment variables:

  • CLARA_SERVICE_HOST

  • CLARA_SERVICE_PORT_API

  • RESULTSSERVICE_SERVICE_HOST

  • RESULTSSERVICE_SERVICE_PORT

11.1.4. Usages

11.1.4.1. DICOM SCP Service

The SCP service accepts standard DICOM C-ECHO and C-STORE commands. Please see the DICOM Interface section for more information.

All received instances are saved immediately to the configured temporary storage location storage>temporary. With the default file processor Nvidia.Clara.Dicom.Processors.JobProcessor, all received instances, after timeout elapsed, are uploaded to Clara’s Payloads CRD service.

DICOM instances received are stored on disk as-is using the original transfer syntax as described in the DICOM Interface section. Users of the Clara Deploy SDK must handle the encoding/decoding of their DICOM files in their container(s). See Third Party Tools for a list of DICOM toolkits available for parsing, encoding or decoding DICOM files.

11.1.4.2. DICOM SCU Service

The DICOM SCU Service in the Clara DICOM Adapter queries the Clara Results Service for available tasks by using the Clara SCU AET as the agent name (dicom>scu>ae-title). Each task retrieved contains a list of DICOM files to be exported to the configured DICOM devices. If greater than 50% of the files failed to be exported, the job is marked as failed, reported back to the Results Service and will be retried at a later time with up to 3 retries.

Please note, DICOM instances are sent as-is, no codec conversion is done as part of the SCU process. See the DICOM Interface section for more information.

11.1.5. DICOM Interface

The following reference describes the connectivity capabilities of the Clara Deploy SDK out of the box. Users implementing the Clara Deploy SDK must update their DICOM Conformance Statement according to their actual application capabilities.

11.1.5.1. DICOM SCP

Clara DICOM SCP implements C-ECHO and C-Store services to interface with other medical devices, such as PACS. It allows users to define multiple AE Titles to enable DICOM communication and maps each AE Title to a pipeline.

11.1.5.1.1. DIMSE Services (SCP)

  • C-STORE - accepts incoming DICOM objects

  • C-ECHO - accepts incoming DICOM verification requests

11.1.5.1.2. SOP Classes (Transfer) and Transfer Syntax Supported

Clara DICOM SCP accepts any proposed transfer syntaxes and stores any accepted instances as-is on disk without any decoding support. Each AE Title may be configured to ignore and not save certain SOP Classes.

11.1.5.1.3. Association Policies

  • Clara DICOM Storage SCP accepts associations but does not initiate associations.

  • Clara DICOM Storage SCP accepts 2 (configurable) simultaneous associations.

  • Asynchronous mode is not supported. All operations are performed synchronously.

  • The Implementation Class UID is 1.3.6.1.4.1.30071.8 and the Implementation Version Name is fo-dicom 4.0.0.

  • Association must be released properly in order for received instances to be associated with a pipeline. Files received from an aborted association or an interrupted connection are either removed immediately or removed based on a configured timeout value.

11.1.5.1.4. Security Profiles

Clara DICOM Storage SCP does not conform to any defined DICOM Security Profiles. It is assumed that the product is used within a secured environment that uses a Firewall, Router Protection, VPN, and/or other network security provisions.

The Clara DICOM Storage SCP service can be configured to check the following DICOM values when determining whether to accept Association Open Requests:

  • Calling AE Title

  • Called AE Title

Clara SCP AE Title can be configured to accept Association Requests from only a limited list of Calling AE Titles.

11.1.5.2. DICOM SCU

Clara DICOM Storage SCU provides DICOM Storage Service to interface with other medical devices, such as PACS. It is executed at system startup and exists in a container using a single configurable AE Title.

11.1.5.2.1. DIMSE Services (SCU)

C-STORE - to send processed results that are stored in DICOM format

The Clara DICOM Storage SCU initiates a push of DICOM objects to the Remote DICOM Storage SCP. The system allows multiple remote SCPs to be configured.

11.1.5.2.2. SOP Classes (Transfer) Supported and Transfer Syntax

The DICOM Store SCU service supports all SOP classes of the Storage Service Class. The DICOM Store SCU service transfers a DICOM object as-is using stored Transfer Syntax without the support of compression, decompression or Transfer Syntax Conversion.

11.1.5.2.3. Association Policies

  • Clara DICOM Storage SCU initiates associations but does not accept associations.

  • Clara DICOM Storage SCU allows 2 (configurable) SCU instances simultaneously.

  • Asynchronous mode is not supported. All operations are performed synchronously.

  • The Implementation Class UID is 1.3.6.1.4.1.30071.8 and the Implementation Version Name is fo-dicom 4.0.0.

11.1.5.2.4. Security Profiles

Not applicable.

11.1.6. Third Party Tools

11.1.6.1. DICOM Toolkits

11.1.7. License

Licenses and model files are available. They can be pulled as part of the procedure described above or available in the Clara Deploy SDK. By pulling and using the container, you accept the terms and conditions of these licenses.

11.1.7.1. Third Party Licenses

11.1.8. Suggested Reading

For Release Notes, Getting Started Guide and Clara Deploy SDK, please visit the NVIDIA Developer forum at https://developer.nvidia.com/clara. Use the NVIDIA Devtalk forum at https://devtalk.nvidia.com/default/board/362/clara-sdk/ for questions regarding this release.