Holoscan SDK Examples

This directory contains examples to help users learn how to use the Holoscan SDK for development. See HoloHub to find additional reference applications.

Build instructions

From source: See the building guide
Python wheels: Download the python examples from GitHub, no building necessary.

NGC container: the python examples and pre-built C++ examples are already included under /opt/nvidia/holoscan/examples. You can rebuild the C++ examples like so:

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

Debian package: Run pre-built examples under /opt/nvidia/holoscan/examples or rebuild the C++ examples as shown above. Debian packages support C++ examples only.

Run instructions

See the README of each example for specific run instructions based on your installation type.

Test instructions

From source: See the building guide
Python wheels: not available
NGC container or debian package:
- Running the following command will run the examples and compare the results with expected baselines.
```
ctest --test-dir $build_dir
```
- To group building and testing:
```
/opt/nvidia/holoscan/examples/testing/run_example_tests
```

Example list

Core

The following examples demonstrate the basics of the Holoscan core API, and are ideal for new users starting with the SDK:

Hello World: the simplest holoscan application running a single operator
Ping: simple application workflows with basic source/sink (Tx/Rx)
1. ping_simple: connecting existing operators
2. ping_custom_op: creating and connecting your own operator
3. ping_multi_port: connecting operators with multiple IO ports
4. ping_distributed: transmit tensors from one fragment to another in a distributed application
5. ping_cycle: connecting operators in a cyclic path
6. ping_simple_async_buffer: connecting two operators with an async buffer
7. ping_periodic_async_buffer: demonstrating async buffer connection between two operators that are running with periodic conditions
Video Replayer: switch the source/sink from Tx/Rx to loading a video from disk and displaying its frames
Distributed Video Replayer: switch the source/sink from Tx/Rx to loading a video from disk and displaying its frames, with a distributed application
Flow Tracker: simple application demonstrating data flow tracking for latency analysis
Custom CUDA kernel 1d: application demonstrating ingestion of 1D custom CUDA kernel in Holoscan SDK
Custom CUDA kernel multi sample: application demonstrating ingestion of multiple custom CUDA kernels of multi dimension in Holoscan SDK
Flow Control: demonstrate how to control dynamic operator execution flow in a pipeline (e.g. condition flow paths and loops)

Core: additional configurations

The following examples illustrate the use of specific schedulers to define when operators are run:

Multithread or Event-Based Schedulers: run operators in parallel
Round-Robin Broadcast and Gather: Illustrates processing of multiple sequential frames in parallel to allow removing a bottleneck. Multiple copies of a "slow" operator are launched in parallel for subsequent frames and then results are gathered back into a common pipeline for further processing/display. This app makes use of the event-based scheduler for this purpose.
Multi-Rate Pipeline: Demonstrates how to override default operator port properties to allow parallel downstream branches of a pipeline to operate at different frame rates

The following examples illustrate the use of specific conditions to modify the behavior of operators:

PeriodicCondition: trigger an operator at a user-defined time interval
AsynchronousCondition: allow operators to run asynchronously (C++ API only)
ExpiringMessageAvailableCondition: allow operators to run when a certain number of messages have arrived or after a specified time interval has elapsed.
MultiMessageAvailableCondition, MultiMessageAvailableTimeoutCondition: allow operators to run only once a certain number of messages have arrived across multiple associated input ports (optionally with a timeout on the interval to wait for messages).
native Conditions: demonstrates how a Holoscan native Condition (not wrapping an underlying GXF SchedulingTerm) can be created and used.
OrConditionCombiner: This example shows the use of the or_combine_port_conditions method to add a OrConditionCombiner resource that notifies the scheduler to use an OR combination instead of AND combination for the conditions present on the specified input ports.

The following examples illustrate the use of specific resource classes that can be passed to operators or schedulers:

Clock: demonstrate assignment of a user-configured clock to the Holoscan SDK scheduler and how its runtime methods can be accessed from an operator's compute method.
ThreadPool: demonstrates pinning of operators to specific CPU threads in a thread pool.
native Resources: demonstrates how a Holoscan native Resource (not wrapping an underlying GXF Component) can be created and used.
CudaStreamPool and CudaStreamCondition: demonstrates how Python apps can make use of a CudaStreamPool resource and CudaStreamCondition condition. Also demonstrates how to use stream-related API from native Python operator compute methods and have CuPy calls within compute use the desired stream.
CudaGreenContext: demonstrates the usage of CudaGreenContext when creating CudaStreamPool. It is backward compatible when CudaGreenContext is not configured for a CudaStreamPool.

Decorator-based Python API

Python Functions as Operators: demonstrates how to use a decorator to convert a Python function into an Operator.

Visualization

Holoviz: display overlays of various geometric primitives

Inference

Activation-map: A simple inference pipeline demonstrates selecting a subset of models.
Bring-Your-Own-Model: create a simple inference pipeline for ML applications

Working with third-party frameworks

The following examples demonstrate how to seamlessly leverage third-party frameworks in holoscan applications:

NumPy native: signal processing on the CPU using numpy arrays
CuPy native: basic computation on the GPU using cupy arrays

Sensors

The following examples demonstrate how sensors can be used as input streams to your holoscan applications:

v4l2 camera: for USB and HDMI input, such as USB cameras or HDMI output of laptop
AJA capture: for AJA capture cards

GXF and Holoscan

Tensor interop: use the Entity message to pass tensors to/from Holoscan operators wrapping GXF codelets in Holoscan applications
Import GXF Components: import the existing GXF Codelets and Components into Holoscan applications
Wrap operator as GXF extension: wrap Holoscan native operators as GXF codelets to use in GXF applications
Wrap Holoscan as GXF Extension: wrap Holoscan native operators and resources as GXF codelets and components within a single GXF extension for use in GXF applications