[Camera streamer 3/5] Standalone NVDEC CUDA decoder

examples/camera_streamer/README.md

@@ -37,6 +37,25 @@ argus_sender/build/argus_sender --config "configs/${PROFILE}.yaml"
 
 The sender listens for a TCP receiver on port 5000 by default.
 
+## Workstation NVDEC decoder
+
+On a Linux workstation with an NVIDIA GPU, CUDA toolkit, CMake and `uv`, run from
+`examples/camera_streamer`:
+
+```bash
+uv venv .venv --python 3.12
+uv pip install --python .venv/bin/python pybind11 numpy
+cmake -S camera_receiver/codec -B camera_receiver/codec/build \
+  -DCMAKE_BUILD_TYPE=Release -DPython3_EXECUTABLE="$PWD/.venv/bin/python"
+cmake --build camera_receiver/codec/build --parallel 2
+```
+
+The build downloads the pinned NVIDIA Video Codec SDK. CPU-side Python tests:
+
+```bash
+uv run --project tests --extra dev python -m pytest tests/python -q
+```
+
 ## Licensing
 
 This example is Apache-2.0 licensed. Existing upstream notices and external SDK

examples/camera_streamer/camera_receiver/.gitignore

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+# Python environment and caches
+.venv/
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Native codec build outputs
+codec/build/
+codec/_camera_receiver_codec*.so
+
+# Local logs and runtime artifacts
+*.log
+*.pid
+*.sock
+*.avs1
+*.hvs2
+*.nv12
+*.h265
+*.hevc

examples/camera_streamer/camera_receiver/codec/CMakeLists.txt

@@ -0,0 +1,123 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Native H.264/HEVC NVDEC pybind11 module for camera_receiver. The .so
+# lands next to __init__.py so the package imports without any
+# install step.
+
+cmake_minimum_required(VERSION 3.20)
+
+# Ampere / Ada / Hopper / Orin / Thor. Override with
+# CMAKE_CUDA_ARCHITECTURES on the configure line for fast iteration.
+if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES)
+  set(CMAKE_CUDA_ARCHITECTURES "80;86;87;89;90")
+endif()
+
+project(camera_receiver_codec LANGUAGES C CXX CUDA)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CUDA_STANDARD 17)
+set(CMAKE_CUDA_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+# ---------------------------------------------------------------------------
+# Dependencies
+# ---------------------------------------------------------------------------
+find_package(CUDAToolkit REQUIRED)
+find_package(Python3 REQUIRED COMPONENTS Interpreter Development.Module)
+
+# pybind11 is pip-installed into the active camera_receiver Python environment.
+execute_process(
+  COMMAND ${Python3_EXECUTABLE} -c "import pybind11; print(pybind11.get_cmake_dir())"
+  OUTPUT_VARIABLE pybind11_DIR
+  OUTPUT_STRIP_TRAILING_WHITESPACE
+  RESULT_VARIABLE _pybind11_rc
+)
+if(NOT _pybind11_rc EQUAL 0)
+  message(FATAL_ERROR "pybind11 not found. `uv pip install pybind11` into the active venv.")
+endif()
+find_package(pybind11 REQUIRED CONFIG)
+
+# NVDEC entry-point library (ships with the NVIDIA driver).
+if(CMAKE_SYSTEM_PROCESSOR MATCHES "aarch64|arm64")
+  set(_lib_arch_dir "/usr/lib/aarch64-linux-gnu/nvidia")
+else()
+  set(_lib_arch_dir "/usr/lib/x86_64-linux-gnu")
+endif()
+
+find_library(NVCUVID_LIBRARY
+  NAMES libnvcuvid.so.1 libnvcuvid.so nvcuvid
+  HINTS ${CUDA_TOOLKIT_ROOT_DIR}/lib64
+  PATHS "${_lib_arch_dir}"
+)
+if(NOT NVCUVID_LIBRARY)
+  message(FATAL_ERROR "libnvcuvid not found. Install the NVIDIA driver.")
+endif()
+message(STATUS "camera_receiver codec: NVCUVID=${NVCUVID_LIBRARY}")
+
+# ---------------------------------------------------------------------------
+# NVIDIA Video Codec SDK headers + reference decoder sources.
+# ---------------------------------------------------------------------------
+set(_nvc_sdk_url
+  "https://edge.urm.nvidia.com/artifactory/sw-holoscan-thirdparty-generic-local/holohub/operators/holohub_nvc_13.0.19.zip"
+)
+set(_nvc_sdk_zip "${CMAKE_BINARY_DIR}/holohub_nvc_13.0.19.zip")
+set(_nvc_sdk_vendor_zip "${CMAKE_CURRENT_SOURCE_DIR}/third_party/holohub_nvc_13.0.19.zip")
+set(_nvc_sdk_dir "${CMAKE_BINARY_DIR}/_deps/nvc_sdk")
+
+if(EXISTS ${_nvc_sdk_vendor_zip} AND NOT EXISTS ${_nvc_sdk_zip})
+  message(STATUS "Using vendored NVIDIA Video Codec SDK zip...")
+  file(COPY ${_nvc_sdk_vendor_zip} DESTINATION ${CMAKE_BINARY_DIR})
+endif()
+if(NOT EXISTS ${_nvc_sdk_zip})
+  message(STATUS "Downloading NVIDIA Video Codec SDK...")
+  file(DOWNLOAD ${_nvc_sdk_url} ${_nvc_sdk_zip}
+    SHOW_PROGRESS
+    EXPECTED_MD5 "a08c33c282bc92469ab8cf863aca9087"
+  )
+endif()
+if(NOT EXISTS ${_nvc_sdk_dir}/NvDecoder)
+  message(STATUS "Extracting NVIDIA Video Codec SDK...")
+  file(MAKE_DIRECTORY ${_nvc_sdk_dir})
+  execute_process(
+    COMMAND ${CMAKE_COMMAND} -E tar xzf ${_nvc_sdk_zip}
+    WORKING_DIRECTORY ${_nvc_sdk_dir}
+  )
+endif()
+
+# ---------------------------------------------------------------------------
+# pybind11 module
+# ---------------------------------------------------------------------------
+pybind11_add_module(_camera_receiver_codec MODULE
+  codec_bindings.cpp
+  nv_video_decoder.cpp
+  nv12_to_rgba.cu
+  ${_nvc_sdk_dir}/NvDecoder/NvDecoder.cpp
+  ${_nvc_sdk_dir}/Logger.cpp
+)
+
+target_include_directories(_camera_receiver_codec PRIVATE
+  ${_nvc_sdk_dir}
+  ${_nvc_sdk_dir}/NvDecoder
+)
+
+target_compile_definitions(_camera_receiver_codec PRIVATE NV_WINDOWS=0 NV_LINUX=1)
+
+# NVCODEC SDK reference sources carry legacy warnings.
+target_compile_options(_camera_receiver_codec PRIVATE
+  $<$<COMPILE_LANGUAGE:CXX>:-Wno-reorder -Wno-uninitialized -Wno-unused-variable
+                            -Wno-unused-parameter -Wno-missing-field-initializers -Wno-sign-compare>
+)
+
+target_link_libraries(_camera_receiver_codec PRIVATE
+  CUDA::cudart
+  CUDA::cuda_driver
+  ${NVCUVID_LIBRARY}
+)
+
+# Drop the .so next to __init__.py so the package imports straight
+# from the source tree.
+set_target_properties(_camera_receiver_codec PROPERTIES
+  LIBRARY_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+)

examples/camera_streamer/camera_receiver/codec/__init__.py

@@ -0,0 +1,23 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Native NVDEC video decoder for camera_receiver."""
+
+from __future__ import annotations
+
+try:
+    from ._camera_receiver_codec import (  # type: ignore[import-not-found]
+        Codec,
+        DecoderConfig,
+        NvVideoDecoder,
+    )
+except ImportError as e:
+    raise ImportError(
+        "camera_receiver native codec not built. Follow "
+        "the host receiver build instructions in examples/camera_streamer/README.md."
+    ) from e
+
+__all__ = [
+    "Codec",
+    "DecoderConfig",
+    "NvVideoDecoder",
+]

examples/camera_streamer/camera_receiver/codec/codec_bindings.cpp

@@ -0,0 +1,95 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+//
+// pybind11 bindings — public surface is ``camera_receiver.codec``.
+
+#include "cuda_buffers.hpp"
+#include "nv_video_decoder.hpp"
+
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+
+#include <cstdint>
+#include <stdexcept>
+#include <string>
+
+namespace py = pybind11;
+using camera_receiver::codec::Codec;
+using camera_receiver::codec::DecoderConfig;
+using camera_receiver::codec::NvVideoDecoder;
+
+PYBIND11_MODULE(_camera_receiver_codec, m)
+{
+    m.doc() = "Native NVDEC H.264/HEVC decoder for camera_receiver.";
+
+    py::enum_<Codec>(m, "Codec").value("H264", Codec::H264).value("HEVC", Codec::HEVC);
+
+    py::class_<DecoderConfig>(m, "DecoderConfig")
+        .def(py::init<>())
+        .def_readwrite("width", &DecoderConfig::width)
+        .def_readwrite("height", &DecoderConfig::height)
+        .def_readwrite("full_range", &DecoderConfig::full_range)
+        .def_readwrite("gpu_id", &DecoderConfig::gpu_id)
+        .def_readwrite("codec", &DecoderConfig::codec);
+
+    py::class_<NvVideoDecoder>(m, "NvVideoDecoder")
+        .def(py::init<const DecoderConfig&>(), py::arg("config"))
+        .def(
+            "decode",
+            [](NvVideoDecoder& self, const py::buffer& packet, const py::object& rgba_out, std::uint32_t width,
+               std::uint32_t height, int rotation) -> bool
+            {
+                py::buffer_info pkt = packet.request();
+                if (pkt.ndim != 1)
+                {
+                    throw std::runtime_error("packet must be a 1D byte buffer");
+                }
+                if (pkt.itemsize != 1)
+                {
+                    throw std::runtime_error("packet must be a uint8 buffer");
+                }
+                // Destination capacity must match the decoder, not caller-supplied dimensions.
+                if (width != self.width() || height != self.height())
+                    throw std::runtime_error("width/height do not match the configured decoder size");
+                const CudaBuf buf = extract_cuda_buffer(rgba_out, width, height);
+                bool produced = false;
+                {
+                    py::gil_scoped_release release;
+                    produced = self.decode(static_cast<const std::uint8_t*>(pkt.ptr),
+                                           static_cast<std::size_t>(pkt.size), buf.ptr, buf.row_pitch_bytes, rotation);
+                }
+                return produced;
+            },
+            py::arg("packet"), py::arg("rgba_out"), py::arg("width"), py::arg("height"), py::arg("rotation") = 0,
+            "Feed one Annex-B AU. Returns True iff a frame was written to rgba_out.")
+        .def(
+            "decode_nv12",
+            [](NvVideoDecoder& self, const py::buffer& packet, const py::object& nv12_out, std::uint32_t width,
+               std::uint32_t height, int rotation) -> bool
+            {
+                py::buffer_info pkt = packet.request();
+                if (pkt.ndim != 1)
+                {
+                    throw std::runtime_error("packet must be a 1D byte buffer");
+                }
+                if (pkt.itemsize != 1)
+                {
+                    throw std::runtime_error("packet must be a uint8 buffer");
+                }
+                // Destination capacity must match the decoder, not caller-supplied dimensions.
+                if (width != self.width() || height != self.height())
+                    throw std::runtime_error("width/height do not match the configured decoder size");
+                const CudaBuf buf = extract_nv12_buffer(nv12_out, width, height);
+                bool produced = false;
+                {
+                    py::gil_scoped_release release;
+                    produced =
+                        self.decode_nv12(static_cast<const std::uint8_t*>(pkt.ptr), static_cast<std::size_t>(pkt.size),
+                                         buf.ptr, buf.row_pitch_bytes, rotation);
+                }
+                return produced;
+            },
+            py::arg("packet"), py::arg("nv12_out"), py::arg("width"), py::arg("height"), py::arg("rotation") = 0,
+            "Feed one Annex-B AU. Returns True iff a frame was copied to a tight NV12 GPU buffer.")
+        .def("reset", &NvVideoDecoder::reset, "Tear down NVDEC state. Use after long stream silence.");
+}