getting_started_web_logo

Getting started

This guide shows how to build the RapidPixel SDK and how to use it in your program, step by step. It assumes that you use the SDK for the first time.

The SDK consists of modules: C++17 libraries in the folders modules/<Category>/<Module>, for example modules/Service/FormatConverter. Most modules are pure C++17 code. A few modules use external libraries, for example FFmpeg, GStreamer or OpenVINO. Your program links such a library only if it uses a module which needs it, see System libraries of the modules.

Ways to use the SDK

There are three ways to use the SDK in a program. Choose one of them for your program and do not mix them: every module has to come into the program only once.

Way What you do Choose it if
1. Built SDK Build the SDK once. Your program uses its header files and its library: with CMake through find_package(RapidPixel) (Use the SDK in a CMake project), or with any other build system (without CMake, Visual Studio, Qt Creator). You can also install the SDK into the system. Several programs use the SDK, your program is not a CMake project, or you want your program to build fast. This is the recommended way.
2. SDK as source code Put the folder of the SDK into your CMake project and add it with add_subdirectory. CMake builds the modules which your program uses together with your program. See Add the SDK to your CMake project as source code. Your program is a CMake project and you want one build, without a separate build of the SDK.
3. Single modules as source code Copy the folders of the modules which your program uses, and of the modules which they need, into your CMake project and add every folder with add_subdirectory. See Add single modules to your CMake project. Your program is a CMake project, needs only a few modules, and you want to keep only their source code in your project.

The code of your program is the same in all three ways: include the header of a module by its name, for example #include "FormatConverter.h", and use the namespace rapidpixel (see Namespace). Only the CMakeLists.txt of your program differs.

Requirements

What Linux Windows
Operating system 64-bit Linux, x86-64 or ARM64 (for example Ubuntu 20.04 or newer, Raspberry Pi OS, NVIDIA Jetson) Windows 10 or 11, 64-bit
C++17 compiler GCC 9 or newer, Clang 10 or newer Visual Studio 2019, 2022 or 2026
CMake 3.15 or newer, 3.19 or newer recommended 3.15 or newer, 3.19 or newer recommended
Build tool Make (default); Ninja is optional Visual Studio
Git to get the sources together with their submodules the same

Some modules need more than the table above. MServer (on Linux) and OConnector need OpenSSL 3.0 or newer: Ubuntu 20.04 and Debian 11 have OpenSSL 1.1.1 only, so there these modules are EXCLUDED unless OpenSSL 3 is installed separately. License on Linux is built without OpenSSL 3 too, but then cannot check the signatures of the licenses: the built-in backend of CryptoProvider has no ECDSA (see System libraries of the modules). VCodecWmf is developed and tested for Windows 11.

With CMake older than 3.19 the list of the system libraries of the modules (see System libraries of the modules) contains some CMake target names instead of the library files.

Build your programs with the same compiler as the SDK, of the same or a newer version. With Visual Studio use the same version as for the SDK: the Release builds of CvTracker, DigitalZoom, Fmd, ImageResizer and VStabiliserCv use whole-program optimization (/GL), and such object files can be linked only by the same version of the Visual Studio tools.

On Ubuntu or Debian install the tools with:

sudo apt-get update
sudo apt-get install -y build-essential cmake git

build-essential contains the compiler and Make, which CMake uses by default. Ninja is not required: it only builds faster. To use it, install ninja-build and add -G Ninja to the first cmake command of the build.

External libraries are needed only for the modules which use them. Install the libraries of the modules you need before you build the SDK: the build skips a module whose required library is missing. The list is in System libraries of the modules.

Build the SDK

This section is for way 1. The build gives one folder, the SDK bundle, with the header files of the modules and one static library which contains all modules. With ways 2 and 3 you do not build the SDK separately: go to Add the SDK to your CMake project as source code or Add single modules to your CMake project.

  1. Get the source code. The source package (sdksrc) already contains all modules: unpack it. From the Git repository, clone it together with its submodules:

    git clone --recursive <repository URL> RapidPixelSdk

    In a repository which is already cloned, get the submodules with git submodule update --init --recursive. Do not add --remote: it changes the versions of the modules.

  2. Configure and build. Open a terminal in the folder RapidPixelSdk.

    Linux:

    cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel $(nproc)

    --parallel $(nproc) compiles on all CPU cores at the same time. Give the number explicitly: with Make, --parallel without a number starts an unlimited number of compilers. On a computer with little memory (for example a Raspberry Pi) use a smaller number, for example --parallel 2.

    Windows (Developer Command Prompt for Visual Studio):

    cmake -S . -B build
cmake --build build --config Release --parallel

    For a Debug build write Debug instead of Release. On Windows build both configurations if your program has a Debug and a Release configuration: the program has to link the library of its own configuration.

  3. Check which modules were built. At the end of the configuration (the first command) CMake prints the list AVAILABLE LIBRARIES:

    OK       | Service/Frame
OK       | Communication/SerialPort
EXCLUDED | VideoCoding/VCodecJetPack

    EXCLUDED means that the module cannot be built on this computer, usually because a required external library or a platform SDK is missing (for example the NVIDIA Jetson modules on a PC). The reason is in the file configure.log in the folder build/_test_wrapper/<category>/<module>, for example build/_test_wrapper/VideoCoding/VCodecJetPack/<id>/configure.log (<id> is a folder with a hexadecimal name). Install the missing library and run the commands of step 2 again.

Build the SDK as a normal user, not with sudo: files of the root user in the build folder lead to permission errors later.

What the build produces

By default the build writes the SDK bundle into the SDK folder itself (option RAPIDPIXEL_OUTPUT_DIR, see Build options):

RapidPixelSdk
    include
        RapidPixel ......................... header files
            RapidPixel.h ................... includes the headers of all modules of your build
            SerialPort.h ................... header of the module SerialPort, and so on
    lib
        Release ............................ Debug for a Debug build
            libRapidPixel.a ................ library with all modules (RapidPixel.lib on Windows)
            RapidPixelDependencies.md ...... modules of the library and the system libraries of each of them
            RapidPixelDependencies.cmake ... the same list for CMake
            lib<Module>.a .................. libraries of the single modules, not needed with libRapidPixel.a
    docs ................................... documentation of the modules
    RapidPixelConfig.cmake ................. connects the SDK to a CMake project (find_package)

A program needs only the folders include and lib and, with CMake, the files RapidPixel*.cmake.

The header files of the SDK need only the standard C++ library: a program compiles without the development files of the external libraries, which are needed only to link it (see System libraries of the modules). There are two ways to include them:

  • add RapidPixelSdk/include/RapidPixel to the include directories and write #include "SerialPort.h" or #include "RapidPixel.h";
  • add RapidPixelSdk/include to the include directories and write #include "RapidPixel/SerialPort.h".

RapidPixel.h is the simplest choice. A program which includes only the headers of the modules it uses compiles faster.

Use the SDK in a CMake project

This section is for way 1, the built SDK, and is the recommended way: CMake adds the include directories, the library of the SDK and the system libraries of the modules.

  1. Write the CMakeLists.txt of your program:

    cmake_minimum_required(VERSION 3.15)
project(MyApp LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_executable(MyApp main.cpp)

find_package(RapidPixel CONFIG REQUIRED)
target_link_libraries(MyApp PRIVATE RapidPixel::SerialPort RapidPixel::SimpleUI)

    Link the target RapidPixel::<Module> of every module which your program uses. The target links the library of the SDK and the system libraries of the module: RapidPixel::SimpleUI adds the X11 libraries, RapidPixel::SerialPort adds nothing. The target RapidPixel::RapidPixel links only the library of the SDK, which is enough for the modules without system libraries.

    To check that your SDK build contains the modules, list them after COMPONENTS: CMake stops with a clear message if a module is missing.

    find_package(RapidPixel CONFIG REQUIRED COMPONENTS SerialPort SimpleUI)

  2. Tell CMake where the SDK is: the folder which contains RapidPixelConfig.cmake.

    cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DRapidPixel_DIR=/path/to/RapidPixelSdk
cmake --build build

    For an SDK installed into the system (see Install the SDK into the system) leave RapidPixel_DIR out. If the SDK is installed into a folder which CMake does not search, give the folder of the installation (the prefix) with -DCMAKE_PREFIX_PATH=/path/to/prefix instead.

  3. In your code include the headers of the modules: #include "SerialPort.h", or #include "RapidPixel.h" for all modules of the SDK build.

In Qt Creator, CLion or Visual Studio open the folder of your CMake project and set RapidPixel_DIR in the CMake settings of the IDE.

Install the SDK into the system

Installing is optional: a program can use the SDK bundle directly, as described above. After the installation into a system folder CMake finds the SDK without RapidPixel_DIR.

  1. Build the SDK as described in Build the SDK.

  2. Install it. cmake --install copies the files of the finished build, it does not build anything.

    Linux, into the system folder /usr/local (asks for the password of the administrator):

    sudo cmake --install build

    Linux, for the current user only (no administrator rights needed):

    cmake --install build --prefix "$HOME/.local"

    Windows (Developer Command Prompt for Visual Studio), once for every configuration which you built:

    cmake --install build --config Release --prefix "C:/Libs/RapidPixel"
cmake --install build --config Debug --prefix "C:/Libs/RapidPixel"

  3. Use the installed SDK in your CMake project as in Use the SDK in a CMake project, without RapidPixel_DIR:

    cmake -S . -B build -DCMAKE_BUILD_TYPE=Release

    CMake searches /usr/local by itself. For another folder give it to CMake: -DCMAKE_PREFIX_PATH="$HOME/.local" or -DCMAKE_PREFIX_PATH=C:/Libs/RapidPixel.

Do not run sudo make install or sudo cmake --build: they also build what is out of date, as the administrator, and the files of the root user in the build folder lead to permission errors later.

The installation contains the header files (<prefix>/include/RapidPixel), the library and its list of system libraries (<prefix>/<libdir>/RapidPixel/<configuration>), the CMake files (<prefix>/<libdir>/cmake/RapidPixel), the list of the modules and the license of the SDK (<prefix>/share). <prefix> is the folder of the installation (/usr/local by default on Linux), <libdir> is lib, lib64 or a multiarch folder, depending on the system. The installation can be moved to another folder. DESTDIR is supported for packaging.

There is no uninstall target: the file install_manifest.txt in the build folder lists the installed files. To remove an installation from /usr/local:

sudo xargs rm -f < build/install_manifest.txt

Use the SDK without CMake

Give the compiler the include directory, and the linker the library of the SDK and after it the system libraries of the modules you use. A program which uses only SerialPort (no system libraries):

g++ -std=c++17 main.cpp -I/path/to/RapidPixelSdk/include/RapidPixel \
    /path/to/RapidPixelSdk/lib/Release/libRapidPixel.a -o myapp

A program which uses SerialPort and SimpleUI: SimpleUI needs the X11 libraries, the file lib/Release/RapidPixelDependencies.md lists them:

g++ -std=c++17 main.cpp -I/path/to/RapidPixelSdk/include/RapidPixel \
    /path/to/RapidPixelSdk/lib/Release/libRapidPixel.a \
    /usr/lib/x86_64-linux-gnu/libX11.so /usr/lib/x86_64-linux-gnu/libXext.so -o myapp

The rules are the same for a Makefile or any other build system:

  1. libRapidPixel.a follows your source and object files.
  2. The system libraries follow libRapidPixel.a, in the order of RapidPixelDependencies.md.
  3. Use the compiler which built the SDK (see Requirements). With Clang do not use -stdlib=libc++: the SDK uses the standard library of GCC (libstdc++), the default of Clang on Linux.

Use the SDK in a Visual Studio project

These steps are for a Visual Studio project without CMake (.sln, .vcxproj). The SDK folder in the example is C:\Libs\RapidPixelSdk.

  1. Right-click your project in Solution Explorer and open Properties. Select the configuration (Debug or Release) at the top of the window, set the steps 2 - 5 for each configuration.
  2. C/C++ > General > Additional Include Directories: add C:\Libs\RapidPixelSdk\include\RapidPixel.
  3. Linker > General > Additional Library Directories: add C:\Libs\RapidPixelSdk\lib\Release for the Release configuration and C:\Libs\RapidPixelSdk\lib\Debug for the Debug configuration.
  4. Linker > Input > Additional Dependencies: add RapidPixel.lib and the libraries of the modules you use from lib\Release\RapidPixelDependencies.md (lib\Debug\... for the Debug configuration).
  5. C/C++ > Language > C++ Language Standard: select ISO C++17 Standard (/std:c++17) or newer.
  6. Press Apply.

The Debug and the Release libraries of Visual Studio use different runtimes: the Debug configuration of your program needs the library from lib\Debug, the Release configuration the one from lib\Release.

Use the SDK in a Qt Creator project

These steps are for a qmake project (.pro file). For a CMake project see Use the SDK in a CMake project.

Linux:

CONFIG += c++17
INCLUDEPATH += /path/to/RapidPixelSdk/include/RapidPixel
LIBS += /path/to/RapidPixelSdk/lib/Release/libRapidPixel.a
# The system libraries of the modules you use, from lib/Release/RapidPixelDependencies.md.
# For example SimpleUI:
LIBS += -lX11 -lXext

Windows:

CONFIG += c++17
INCLUDEPATH += C:/Libs/RapidPixelSdk/include/RapidPixel
CONFIG(debug, debug|release) {
    LIBS += C:/Libs/RapidPixelSdk/lib/Debug/RapidPixel.lib
} else {
    LIBS += C:/Libs/RapidPixelSdk/lib/Release/RapidPixel.lib
}
# The system libraries of the modules you use, from lib/<configuration>/RapidPixelDependencies.md.

Add the SDK to your CMake project as source code

This is way 2: your CMake project builds the SDK together with your program, you do not build the SDK separately. CMake builds only the modules which your program links and the modules which they need.

  1. Put the source code of the SDK into the folder of your project, for example into the folder RapidPixelSdk: unpack the source package there, or add the Git repository of the SDK as a submodule of your repository (git submodule add <repository URL> RapidPixelSdk, then git submodule update --init --recursive). The folder of your project:

    MyApp
    CMakeLists.txt
    main.cpp
    RapidPixelSdk ............ source code of the SDK

  2. Write the CMakeLists.txt of your program:

    cmake_minimum_required(VERSION 3.15)
project(MyApp LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_subdirectory(RapidPixelSdk)

add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE RapidPixel::FormatConverter RapidPixel::SerialPort)

    Link the target RapidPixel::<Module> of every module which your program uses, as with the built SDK: the target links the module, the modules which it needs and their system libraries. The target RapidPixel::RapidPixel links all modules of the SDK and gives the header RapidPixel.h; with it CMake builds all modules.

  3. Build your program:

    cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel 4

    With Visual Studio use cmake --build build --config Release.

The first configuration takes a few minutes: CMake checks every module of the SDK and prints the list AVAILABLE LIBRARIES, as in Build the SDK. A module which is EXCLUDED there has no target: install its external libraries (System libraries of the modules) and configure again.

As a part of your project the SDK builds only its modules: it does not build its example applications, does not collect its documentation, does not package its sources, does not add installation rules and does not write files into its own folder. The Build options work as in the build of the SDK: set them before add_subdirectory, for example set(CVTRACKER_AVX2 OFF CACHE BOOL "" FORCE). To make the configuration faster, switch off the modules which your program does not need, for example set(COMPILE_VideoCoding/VCodecLibav OFF CACHE BOOL "" FORCE). Do not switch off a module which a module of your program needs, see Dependencies of the modules.

Add single modules to your CMake project

This is way 3: your project contains only the source code of the modules which your program uses. Every module of the SDK is a CMake project in its folder modules/<Category>/<Module>, which your project adds with add_subdirectory.

A module needs the modules on which it depends, and it does not add them by itself: copy and add them too. The table Dependencies of the modules lists them for every module. The example below is a program which uses FormatConverter and SerialPort. The table says that FormatConverter needs Frame and SerialPort needs no other module.

  1. Copy the folders of the modules from the SDK into a folder of your project, for example 3rdparty. Copy the whole folder of every module. The category folders are not needed:

    MyApp
    CMakeLists.txt
    main.cpp
    3rdparty
        Frame ................ copy of RapidPixelSdk/modules/Service/Frame
        FormatConverter ...... copy of RapidPixelSdk/modules/Service/FormatConverter
        SerialPort ........... copy of RapidPixelSdk/modules/Communication/SerialPort

  2. Write the CMakeLists.txt of your program. Add the modules which a module needs before the module, in the order of the table:

    cmake_minimum_required(VERSION 3.15)
project(MyApp LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_subdirectory(3rdparty/Frame)
add_subdirectory(3rdparty/FormatConverter)
add_subdirectory(3rdparty/SerialPort)

add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE FormatConverter SerialPort)

    The target of a module has the name of the module, without RapidPixel::. It links the modules which the module needs and its system libraries.

  3. Build your program:

    cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel 4

Rules:

  • Add every module only once, also when several modules need it. For example, a program which uses FormatConverter and SimpleUI adds Frame once, then FormatConverter and SimpleUI.
  • Copy all modules from the same version of the SDK.
  • Install the external libraries of the modules before the configuration (System libraries of the modules). The build of the SDK skips a module whose required library is missing, but here CMake stops with an error.
  • A module which is a part of your project does not build its test, example and demo applications.
  • The README of every module (in its folder and in the folder docs of the SDK) describes the module, its CMake options and, in the section Build and connect to your project, how to build the module alone.

Dependencies of the modules

The table lists for every module the other modules of the SDK which it needs (directly or through other modules), in an order in which your project can add them: every module comes after the modules which it needs. Way 3 needs this list. Ways 1 and 2 take care of it themselves.

Module Folder in the SDK Modules it needs, in the order to add them
AFEngine modules/Lens/AFEngine Frame
BadPixelProcessor modules/VideoFiltering/BadPixelProcessor Frame, ConfigReader, VFilter
BoberClient modules/Communication/BoberClient Logger, UdpSocket
BoberManager modules/Communication/BoberManager UdpSocket
Camera modules/Camera/Camera ConfigReader
ChildProcess modules/Service/ChildProcess -
ColorProcessor modules/VideoFiltering/ColorProcessor Frame, ConfigReader, VFilter
ConfigReader modules/Service/ConfigReader -
CryptoProvider modules/Service/CryptoProvider -
CvTracker modules/VideoTracking/CvTracker Frame, ConfigReader, VTracker
Dehazer modules/VideoFiltering/Dehazer Frame, ConfigReader, VFilter
Denoiser modules/VideoFiltering/Denoiser Frame, ConfigReader, VFilter
DigitalZoom modules/VideoFiltering/DigitalZoom Frame, ConfigReader, ImageResizer, VFilter
DnnOnnxDetector modules/ObjectDetection/DnnOnnxDetector Frame, ConfigReader, FormatConverter, ImageResizer, ObjectDetector
DnnOpenVinoDetector modules/ObjectDetection/DnnOpenVinoDetector Frame, ConfigReader, FormatConverter, ImageResizer, ObjectDetector
FileFinderByName modules/Service/FileFinderByName -
Flc modules/Lens/Flc Frame, ConfigReader, Logger, Lens, SerialPort
FlirBosonCamera modules/Camera/FlirBosonCamera ConfigReader, Logger, Camera, SerialPort
Fmd modules/ObjectDetection/Fmd Frame, ConfigReader, Logger, ObjectDetector
FormatConverter modules/Service/FormatConverter Frame
Frame modules/Service/Frame -
FujiSxCamera modules/BlockCamera/FujiSxCamera Frame, ConfigReader, Logger, Camera, Lens, SerialPort
G5Camera modules/BlockCamera/G5Camera Frame, ConfigReader, Logger, Camera, Lens, SerialPort
Ged modules/ObjectDetection/Ged Frame, ConfigReader, ObjectDetector
Gmd modules/ObjectDetection/Gmd Frame, ConfigReader, ObjectDetector
HitachiCamera modules/Camera/HitachiCamera ConfigReader, Logger, Camera, SerialPort
ImageFlip modules/VideoFiltering/ImageFlip Frame, ConfigReader, VFilter
ImageResizer modules/Service/ImageResizer -
IRayBlockCamera modules/BlockCamera/IRayBlockCamera Frame, ConfigReader, Logger, Camera, Lens, SerialPort
IRayFtCamera modules/Camera/IRayFtCamera ConfigReader, Logger, Camera, SerialPort
Joystick modules/Service/Joystick -
Klc modules/Lens/Klc Frame, ConfigReader, Logger, Lens, SerialPort
KlvEncoder modules/Communication/KlvEncoder -
KowaCamera modules/Camera/KowaCamera ConfigReader, Logger, Camera, SerialPort
Lens modules/Lens/Lens Frame, ConfigReader
License modules/Service/License CryptoProvider
Logger modules/Service/Logger -
Lrf modules/LaserRangeFinder/Lrf ConfigReader
LrfUltisense modules/LaserRangeFinder/LrfUltisense ConfigReader, Logger, SerialPort, Lrf, LrfUltisenseParser
LrfUltisenseParser modules/LaserRangeFinder/LrfUltisenseParser -
MotionMagnificator modules/VideoFiltering/MotionMagnificator Frame, ConfigReader, VFilter
MServer modules/VideoStreaming/MServer Frame, ConfigReader, FormatConverter, VOverlay, ImageResizer, CryptoProvider, VCodec, VStreamer
MvExtractorH264 modules/ObjectDetection/MvExtractorH264 Frame
NetworkHealthChecker modules/VideoStreaming/NetworkHealthChecker UdpSocket
NtpUdpChannel modules/Communication/NtpUdpChannel UdpSocket
ObjectDetector modules/ObjectDetection/ObjectDetector Frame, ConfigReader
OConnector modules/Communication/OConnector CryptoProvider
Olc modules/Lens/Olc Frame, ConfigReader, Logger, Lens, SerialPort, AFEngine
OwlCamera modules/Camera/OwlCamera ConfigReader, Logger, Camera, SerialPort
PanTilt modules/BlockCamera/PanTilt ConfigReader
PanTiltSynchronizer modules/VideoStabilization/PanTiltSynchronizer Frame
PelcoDParser modules/Communication/PelcoDParser -
PtzEmulator modules/Service/PtzEmulator Frame, ConfigReader, Camera, Lens, PanTilt, VSource, SimpleUI
Rpl modules/Lens/Rpl Frame, ConfigReader, Logger, Lens, SerialPort, AFEngine
RtpPusher modules/VideoStreaming/RtpPusher -
SerialPort modules/Communication/SerialPort -
SimpleFileDialog modules/Service/SimpleFileDialog -
SimpleUI modules/Service/SimpleUI Frame
Slc modules/Lens/Slc Frame, ConfigReader, Logger, Lens, SerialPort, AFEngine
SnmpServer modules/Communication/SnmpServer CryptoProvider
SunnyLens modules/Lens/SunnyLens Frame, ConfigReader, Logger, Lens, SerialPort, AFEngine
TcpClient modules/Communication/TcpClient -
TcpServer modules/Communication/TcpServer -
UdpDataChannel modules/Communication/UdpDataChannel UdpSocket
UdpSocket modules/Communication/UdpSocket -
VCodec modules/VideoCoding/VCodec Frame
VCodecGst modules/VideoCoding/VCodecGst Frame, Logger, VCodec
VCodecImxVpu modules/VideoCoding/VCodecImxVpu Frame, Logger, VCodec
VCodecJetPack modules/VideoCoding/VCodecJetPack Frame, Logger, VCodec
VCodecLibav modules/VideoCoding/VCodecLibav Frame, Logger, VCodec
VCodecLibva modules/VideoCoding/VCodecLibva Frame, Logger, VCodec
VCodecV4L2 modules/VideoCoding/VCodecV4L2 Frame, Logger, VCodec
VCodecWmf modules/VideoCoding/VCodecWmf Frame, VCodec
VDecoderH264 modules/VideoCoding/VDecoderH264 Frame, VCodec
VDecoderH265 modules/VideoCoding/VDecoderH265 Frame, VCodec
VDecoderJPEG modules/VideoCoding/VDecoderJPEG Frame, VCodec
VEncoderJPEG modules/VideoCoding/VEncoderJPEG Frame, VCodec
VFilter modules/VideoFiltering/VFilter Frame, ConfigReader
VideoRecorderMp4 modules/Service/VideoRecorderMp4 Frame, FormatConverter, VCodec, VEncoderJPEG
ViscaCamera modules/BlockCamera/ViscaCamera Frame, ConfigReader, Logger, Camera, Lens, SerialPort, PanTilt, ViscaParser
ViscaParser modules/BlockCamera/ViscaParser -
VOutputFb modules/Service/VOutputFb Frame
VOutputPipe modules/Service/VOutputPipe Frame
VOutputV4L2 modules/Service/VOutputV4L2 Frame, Logger
VOverlay modules/Service/VOverlay Frame
VPipeline modules/VPipeline Frame, ConfigReader, FormatConverter, Logger, VFilter, VSource, Camera, Lens, ObjectDetector, VStabiliser, VTracker
VSource modules/VideoSource/VSource Frame, ConfigReader
VSourceFile modules/VideoSource/VSourceFile Frame, ConfigReader, FormatConverter, VSource, VCodec, VDecoderH264, VDecoderH265, VDecoderJPEG
VSourceLibCamera modules/VideoSource/VSourceLibCamera Frame, ConfigReader, Logger, VSource
VSourceStream modules/VideoSource/VSourceStream Frame, ConfigReader, FormatConverter, CryptoProvider, VSource, VCodec, VDecoderH264, VDecoderH265, VDecoderJPEG
VSourceV4L2 modules/VideoSource/VSourceV4L2 Frame, ConfigReader, Logger, VSource
VSourceWmf modules/VideoSource/VSourceWmf Frame, ConfigReader, VSource
VStabiliser modules/VideoStabilization/VStabiliser Frame, ConfigReader
VStabiliserCv modules/VideoStabilization/VStabiliserCv Frame, ConfigReader, VStabiliser
VStreamer modules/VideoStreaming/VStreamer Frame, ConfigReader, VOverlay, VCodec
VTracker modules/VideoTracking/VTracker Frame, ConfigReader
Ylc modules/Lens/Ylc Frame, ConfigReader, Logger, Lens, SerialPort, AFEngine

System libraries of the modules

Most modules of the SDK are pure C++17 code and need no external library. The table lists the modules which use external libraries. Whether a module uses a library is decided when you build the SDK:

  • a required library is missing: the module is not built (EXCLUDED);
  • an optional library is missing: the module is built without the function which needs it.

A program links an external library only if it uses a module which needs it. The exact list for your build, with the files of the libraries, is in lib/<configuration>/RapidPixelDependencies.md next to the library of the SDK (for an installation in <prefix>/lib/RapidPixel/<configuration>). The CMake targets RapidPixel::<Module> link these libraries automatically.

External library Modules which require it Modules which use it if it is installed Ubuntu / Debian packages
OpenMP (parallel processing, part of the compiler) Ged, Gmd, CvTracker FormatConverter, ImageResizer, Dehazer, Denoiser, MotionMagnificator, VStabiliserCv and the modules which use FormatConverter or ImageResizer, for example VSourceFile, VideoRecorderMp4, DigitalZoom, VPipeline included in GCC and Visual Studio; Clang: libomp-dev
OpenSSL 3 MServer on Linux; OConnector; License on Linux (signatures of the licenses, through CryptoProvider) CryptoProvider on Linux (without OpenSSL a built-in implementation without ECDSA is used; Windows uses the system CNG) and the modules which use it: SnmpServer, VSourceStream (also TLS: RTSPS) libssl-dev
X11 (libX11, libXext) - SimpleUI on Linux (without X11 the window is headless) and PtzEmulator, which uses SimpleUI libx11-dev libxext-dev
libsystemd - SimpleFileDialog on Linux (XDG desktop portal; without it the programs zenity or kdialog are used) libsystemd-dev
FFmpeg (licenses of the components: see the note below the table) VCodecLibav - libavcodec-dev libavformat-dev libavutil-dev libavfilter-dev libswscale-dev
GStreamer 1.0 (licenses of the plugins: see the note below the table) VCodecGst - libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev; at run time the plugins of the elements used in the pipelines, for example gstreamer1.0-plugins-good, gstreamer1.0-plugins-bad, gstreamer1.0-plugins-ugly
VA-API VCodecLibva - libva-dev
libcamera VSourceLibCamera - libcamera-dev
OpenVINO DnnOpenVinoDetector - see the installation guide of OpenVINO
ONNX Runtime (package from the releases page, not an Ubuntu package) DnnOnnxDetector - extract the package and pass its folder to the first cmake command of the build: -DCMAKE_PREFIX_PATH=<ONNX Runtime folder>
OpenCV 4.5 or newer Fmd Fmd: module optflow of opencv_contrib, module cudaoptflow of an OpenCV build with CUDA libopencv-dev
EGL, OpenGL ES 3 - VStabiliserCv (acceleration) libegl-dev libgles-dev
NVIDIA Jetson Multimedia API, NVIDIA VPI VCodecJetPack VCodecV4L2 (Jetson controls), Denoiser and Fmd (VPI) JetPack of NVIDIA
NXP i.MX G2D, Hantro VPU VCodecImxVpu (Hantro) ImageResizer (G2D) and the modules which use it: DigitalZoom, DnnOnnxDetector, DnnOpenVinoDetector, MServer BSP of NXP
Windows Media Foundation, Direct3D 11, Windows Imaging Component VSourceWmf, VCodecWmf - part of Windows

On Windows the network modules also link the system libraries ws2_32 and iphlpapi, MServer and RtpPusher link winmm, SimpleFileDialog links ole32 and CryptoProvider links bcrypt (Windows CNG): they are part of Windows and RapidPixelDependencies.md lists them too. On Linux with a C library older than glibc 2.34 (Ubuntu 20.04, Debian 11) the thread library is a separate library: the modules that start threads link it through the CMake target Threads::Threads, so the RapidPixel::<Module> targets pass it to the program and RapidPixelDependencies.md lists it for a build without CMake. VCodecV4L2 and VCodecJetPack link libdl (part of the C library).

A program which runs on another computer needs the runtime packages of its external libraries there too (for example libopencv-core for Fmd).

Licenses of FFmpeg and GStreamer components. FFmpeg and GStreamer consist of many components, and the components have their own licenses. The license of an FFmpeg build depends on how it is configured: the core libraries are LGPL 2.1 or later, a build with GPL components (for example libx264, libx265; the packages of Ubuntu and Debian are built so) is GPL, a build with nonfree components (--enable-nonfree) may not be redistributed. GStreamer itself is LGPL 2.1 or later, but every plugin, and the library which the plugin wraps, has its own license (for example x264enc of gst-plugins-ugly is GPL). The SDK does not select the FFmpeg build or the GStreamer plugins, so the user of VCodecLibav and VCodecGst has to check and control the licenses of the FFmpeg build, of the GStreamer plugins used and of their components, and the patent licenses of the codecs, for every product and distribution. See FFmpeg license and legal considerations and GStreamer licensing.

OpenCV is needed only by one module of the SDK: Fmd (the library and its example, demo and benchmark applications). The test applications and examples of the other modules, the example applications and the tutorials of the SDK do not use OpenCV: they generate or read the video frames and draw on them with modules of the SDK (SimpleUI, FormatConverter, VSourceFile).

Build options

Pass the options to the first command of the build, for example cmake -S . -B build -DRAPIDPIXEL_BUILD_EXAMPLES=OFF. When your project adds the SDK with add_subdirectory (way 2), set them before add_subdirectory, for example set(RAPIDPIXEL_BUILD_EXAMPLES ON CACHE BOOL "" FORCE). Some defaults differ in this case, the second value in the column Default.

Option Default Purpose
RAPIDPIXEL_BUILD_MODULES ON Build the modules of the SDK
RAPIDPIXEL_BUILD_EXAMPLES ON / OFF Build the example applications
RAPIDPIXEL_BUILD_DOCS ON / OFF Collect the documentation into docs: the main pages of the SDK, the README of every module (other Markdown files of the modules, for example GETTING_STARTED.md, are not copied, and the links to them become plain text) and the images which they reference. Other files of the static folders (videos, test data) are not copied, and the files of an earlier collection which are not collected any more are deleted
RAPIDPIXEL_PACKAGE_SOURCES ON / OFF Copy the sources of the SDK into build/sdksrc during the build
RAPIDPIXEL_INSTALL ON / OFF Add the installation rules of the SDK (cmake --install)
RAPIDPIXEL_OUTPUT_DIR SDK folder / bundle in the build folder of the SDK Folder of the SDK bundle (include, lib, docs)
COMPILE_<category>/<module> ON Build or skip one module or example, for example -DCOMPILE_VideoCoding/VCodecJetPack=OFF
SDKSRC_DIR build/sdksrc Folder of the source package
CVTRACKER_AVX2 ON On x86-64 compile CvTracker for the instruction set level x86-64-v3 (-march=x86-64-v3: AVX2, FMA; /arch:AVX2 with Visual Studio). The result runs on every CPU with AVX2 and FMA (Intel Haswell, AMD Excavator / Zen and newer), whatever computer built it. Set it to OFF for CPUs without AVX2: CvTracker then needs about 1.5 times more time per frame. No effect on ARM64

Notes:

  • With Visual Studio and other multi-configuration generators choose Debug or Release at build time with --config; CMAKE_BUILD_TYPE is for single-configuration generators (Ninja, Make).
  • Use a separate RAPIDPIXEL_OUTPUT_DIR for builds which run at the same time or have different module selections. When you upgrade from an SDK version without file manifests, use a new RAPIDPIXEL_OUTPUT_DIR: later builds remove the obsolete files recorded by the SDK, but not unknown files.
  • If an external library is installed in a folder which CMake does not search, give CMake the folder with CMAKE_PREFIX_PATH, the <Package>_DIR or <Package>_ROOT variable of the library, or a toolchain file (CMAKE_TOOLCHAIN_FILE) for cross-compilation.
  • Turning a module off does not turn off a module which it requires.
  • The source packaging replaces only an empty folder or a package made by this packager before, and never writes into the sources.

Namespace

All classes, enums, functions and constants of the SDK libraries are declared in the namespace rapidpixel, for example rapidpixel::Frame, rapidpixel::VSourceFile and rapidpixel::ConfigReader. Earlier versions of the SDK used separate namespaces for the libraries (cr::video, cr::utils, cr::lens and others). These names stay available for compatibility: the public headers declare them as namespaces which contain all names of the namespace rapidpixel, so the code which uses them, including the code which declares its own classes in these namespaces, compiles without changes. New code should use the namespace rapidpixel. The names of the symbols in the SDK libraries are changed, so an application built with an earlier version of the SDK has to be rebuilt.

Example application

The folder example of the SDK contains a minimal CMake project which prints the version of the SDK. Its CMakeLists.txt:

cmake_minimum_required(VERSION 3.15)



################################################################################
## EXECUTABLE-PROJECT
## name and version
################################################################################
project(RapidPixelExample VERSION 1.0.0 LANGUAGES CXX)



################################################################################
## SETTINGS
## basic project settings before use
################################################################################
set(CMAKE_INCLUDE_CURRENT_DIR ON)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)



################################################################################
## TARGET
## create target and add include path
################################################################################
# create glob files for *.h, *.cpp
file (GLOB H_FILES   ${CMAKE_CURRENT_SOURCE_DIR}/*.h)
file (GLOB CPP_FILES ${CMAKE_CURRENT_SOURCE_DIR}/*.cpp)
# concatenate the results (glob files) to variable
set  (SOURCES ${CPP_FILES} ${H_FILES})
# create executable from src
if (NOT TARGET ${PROJECT_NAME})
    add_executable(${PROJECT_NAME} ${SOURCES})
endif()

find_package(RapidPixel CONFIG REQUIRED)
target_link_libraries(${PROJECT_NAME} PRIVATE RapidPixel::RapidPixel)

Source code of the example:

#include <iostream>

#include "RapidPixel/RapidPixelVersion.h"


int main()
{
	std::cout << "======================================" << std::endl;
	std::cout << "========= RapidPixel example =========" << std::endl;
	std::cout << "======================================" << std::endl;

	std::cout << "RapidPixel SDK version: " << rapidpixel::RapidPixel::getVersion() << std::endl;

	return 0;
}

Build and run it from the SDK folder after the SDK is built:

cmake -S example -B build/example -DRapidPixel_DIR=/absolute/path/to/RapidPixelSdk
cmake --build build/example --config Release

On Linux the program is build/example/RapidPixelExample, with a multi-configuration generator build/example/Release/RapidPixelExample. For an installed SDK use CMAKE_PREFIX_PATH instead of RapidPixel_DIR.

The larger applications in modules/ExamplesTemplates are built together with the SDK (option RAPIDPIXEL_BUILD_EXAMPLES); their programs are in build/bin. They need hardware, network endpoints, models or configuration files of their own. Their control protocols, including the web template, are demonstrations and do not replace an authenticated management interface in a product.

Troubleshooting

Problem Cause and solution
A module is EXCLUDED in AVAILABLE LIBRARIES A required external library or platform SDK is missing. Read configure.log in the folder build/_test_wrapper/<category>/<module>, install the library (System libraries of the modules) and build the SDK again.
fatal error: <Module>.h: No such file or directory Way 1: the module is not in your SDK build (see the list in lib/<configuration>/RapidPixelDependencies.md) or the include directory is wrong (see What the build produces). Way 3, while CMake builds a module of the SDK: a module which it needs is not added; add it, see Dependencies of the modules.
Target "MyApp" links to target "RapidPixel::<Module>" but the target was not found Way 1: the module is not in your SDK build; list your modules after COMPONENTS in find_package to get a clear message. Way 2: the module is EXCLUDED or switched off, see AVAILABLE LIBRARIES in the output of the configuration.
cannot find -l<Module> (GCC, Clang) or cannot open file '<Module>.lib' (Visual Studio) Way 3: a module which your program or another module links is not added with add_subdirectory, see Dependencies of the modules.
undefined reference to ... (GCC, Clang) or LNK2019: unresolved external symbol (Visual Studio) The system libraries of a module are missing or come before the library of the SDK. With CMake link RapidPixel::<Module> of every module you use. Without CMake put the libraries of RapidPixelDependencies.md after the library of the SDK.
LNK2038: mismatch detected for 'RuntimeLibrary' or '_ITERATOR_DEBUG_LEVEL' The configuration of your program and of the library differ: link lib\Debug\RapidPixel.lib in the Debug configuration and lib\Release\RapidPixel.lib in the Release configuration.
error while loading shared libraries: lib<name>.so when the program starts An external library which a module needs is not installed on this computer: install its runtime package.
Permission denied in the build folder The folder was created with sudo. Delete it and build the SDK as a normal user.
file failed to open for writing (Permission denied): .../install_manifest.txt An earlier sudo cmake --install wrote this file as the administrator. Delete it with sudo rm build/install_manifest.txt and run the command again.

Table of contents