Clara Deploy SDK is being consolidated into Clara Holoscan SDK

More info https://catalog.ngc.nvidia.com/orgs/nvidia/teams/clara/collections/claradeploy

Clara Deploy DICOM Segmentation Writer Operator

CAUTION: Investigational device, not for diagnostic use. Limited by Federal (or United States) law to investigational use.

This research use only software has not been cleared or approved by FDA or any regulatory agency.

This asset requires the Clara Deploy SDK. Follow the instructions on the Clara Ansible page to install the Clara Deploy SDK.

Overview

This example application creates a DICOM Segmentation object from a segmentation mask image in MetaImage or NIfTI format, along with metadata extracted from the original DICOM Part 10 files. The output is a DICOM instance of modality type SEG, saved in a DICOM Part 10 file.

Inputs

This application, in the form of a Docker container, expects the following inputs:

• in the /input folder, by default, there must be a segmentation image file in MetaImage or NIfTI format
• In the /dcm folder, by default, the original DICOM instance files of the DICOM series that are used to generate the segmentation mask. The instance files can be in a subfolder under /dcm, but all instances of a single series must be within the same folder
• in the folder /series_selection, by default, the selected series image file, selected-images.json, output of DICOM Parser or Series Selection operator, whichever is used to select the series and its image for inference
• The labels for the segments are provided as a stringfied array of strings in the well-known environment variable, NVIDIA_SEG_LABELS. It is further assumed that the pixel value for the segments starts at 1 and increment sequentially. For example, in a lung and tumor segmentation, the pixel value for lung is 1, and tumor 2. The array assigned to the NVIDIA_SEG_LABELS is then '["lung", "tumor"]'. If the environment variable is not set or is blank, the application will assume a default segmentation label default-label for pixel value 1

The /input and /dcm folders need to be mapped to the host folders when the Docker container is started. If multiple series are in /dcm and series selection has been used to select specific series, then /series_selection need to be mapped to a folder containing the selected-images.json file.

Outputs

This application saves the DICOM Segmentation object to the output folder /output by default in DICOM Part 10 File Format. The file name is generated by suffixing the input file name with -DICOMSEG and the extension dcm. The output folder must be mapped to a host folder.

Logs generated by the application are saved in the folder /logs by default, which similarly must be mapped to a host folder.

Environment Variables

The application supports the following environment variables:

• NVIDIA_CLARA_INPUT: The root folder where the application searches for AI result file, default /input
• NVIDIA_CLARA_OUTPUT: The folder where the application saves generated DICOM instance files, default /output
• NVIDIA_CLARA_LOGS: The folder for application logs, default /logs
• NVIDIA_CLARA_DCM: The folder where the application searches for the original DICOM study instance files, default /dcm
• NVIDIA_CLARA_SERIES_SELECTION: The folder where the application searches for selected series JSON file, default /series_selection
• NVIDIA_SEG_LABELS: The labels for the segments provided as a stringfied array of strings.

Directory Structure

The directories in the container are shown below. The core of the application code is under the folder dicomseg.

/app_dicomseg_writer
├── buildContainers.sh
├── dicomseg
│ ├── app.py
│ ├── dicomseg_writer.py
│ ├── __init__.py
│ ├── runtime_envs.py
│ └── series_instance_parser.py
├── Dockerfile
├── __init__.py
├── logging_config.json
├── main.py
├── ngc
│   ├── metadata.json
│   └── overview.md
├── public
│   └── docs
│   └── README.md
├── requirements.txt
├── run_app_docker.sh
└── test-data
 ├── dcm
 │   ├── IMG0001.dcm
 │   ├── IMG0002.dcm
 │   ├── IMG0003.dcm
 │   ├── IMG0004.dcm
 │   ├── IMG0005.dcm
 │   ├── IMG0006.dcm
 │   ├── IMG0007.dcm
 │   ├── IMG0008.dcm
 │   ├── IMG0009.dcm
 │   ├── IMG0010.dcm
 │   ├── IMG0011.dcm
 │   ├── IMG0012.dcm
 │   ├── IMG0013.dcm
 │   ├── IMG0014.dcm
 │   ├── IMG0015.dcm
 │   ├── IMG0016.dcm
 │   ├── IMG0017.dcm
 │   ├── IMG0018.dcm
 │   └── IMG0019.dcm
 └── mhd
 ├── 1.2.826.0.1.3680043.2.1125.1.48532560258338587890405155270906492.output.mhd
 └── 1.2.826.0.1.3680043.2.1125.1.48532560258338587890405155270906492.output.raw

Executing the Operator Docker Image

Prerequisites

• The segmentation mask image file in MetaImage or NIfTI format, as well as segment labels
• The original dcm files from the single DICOM series used for the segmentation

Step 1

Change to your working directory (e.g. my_test).

Step 2

Create, if they do not exist, the following directories under your working directory:

• input, and copy over the segmentation mask image file.
• dcm, and copy over the dcm files of the original DICOM series.
• output for the generated DICOM Segmentation dcm file.
• logs for log files.

Step 3

In your working directory, create a shell script (e.g. run_app_docker.sh or other name if you prefer), copy and paste the sample content below, modify the variable APP_NAME to that of the Docker Image name and tag, and save the file.

SCRIPT_DIR=$(dirname "$(readlink -f "$0")")
TESTDATA_DIR=$(readlink -f "${SCRIPT_DIR}"/test-data)
APP_NAME="dicomseg_writer:latest"
INPUT_TYPE="mhd"

# Build Docker image. Which is not needed if the Docker image has been pulled.
# docker build -t ${APP_NAME} -f ${SCRIPT_DIR}/Dockerfile ${SCRIPT_DIR}

# Run ${APP_NAME} container.
docker run -t --name test_dicomseg_writer --rm \
 -v ${TESTDATA_DIR}/${INPUT_TYPE}:/input \
 -v ${SCRIPT_DIR}/output:/output \
 -v ${SCRIPT_DIR}/logs:/logs \
 -v ${TESTDATA_DIR}/dcm:/dcm \
 -e DEBUG_VSCODE \
 -e DEBUG_VSCODE_PORT \
 -e NVIDIA_CLARA_NOSYNCLOCK=TRUE \
 -e NVIDIA_SEG_LABELS=[\"test-label\"] \
 ${APP_NAME}

echo "${APP_NAME} has finished."

Step 4

Execute the script below and wait for the application container to finish:

./run_app_docker.sh

Step 5

Check for the following output files:

• The segmentation results in the output directory
• A file with the same name as the input file, suffixed with -DICOMSEG and the extension .dcm.

Step 6

To visualize the results, use 3D Slicer or another DICOM viewer that supports DICOM SEG. For detailed steps, see the viewer documentation. The key steps are as follows:

1. Import the DICOM Segmentation dcm file as well as the original DICOM series.
2. Load both the original and the SEG series.
3. Scroll through the slices.
4. To view 3D rendering, select the Volume Rendering module and enable the loaded volume.

Executing the Operator Docker Image Interactively

If you want to see the internals of the container and/or manually run the application inside the container, follow these steps:

1. Start the container in a interactive session. Tp do this, you need to modify the sample script above by replacing docker run -t with docker run -it --entrypoint /bin/bash, and then run the script file.
2. Once in the container terminal, ensure the current directory is /app.
3. Check /input and /dcm have the expected image file(s) and DICOM instance files respectively.
4. Check /output and /logs folders and remove existing files if any.
5. Enter the command python ./main.py, and watch the application execute and finish in under 200 ms.
6. Check the output folder for the newly created DICOM file.
7. Enter command exit to exit the container.

License

An End User License Agreement is included with the product. By pulling and using the Clara Deploy asset on NGC, you accept the terms and conditions of these licenses.

Suggested Reading

Release Notes, the Getting Started Guide, and the SDK itself are available at the NVIDIA Developer forum.

For answers to any questions you may have about this release, visit the NVIDIA Devtalk forum.