Planar Calibration

Convert pixel displacements to physical units (mm, m/s) using calibration targets. PIVTools supports four planar calibration methods to match your experimental setup and accuracy requirements.

Getting Started

Calibration converts raw PIV results from pixel displacements to physical velocity units. The calibration process typically involves capturing images of a known target, then using these to compute the mapping from image coordinates to world coordinates.

1. Configure Images

Set up calibration target images

2. Choose Method

Scale Factor, Dotboard, ChArUco, or Polynomial

3. Generate Model

Compute camera parameters

4. Apply to Vectors

Calibrate PIV results

Overview

PIV processing produces velocity fields in units of pixels per frame. To obtain physically meaningful results, you need to calibrate the data to convert to real-world units (typically m/s). The choice of calibration method depends on your optical setup and the level of accuracy required.

Uniform Calibration

Scale Factor method: Applies the same conversion factor everywhere in the image. Best for telecentric lenses, small fields of view, or preliminary analysis.

velocity = (pixels / px_per_mm) / dt

Spatially-Varying Calibration

Dotboard, ChArUco, Polynomial: Accounts for lens distortion by computing different conversion factors across the image. Essential for accurate measurements.

velocity = f(x, y, pixels, dt)

When to Use Each Method

Method	Best For	Requirements
Scale Factor	Quick analysis, telecentric lenses	Known px/mm ratio, time step
Planar Dotboard	Standard PIV with lens distortion	Circular dot grid target, 10-20 images
Planar ChArUco	Robust detection, partial occlusion	ChArUco board, multiple images
Polynomial (XML)	LaVision DaVis users	Calibration.xml from DaVis export

Calibration Image Setup

Before running calibration, you need to configure how PIVTools locates your calibration target images. This setup differs from PIV image configuration in several important ways, particularly around directory structure and camera subfolder handling.

Path Order Options

When using camera subfolders for multi-camera setups, you can choose how the directory structure is organised. This flexibility accommodates different lab conventions.

camera_first (default)

Camera folder contains calibration subfolder

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

calibration_first

Calibration folder contains camera subfolders

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

IM7 Container Format Handling

LaVision IM7 files can contain data from multiple cameras in a single file, or each camera can have its own files in separate subfolders. Theuse_camera_subfolderssetting controls which mode PIVTools expects.

Multi-camera IM7 (default)

Set use_camera_subfolders: false. Each .im7 file contains data for all cameras.

source_path/
└── calibration/
├── B00001.im7 (Cam1+Cam2)
└── B00002.im7

Single-camera IM7

Set use_camera_subfolders: true. Each camera's .im7 files are in separate subdirectories.

source_path/
├── Cam1/B00001.im7
├── Cam1/B00002.im7
├── Cam2/B00001.im7
└── Cam2/B00002.im7

GUI Controls

Image Type:Standard, CINE, LaVision SET, LaVision IM7

Image Format:Filename pattern (e.g., calib%05d.tif)

Number of Images:Total calibration images to process

Calibration Subfolder:Subfolder within source path

Use Camera Subfolders:Toggle for multi-camera organisation

Path Order:camera_first or calibration_first

Camera Subfolder Names:Custom names (e.g., View_Left, View_Right)

Platform Compatibility

LaVision formats (.im7, .set) require the ReadIMX library which is only available on Windows and Linux. macOS users should export calibration images to TIFF format.

Scale Factor Method

The simplest calibration method. Scale Factor applies a uniform conversion from pixels to millimeters across the entire image. No calibration target images are required - you just need to know the pixel-to-mm ratio and the time between frames.

Conversion Formula

x_mm = x_px / px_per_mm

v_ms = (v_px / px_per_mm) / (dt × 1000)

Where px_per_mm is the number of pixels per millimeter, and dt is the time between frames in seconds.

How to Measure px_per_mm

1.Place a ruler or known-size object in the field of view
2.Capture an image and measure the pixel distance
3.Divide pixels by millimeters

Example: 1024 px across 300 mm = 3.41 px/mm

Parameters

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

GUI Workflow

1Select source path from dropdown
2Enter Δt (time between frames in seconds)
3Enter px_per_mm (from your measurement)
4Click "Calibrate Vectors" to apply calibration
5Click "Set as Active" to make this the active method

Planar Dotboard

Planar Dotboard calibration uses OpenCV's camera model to compute intrinsic parameters (focal length, principal point) and distortion coefficients from images of a circular dot grid target. This method provides spatially-varying calibration that corrects for lens distortion.

Requirements

Calibration target with regular grid of circular dots
Multiple images from different angles (typically 10-20)
Known physical spacing between dots

Parameters

Parameter	Description	Example
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 images	false
asymmetric	Asymmetric grid pattern	false
dt	Time between frames (seconds)	0.0057553

GUI Workflow

1Configure calibration images (Image Type, Format, Number)
2Set grid detection parameters (cols, rows, spacing)
3Browse calibration images to verify detection works
4Click "Generate Model" to run calibration
5Review camera matrix and RMS reprojection error
6Click "Calibrate Vectors" to apply to PIV data
7Click "Set as Active" to make this the active method

Outputs

Camera Matrix: Intrinsic parameters (fx, fy, cx, cy)
Distortion Coefficients: 5 radial/tangential params
Extrinsics: Rotation and translation vectors
RMS Error: Reprojection error (quality metric)

Output Directory

base_path/
└── calibration/
    └── Cam1/
        └── dotboard_planar/
            ├── model/
            ├── indices/
            └── figures/

Planar ChArUco

ChArUco calibration combines a chessboard pattern with ArUco markers for robust detection. The ArUco markers allow identification of which corners are visible, making this method work even with partial occlusion or at oblique viewing angles.

Advantages over Dotboard

Works with partial visibility (markers identify corners)
More robust in low contrast conditions
Easier detection at oblique angles

ArUco Dictionary Options

Different marker sizes and quantities. Larger dictionaries allow more unique markers.

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
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 to accept frame	6
dt	Time between frames (seconds)	0.0057553

GUI Workflow: Same as Dotboard - configure images, set parameters, generate model, apply to vectors, and set as active method.

Polynomial (LaVision XML)

Polynomial calibration uses 3rd-order polynomial coefficients exported from LaVision DaVis software. This method reads the standard Calibration.xml file format and applies polynomial distortion correction to convert pixel coordinates to world coordinates.

Use XML Mode (Default)

Automatically reads polynomial coefficients from Calibration.xml file. This is the standard approach for LaVision DaVis users.

Default location:
source_path/calibration/Calibration.xml

Manual Entry Mode

Disable "Use XML" to manually enter polynomial coefficients. Useful when XML is not available or coefficients are from another source.

10 coefficients per axis:
1, s, s², s³, t, t², t³, st, s²t, st²

Parameters per Camera

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

GUI Workflow

1Enable "Use XML values" toggle (default)
2Set XML path (or leave empty for default location)
3Coefficients auto-populate from XML
4Click "Calibrate Vectors" to apply calibration
5Click "Set as Active" to make this the active method

CLI Usage

Calibration uses two separate CLI commands: one to generate the camera model from calibration images, and one to apply the calibration to PIV vectors.

Step 1: Generate Camera Model

Detect calibration targets and generate camera model files.

Model Generation Commands

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

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

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

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

Step 2: Apply Calibration to Vectors

Apply the generated camera model to convert PIV vectors from pixels to physical units. Use the --method flag to override the calibration method from config.yaml.

Apply Calibration

pivtools-cli apply-calibration [OPTIONS]

Options

Flag	Description	Default
--method, -m	Calibration method: dotboard, charuco, or scale_factor	From config
--camera, -c	Camera number to process	All 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

# Calibrate using method from config.yaml
pivtools-cli apply-calibration

# Override with dotboard calibration method
pivtools-cli apply-calibration --method dotboard

# Use scale factor calibration
pivtools-cli apply-calibration --method scale_factor

# Calibrate camera 1 with charuco method
pivtools-cli apply-calibration --method charuco --camera 1

# Calibrate ensemble data
pivtools-cli apply-calibration --type-name ensemble

# Process specific paths and runs
pivtools-cli apply-calibration -c 1 -t instantaneous -r 1,2,3

Complete Workflow

Full Calibration Workflow

# 1. Generate camera model from calibration images
pivtools-cli detect-planar

# 2. Run PIV processing
pivtools-cli instantaneous

# 3. Apply calibration to vectors (uses config method)
pivtools-cli apply-calibration

# Or specify method explicitly
pivtools-cli apply-calibration --method dotboard

Tip: Use --method to override the calibration method from config.yaml. Available methods:dotboard,charuco, andscale_factor.

Complete YAML Configuration

For power users who prefer direct YAML configuration, here's a complete reference with all calibration-related options.

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

  # Calibration image settings
  image_format: planar_calibration_plate_%02d.tif
  num_images: 19
  image_type: standard  # standard, cine, lavision_set, lavision_im7
  zero_based_indexing: false
  use_camera_subfolders: true
  subfolder: enhanced
  camera_subfolders: ["Cam1", "Cam2"]
  path_order: camera_first  # or calibration_first

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

  # Dotboard Method
  dotboard:
    camera: 1
    pattern_cols: 10
    pattern_rows: 10
    dot_spacing_mm: 12.22
    enhance_dots: false
    asymmetric: false
    grid_tolerance: 0.5
    ransac_threshold: 3
    dt: 0.0057553
    source_path_idx: 0

  # ChArUco Method
  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) Method
  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: []

GUI to YAML Field Mapping

GUI Control	YAML Field	Description
Active Method Button	calibration.active	scale_factor, dotboard, charuco, polynomial
PIV Type Selector	calibration.piv_type	instantaneous or ensemble
Image Format	calibration.image_format	Calibration image filename pattern
Number of Images	calibration.num_images	Total calibration images
Image Type	calibration.image_type	standard, cine, lavision_set, lavision_im7
Use Camera Subfolders	calibration.use_camera_subfolders	Enable camera subfolder organisation
Path Order	calibration.path_order	camera_first or calibration_first
Calibration Subfolder	calibration.subfolder	Subfolder within source path
Camera Subfolder Names	calibration.camera_subfolders	Custom folder names array

Next: Create Visualisation Videos

Now that your vectors are calibrated, create animated visualisations of your velocity fields using the Video Maker tool.

Continue to Video Maker