12.1. Clara DICOM Adapter

Designed for the Clara Deploy SDK, the Clara DICOM Adapter implements the necessary DICOM services for interoperability between Clara and other medical devices. The Clara DICOM Adapter allows you to send/receive DICOM objects using standard DICOM protocols and interpret standard DICOM part-10 formats.

This container requires Docker 18.09.2 or higher.

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

12.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, use the following command to stop the service first:

            

            
clara dicom stop
        

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

• dicom

  • scp: DICOM SCP Service settings

  • scu: DICOM SCU service settings

• pipeline-mappings: Pipeline mappings that map Clara AE Titles to pipelines

The Clara DICOM Adapter allows multiple Clara AE Titles to be configured so that each AE Title is mapped to a pipeline with a single DICOM destination.

12.1.3.1.CLI

If read-aetitles-from-crd, read-sources-from-crd and/or read-destinations-from-crd are set to true, the Clara CLI tool can be used to configure Clara AE Titles, DICOM Sources and/or DICOM Destinations respectively. RESTful APIs may also be used for the same purpose.

12.1.3.2.Samples

12.1.3.2.1.Mapping Clara AE Titles to Pipelines

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

12.1.3.2.1.1.ct_ai_pipeline

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

12.1.3.2.1.2.mammo_ai_pipeline

            

            
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: 0fcdcdea89c6456fb20abc7379c54ef2
  - name: mammo_ai_pipeline
    clara-ae-title: NVIDIADGX101
    pipeline-id: 3c9d3b9386d44bc2b89b7a12de9f7bda
        

12.1.3.3.Schema

            

            
dicom:
  scp: #DICOM SCP configurations.
    port: #(int, optional) Default 104. DICOM SCP Port number.
    read-aetitles-from-crd: true # (bool). Default true. Gets or sets whether or not to read Clara AE Titles from Kubernetes CRD. When true, "ae-tiles" list is not used.
    read-sources-from-crd: true #(bool). Default true. Get or sets whether or not to read source AE Titles from Kubernetes CRD. When true, "sources" list is not used.
    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.
        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.
    log-dimse-datasets: #$(bool, optional) Default false. Gets or sets whether or not to write command and data datasets to log.
    log-data-pdus: #$(bool, optional) Default false. Gets or sets whether or not to write message to log for each P-Data-TF PDU sent or received.
    read-destinations-from-crd: # (bool) Default true. Gets or sets whether or not read and use destinations from Kubernetes CRD.  WHen true, "destinations" list is not used.
    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) A 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 SDK) Endpoint of the Platform API.
    results-service-endpoint: http://localhost:50080  #(string, optional when using Clara SDK) Endpoint of the Results Service API.
        

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

• CLARA_SERVICE_HOST

• CLARA_SERVICE_PORT_API

• CLARA_RESULTSSERVICE_SERVICE_HOST

• CLARA_RESULTSSERVICE_SERVICE_PORT

12.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 are uploaded to the Clara Payloads CRD service after the timeout elapses.

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

12.1.4.2.DICOM SCU Service

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

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

12.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.

12.1.5.1.1.DIMSE Services (SCP)

• C-STORE: Accepts incoming DICOM objects

• C-ECHO: Accepts incoming DICOM verification requests

12.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.

12.1.5.1.3.Association Policies

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

• Clara DICOM Storage SCP accepts two (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”.

• An association must be released properly 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.

12.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.

12.1.5.2.DICOM SCU

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

12.1.5.2.1.DIMSE Services (SCU)

C-STORE: Sends 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.

12.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 the stored Transfer Syntax, without the support of compression, decompression, or Transfer Syntax Conversion.

12.1.5.2.3.Association Policies

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

• Clara DICOM Storage SCU allows two (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”.

12.1.5.2.4.Security Profiles

Not applicable

Clara DICOM Adapter supports the following RESTful APIs on (default) port 5000.

12.1.6.1.GET /api/config/claraaetitle

12.1.6.2.GET /api/config/sourceaetitle

12.1.6.3.GET /api/config/destinationaetitle

Retrieves list of (Clara|Source|Destination) AE Titles.

12.1.6.3.1.Parameters

N/A

12.1.6.3.2.Responses

Response Content Type: JSON

Returns list of AE Titles (in Kubernetes CRD JSON format):

12.1.6.3.3.Example Request

            

            
curl --location --request GET 'http://localhost:5000/api/config/destinationaetitle'
        

12.1.6.4.POST /api/config/claraaetitle

Create a new Clara AE Title.

12.1.6.4.1.Parameters

Required fields listed below. Refer to Schema section for complete list.

12.1.6.4.2.Responses

Response Content Type: JSON

Returns created CRD formatted in JSON.

12.1.6.4.3.Example Request

            

            
curl --location --request POST 'http://localhost:5000/api/config/claraaetitle' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "clara-brain-tumor",
"pipelineId": "7b9cda79ed834fdc87cd4169216c4011",
"aeTitle": "BrainTumorModel",
"timeout": 0
}'
        

12.1.6.5.POST /api/config/sourceaetitle

Create a new Source AE Title.

12.1.6.5.1.Parameters

Required fields listed below. Refer to Schema section for complete list.

12.1.6.5.2.Responses

Response Content Type: JSON

Returns created CRD formatted in JSON.

12.1.6.5.3.Example Request

            

            
curl --location --request POST 'http://localhost:5000/api/config/sourceaetitle' \
--header 'Content-Type: application/json' \
--data-raw '{
"hostIp": "1.2.3.4",
"aeTitle": "Orthanc"

}'
        

12.1.6.6.POST /api/config/destinationaetitle

Create a new Destination AE Title.

12.1.6.6.1.Parameters

Required fields listed below. Refer to Schema section for complete list.

12.1.6.6.2.Responses

Response Content Type: JSON

Returns created CRD formatted in JSON.

12.1.6.6.3.Example Request

            

            
curl --location --request POST 'http://localhost:5000config/destinationaetitle' \
--header 'Content-Type: application/json' \
--data-raw '{
"name":"pacs",
"hostIp": "10.20.30.40",
"aeTitle": "ARCHIVEX",
"port": 104

}'
        

12.1.6.7.DELETE /api/config/claraaetitle/[name]

12.1.6.8.DELETE /api/config/sourceaetitle/[name]

12.1.6.9.DELETE /api/config/destinationaetitle/[name]

Deletes a (Clara|Source|Destination) AE Title.

12.1.6.9.1.Parameters

12.1.6.9.2.Responses

Response Content Type: JSON

Returns status of the deleted CRD.

12.1.6.9.3.Example Request

            

            
curl --location --request DELETE 'http://localhost:5000/api/config/claraaetitle/clara-brain-tumor' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "clara-brain-tumor1",
"pipelineId": "7b9cda79ed834fdc87cd4169216c4011",
"aeTitle": "BrainTumor1",
"timeout": 0
}'
        

12.1.7.1.0.6.0

• ➕New: configure Clara AE-Titles, Sources and *Destinations via Kubernetes CRD is added which allows user to add a new Clara AE-Title and associate it with a Clara Pipeline without restarting DICOM Adapter. DICOM sources and destination can also be added via CRD.

• ➖Removed: timeout-group is no longer supported. This can be replaced by custom plug-in if required. timeout is still supported to accept multiple associations and associate al received DICOM instances with a Clara job.

12.1.8.1.DICOM Toolkits

• fo-dicom .NET

• dcmtk C++

• pydicom Python

• go-dicom Go