Holoscan dGPU Container

Overview

The Holoscan container is part of NVIDIA Holoscan, the AI sensor processing platform that combines hardware systems for low-latency sensor and network connectivity, optimized libraries for data processing and AI, and core microservices to run streaming, imaging, and other applications, from embedded to edge to cloud. It can be used to build streaming AI pipelines for a variety of domains, including Medical Devices, High Performance Computing at the Edge, Industrial Inspection and more.

In previous releases, the prefix Clara was used to define Holoscan as a platform designed initially for medical devices. As Holoscan has grown, its potential to serve other areas has become apparent. With version 0.4.0, we're proud to announce that the Holoscan SDK is now officially built to be domain-agnostic and can be used to build sensor AI applications in multiple domains. Note that some of the content of the SDK (sample applications) or the documentation might still appear to be healthcare-specific pending additional updates. Going forward, domain specific content will be hosted on the HoloHub repository.

The Holoscan container includes the Holoscan libraries, GXF extensions, headers, example source code, and sample datasets, as well as all the dependencies that were tested with Holoscan. It is the recommended way to run the Holoscan examples, while still allowing you to create your own C++ and Python Holoscan application.

Visit the NGC demo website for a live demonstration of some of Holoscan capabilities.

Prerequisites

The Holoscan container is designed to run on any of the Holoscan Developer Kits (aarch64) as well as x86_64 systems.

For a full list of Holoscan documentation, visit the Holoscan developer page.

For Clara AGX and NVIDIA IGX Orin Developer Kits (aarch64)

Set up your developer kit:

• NVIDIA Clara AGX
• NVIDIA IGX Orin [ES]
• NVIDIA IGX Orin: coming soon

Make sure you have joined the Holoscan SDK Program and, if needed, the Rivermax SDK Program before using the NVIDIA SDK Manager.

• SDK Manager will install Holopack 1.2 as well as the nvgpuswitch.py script. Once configured for dGPU mode, your developer kit will include the necessary components to run the Holoscan container.
• The Holoscan container does not currently support Rivermax.
• Refer to the User Guide for additional steps to support the AJA capture card.

For x86_64 systems

You'll need the following to run the container on x86_64:

• OS: Ubuntu 20.04
• NVIDIA GPU
  • Ampere or above recommended for best performance
  • Quadro/NVIDIA RTX necessary for GPUDirect RDMA support
  • Tested with NVIDIA RTX 6000 and NVIDIA RTX A6000
• NVIDIA dGPU drivers: 510.73.08 or above
• NVIDIA Container Toolkit

Running the container

1. Log in to the NGC docker registry

2. Press the Copy Image Path button at the top of this webpage, choose the version you want to test, and set this as your NGC_CONTAINER_IMAGE_PATH in your terminal

   # For example
   export NGC_CONTAINER_IMAGE_PATH="nvcr.io/nvidia/clara-holoscan/holoscan:v0.5.0"
   

3. Ensure that X11 is configured to allow commands from docker:

   xhost +local:docker
   

4. Start the container

   Add --device /dev/ajantv20:/dev/ajantv20 in the docker run command if you also have an AJA capture card you'd like to access from the container. Similarly, add --device /dev/video0:/dev/video0 (and/or video1, etc...) to make your USB cameras available to the V4L2 codelet in the container.

   # Find the nvidia_icd.json file which could reside at different paths
   # Needed due to https://github.com/NVIDIA/nvidia-container-toolkit/issues/16
   nvidia_icd_json=$(find /usr/share /etc -path '*/vulkan/icd.d/nvidia_icd.json' -type f -print -quit 2>/dev/null | grep .) || (echo "nvidia_icd.json not found" >&2 && false)
   
   # Run the container
   docker run -it --rm --net host \
     --runtime=nvidia \
     -v /tmp/.X11-unix:/tmp/.X11-unix \
     -v $nvidia_icd_json:$nvidia_icd_json:ro \
     -e NVIDIA_DRIVER_CAPABILITIES=graphics,video,compute,utility,display \
     -e DISPLAY=$DISPLAY \
     ${NGC_CONTAINER_IMAGE_PATH}
   

Running examples

The Holoscan container includes Python, C++, and GXF examples that can be run within the container. Refer to the run instructions under each example folder in the GitHub repository.

Example to run the Hello World example in C++:

cd /opt/nvidia/holoscan/examples
./hello_world/cpp/hello_world

Building examples

The Holoscan container includes the source code and CMake configuration of the C++ and GXF examples to showcase how you can build your own applications using the Holoscan SDK. You can build from these source directories or copy them anywhere on your system to experiment with.

Example to build all the C++ and GXF examples:

export src_dir="/opt/nvidia/holoscan/examples/" # Add "<example_of_your_choice>/cpp" to build a specific example
export build_dir="</path/of/your/choice/>"
cmake -S $src_dir -B $build_dir -G Ninja \
  -D Holoscan_ROOT="/opt/nvidia/holoscan"
cmake --build $build_dir -j

If you build a C++ or GXF example that depends on external data, make sure to edit any relative path in the yaml config if you want to run from a different working directory.

Also see the HoloHub repository for a collection of Holoscan operators and applications which you can use in your pipeline or for reference.

License

By pulling and using the container, you accept the terms and conditions of this End User License Agreement.