How to Run a Reference Pipeline

Clara Deploy SDK comes bundled with a set of reference pipelines. This section provides general guidelines for executing them on your local development machine. For information specific to a reference pipeline, please view the documentation for that pipeline.

Download the Reference Pipeline

Refer to Setup section for downloading the pipeline.

Run Reference Pipelines by Sending DICOM Instances Over the Network

Many reference pipelines are triggered by the Clara DICOM Adaptor after it has received DICOM instances from an external sender to one of its mapped AE Titles.

This section explains the process with an example Brain Tumor Segmentation Pipeline.

External DICOM Sender and DICOM Receiver

You need an external DICOM Service Class User (SCU) application to send images to the Clara DICOM Adapter (acting as a DICOM SCP). Similarly, when your pipeline finishes executing, you may want to send the output to an external DICOM receiver.

For this example, we will use the open-source DICOM toolkit DCMTK to provide the external DICOM sender and DICOM receiver functionality.

Install DCMTK

Install DCMTK utilities with the following command:

sudo apt-get install dcmtk

Setup an External DICOM Receiver

You can use the storescp utility as an external DICOM receiver. Open a terminal and run the following commands to set up a DICOM Receiver. This will create a directory on your machine where DICOM images produced by Clara Deploy SDK will be stored. We will refer to that directory as the "dicom-destination-directory".

mkdir dicom-destination-directory
cd dicom-destination-directory
sudo storescp -v --fork -aet MYPACS 1004

• MYPACS: The Application Entity (AE) title of the external DICOM Receiver

• 1004: The port number where storescp will listen for any incoming DICOM traffic. Note that the IP address will be the same as that of the local system.

Setup an External DICOM Sender

You can use the storescu utility from DCMTK as a DICOM sender.

Customize the Pipeline

Before publishing a pipeline, you can modify the default settings in the pipeline definition YAML to configure the resource request and orchestration mode. We will use the brain-tumor-pipeline.yaml to show the steps.

Customize GPU request

If multiple GPUs are available, the number of GPUs requested for an operator and/or pipeline depedent service (e.g. TensorRT Inference Server) can be customized.

The GPU request for TensorRT Inference Server is set to 1 by default, as shown below:

- name: trtis
  # TensorRT Inference Server, required by this AI application.
    container:
      image: nvcr.io/nvidia/tensorrtserver
      tag: 19.08-py3
      command: ["trtserver", "--model-store=$(NVIDIA_CLARA_SERVICE_DATA_PATH)/models"]
    requests:
      gpu: 1

With the default setting, the TensorRT Inference Server can only access one GPU. When more GPUs are available and intended to increase inference performance, the GPU request number may be customized to match the desired number (e.g. 4), as shown below:

- name: trtis
  # TensorRT Inference Server, required by this AI application.
    container:
      image: nvcr.io/nvidia/tensorrtserver
      tag: 19.08-py3
      command: ["trtserver", "--model-store=$(NVIDIA_CLARA_SERVICE_DATA_PATH)/models"]
    requests:
      gpu: 4

Note: If another pipeline with a lesser number of GPUs for the TensorRT Inference Server has been published and triggered, the changes made here will not affect that instance of TensorRT Inference Server.

Customize the Orchestration Mode

In this release of the Clara Deploy Platform, Clara Pipeline Driver orchestration is supported, in addition to the Argo-based orchestration mode.

This mode can be customized with the api-version attribute in the pipeline definition YAML file: Setting the api-version to 0.3.0 causes the pipeline to run in Argo mode, whereas setting it to 0.4.0 enables the Clara Pipeline Driver mode. The following example from the brain-tumor-pipeline.yaml specifies Argo mode:

api-version: 0.3.0
name: brain-tumor-pipeline

Create the Pipeline

Please refer to the Setup section to create this Pipeline.

Tip: Note the pipeline ID as it will be used in a later section to define a new pipeline mapping in the DICOM adapter.

Configure the Clara DICOM Destination

When you send images to the Clara Deploy SDK, the DICOM Adapter component acts as the internal DICOM Service Class Provider or a receiving agent.

• Open the ~/.clara/charts/dicom-adapter/files/dicom-server-config.yaml file.
• In the dicom->scp->sources section, ensure sender host-ip and ae-titles are correct. Alternatively, set reject-unknown-sources to false, which will allow any DICOM sender to create an association.

dicom:
 scp:
 reject-unknown-sources: false
 sources:
 - host-ip: 172.22.8.156
 ae-title: DCM4CHEE

• In the dicom->scp->ae-titles section, add a new ae-title with the name BrainSeg:

dicom:
 scp:
 ae-titles:
 - ae-title: BrainSeg

Note: Per the DICOM standard, the length of the ae-Title value should not exceed 16 characters.

• In the pipeline-mappings section, define a new mapping with brain-Seg as the name and BrainSeg as the clara-ae-title, and use the pipeline-id that was created earlier:

pipeline-mappings:
- name: brain-seg
 clara-ae-title: BrainSeg
 pipeline-id: [your-pipeline-id-from-above]

• Update the IP address of the MYPACS destination by changing the host-ip field to the IP of your local development machine:

dicom:
 scu:
 destinations:
 - name: MYPACS
 host-ip: [IP-address-of-remote-PACS]
 port: 1004
 ae-title: MYPACS

• Restart the DICOM server by issuing the following commands:

# Stop DICOM Adapter by running the following command:
clara dicom stop
# Run the following command to check whether the DICOM adapter pod is still running:
kubectl get pods | grep clara-dicom-adapter
# Once the DICOM adapter pod is fully stopped and no pod is returned with the above command, the DICOM adapter can be started by running the following command:
clara dicom start

• Verify that the DICOM Adapter is correctly started:

helm ls | grep dicom-adapter
kubectl get pods | grep dicom-adapter

Trigger the Pipeline

A pipeline is triggered when a DICOM series is sent to the AE title of the Clara DICOM Adapter associated with that pipeline. To trigger this pipeline, you will need a set of relevant DICOM images that can be used as source input data.

For this pipeline, a sample test dataset in DICOM format is available within the package in <unzipped input>/dcm.

1. Open a terminal and go to the directory that contains all your DICOM images.

2. Trigger the pipeline by pushing DICOM data to the proper AE title:

storescu -v +sd +r -xb -aet "DCM4CHEE" -aec "BrainSeg" AA.BBB.CC.DD 104 ./

Replace "AA.BBB.CC.DD" with the IP of your local machine.

When the above step is successfully completed, you should see the following result in the terminal:

I: Received Store Response (Success) <br>
I: Releasing Association

Verify the Pipeline Execution in Dashboard

Go to the Clara dashboard UI using a web browser: The URL is <machine-ip>:8000.

• You should see a job with a name that includes the name of the pipeline you created.
• You can inspect the status of each operator inside that job
• Using the UI to view the status of Pipeline Jobs executed using the "Clara orchestrator" option is currently not available.

Verify That the External DICOM Receiver Received Your Images

If your pipeline outputs DICOM images and sends them to an external DICOM receiver, you may want to verify that the images were indeed received. If you used the storescp utility from DCMTK as mentioned earlier, use a terminal to navigate to the "dicom-destination-directory" and verify whether the expected images are stored there. Also, you may want to use a third-party DICOM viewer to view those images.