Getting Started
🚧 Documentation is under development
The Video Stitching for Embedded Systems guide is currently under active development. Some sections may be incomplete or change without notice.
Questions? Contact RidgeRun or email to support@ridgerun.com.
Getting Started
This section covers the requirements to build the Stitcher, LibPanorama and Stitcher installation steps. Additionally, it shows how to the three-camera rectilinear example.
Requirements
Hardware
The Stitcher has been developed and validated on the following platforms:
- NVIDIA Jetson
- Qualcomm Dragonwing
- NXP i.MX95
The available GPU backend depends on the target platform and the LibPanorama build:
- NVIDIA Jetson can use either the CUDA/NPP or OpenGL backend.
- Qualcomm Dragonwing uses the OpenGL backend.
- NXP i.MX95 uses the OpenGL backend.
- The System backend can be used without GPU acceleration.
Software Dependencies
The Stitcher requires:
- C++17 compatible compiler
- Meson
- Ninja
pkg-config- LibPanorama
- GStreamer 1.20 or newer
- GStreamer GL 1.20 or newer when building
rrglstitcher
The following dependencies are used by additional components:
- CppUTest for the unit tests.
- OpenCV 4 for the example application.
LibPanorama must be built and installed before configuring the Stitcher.
On Debian-based systems, the main development dependencies can be installed with:
sudo apt update
sudo apt install -y \
build-essential \
git \
wget \
unzip \
python3-pip \
ninja-build \
pkg-config \
libjsoncpp-dev \
libopencv-dev \
libopencv-core-dev \
libopencv-video-dev \
libopencv-highgui-dev \
libopencv-videoio-dev \
libgstreamer1.0-dev \
libgstreamer-plugins-base1.0-dev \
gstreamer1.0-gl \
gstreamer1.0-plugins-base \
gstreamer1.0-plugins-good \
gstreamer1.0-plugins-bad \
gstreamer1.0-libav \
libcpputest-dev
Meson can be installed with:
sudo -H pip3 install meson
Package names may differ on embedded Linux distributions.
The main dependencies can be checked with:
pkg-config --modversion gstreamer-1.0 pkg-config --modversion gstreamer-gl-1.0 pkg-config --modversion opencv4 pkg-config --modversion cpputest
How to Get the Code
TODO: Add product purchasing, licensing, and repository access instructions.
Build and Install
Build LibPanorama
LibPanorama provides the processing backend used by the Stitcher and must be installed first.
Choose one of the following configurations depending on the backend required by the target platform.
OpenGL
Use this configuration for OpenGL acceleration. This is the recommended configuration when using rrglstitcher.
meson setup builddir \
--prefix=/usr \
-Dnpp=disabled \
-Dopengl=enabled
This configuration can be used on NVIDIA Jetson, Qualcomm Dragonwing, NXP i.MX95, and other platforms with a supported OpenGL implementation.
CUDA/NPP
On NVIDIA platforms, LibPanorama can instead be built using the CUDA/NPP backend:
meson setup builddir \
--prefix=/usr \
-Dnpp=enabled \
-Dopengl=disabled
This configuration can be used by rrstitcher, but does not provide the OpenGL support required by rrglstitcher.
System
To build LibPanorama without GPU acceleration, disable both GPU backends:
meson setup builddir \
--prefix=/usr \
-Dnpp=disabled \
-Dopengl=disabled
After selecting the backend, compile LibPanorama:
meson compile -C builddir
Optionally, run the tests:
meson test -C builddir
Install LibPanorama:
sudo meson install -C builddir
Verify that it can be found through pkg-config:
pkg-config --modversion libpanorama-0.0
builddir with a different backend, remove the build directory or reconfigure it before selecting another backend.Build the Stitcher
When LibPanorama was built with OpenGL support, configure the Stitcher with:
meson setup builddir --prefix=/usr
The default configuration builds:
- The Stitcher C++ library.
- The example application.
- The unit tests.
- The
rrstitcherGStreamer element. - The
rrglstitcherGStreamer element.
If LibPanorama was built with the CUDA/NPP or System backend instead, disable rrglstitcher:
meson setup builddir \
--prefix=/usr \
-Dgstreamer-gl=disabled
Compile the Stitcher:
meson compile -C builddir
Run the tests:
meson test -C builddir
Install the library and GStreamer plugin:
sudo meson install -C builddir
The GStreamer elements are provided by the libgstrrstitcher.so plugin.
Verify rrstitcher with:
gst-inspect-1.0 rrstitcher
When using the OpenGL build, also verify rrglstitcher:
gst-inspect-1.0 rrglstitcher
If the elements are found, gst-inspect-1.0 will display their properties and pad templates.
Three-Camera Rectilinear Quick Start
The example application included with the Stitcher is the shortest way to test a three-camera rectilinear calibration.
The example requires:
- Three images captured from the calibrated cameras.
- A calibration file for the same three-camera setup.
- OpenCV 4 support.
A test directory can be organized as follows:
stitcher-test/ ├── calibration.json ├── camera-0.png ├── camera-1.png └── camera-2.png
The image order must match the camera indices in the calibration file.
From the Stitcher repository, run:
./builddir/examples/stitcher-example \
-n 3 \
-c stitcher-test/calibration.json \
-s stitcher-test/camera-0.png \
-s stitcher-test/camera-1.png \
-s stitcher-test/camera-2.png \
-o panorama.png
The arguments are:
-n 3: number of input cameras.-c: calibration file.-s: input image. Add one for each camera.-o: output panorama.
After the application finishes, panorama.png should contain the stitched three-camera view.
If the example application was not built, first check that OpenCV 4 is available:
pkg-config --modversion opencv4
Then enable the OpenCV example and rebuild:
meson configure builddir -Dopencv=enabled meson compile -C builddir
For details on generating the calibration file, see Configuration and Calibration.
Once the example is working, continue with GStreamer Usage for real-time video pipelines.