Planar Calibration

Convert pixel displacements to physical velocity units (m/s). Four methods available depending on your optical setup and accuracy requirements.

Overview

Calibration converts raw PIV results from pixel displacements to physical units. Choose a method based on your target type and required accuracy.

Method	Type	Best For	Target Required
Scale Factor	Uniform	Telecentric lenses, quick analysis	Known px/mm ratio
Dotboard	Spatially-varying	Standard PIV with lens distortion	Circular dot grid, 10-20 images
ChArUco	Spatially-varying	Partial occlusion, oblique angles	ChArUco board, multiple images
Polynomial (XML)	Spatially-varying	LaVision DaVis users	Calibration.xml from DaVis

Uniform calibration (Scale Factor) applies the same conversion everywhere: velocity = (pixels / px_per_mm) / (dt * 1000). Spatially-varying methods (Dotboard, ChArUco, Polynomial) compute different conversion factors across the image to correct for lens distortion.

Calibration Image Setup

Dotboard and ChArUco methods require calibration target images. Configure the image source before running detection.

Directory Structure

The path_order setting controls how camera and calibration subfolders are nested.

camera_first (default)

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

calibration_first

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

Image Settings

Setting	YAML Key	Description
Image Format	image_format	Filename pattern (e.g. calib_%02d.tif)
Number of Images	num_images	Total calibration images to process
Image Type	image_type	standard, cine, lavision_set, lavision_im7
Zero-Based Indexing	zero_based_indexing	Start image numbering from 0
Camera Subfolders	use_camera_subfolders	Enable per-camera subdirectories
Path Order	path_order	camera_first or calibration_first
Subfolder Name	subfolder	Calibration subfolder name

Image Viewer Tools

The Calibration Image Viewer includes interactive tools for verifying your setup:

Measure Tool: Click two points on the image to measure distance in pixels (dx, dy, and total length). Useful for verifying dot spacing and image scale.
Grid Overlay: Toggleable grid with configurable size (8x8 to 64x64) and adjustable line thickness. Helps verify alignment and spacing.
Magnifier: 2.5x circular zoom lens following the cursor for precise feature inspection.
Contrast Controls: Dual-slider for manual min/max adjustment, with auto-scale toggle.

IM7 Container Format

LaVision IM7 files can contain multiple cameras in a single file. Set use_camera_subfolders: false for multi-camera IM7 containers. PIVTools extracts each camera frame automatically.

Platform Note

LaVision formats (.im7, .set) require lvpyio, available on Windows and Linux only. macOS users should export calibration images to TIFF.

Scale Factor

Uniform px-to-mm conversion. No calibration images needed -- just enter the known pixel-to-mm ratio and the time between laser pulses.

Parameters

Parameter	Description	Example
px_per_mm	Pixels per millimetre	3.41
dt	Time between frames (seconds)	0.56
source_path_idx	Which source path to calibrate	0

GUI Workflow

1Select source path from the dropdown
2Enter dt (time between frames in seconds)
3Enter px_per_mm (pixels per millimetre)
4Click "Calibrate Vectors" to apply
5Click "Set as Active" to make this the active method

Planar Dotboard

Uses OpenCV camera model to compute intrinsic parameters and distortion coefficients from images of a circular dot grid target. Provides spatially-varying calibration that corrects for lens distortion.

Parameters

Parameter	Description	Default
pattern_cols	Horizontal dot count	10
pattern_rows	Vertical dot count	10
dot_spacing_mm	Physical spacing between dot centres (mm)	28.89
asymmetric	Asymmetric grid pattern	false
dt	Time between frames (seconds)	1.0

Detection Algorithm

Histogram-based blob detection determines image polarity automatically (dark dots on light or vice versa). Detected dots are linked into a grid using cKDTree nearest-neighbour search. A RANSAC homography filters outliers before OpenCV calibrateCamera computes the camera model.

GUI Workflow

1Configure calibration images (format, count, subfolder)
2Set grid parameters (cols, rows, dot spacing)
3Use "Detect One" to preview detection on a single frame -- detected dots are overlaid on the image
4Click "Generate Model" to run detection on all frames and compute the camera model
5Review RMS reprojection error (target: < 0.5 px)
6Click "Calibrate Vectors" to apply calibration to PIV data
7Click "Set as Active" to make this the active method

Outputs

Camera Model

Camera Matrix: fx, fy, cx, cy
Distortion: 5 radial/tangential coefficients
Extrinsics: Rotation + translation per frame
RMS Error: Reprojection quality metric

Output Directory

base_path/calibration/Cam1/dotboard_planar/
├── model/dotboard_model.mat
├── indices/indexing_*.mat
└── figures/

Multi-camera: When processing all cameras, each camera runs in a separate thread with its own calibrator instance for maximum parallelism.

Planar ChArUco

Combines a chessboard pattern with ArUco markers. The markers identify which corners are visible, so detection works with partial occlusion and at oblique viewing angles.

Parameters

Parameter	Description	Default
squares_h	Horizontal square count	10
squares_v	Vertical square count	9
square_size	Square size in metres	0.03
marker_ratio	Marker size relative to square	0.5
aruco_dict	ArUco dictionary type	DICT_4X4_1000
min_corners	Minimum corners to accept a frame	6
dt	Time between frames (seconds)	1.0

ArUco Dictionaries

Available dictionaries: DICT_4X4, DICT_5X5, DICT_6X6, DICT_7X7 -- each with 50, 100, 250, or 1000 markers. Larger dictionaries support more unique markers; smaller bit sizes detect faster.

GUI Workflow

Same as Dotboard: configure images, set board parameters, generate model, review RMS, apply to vectors, and set as active.

Output Directory

base_path/calibration/Cam1/charuco_planar/
├── model/camera_model.mat
└── indices/indexing_*.mat

Polynomial (LaVision XML)

Imports 3rd-order polynomial calibration coefficients from a LaVision DaVis Calibration.xml file. No target detection step required.

XML Mode (default)

Enable use_xml: true. Reads coefficients directly from the XML file. Default location: source_path/Calibration.xml.

Manual Entry Mode

Set use_xml: false and enter 10 polynomial coefficients per axis manually: 1, s, s2, s3, t, t2, t3, st, s2t, st2.

Per-Camera Parameters

Parameter	Description
origin.x, origin.y	Normalisation origin (s_o, t_o)
normalisation.nx, .ny	Normalisation scale factors
mm_per_pixel	Pixel-to-mm conversion factor
coefficients_x	10-element array for x displacement
coefficients_y	10-element array for y displacement

GUI Workflow

1Enable "Use XML" toggle (default on)
2Set XML path or leave empty for default location
3Click "Load XML" to populate coefficients
4Click "Calibrate Vectors" to apply
5Click "Set as Active"

Setting the Datum

After calibration, use the Set Datum control to shift the coordinate origin. This applies x/y offsets to the coordinates of all runs in the selected data type.

CLI Usage

Planar calibration uses two CLI steps: detect targets to generate a camera model, then apply the calibration to PIV vectors.

Step 1: Generate Camera Model

Detection Commands

# Dotboard detection
pivtools-cli detect-planar

# ChArUco detection
pivtools-cli detect-charuco

# Process specific camera
pivtools-cli detect-planar --camera 1

# Process specific paths
pivtools-cli detect-planar -p 0,1

Step 2: Apply Calibration

Apply Calibration

# Use active method from config.yaml
pivtools-cli apply-calibration

# Override method
pivtools-cli apply-calibration --method dotboard
pivtools-cli apply-calibration --method charuco
pivtools-cli apply-calibration --method scale_factor

# Specific camera + data type
pivtools-cli apply-calibration --camera 1 --type-name ensemble

# Specific runs
pivtools-cli apply-calibration -r 1,2,3

apply-calibration Options

Flag	Description	Default
--method, -m	Calibration method: dotboard, charuco, scale_factor	From config
--camera, -c	Camera number	All cameras
--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
--align-coordinates	Apply global coordinate alignment after calibration	Off

Complete Workflow

Full Planar Calibration Workflow

# 1. Detect calibration targets
pivtools-cli detect-planar       # or detect-charuco

# 2. Run PIV processing
pivtools-cli instantaneous

# 3. Apply calibration to vectors
pivtools-cli apply-calibration

Complete YAML Reference

calibration:
  # Active method
  active: dotboard  # scale_factor, dotboard, charuco, polynomial
  piv_type: instantaneous

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

  # Scale Factor
  scale_factor:
    dt: 0.56
    px_per_mm: 3.41
    source_path_idx: 0

  # Dotboard
  dotboard:
    camera: 1
    pattern_cols: 10
    pattern_rows: 10
    dot_spacing_mm: 12.22
    asymmetric: false
    dt: 0.0057553
    source_path_idx: 0

  # ChArUco
  charuco:
    camera: 1
    squares_h: 10
    squares_v: 9
    square_size: 0.03
    marker_ratio: 0.5
    aruco_dict: DICT_4X4_1000
    min_corners: 6
    dt: 0.0057553
    source_path_idx: 0

  # Polynomial (LaVision XML)
  polynomial:
    xml_path: ''
    use_xml: true
    dt: 0.0057553
    source_path_idx: 0
    cameras:
      1:
        origin: {x: 0.0, y: 0.0}
        normalisation: {nx: 512.0, ny: 384.0}
        mm_per_pixel: 0.0
        coefficients_x: []
        coefficients_y: []

Measure Tool

The calibration image viewer includes a pixel measurement tool for determining distances in your images. This is useful for verifying dot spacing or estimating px_per_mm for the Scale Factor method.

Toggle measure mode with the ruler button in the viewer toolbar
Click two points on the image to define start and end
A line is drawn between the points showing the pixel distance
Displays dx, dy, and total Euclidean length in pixels
Click again to start a new measurement

Calculating px_per_mm

If you know a physical distance in your image (e.g., a ruler or known feature), measure it in pixels with this tool, then divide by the known length in mm to get your px_per_mm value for Scale Factor calibration.

Global Coordinate System

For multi-camera setups, the Global Coordinate System aligns all cameras into a single physical coordinate frame. It uses a chain topology (camera N to camera N+1) with shared overlap features between adjacent camera pairs.

Chain topology: N cameras require N-1 adjacent overlap pairs
Datum point defines the coordinate origin (pixel + physical position)
Overlap features link adjacent cameras via shared physical points
Automatic Invert Ux detection based on feature position relative to datum
Applied automatically after calibration in both GUI and CLI

Configuration

Setting	Description
enabled	Enable global coordinate alignment
datum_pixel	Pixel coordinates of the datum point {x, y}
datum_physical	Physical coordinates of the datum point {x, y} in mm
datum_frame	Frame number containing the datum point
overlap_pairs	List of adjacent camera pairs with shared pixel features
invert_ux	Negate ux velocity and reflect x-coordinates (auto-detected or manual)

GUI Workflow

1Open the calibration image viewer and navigate to the Global Coordinates panel
2Set the datum point by clicking a known physical location on camera 1
3Enter the physical coordinates (mm) of the datum point
4For each adjacent camera pair, select overlap features visible in both cameras
5Invert Ux is auto-detected; override manually if needed
6Alignment is applied automatically when calibrating vectors

CLI Usage

Global Coordinate CLI

# Apply alignment after calibration in one step
pivtools-cli apply-calibration --align-coordinates

# Or as a standalone command on already-calibrated data
pivtools-cli align-coordinates

# Process specific paths
pivtools-cli align-coordinates -p 0,1

Invert Ux

When the first overlap feature is to the left of the datum origin, the x-axis direction is automatically inverted. This negates ux and UV_stress in all cameras and reflects x-coordinates around the datum physical x-position in coordinates.mat.

For a more detailed guide including camera participation rules, complete YAML field reference, and step-by-step workflow, see the dedicated Global Coordinates page.

Next: Stereo Calibration

For three-component velocity measurements using stereo camera pairs.

Continue to Stereo Calibration