Built With
A low-computation, high-performance synced stereo vision driver for UVC cameras and ROS2. This package captures synchronized images from dual UVC cameras using OpenCV GStreamer and publishes them to ROS topics via image_transport, with support for real-time stereo odometry via RTAB-Map. Designed and tested on the Raspberry Pi 5.
Successfully used to map a 4-aisle research building with 10+ waypoints using full RTAB-Map stereo odometry on a Raspberry Pi 5. Full project info can be found here, and a demo video found here.
- Software-level synchronized stereo capture
- Raw image publishing using
image_transport - Full camera parameter configuration
- Real-time disparity, depth image, and point cloud generation
- RTAB-Map stereo odometry integration
- In-package calibration and RMS error pruning tool
# Clone + build
cd ~/ros2_ws/src
git clone git@github.com:adenm-10/stereo-cam.git
cd ..
colcon build --packages-select stereo_cam
source install/setup.bash- ROS 2 Jazzy
- Ubuntu 24.04
- Raspberry Pi 5 (or compatible SBC)
rosdep install --from-paths src --ignore-src -r -y
⚠️ Runrosdep initandrosdep updatebeforehand. Iflibcamera-devisn't found, see below.
sudo apt update
sudo apt install -y \
libopencv-dev \
libcamera-dev \
libi2c-dev| Parameter | Description |
|---|---|
left_device_file |
Path to the left camera device (e.g., /dev/video0) |
right_device_file |
Path to the right camera device (e.g., /dev/video4) |
left_payload_type |
Video payload format for left camera (e.g., MJPG, YUYV, H264) |
right_payload_type |
Same as above, for right camera |
image_width |
Image width in pixels |
image_height |
Image height in pixels |
frame_rate |
Desired framerate in Hz |
gst_pixel_format |
GStreamer pixel format (e.g., BGR, GRAY8) |
it_pixel_format |
ROS ImageTransport pixel format (e.g., bgr8, mono8) |
frame_id |
Frame ID to assign in published image headers |
calibration_file |
Path to stereo calibration YAML file (package:// supported) |
enable_depth |
Whether to launch the DepthNode from within the StereoNode |
-
*_device_file: To find the video driver file "dev/video*" for both camerasls /dev/video*- See what video files are available
v4l2:///dev/video*- Open them in VLC to see which are the ones your cameras are using
-
To Figure out the compatible compression algorithms, resolutions, and framerates you can use
- Relevant parameters:
*_payload_typeimage_widthimage_heightframe_rate
v4l2-ctl --device=/dev/video* --list-formats-ext- Run for both cameras, find a common configuration and use that for both
- Relevant parameters:
The EKF node's and appropriate documentation can be find in the EKF files themselves at config/odom/ekf_*.yaml, along with in depth documentation in the original robot_localization/params/ekf.yaml file on the robot_localization repository.
The rtabmap_odom node has ~350 parameters, and thus, is a bit difficult to configure. That said, notes on my configurations (mostly to minimize computation), can be found in the config/odom/rtab_odom_stereo.yaml file.
To get more info on rtabmap_odom parameters and usage, I recommend reading the demos and examples on the rtabmap_ros repository, and reading through the parameter descriptions in the referenced yaml file.
ros2 launch stereo_cam stereo_calib.launch.pyros2 launch stereo_cam stereo_cam.launch.pyros2 launch stereo_cam image_proc_pipeline.launch.pyIncludes image rectification, optional disparity generation, and stereo odometry node.
- Chessboard: 6x4 inner corners, 30mm squares
- Stable mounting, good lighting
ros2 run stereo_cam stereo_calib --ros-args \
-p num_corners_vertical:=6 \
-p num_corners_horizontal:=4 \
-p square_size_mm:=30 \
-p show_chess_corners:=truek: Save current stereo pairc: Run calibrationq: Quit nodef: Flag poor image pairs (RMS contribution)
- YAML saved to:
install/stereo_cam/share/stereo_cam/config/StereoCalibration.yaml - Feature match image:
img_matches.jpg - NOTE: For some reason the baseline calculations are off for me by 10^3. I had to manually reduce the fourth element in P2 from e+04 to e+01
💡 Take 30–40 pictures. Use RMS analysis to remove ~10–15 poor pairs for accurate calibration.
Supports v4l2-ctl tuning for:
- brightness
- contrast
- saturation
- hue
- white_balance_temperature
- auto_exposure / exposure_time_absolute
- sharpness / gamma / gain
Full list:
v4l2-ctl --device=/dev/videoX --list-ctrls-menu-
No cameras detected:
- Check payload type, resolution, and framerate compatibility for both cameras
- Verify camera permissions
- Ensure all packages are properly installed
-
Poor performance:
- Reduce resolution or frame rate
- Check system resources
- For rtabmap, this resource shows how to tune for minimal computation
- For ROS2 performance tuning:
- Calibration:
- For some reason the baseline calculations are off for me by 10^3. I had to manually reduce the fourth element in P2 from e+04 to e+01
-
Synchronization issues:
- Normally due to high RAM and CPU usage
This package is released under the GNU General Public License v3.0 (GPLv3). See the LICENSE file for details.
This means:
- You can freely use and modify this software
- If you distribute the software or hardware containing this software, you must:
- Make the source code available
- License your modifications under GPLv3
- Provide installation instructions
- Hardware sales are allowed, but software modifications must remain open source
Developed by Aden McKinney
University of Central Florida, Computer Engineering Senior Design