ros2-zed-camera-calibration

Stereo calibration tool in C++/OpenCV using ROS2

Upstream Project

This repository is based on the original Stereolabs project:

• https://github.com/stereolabs/zed-opencv-calibration

The upstream project focuses on ZED SDK + OpenCV calibration without ROS.

This repository extends that approach by adding optional ROS2 input support and other tools while keeping the original ZED-based workflow.

Requirements

Base (always):

• CMake >= 3.5
• C++17 compiler
• OpenCV 4.x

For ZED mode:

• ZED SDK >= 5
• CUDA compatible with ZED SDK

Only for ROS2 mode:

• ROS2 (with environment sourced)
• ament_cmake
• rclcpp
• sensor_msgs
• cv_bridge
• message_filters

Build Instructions

Open a terminal on your Linux system and execute the following commands:

git clone https://github.com/diegomarzaa/ros2-zed-camera-calibration
cd ros2-zed-camera-calibration
mkdir build

Depending on your desired configuration, choose one of the following build options:

1. ROS2

cmake -S . -B build -DWITH_ZED=OFF -DWITH_ROS2=ON
cmake --build build -j$(nproc)

2. Normal ZED (no ROS2)

cmake -S . -B build
cmake --build build -j$(nproc)

3. Only Local Images

cmake -S . -B build -DWITH_ZED=OFF -DWITH_ROS2=OFF
cmake --build build -j$(nproc)

Generated binary:

./build/ros2_zed_camera_calibration

ROS2 Publisher

You can use the ZED ROS2 Wrapper package.

Make sure to configure it to publish the left and right images to separate topics and to include the raw image. You might need to create a ROS2 parameters override file to enable these options. For example:

cat > /tmp/override.yaml <<'YAML'
/**:
  ros__parameters:
    video:
      publish_left_right: true
      publish_raw: true
YAML

ros2 launch zed_wrapper zed_camera.launch.py \
  camera_model:=zed2i \
  ros_params_override_path:=/tmp/override.yaml

ROS2 Calibration

Once you have the ZED ROS2 wrapper you can start the calibration tool. Make sure to specify the correct topics. For example:

./build/ros2_zed_camera_calibration \
  --source ros2 \
  --left_topic /zed/zed_node/left/color/raw/image \
  --right_topic /zed/zed_node/right/color/raw/image \
  --serial_number 12345

Optional hands-free mode for ROS2/ZED live sources, where valid samples are automatically captured without user confirmation:

./build/ros2_zed_camera_calibration \
  --source ros2 \
  --left_topic /zed/zed_node/left/color/raw/image \
  --right_topic /zed/zed_node/right/color/raw/image \
  --serial_number 12345 \
  --auto_capture

You can tune the capture pacing:

--auto_capture_interval 0.8

Captured samples are stored in calibration_images_in_progress/ during acquisition. If you stop the app after collecting samples, they remain on disk. On the next run, the tool detects the existing dataset and resumes appending new captures to it, allowing you to build your dataset iteratively across multiple sessions. On resume, input resolution must match the existing dataset resolution. If not, the run aborts to avoid mixed-resolution data.

After a successful calibration, the dataset is promoted to calibration_images_final/

If you want to force a clean start:

--clear_image_folder

To calibrate only from previously saved samples (without live capture):

./build/ros2_zed_camera_calibration --use_stored_values

Alternative Input Sources

Live ZED

./build/ros2_zed_camera_calibration

SVO example:

./build/ros2_zed_camera_calibration --svo /path/to/capture.svo

With Local images

./build/ros2_zed_camera_calibration \
  --source file \
  --image_folder ./example_images \
  --serial_number 12345

Batch mode (auto-accept valid samples):

./build/ros2_zed_camera_calibration \
  --source file \
  --image_folder ./example_images \
  --serial_number 12345 \
  --auto_accept

Parameters

Usage: ./ros2_zed_camera_calibration [OPTIONS]
  --h_edges <value>      Number of horizontal inner edges of the checkerboard
  --v_edges <value>      Number of vertical inner edges of the checkerboard
  --square_size <value>  Size of a square in the checkerboard (in mm)
  --fisheye              Use fisheye lens model.
  --left_sn <sn>         S/N of the left camera if using virtual stereo.
  --right_sn <sn>        S/N of the right camera if using virtual stereo.
  --help, -h             Show this help message.

  # For ROS2:
  --source ros2           Use ROS2 image topics as input.
  --left_topic <topic>    ROS2 topic for left camera images.
  --right_topic <topic>   ROS2 topic for right camera images.
  --ros_timeout <sec>     Timeout for ROS2 image subscription (default: 10 sec).
  --auto_capture          Auto-capture valid samples in live sources (ROS2/ZED).
  --auto_capture_interval <sec>  Minimum interval between auto-capture attempts (default: 0.6).
  --clear_image_folder    Remove previously stored images from calibration_images_in_progress before acquisition.

  # For file input:
  --source file          Use local image files as input.
  --image_folder <path>  Path to the folder containing left and right images.
  --left_prefix <str>    Prefix for left images (e.g., "left_").
  --right_prefix <str>   Prefix for right images (e.g., "right_").
  --auto_accept          Automatically accept valid samples without user confirmation.

  # Zed-specific parameters
  --svo <file>           Path to the SVO file.
  --stream <ip>          IP address of the ZED camera stream.
  --left_id <id>         Id of the left camera if using virtual stereo.
  --right_id <id>        Id of the right camera if using virtual stereo.

Calibration Process

Check Calibration Process in the original repository for detailed steps.

Output Files

• calibration_images_in_progress/ - current capture session and resumable dataset.
• calibration_images_final/ - dataset moved here automatically after successful calibration (latest successful dataset).
• zed_calibration_<serial>.yml - OpenCV format calibration file, obtained after a full valid calibration.