objectvideogenerator_web_logo

ObjectVideoGenerator C++ application

v1.0.0

Table of contents

Overview

ObjectVideoGenerator is a C++ application that generates reference video to test video processing algorithms (for example detection and tracking of objects) at a known contrast of the object: a gray rectangular object moves over a background, and Gaussian noise covers the whole frame, the object too. The contrast of the object is set in percent of the background brightness and the noise by its standard deviation in brightness levels; the signal-to-noise ratio follows from them (see the formulas in How the video is generated).

The application reads the parameters from the file ObjectVideoGenerator.json and creates the file with the default parameters if it does not exist. The window shows the generated video and the sliders of the main parameters; a changed parameter is written into the file at once. The key R records the set number of frames into an MP4 file with the main parameters in its name; a recording with the same parameters overwrites the file. The next video is recorded without a restart of the application.

The application uses the libraries ConfigReader (configuration file), SimpleUI (window) and VideoRecorderMp4 (MP4 files) and has no other dependencies.

ObjectVideoGenerator is general-purpose software: it is not tied to any sector or application, and the developer of a program decides what the program does with it.

Versions

Table 1 - Application versions.

Version Release date What’s new
1.0.0 12.11.2026 - First version.

Application files

The repository structure is shown below:

CMakeLists.txt ----------------------- Main CMake file of the application.
src ---------------------------------- Folder with application source code.
    CMakeLists.txt ------------------- CMake file of the application.
    main.cpp ------------------------- Source C++ file of the application: window, configuration file, recording.
    ObjectVideoGenerator.h ----------- Header file of the generator of the frames and of the parameters.
    ObjectVideoGenerator.cpp --------- C++ implementation file of the generator of the frames.
    ObjectVideoGeneratorVersion.h ---- Header file with application version.
    ObjectVideoGeneratorVersion.h.in - File for CMake to generate version header.
static ------------------------------- Folder with images of this documentation.
    objectvideogenerator_web_logo.png  Logo.
    objectvideogenerator_interface.png Window of the application.

How the video is generated

The frames are gray (8 bits per pixel). Each pixel is computed as follows (the names are the parameters of the configuration file):

background pixel = medium + n
object pixel     = medium + n + C
contrast         C = +contrast * medium / 100  (positiveContrast = 1, the object is brighter)
                 C = -contrast * medium / 100  (positiveContrast = 0, the object is darker)
signal-to-noise ratio  SNR = |C| / sko

n is a random value of the normal distribution with the mean 0 and the standard deviation sko (in brightness levels 0 - 255), new for each pixel of each frame. The result is cut to 0 - 255 and rounded down. So contrast is the difference of the mean brightness of the object and of the background in percent of the background brightness, and SNR is this difference in standard deviations of the noise. Example: with sko = 5, medium = 100 and contrast = 15 % the background has the mean brightness 100 and the object 115 (C = 15, SNR = 3), both with the standard deviation 5 (measured: 99.5 and 114.5, the rounding down lowers both by 0.5). With medium = 0 the contrast C is 0: there is no object. With sko = 0 there is no noise (SNR is infinite).

The SNR holds in the recorded video if sko is at least 2, the brightness stays inside 0 - 255 (medium + C + 3 * sko <= 255 for a brighter object, medium - C - 3 * sko >= 0 for a darker one) and the JPEG quality is 100: measured 2.2 % lower with sko 2 and 0.4 % lower with sko 5. Otherwise the SNR changes, for example about 15 % lower with sko 0.5 (the rounding to integers changes the noise), about 30 % lower with medium 245 and C = 15 (the brightness is cut) and about 30 % higher with the quality 80 (the noise is smoothed).

The object is a rectangle of objectW x objectH pixels with the center (x, y): its top left corner is (x - objectW / 2, y - objectH / 2), integer division. The part of the object outside of the frame is not drawn. The object starts at (startX, startY) and moves by (velX, velY) after each frame. A speed changes its sign when the center comes closer than border to an edge of the frame (x < border or x > frameW - border; the same for y and frameH). The random generator (std::mt19937 with std::normal_distribution) gets a new seed at each start of the preview and of each recording.

How to run the application

Requirements: Windows or Linux, CMake 3.13 or newer, a C++17 compiler (MSVC on Windows, GCC or Clang on Linux). On Linux the window needs the X11 development packages (Debian / Ubuntu: sudo apt install libx11-dev libxext-dev).

The repository does not contain sub-repositories. The libraries must be placed in the same folder as ObjectVideoGenerator: copy their folders, for example from the folder modules of the RapidPixel SDK. The folder structure must be:

<work folder>
    ObjectVideoGenerator
    Frame
    ConfigReader
    FormatConverter
    VCodec
    VEncoderJPEG
    VideoRecorderMp4
    SimpleUI

Typical commands to build the application:

cd ObjectVideoGenerator
mkdir build
cd build
cmake ..
make

On Windows use cmake --build . --config Release instead of make. The main CMakeLists.txt file adds the folders ../Frame, ../ConfigReader, ../FormatConverter, ../VCodec, ../VEncoderJPEG, ../VideoRecorderMp4 and ../SimpleUI (in this order); if a folder does not exist CMake stops with an error. The build type defaults to Release, the application has no CMake options. If the application is a part of a bigger CMake project (an SDK with the libraries), the top-level CMakeLists.txt file adds the libraries and the application (in any order); without the libraries the compiler stops with an error like “ConfigReader.h: No such file or directory”. The application is then built from the root of the project:

cd /path/to/SDK
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --target ObjectVideoGenerator

Run the application in the folder for the configuration file and the recordings (the working directory). The executable file is in build/bin (build\bin\Release\ObjectVideoGenerator.exe on Windows):

cd build/bin
./ObjectVideoGenerator

The console shows the messages of the application, for example:

ObjectVideoGenerator v1.0.0
Configuration file ObjectVideoGenerator.json created with the default params
Keys in the window: R - start or stop a recording, ESC - exit
Recording started: sko_5_medium_100_contrast_15_positive_snr_3_frame_640x480_object_16x16_velocity_1_1_quality_100.mp4, 1000 frames
Recording finished: 1000 of 1000 frames generated

The exit code is 0 after ESC or a closed window, and 1 if the configuration file can’t be read or created or has an invalid parameter (the console names it), or if the window can’t be created.

Configuration file

The file ObjectVideoGenerator.json in the working directory with the default parameters:

{
    "VIDEO_PARAMS": {
        "sko": 5.0,
        "medium": 100.0,
        "contrast": 15.0,
        "objectW": 16,
        "objectH": 16,
        "startX": 100,
        "startY": 100,
        "frameW": 640,
        "frameH": 480,
        "border": 80,
        "velX": 1,
        "velY": 1,
        "numFrames": 1000,
        "fps": 30,
        "positiveContrast": 1,
        "jpegQuality": 100
    }
}

Table 2 - Parameters.

Parameter Valid values Description
sko 0 - 50 Standard deviation of the noise, brightness levels (float).
medium 0 - 255 Mean brightness of the background (float).
contrast 0 - 100 Contrast of the object, % of medium (float).
objectW, objectH 0 - frameW, 0 - frameH Size of the object, pixels. 0 - no object.
startX, startY 0 - frameW - 1, 0 - frameH - 1 Position of the center of the object on the first frame, pixels.
frameW, frameH 64 - 8192 Frame size, pixels.
border 0 - half of the smaller frame size Distance from the edges of the frame where the object turns back, pixels.
velX, velY -100 - 100 Speed of the object, pixels per frame (positive: right, down).
numFrames 1 - 1000000 Number of frames of a recording.
fps 1 - 1000 Frame rate of the recordings and of the preview.
positiveContrast 0 or 1 1 - the object is brighter than the background, 0 - darker.
jpegQuality 0 - 100 JPEG quality of the recordings, % (0 is encoded as 1).

All parameters are required; a number with a fraction in an int parameter is cut to its integer part. If the file can’t be read, is larger than 65536 bytes, is not valid JSON, misses a parameter or has a value out of its range, the application prints the reason and stops with the exit code 1 without changes of the file: correct the file or delete it to get the default parameters. The float parameters are written with 17 significant digits (5.3 as 5.3000001907348633).

Window and control

objectvideogenerator_interface

The window shows the sliders, the video scaled to the window and the status (state, frame number, parameters, SNR; the status is not recorded). The preview plays the frames with the frame rate fps and starts again after numFrames frames, so it shows the motion of a recording. A slider change is written into the configuration file at once and restarts the preview; a running recording keeps its parameters. A slider is moved with the mouse or by one step per notch of the mouse wheel.

Table 3 - Sliders.

Slider Parameter Range
Noise SKO sko 0 - 50
Background mean medium 0 - 255
Contrast, % contrast 0 - 100
Object width, Object height objectW, objectH 0 - frame size
Velocity X, Velocity Y velX, velY -100 - 100
JPEG quality, % jpegQuality 0 - 100

Table 4 - Keys (the window must be active).

Key Description
R Start a recording of numFrames frames with the current parameters (the recording stops by itself after the last frame). R during a recording stops it: the file keeps the recorded frames.
ESC Exit. A running recording is stopped and its file is completed. Closing the window does the same.

Recorded video files

Each recording writes a file in the working directory, the name contains the main parameters:

sko_<sko>_medium_<medium>_contrast_<contrast>_<positive or negative>_snr_<SNR>_frame_<frameW>x<frameH>_object_<objectW>x<objectH>_velocity_<velX>_<velY>_quality_<jpegQuality>.mp4
for example sko_5_medium_100_contrast_15_positive_snr_3_frame_640x480_object_16x16_velocity_1_1_quality_100.mp4 (floats with at most 6 significant digits, contrast in %, snr = C / sko, inf without noise). A recording with the same parameters in the name overwrites the file, the console adds “(the existing file is overwritten)” to the message “Recording started”. startX, startY, border, numFrames and fps are not in the name: a recording that differs only in them overwrites the file too. Other files are not changed.

The file is MP4 with Motion JPEG video (grayscale JPEG), frameW x frameH, fps frames per second, numFrames frames; it is played for example by ffmpeg / ffplay. The frames are generated and recorded as fast as possible. The default quality 100 keeps the noise: a decoded pixel differs from the generated one by at most 2 and the standard deviation of the noise stays 5.0 (sko 5, about 195000 bytes per 640 x 480 frame). A lower quality makes smaller files but smooths the noise and changes the signal-to-noise ratio: quality 80 gives 36000 bytes per frame and the standard deviation 3.9 instead of 5.0.

One file can hold less than 4 GiB of video data (a limit of VideoRecorderMp4): about 22000 frames of 640 x 480 or 3200 frames of 1920 x 1080 pixels with the quality 100 and sko 5. If a frame can’t be recorded (the file can’t be created, the file reached the limit or the disk is full), the recording stops with the message “ERROR: Can’t write the file <name>, recording stopped”; a file that reached the limit keeps the frames recorded before it.


Table of contents