Stereo Calibration

Enable three-component (3C) velocity measurements by calibrating stereo camera pairs. PIVTools computes the geometric relationship between cameras for accurate 3D reconstruction.

Stereo PIV Overview

Stereo PIV uses two cameras viewing the measurement plane from different angles. By combining the 2D velocity fields from each camera, the out-of-plane velocity component (w) can be recovered, giving full 3D velocity vectors (u, v, w).

1. Configure Cameras

Set up stereo camera pair

2. Capture Targets

Multiple target positions

3. Generate Model

Compute stereo geometry

4. Reconstruct 3D

Convert 2D to 3D velocity

Overview

Stereo calibration establishes the geometric relationship between two cameras viewing the same measurement plane. The resulting stereo model contains intrinsic parameters for each camera (focal length, principal point, distortion) as well as extrinsic parameters describing the relative position and orientation of the cameras.

Intrinsic Parameters

Computed independently for each camera. Describe the internal optical properties.

Camera Matrix: fx, fy (focal length), cx, cy (principal point)
Distortion: 5 radial/tangential coefficients

Extrinsic Parameters

Describe the geometric relationship between the two cameras.

Rotation Matrix (R): 3×3 rotation from cam1 to cam2
Translation Vector (T): Position offset between cameras
Essential/Fundamental: Epipolar geometry matrices

Quality Metrics

After calibration, review these metrics to assess quality:

Stereo RMS Error

Reprojection error (pixels). Target: < 0.5 px

Relative Angle

Angle between cameras (degrees). Typical: 30-60°

Baseline Distance

Camera separation (mm). Verify against setup

Available Methods

Method	Best For	Target Required
Stereo Dotboard	Standard stereo PIV setups	Circular dot grid, 10-20 positions
Stereo ChArUco	Robust detection, partial visibility	ChArUco board, multiple positions

Calibration Image Setup

Stereo calibration requires synchronised images from both cameras at each target position. The configuration options are similar to planar calibration but must accommodate two camera views.

Camera Pair Configuration

Stereo calibration processes images from both cameras simultaneously. The camera pair is configured in the stereo calibration settings, specifying which cameras (1 and 2) form the stereo pair.

camera_first (default)

Each camera folder contains calibration images

source_path/
├── Cam1/
│ └── calibration/
│ ├── calib_001.tif
│ └── calib_002.tif
└── Cam2/
    └── calibration/
        ├── calib_001.tif
        └── calib_002.tif

calibration_first

Calibration folder contains both camera subfolders

source_path/
└── calibration/
    ├── Cam1/
    │ ├── calib_001.tif
    │ └── calib_002.tif
    └── Cam2/
        ├── calib_001.tif
        └── calib_002.tif

Multi-Camera IM7 Files

LaVision IM7 files often contain synchronised data from both stereo cameras in a single file. Set use_camera_subfolders: falsefor this configuration. PIVTools will automatically extract both camera frames.

source_path/calibration/B00001.im7 → Contains Cam1 + Cam2 frames

Image Synchronisation

Critical: Calibration images must be synchronised between cameras. Each image index (e.g., calib_001.tif) must show the target at the exact same position for both cameras. Misaligned images will produce incorrect stereo geometry.

Stereo Dotboard

Stereo Dotboard calibration extends the planar dotboard model to two cameras. Both cameras are calibrated simultaneously using shared views of a circular dot grid target at multiple positions. The algorithm computes both intrinsic parameters and the stereo geometry.

Requirements

Circular dot grid target with known spacing
10-20 target positions covering the measurement volume
Synchronised images from both cameras at each position
Target visible in both camera views simultaneously

Parameters

Parameter	Description	Example
camera_pair	Cameras forming stereo pair [cam1, cam2]	[1, 2]
pattern_cols	Horizontal dot count	10
pattern_rows	Vertical dot count	10
dot_spacing_mm	Physical spacing between dots	12.22
enhance_dots	Pre-processing for low contrast	false
asymmetric	Asymmetric grid pattern	false
dt	Time between frames (seconds)	0.0057553

GUI Workflow

1Configure calibration images (Image Type, Format, Number)
2Set camera pair (e.g., Camera 1 and Camera 2)
3Set grid detection parameters (cols, rows, dot spacing)
4Browse calibration images to verify detection in both views
5Click "Generate Model" to compute stereo calibration
6Review stereo RMS error, relative angle, and baseline
7Click "Calibrate Vectors" to apply to stereo PIV data
8Click "Set as Active" to make this the active method

Stereo Model Outputs

Camera Matrices: Intrinsics for both cameras
Distortion Coefficients: 5 params per camera
Rotation Matrix (R): Camera 1 to Camera 2 rotation
Translation Vector (T): Baseline offset
Rectification (R1, R2): For image alignment
Projection (P1, P2): Rectified projection matrices
Q Matrix: Disparity-to-depth mapping

Output Directory

base_path/
└── calibration/
    └── stereo_Cam1_Cam2/
        └── dotboard/
            ├── model/
            │ └── stereo_model.mat
            ├── indices/
            └── figures/

Stereo ChArUco

Stereo ChArUco calibration combines the robustness of ArUco marker detection with stereo geometry computation. The ChArUco board allows for reliable corner detection even with partial occlusion, making it ideal for setups with limited visibility.

Advantages

Works when target is partially visible
Robust detection at oblique viewing angles
ArUco markers identify which corners are visible
Better performance in varying lighting conditions

ArUco Dictionary Options

Choose dictionary based on board size and detection requirements.

DICT_4X4_50/100/250/1000

DICT_5X5_50/100/250/1000

DICT_6X6_50/100/250/1000

DICT_7X7_50/100/250/1000

Parameters

Parameter	Description	Example
camera_pair	Cameras forming stereo pair	[1, 2]
squares_h	Horizontal squares	10
squares_v	Vertical squares	9
square_size	Square size in meters	0.03
marker_ratio	Marker size relative to square	0.5
aruco_dict	ArUco dictionary type	DICT_4X4_1000
min_corners	Minimum corners per frame	6
dt	Time between frames (seconds)	0.0057553

GUI Workflow: Same as Stereo Dotboard - configure images, set camera pair and board parameters, generate model, verify quality metrics, and apply to vectors.

3D Velocity Reconstruction

Once the stereo model is computed, PIVTools can reconstruct three-component (3C) velocity fields from the 2D PIV data captured by each camera. The reconstruction uses the stereo geometry to triangulate corresponding velocity vectors.

Reconstruction Process

2D PIV (Cam 1)

u', v' in image plane

2D PIV (Cam 2)

u'', v'' in image plane

3D Velocity

u, v, w in world coordinates

Input Requirements

Valid stereo calibration model
2D PIV vectors from Camera 1
2D PIV vectors from Camera 2
Matching grid coordinates between cameras

Output Variables

u: Velocity component in x-direction (m/s)
v: Velocity component in y-direction (m/s)
w: Out-of-plane velocity component (m/s)
x, y: World coordinates (mm)

Note: 3D reconstruction quality depends on stereo calibration accuracy and proper overlap between the PIV fields from both cameras. Ensure both cameras cover the same measurement region with matching interrogation windows.

CLI Usage

Stereo calibration uses separate CLI commands: one to generate the stereo model from calibration images, and apply-stereo to reconstruct 3D velocities from PIV vectors.

Step 1: Generate Stereo Model

Detect calibration targets from both cameras and generate the stereo calibration model.

Stereo Model Generation Commands

# Detect dot/circle grid and generate stereo model
pivtools-cli detect-stereo-planar

# Detect ChArUco board and generate stereo model
pivtools-cli detect-stereo-charuco

# Process specific paths
pivtools-cli detect-stereo-planar -p 0

Options

Flag	Description	Default
--active-paths, -p	Comma-separated path indices	From config

Step 2: Reconstruct 3D Velocity

Use the apply-stereo command to reconstruct 3D velocity vectors (ux, uy, uz) from the 2D PIV data of both cameras.

Apply Stereo Calibration

pivtools-cli apply-stereo [OPTIONS]

Options

Flag	Description	Default
--method, -m	Stereo method: dotboard or charuco	From config
--camera-pair, -c	Camera pair as "1,2"	From config
--type-name, -t	Data type (instantaneous/ensemble)	instantaneous
--runs, -r	Comma-separated run numbers	All runs
--active-paths, -p	Comma-separated path indices	From config

Examples

# Reconstruct 3D velocity (uses config settings)
pivtools-cli apply-stereo

# Specify camera pair explicitly
pivtools-cli apply-stereo --camera-pair 1,2

# Use charuco stereo model with specific method
pivtools-cli apply-stereo --method charuco -c 1,2

# Reconstruct specific runs
pivtools-cli apply-stereo -t instantaneous -r 1,2,3

# Process specific paths
pivtools-cli apply-stereo -p 0,1

Complete Stereo Workflow

Full Stereo PIV Workflow

# 1. Generate stereo calibration model
pivtools-cli detect-stereo-charuco

# 2. Run PIV processing for both cameras
pivtools-cli instantaneous

# 3. Apply stereo 3D reconstruction
pivtools-cli apply-stereo --camera-pair 1,2

# 4. Compute statistics
pivtools-cli statistics

Tip: Use --method to specify the stereo calibration method (dotboard or charuco) and --camera-pairto specify which cameras to use for 3D reconstruction.

Complete YAML Configuration

Complete reference for all stereo calibration settings in config.yaml.

calibration:
  # Active method selection
  active: stereo_dotboard  # stereo_dotboard or stereo_charuco
  piv_type: instantaneous  # instantaneous or ensemble

  # Calibration image settings (shared)
  image_format: calib_%03d.tif
  num_images: 15
  image_type: standard
  zero_based_indexing: false
  use_camera_subfolders: true
  subfolder: calibration
  camera_subfolders: ["Cam1", "Cam2"]
  path_order: camera_first

  # Stereo Dotboard Method
  stereo_dotboard:
    camera_pair: [1, 2]
    pattern_cols: 10
    pattern_rows: 10
    dot_spacing_mm: 12.2222
    enhance_dots: false
    asymmetric: false
    dt: 0.0057553
    stereo_model_type: dotboard

  # Stereo ChArUco Method (board params from charuco section)
  stereo_charuco:
    camera_pair: [1, 2]
    dt: 0.0057553

  # ChArUco board parameters (used by both planar and stereo)
  charuco:
    squares_h: 10
    squares_v: 9
    square_size: 0.03
    marker_ratio: 0.5
    aruco_dict: DICT_4X4_1000
    min_corners: 6

GUI to YAML Field Mapping

GUI Control	YAML Field	Description
Active Method Button	calibration.active	stereo_dotboard or stereo_charuco
Camera 1 Selector	calibration.stereo_dotboard.camera_pair[0]	First camera in pair
Camera 2 Selector	calibration.stereo_dotboard.camera_pair[1]	Second camera in pair
Pattern Columns	calibration.stereo_dotboard.pattern_cols	Horizontal dot count (dotboard)
Pattern Rows	calibration.stereo_dotboard.pattern_rows	Vertical dot count (dotboard)
Dot Spacing (mm)	calibration.stereo_dotboard.dot_spacing_mm	Physical grid spacing (dotboard)
Squares H	calibration.charuco.squares_h	ChArUco horizontal squares
Squares V	calibration.charuco.squares_v	ChArUco vertical squares
Square Size	calibration.charuco.square_size	Square size in meters
ArUco Dictionary	calibration.charuco.aruco_dict	Marker dictionary type

Next: Create Visualisation Videos

Visualise your calibrated 3D velocity fields with animated videos using the Video Maker tool.

Continue to Video Maker