Overview

Camera source components for Holoscan SDK 5.x.

This is a Holoscan Module: a self-contained, redistributable C++ library that extends Holoscan SDK with reusable operators under the holoscan::camera namespace.

Choose the backend that matches your camera and host, then use its reference application to validate the graph and capture frames.

Supported platforms

Camera requires an SDK installation with holoscan::sensor_io and CUDA 13. Backend support also depends on the host BSP, camera driver, and development libraries; installing the SDK alone does not establish camera compatibility.

The table describes Holoscan Camera 1.0 support. “Supported” identifies a combination intended for Holoscan validation. SIPL capture is supported only on Jetson AGX Thor with JetPack 7.2.1 in this release. SIPL on IGX Thor T5000 requires JetPack 7.2.1. V4L2 capture is supported on both IGX Thor T5000 and T7000 with IGX OS 2.0. See the known issues for current build and capture limitations on these platforms.

IGX OS 2.0 corresponds to R38.5; JetPack 7.2.1 corresponds to R39.2. On IGX R38.5, the container skips Argus and SIPL dependency downloads. Experimental SIPL source builds on IGX Thor T5000 require the matching R38.5 SIPL development archive under /usr/src/jetson_sipl_api. The ./holoscan_camera wrapper detects that host tree and mounts it read-only into the build container; it does not download or substitute R39 headers. See the SIPL operator guide for the required pre-step and an alternate source-path override. Installing these headers does not establish capture compatibility or release support. SIPL targets default off on R38.5 and must be enabled explicitly. For a V4L2-only build, use -DHOLOSCAN_CAMERA_BUILD_ALL=OFF -DAPP_holoscan_camera_v4l2=ON. See the Argus build guide for an explicit host header mount for experimental builds. IGX Argus capture is not a supported combination in the table above.

Python wheel support

One native wheel is built per architecture. The ARM64 wheel contains V4L2, R39 SIPL API v2, and Argus in separate native extensions. V4L2 works without loading the optional BSP backends on SBSA, DGX Spark, and R38. SIPL is supported only on Jetson AGX Thor with JetPack 7.2.1 (R39.2). Argus is supported only on Jetson Orin with JetPack 7.2.1 (R39.2). Both require the matching BSP runtime. The x86_64 wheel provides native V4L2 support; SIPL and Argus require ARM64. See the Python guide for import and build details.

Operators

Applications

Configuration

Configure Camera operators when constructing the C++ graph:

YAML support

Camera currently provides no from_yaml or from_yaml_node loader. Applications that use YAML must parse their own settings and pass the resulting values to the C++ constructors. The SIPL vendor JSON configurations describe the NvSIPL platform; they are consumed by that stack and do not provide a general Camera operator configuration format.

Use the operator guides for C++ construction examples and each application’s guide for the CLI options it implements.

Install Holoscan Camera 1.0

Python wheel

Install the published Camera wheel in a CPython 3.12 or newer virtual environment on Linux with glibc 2.39 or newer (such as Ubuntu 24.04) and a compatible CUDA 13 runtime:

python -m pip install "holoscan-camera==1.0.0"

This installs the architecture-specific Camera CUDA 13 wheel and its holoscan-core-cu13==5.0.0 dependency. Optional SIPL and Argus capture require the supported hardware and matching BSP runtime described in Supported platforms. See the Python guide for imports and backend requirements.

Debian packages

Install the Holoscan Camera Debian package for C++ headers, libraries, and CMake integration.

• Workstation support: Visit NVIDIA Holoscan Debian downloads to configure the NVIDIA package repository for your platform. Camera packages are published in the Ubuntu 24.04 x86_64 repository and ARM64 SBSA repository as holoscan-camera-cuda-13 and its runtime/development dependencies.
• NVIDIA Devkit support: Use the matching JetPack or IGX package channel on BSP-based devices; an ARM64 SBSA package does not establish SIPL or Argus support.

Build, test, and consume

Set HOLOSCAN_SDK_ROOT to an SDK 5.x installation containing holoscan::sensor_io; see the SDK installation guide. Run these commands from the Camera repository root. Graph validation and unit tests do not qualify physical capture; follow each application guide for live-camera tests.

Quick Start

The wrapper installs the CLI from requirements-cli.txt and requires Python 3.11 or newer. If python3 is older, as on Ubuntu 22.04, run the wrapper from an activated Python 3.11+ virtual environment.

Run these commands from the repository root after completing SDK setup:

# Build and validate the C++ V4L2 example graph without a camera.
./holoscan_camera run holoscan_camera_v4l2 --language cpp
# Run the reference application's tests.
./holoscan_camera test holoscan_camera_v4l2 --language cpp
# Build the Debian package and the raw CPack TGZ.
./holoscan_camera package holoscan-camera --pkg-generator DEB,TGZ

For device access, capture options, C++ integration, and frame placement, see the V4L2 operator guide.

The V4L2 sample also provides Python validate, capture, and preview modes. The CLI prefers Python when --language is omitted. Use --language cpp for the native sample, including with an SDK installation without Python bindings. With matching SDK and Visualization Python bindings, NumPy, and a compatible NVIDIA GPU with display access, show live camera frames with:

./holoscan_camera run holoscan_camera_v4l2 preview --language python \
  --run-args='--device /dev/video0 --width 640 --height 480 --fps 30'

Close the preview window or press Escape to stop. See the Python application guide for environment setup, supported camera modes, and tests.

SIPLCaptureOp targets Jetson AGX Thor (aarch64) and needs a mapped NvSIPL-managed camera; see sipl_player, sipl_frame_saver and sipl_stereo_monitor for reference applications, and the SIPL operator guide for supported JetPack/L4T versions and usage. sipl_player also has a Python version.

Building Without HoloHub CLI

Start with V4L2 and its reference application; this avoids requiring SIPL or Argus development libraries on a V4L2-only host.

cmake -S . -B build -G Ninja \
    -Dholoscan_ROOT="$HOLOSCAN_SDK_ROOT" \
    -DAPP_holoscan_camera_v4l2=ON \
    -DHOLOSCAN_CAMERA_BUILD_TESTING=ON
cmake --build build -j"$(nproc)"
ctest --test-dir build --output-on-failure -LE gpu

-LE gpu drops the device-resident placement check, which is the one test that needs a visible CUDA device. Drop the exclusion on a runner that has one.

For SIPL or Argus, follow the operator-specific prerequisites before enabling those targets. HOLOSCAN_CAMERA_BUILD_ALL=ON enables additional components whose development dependencies may be absent on your host.

Consume the installed module

The package installs holoscan-camera-config.cmake under <libdir>/cmake/holoscan-camera and its exported targets under <libdir>/cmake/holoscan. After installing Camera and its SDK dependencies, a CMake consumer uses the Camera package and its exported targets:

find_package(holoscan-camera CONFIG REQUIRED)
target_link_libraries(my_pipeline PRIVATE holoscan::camera)

Add the installation prefixes to CMAKE_PREFIX_PATH when they are outside CMake’s search paths. holoscan::camera aggregates the operators enabled in that build; consumers may instead link holoscan::v4l2_capture_op, holoscan::sipl_capture_op, or holoscan::argus_capture_op when available.

Benchmarks

Read the V4L2 benchmarks and SIPL benchmarks for the tested hardware, commands, and observed capture behavior. Use the Argus operator’s qualification results for its current capture evidence.

Optional Python bindings expose native capture operators to Holoscan SDK Python graphs. See individual components for support details.

Language Support

Holoscan SDK 5 operators are implemented in C++. Optional Python bindings expose V4L2, SIPL, and Argus through holoscan_camera.operators, with Python CLI build, test, capture, and live-preview support. They require a matching Python-enabled SDK installation and CPython 3.12 or newer. See the Python build guide for the dependency versions and setup.

FAQ + Troubleshooting

Integrating with custom Holoscan SDK 5.0 development

Use the local SDK workflow in the developer guide to develop Camera against a custom Holoscan SDK installation:

1. Develop and test changes in the Holoscan SDK 5.0 project
2. Update the Holoscan SDK 5.0 installation folder to latest development
3. Rebuild Holoscan Camera against the local SDK installation as documented above

SDK installation troubleshooting

The wrapper can auto-detect an SDK installation under ../holoscan-sdk, but that check does not verify whether it includes holoscan::sensor_io. Set HOLOSCAN_SDK_ROOT explicitly to select the SDK installation you built.

If CMake finds the SDK package but reports holoscan_FOUND as FALSE, the installation may be missing the required sensor_io component. Check for holoscan-sensor-io-targets.cmake in the SDK installation. If it is missing, rebuild and install your selected Holoscan SDK 5.0 source with sensor_io, then update HOLOSCAN_SDK_ROOT and configure Holoscan Camera again.

Incorrect SDK installation

Holoscan Camera depends on Holoscan SDK 5.0 and its CUDA 13 dependency. Earlier Holoscan installations are not compatible. Start with clean build and installation folders and a compatible SDK source baseline from SDK installation, then try again. The SDK package version alone does not establish source compatibility.

License

Apache-2.0 - see LICENSE.