Getting Started - Building PVA ISP

Table of Contents [Sticky]

Before Starting

This page describes two ways to install or build PVA ISP:

Quick Start: Install a prebuilt PVA ISP library provided by RidgeRun and, optionally, its GStreamer plug-in.
Advanced Building: Build the library or example applications from source using x86 emulation or the NVIDIA Jetson (L4T) build mode.

The instructions below refer to PVA ISP v2.0.1. Use the dependencies and release package supplied for your target JetPack/L4T configuration.

Quick Start

The Quick Start assumes that RidgeRun has provided a compiled PVA ISP library. If you need to compile the PVA device code, see Advanced Building.

Runtime Dependencies

The Jetson target requires the PVA runtime components appropriate for its JetPack/L4T release. The following packages are listed for the current documented environment:

Package	Purpose
`nvidia-l4t-pva`	NVIDIA PVA support package matching the installed JetPack/L4T release.
`pva-sdk-2.9-l4t`	PVA SDK 2.9 runtime.
`pva-allow-2` (documented version: `2.0.5`)	PVA execution authorization package.

Install the L4T PVA and authorization packages:

sudo apt update
sudo apt install nvidia-l4t-pva
sudo apt install pva-allow-2=2.0.5

For JetPack 6, the PVA SDK 2.9 runtime package may need to be downloaded from NVIDIA's Jetson repository and installed manually:

sudo apt install ./pva-sdk-2.9-l4t_<version>_arm64.deb

Verify the installed packages:

dpkg-query -W -f='${Package}\t${Version}\n' \
    nvidia-l4t-core \
    nvidia-l4t-pva \
    pva-sdk-2.9-l4t \
    pva-allow-2

Compatibility

The nvidia-l4t-pva package must match the installed JetPack/L4T release. Confirm the PVA SDK and authorization-package versions required for the specific binary provided by RidgeRun.

Installing the PVA ISP Library

Copy the v2.0.1 release package to the Jetson and extract it:

export VERSION=2.0.1
tar -xzf pva_isp-${VERSION}-aarch64.tar.gz
chmod +x pva_isp_install.sh
./pva_isp_install.sh

The installer uses /usr as its default installation prefix. Installing there may require elevated privileges. To choose another installation directory, pass --prefix:

./pva_isp_install.sh --prefix /opt/pva_isp

The package contains the shared ISP library, public headers, and the example binaries included in the selected build configuration. The library also provides pva_isp.pc for pkg-config integration.

GStreamer Integration (Optional)

The PVA ISP GStreamer plug-in is a separate integration component. It depends on GstCUDA and can be used with V4L2 capture components suitable for the camera's Bayer format and bit depth.

GstCUDA

GstCUDA provides the CUDA interoperability framework required by the PVA ISP GStreamer integration. Contact RidgeRun for access to the corresponding package.

Bayer Capture

For capture paths that require Bayer formats with more than 8 bits per pixel, see the custom V4L2 source guide. An alternative capture component is RRV4L2SRC, an extended V4L2 source that supports camera buffer layouts used by ISP pipelines.

Building the GStreamer Plug-in

After obtaining access to the plug-in repository:

CUSTOMER=test
git clone https://gitlab.ridgerun.com/ridgerun/orders/${CUSTOMER}/gst-pva-isp
cd gst-pva-isp
meson setup builddir --prefix=/usr
meson compile -C builddir
sudo meson install -C builddir

Replace test with the customer repository name supplied by RidgeRun.

Verify the elements:

gst-inspect-1.0 pvaisp
gst-inspect-1.0 pvacudaupload

Installation Complete

After installing the library and any optional integration components, continue to Evaluating PVA ISP.

Advanced Building

This section covers source builds, including the PVA device-code compiler and the example applications.

Compilation Dependencies

Required or conditional development components include:

CMake 3.20 or newer and standard C/C++ build tools.
AArch64 cross-compilers when cross-compiling for Jetson on an x86 host.
NVIDIA PVA SDK development packages and CUPVA host libraries for the target generation.
One PVA device compiler: Synopsys ASIP Programmer with a valid license, or the NVIDIA NVVPU compiler when made available by NVIDIA.
yaml-cpp when building the example applications. The shared ISP library itself does not depend on yaml-cpp.
CUDA and NvSci development packages only when the selected build enables those interoperability features.

Basic host build tools can be installed with:

sudo apt update
sudo apt install \
    cmake \
    ccache \
    gcc \
    g++ \
    make \
    gcc-aarch64-linux-gnu \
    g++-aarch64-linux-gnu

For development environments using the PVA SDK 2.9 packages, install the relevant SDK development package:

sudo apt install pva-sdk-2.9-l4t-dev

Install the yaml-cpp development package for the architecture used to build the examples. For example, on a native Ubuntu build environment:

sudo apt install libyaml-cpp-dev

When cross-compiling example applications from x86 to AArch64, yaml-cpp must also be available for the target architecture, such as through libyaml-cpp-dev:arm64 or an appropriate AArch64 sysroot.

PVA Device Compiler

The PVA device code can be built using Synopsys ASIP Programmer or the NVIDIA NVVPU compiler. Compiler availability and setup depend on the development environment. Performance may vary between toolchains.

Build Modes

Build Mode	Description
`NATIVE`	Builds the ISP library and examples for x86 emulation and validation.
`L4T`	Builds artifacts intended for NVIDIA Jetson platforms.

Building for x86 Emulation

The NATIVE build mode supports development and validation on an x86 system:

cmake -S . -B builddir \
    -DPVA_BUILD_MODE=NATIVE \
    -DCMAKE_CXX_FLAGS=-O3
cmake --build builddir

By default, the native configuration enables both the ISP library and the examples. You can disable tests if they are not needed:

cmake -S . -B builddir \
    -DPVA_BUILD_MODE=NATIVE \
    -DBUILD_TESTING=OFF
cmake --build builddir

Building for NVIDIA Jetson (L4T)

The library is intended to be cross-compiled for Jetson from an x86 host. Example applications can be cross-compiled on x86 or built natively on an ARM target, provided their architecture-specific dependencies are installed.

To build the ISP library:

cmake -S . -B builddir \
    -DPVA_BUILD_MODE=L4T \
    -DCMAKE_CXX_FLAGS=-O3 \
    -DPVA_ISP_BUILD_LIBRARY=ON
cmake --build builddir

To build only the examples against an already available ISP library:

cmake -S . -B builddir \
    -DPVA_BUILD_MODE=L4T \
    -DPVA_ISP_BUILD_LIBRARY=OFF \
    -DPVA_ISP_BUILD_EXAMPLES=ON
cmake --build builddir

The source code and compatible compilation toolchain must be available when rebuilding the PVA device kernels. RidgeRun can also provide prebuilt libraries for supported configurations.

Build Configuration

Optional CMake Switches

Option	Description
`PVA_ISP_BUILD_LIBRARY`	Build `libpva_isp.so`.
`PVA_ISP_BUILD_EXAMPLES`	Build the example applications.
`PVA_ISP_STRUCTURED_OUTPUT`	Place the build artifacts under `builddir/out/bin` and `builddir/out/lib`.
`BUILD_TESTING`	Build tests when the ISP library is enabled (defaults to `ON`).
`PVA_ISP_ENABLE_DOCS`	Enable the documentation build.

Default Behavior

Build Mode	Library	Examples
`NATIVE`	ON	ON
`L4T`	OFF	OFF

For L4T builds, explicitly enable at least one of PVA_ISP_BUILD_LIBRARY=ON or PVA_ISP_BUILD_EXAMPLES=ON.

To place compiled executables and libraries in separate output directories, configure with:

-DPVA_ISP_STRUCTURED_OUTPUT=ON

The resulting directories are builddir/out/bin and builddir/out/lib.

Installing from the Build Tree

A direct CMake installation is available as an alternative to the packaged Jetson installation flow:

cmake --install builddir --prefix <install-prefix>

When the library build is enabled, installation includes libpva_isp.so, public headers, and pva_isp.pc. For a nonstandard installation prefix, expose its pkg-config directory before building downstream projects:

export PKG_CONFIG_PATH=<install-prefix>/lib/pkgconfig:$PKG_CONFIG_PATH

For a Meson application, the dependency can be resolved using:

pva_isp_dep = dependency('pva_isp', required : true)

Jetson Packaging

The default Jetson package target produces builddir/pva_isp-2.0.1-aarch64.tar.gz. The tarball already contains a staged installation tree, so a separate cmake --install step is not required before deploying the package.

Copy the tarball to the Jetson:

scp builddir/pva_isp-2.0.1-aarch64.tar.gz \
    <jetson-user>@<jetson-ip>:~/pva-isp/

On the Jetson, extract the package and use the installer described in Installing the PVA ISP Library.

Example Applications

The project includes the following applications:

Application	Purpose
`isp_minimal`	Basic RAW Bayer input to NV12 output, with optional joined-kernel pipelines and DLUT tone mapping.
`isp_multicamera`	Simulates multiple cameras using independent joined-kernel pipelines and execution sessions.
`isp_minimal_cuda`	Demonstrates external CUDA input/output buffers and rebinding between processing iterations. Built when the CUDA Toolkit is available.
`isp_app`	Extended validation application with image and V4L2 capture modes, histogram output, graph export, and execution statistics.

The examples use a YAML configuration file. The maintained reference file in the project source tree is examples/configs/params.yaml. Use the version distributed with your project release when preparing a configuration; the YAML schema and supported properties evolve with the library.

The commands below use installed executable names. For uninstalled builds, use the path where CMake placed the executable (for structured output, builddir/out/bin/).

isp_minimal

The minimal example reads a RAW image, processes it through the ISP pipeline, and writes an NV12 output file.

isp_minimal \
    --image <path> \
    --resolution <width>x<height> \
    --parameters <yaml> \
    --output <path>

Additional options include:

--num-frames: Number of processing iterations (default: 100). Only the final NV12 frame is written.
--dump-graph: Export the pipeline topology as a Graphviz DOT file.
--no-convolution: Skip the Convolution stage while retaining Color Correction.
--disable-blc: Skip Black Level Correction and use the White Balance Gains stage in the regular graph.
--join-kernels: Select fused stages. When convolution is enabled, this also selects Convolution + Color Correction.
--gtm-dlut: Use DLUT-based Global Tone Mapping. With --join-kernels, use the fused Post RGB DLUT stage.
--stats: Print PVA execution statistics.

If --output is omitted, the default filename is <image>.nv12.

isp_multicamera

The multicamera example loads a single RAW16 image and copies it into independent pipelines, simulating 2 to 16 cameras. Each pipeline uses the joined-kernel path Input Stage -> Pre RGB -> Post RGB DLUT and a private execution session. Convolution and Color Correction are intentionally omitted from this example.

isp_multicamera \
    --image <path> \
    --resolution <width>x<height> \
    --parameters <yaml> \
    --num-cameras 4 \
    --num-frames 100

Cameras execute in concurrent pairs, while successive pairs execute sequentially. An odd final camera executes alone. This allows each pair to submit work on independent CUPVA streams.

Optional arguments include --output-prefix, --dump-graph, and --stats. The default camera count is two. Output files are named <prefix>_camera0.nv12, <prefix>_camera1.nv12, and so on.

isp_minimal_cuda

The CUDA example demonstrates how to rotate external input and output buffer pairs between processing iterations without rebuilding the ISP pipeline. Its joined-kernel graph is Input Stage -> Pre RGB -> Color Correction -> Post RGB DLUT.

isp_minimal_cuda \
    --image <path> \
    --resolution <width>x<height> \
    --parameters <yaml> \
    --num-buffers 2 \
    --num-frames 100

--num-buffers selects the number of CUDA-mapped RAW input/NV12 output buffer pairs (default: 2).
--output, --dump-graph, and --stats are also supported.
The example uses Pipeline::updateExternalFrame() to update buffer addresses between completed process() calls. The frame layout and allocation metadata must remain compatible; only buffer addresses are changed.
Only the final processed frame is written to the output file.

isp_app

The full application supports single-image processing and V4L2 capture, histogram CSV export, graph export, optional performance statistics, and joined-kernel execution.

Single-image mode:

isp_app \
    -i <path> \
    -r <width>x<height> \
    -p <parameters> \
    -g <graph.dot> \
    -s

V4L2 streaming mode:

isp_app \
    -d <device> \
    -r <width>x<height> \
    -f <format> \
    -n <num-frames> \
    -p <parameters> \
    -s

Main options:

-i, --image: Input Bayer image path for single-image mode.
-d, --device: V4L2 capture device for streaming mode.
-r, --resolution: Image dimensions in WIDTHxHEIGHT format.
-f, --format: Capture format: 0=BG12, 1=RG10, or 2=BYR2.
-n, --num-frames: Number of streaming frames (default: 100).
-p, --parameters: YAML parameters file.
-g, --dump-graph: Export a Graphviz DOT representation of the pipeline.
-j, --join-kernels: Use fused Input Stage, Pre RGB, Convolution + Color Correction, and Post RGB stages, retaining Histogram and Auto Exposure.
-s, --stats: Print PVA execution statistics.

Joined-Kernel Debug Export

In the current implementation, the debug and scene-key CSV exporters require standalone stages. Set debug.export_debug_csv and debug.export_scene_key to false when using isp_app --join-kernels.

Runtime Configuration and Multiple Pipelines

Applications can change many stage parameters between processing iterations using Pipeline::setStageProperty(). Runtime updates become effective on the next processed frame and must not be made concurrently with process().

Runtime-adjustable parameters include decompand control points, black levels, per-site digital gains, manual white-balance gains, convolution kernels, color-correction matrices, histogram controls, auto-exposure controls, and tone-mapping and gamma LUT properties. Some properties remain configuration-only, including decompand input shift, Bayer format selection, and white-balance mode selection. See the project README for the exact stage-property names and update modes.

By default, each pipeline has its own isp::ExecutionSession and independent CUPVA stream, allowing separate pipelines to run concurrently. Applications can explicitly share one isp::ExecutionSession among pipelines when they need to reuse stream resources; calls to process() on a shared session are serialized.

Generating Documentation

Documentation can be generated without enabling the library or example application builds:

cmake -S . -B builddir \
    -DPVA_ISP_BUILD_LIBRARY=OFF \
    -DPVA_ISP_BUILD_EXAMPLES=OFF \
    -DPVA_ISP_ENABLE_DOCS=ON
cmake --build builddir --target docs

The generated HTML and LaTeX documentation is saved under builddir/docs/.

Known Issue: DLUT Performance with PVA SDK 2.9

The default sampler configuration in PVA SDK 2.9 may reduce the performance of kernels using the DLUT. The project README documents a sampler-header fix required to obtain the expected performance from DLUT-based Global Tone Mapping. Consult RidgeRun for the applicable SDK patch before compiling kernels that use DLUT-based processing.

❯

Share This Page

Send Email Using