9.3. Clara Deploy DICOM Parser Operator

CAUTION: This is NOT for diagnostics use.

9.3.1. Overview

This example operator, in the form of a Docker container, parses DICOM instances in DICOM Part 10 file format to extract and save key DICOM metadata in a JSON file. It also converts DICOM pixel data, for applicable series such as CT and MR axial, into volume images, and saves them in a configurable file format, e.g. MetaImage or NIfTI, along with a JSON file mapping series instance UID to the image file name.

The output of this operator is expected to be consumed by the downstream operators in the pipeline in order to intelligently select and arrange image files as input to their procdessing step, e.g. a multi-channel AI inference operator.

9.3.2. Inputs

This operator expects by default an input folder /input, which contains DICOM instance files, extension dcm, and subfolders of such files.

9.3.3. Outputs

This application saves the meatdata in JSON format as well as image files to the output folder, /output by default, as the following:

  • dicom-metadata.json contains the extracted DICOM metadata in JSON format, organized in study, series, and instances hierarchy.

  • series-images.json contains the series to converted images mapping in JSON format.

  • images files, whose format depends on the runtime configuration of the supported formats: mhd, nii, and nii.gz.

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

9.3.4. Directory Structure

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

.
├── buildContainers.sh
├── Dockerfile
├── __init__.py
├── logging_config.json
├── main.py
├── ngc
│   ├── metadata.json
│   └── overview.md
├── parser
│   ├── app.py
│   ├── __init__.py
│   ├── metadata_parser.py
│   ├── series_converter.py
│   └── runtime_envs.py
├── public
│   └── docs
│       └── README.md
├── requirements.txt
├── run_app_docker.sh
└── test-data
    └── dcm
        └── study1
            └── series1
                ├── IMG0001.dcm
                ├── IMG0002.dcm
                ...
                ├── IMG0018.dcm
                └── IMG0019.dcm
            └── series2
                └── RT000000.dcm
        └── study2
            └── series1
                ├── IMG0001.dcm
                ├── IMG0002.dcm
                ...
                ├── IMG0020.dcm
                └── IMG0021.dcm

9.3.5. Parameters

To control the format of converted image files, the operator uses a runtime environment variable to specify the extension of the expected file format, with default being mhd:

  • NVIDIA_CLARA_IMAGE_FORMAT=['mhd' | 'nii' | 'nii.gz']

9.3.6. Executing Operator Locally

If you want to see the internals of the container and want to manually run the application, follow these steps.

  1. Start the container in interactive mode. See the next section on how to run the container, and replace the docker run command with docker run --entrypoint /bin/bash

  2. Once in the the Docker terminal, ensure the current directory is dicom-parser.

  3. Copy test-data/dcm/* to /input

  4. Create folders /output and /logs

  5. Type in command python ./main.py"

  6. Once finished, type exit.

9.3.7. Executing Operator in Docker

9.3.7.1. Prerequisites

  1. Ensure there are DICOM instance files, with extension dcm, from a single or multiple DICOM studies or series.

9.3.7.2. Step 1

Change to your working directory, e.g. my_test.

9.3.7.3. Step 2

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

  • input, and copy over the DCIOM instance files or folders.

  • output for the generated metadata files and image files.

  • logs for log files.

9.3.7.4. Step 3

In your working directory, create a shell script, e.g. run_app_docker.sh or other name if you prefer, copy the sample content below, save it, and make sure the variable TAG has the same value as the actual container tag, e.g. 0.5.0-2003.6,

SCRIPT_DIR=$(dirname "$(readlink -f "$0")")
TESTDATA_DIR=$(readlink -f "${SCRIPT_DIR}"/test-data)
APP_NAME="dicom-parser"
OUTPUT_IMAGE_FORMAT='mhd'

# Pull Docker image if not already, example below
# docker pull nvcr.io/ea-nvidia-clara/clara/dicom-parser:<TAG>
# docker tag dicom-parser:<TAG> dicom-parser:latest

# Run ${APP_NAME} container.
docker run --name ${APP_NAME} -t --rm \
    -v ${TESTDATA_DIR}:/input \
    -v ${SCRIPT_DIR}/output:/output \
    -v ${SCRIPT_DIR}/logs:/logs \
    -e NVIDIA_CLARA_IMAGE_FORMAT=${OUTPUT_IMAGE_FORMAT} \
    -e DEBUG_VSCODE \
    -e DEBUG_VSCODE_PORT \
    -e NVIDIA_CLARA_NOSYNCLOCK=TRUE \
    ${APP_NAME}

echo "${APP_NAME} has finished."

9.3.7.5. Step 4

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

./run_app_docker.sh.

9.3.7.6. Step 5

Check for the following output files:

  1. Metadata files in the output directory, dicom-metadata.json and series-images.json

  2. Image files, whose names are also in the series-images.json

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

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