Getting Started - Horizon Lock guide
RidgeRun Video Stabilization Library Horizon Lock Guide
This guide explains how to use the currently supported integrators and stabilizers in the RidgeRun Video Stabilization Library. :contentReference[oaicite:0]{index=0}
The following integrators are currently supported:
simple-complementarybasic-vqfvqf
The following stabilizer modes are currently available:
spherical-exponentialfixed-horizon
Common Flags
Integrator Selection
Use one of the following options:
--integrator simple-complementary --integrator basic-vqf --integrator vqf
Accelerometer Support
--enable-accelerometer --time-constant <seconds>
Use --enable-accelerometer when your IMU data includes accelerometer samples and you want the integrator to use them.
If omitted, the pipeline runs in gyro-only mode.
Stabilizer Selection
--stabilizer spherical-exponential --stabilizer fixed-horizon --horizon-angle <degrees>
The fixed-horizon stabilizer uses --horizon-angle as the desired horizon reference angle.
Online Sensor Sampling
The online example separates hardware sensor frequency from consumption rate:
--sensor-frequency --sensor-sampling-rate
If --sensor-sampling-rate is not specified, it defaults to the value of --sensor-frequency.
Online Logging
Enable runtime logging with:
--enable-log-data --write-accel-data
When accelerometer logging is enabled, the generated CSV format becomes:
ts,ax,ay,az,gx,gy,gz
Without accelerometer logging:
ts,gx,gy,gz
Offline Example
The offline example accepts:
- Input video with
-f - IMU CSV with
-g - Optional frame synchronization file with
--frame-log
Complementary Integrator (Gyro Only)
./build/examples/concept/rvs-complete-offline-concept \ -f input_video.mp4 \ -g imu_gyro_only.csv \ --frame-log frame_log.csv \ -o stabilized.mp4 \ -b opencv -c calibration.yml -l fisheye -us \ -z xYz -k0 0.0 -k1 0.005828 -s 5 -a 5 -w 1920 -h 1080 \ --integrator simple-complementary
Basic VQF Integrator (Gyro Only)
./build/examples/concept/rvs-complete-offline-concept \ -f input_video.mp4 \ -g imu_gyro_only.csv \ --frame-log frame_log.csv \ -o stabilized.mp4 \ -b opencv -c calibration.yml -l fisheye -us \ -z xYz -k0 0.0 -k1 0.005828 -s 5 -a 5 -w 1920 -h 1080 \ --integrator basic-vqf
Full VQF Integrator with Accelerometer
./build/examples/concept/rvs-complete-offline-concept \ -f input_video.mp4 \ -g imu_accel_gyro.csv \ --frame-log frame_log.csv \ -o stabilized.mp4 \ -b opencv -c calibration.yml -l fisheye -us \ -z xYz -k0 0.0 -k1 0.005828 -s 5 -a 5 -w 1920 -h 1080 \ --integrator vqf \ --enable-accelerometer \ --time-constant 1 \ --stabilizer fixed-horizon \ --horizon-angle 0
Online Example
The online example captures data directly from a camera and IMU at runtime.
Complementary Integrator (Gyro Only)
./build/examples/concept/rvs-complete-online-concept \ --width 1920 \ --height 1080 \ --framerate 60/1 \ --sensor-name Icm42600 \ --sensor-device /dev/i2c-7 \ --sensor-frequency 1000 \ --sensor-sampling-rate 1000 \ --sensor-orientation xYz \ --smoothing-constant 0.2 \ --integrator simple-complementary \ --stabilizer spherical-exponential \ --field-of-view 2.5 \ --calibration-file ~/calibration.yml \ --backend CUDA \ --unstabilized-output unstabilized_output.mp4 \ --stabilized-output stabilized_output.mp4 \ --video-format raw \ --video-device 0
Full VQF Integrator with Accelerometer
./build/examples/concept/rvs-complete-online-concept \ --width 1920 \ --height 1080 \ --framerate 60/1 \ --sensor-name Icm42600 \ --sensor-device /dev/i2c-7 \ --sensor-frequency 1000 \ --sensor-sampling-rate 1000 \ --sensor-orientation xYz \ --smoothing-constant 0.2 \ --integrator vqf \ --enable-accelerometer \ --time-constant 1 \ --stabilizer fixed-horizon \ --horizon-angle 0 \ --field-of-view 2.5 \ --calibration-file ~/calibration.yml \ --backend CUDA \ --unstabilized-output unstabilized_output.mp4 \ --stabilized-output stabilized_output.mp4 \ --video-format raw \ --video-device 0 \ --enable-log-data \ --write-accel-data
Recommended Horizon Lock Preset
For Horizon Lock testing, start with the following values:
--integrator vqf--enable-accelerometer--time-constant 1--stabilizer fixed-horizon--horizon-angle 0
If the camera is mounted upside down, also use:
--flip-method 2
These are the recommended starting values for Horizon Lock because they keep the stabilization centered on gravity-aware attitude estimation. The basic-vqf and simple-complementary integrators are still available, but they are mainly useful for comparison.
For offline replay using logs generated by the online example, keep the frame sync aligned with the recorded logs:
-k0 0.0 -k1 0.0
For offline replay of raw sensor captures, keep the capture-specific timestamp correction used for that dataset.
Offline example:
./build/examples/concept/rvs-complete-offline-concept \ -f input_video.mp4 \ -g imu_accel_gyro.csv \ --frame-log frame_log.csv \ -o stabilized.mp4 \ -b opencv -c calibration.yml -l fisheye -us \ -z xYz -k0 0.0 -k1 0.0 -s 2.5 -a 0.2 -w 1920 -h 1080 \ --integrator vqf \ --enable-accelerometer \ --time-constant 1 \ --stabilizer fixed-horizon \ --horizon-angle 0 \ --flip-method 2
Online example:
./build/examples/concept/rvs-complete-online-concept \ --width 1920 \ --height 1080 \ --framerate 60/1 \ --sensor-name Icm42600 \ --sensor-device /dev/i2c-7 \ --sensor-frequency 1000 \ --sensor-sampling-rate 1000 \ --sensor-orientation xYz \ --flip-method 2 \ --smoothing-constant 0.2 \ --integrator vqf \ --enable-accelerometer \ --time-constant 1 \ --stabilizer fixed-horizon \ --horizon-angle 0 \ --field-of-view 2.5 \ --calibration-file ~/calibration.yml \ --backend CUDA \ --unstabilized-output unstabilized_output.mp4 \ --stabilized-output stabilized_output.mp4 \ --video-format raw \ --video-device 0 \ --enable-log-data \ --write-accel-data
GStreamer Plugin
The rvstabilize GStreamer element exposes the same core controls used by the examples.
Available properties include:
integratorenable-accelerometertime-constantstabilizerstabilizer-horizon-angleimu-frequencyimu-sampling-rateimu-sensorimu-sensor-deviceimu-data-order
Gyro Only Configuration
rvstabilize \ imu-sensor=icm42600 \ imu-sensor-device=/dev/i2c-7 \ imu-frequency=1000 \ imu-sampling-rate=1000 \ imu-data-order=xYz \ integrator=complementary \ stabilizer=spherical-exponential-algorithm
VQF with Accelerometer
rvstabilize \ imu-sensor=icm42600 \ imu-sensor-device=/dev/i2c-7 \ imu-frequency=1000 \ imu-sampling-rate=1000 \ imu-data-order=xYz \ integrator=vqf \ enable-accelerometer=true \ time-constant=1 \ stabilizer=fixed-horizon-algorithm \ stabilizer-horizon-angle=0
Pipeline Example
The plugin integrates into a standard GStreamer pipeline as a transform element:
gst-launch-1.0 <source> ! rvstabilize <properties> ! <sink>
Use the following command to inspect the plugin on your target device:
gst-inspect-1.0 rvstabilize
The following example shows a Jetson pipeline with an imx477 camera, icm42688 IMU and the recommended preset:
gst-launch-1.0 -e \
nvarguscamerasrc sensor-id=0 ! \
'video/x-raw(memory:NVMM),width=1920,height=1080,framerate=60/1' ! \
queue ! \
nvvidconv ! \
'video/x-raw,format=RGBA,framerate=60/1' ! \
rvstabilize \
enable=true \
camera-timestamp-offset=30000 \
imu-sensor=icm42600 \
imu-sensor-device=icm42688 \
imu-frequency=1000 \
imu-sampling-rate=1000 \
imu-data-order=YXz \
integrator=vqf \
enable-accelerometer=true \
time-constant=1 \
stabilizer=fixed-horizon \
horizon-angle=0 \
undistort=fisheyecuda \
undistort-fov-scale=1.0 \
hw-device-index=0 \
undistort-intrinsic-matrix='<1015.6788607443536, 0.0, 500.1121670052026, 0.0, 1018.5384072964622, 326.48997642250316, 0.0, 0.0, 1.0>' \
undistort-distortion-coefficients='<-0.24605296200942733,0.8037917870726398,-3.8267918597812476,6.6195388284232735>' ! \
queue ! \
nvvidconv ! 'video/x-raw(memory:NVMM),format=NV12' ! \
nvv4l2h264enc insert-sps-pps=true iframeinterval=60 bitrate=4000000 ! \
h264parse ! \
qtmux ! \
filesink location=$HOME/vqf_fixed_horizon.mp4
Notes
basic-vqfis the lightweight VQF implementation.vqfis the complete VQF implementation.- For offline frame synchronization, provide
--frame-logso the example can infer frame timestamps correctly. - If your IMU CSV contains only gyroscope data, omit
--enable-accelerometer. - If your IMU CSV includes accelerometer data, use
--enable-accelerometer. - For online logging of accelerometer data, also enable
--write-accel-data. :contentReference[oaicite:2]{index=2}
