Global Coordinates
Align multi-camera coordinate systems into a unified physical reference frame after calibration.
Overview
After calibrating each camera independently, their coordinate systems may not share a common origin or orientation. Global coordinate alignment shifts and optionally flips each camera's coordinates so all fields share the same physical reference frame.
- Chain topology: cameras linked N to N+1 via shared feature points
- Datum point defines the physical origin on Camera 1
- Overlap features identify the same physical location across adjacent cameras
- Automatic x-direction detection with manual override
- Applied automatically after calibration in the GUI, or standalone via CLI
Concepts
Chain Topology
Cameras are linked in a chain: Camera 1 connects to Camera 2, Camera 2 connects to Camera 3, and so on. For N cameras, you need N-1 overlap pairs. Each pair identifies a single physical feature visible from both cameras.
The camera chain must be continuous — every adjacent pair needs an overlap point. For example, cameras 1, 2, 3, 4 require pairs 1→2, 2→3, 3→4. Gaps (e.g., 1→3 without 2) are not supported.
Datum Point
The datum is a point on Camera 1's calibration image that defines where the physical origin (0, 0) is located. You click the image to select it. The datum has physical coordinates (in mm) that default to (0, 0) but can be set to any value if your origin is offset from the datum feature.
Overlap Pairs
Each adjacent camera pair requires one shared feature. For each pair, you pick the same physical point on both cameras' images. The alignment algorithm uses these matched points to compute the coordinate shift between cameras.
| Term | Description |
|---|---|
| Origin (O) | The datum pixel on Camera 1. Defines physical (0,0) or a specified offset. |
| Feature (F) | A matched point shared by two adjacent cameras. Each camera in a pair has one feature. |
| Overlap pair | Two cameras (A, B) linked by a shared feature. pixel_on_a and pixel_on_b identify the same physical location. |
| Invert Ux | Negate x-velocities and reflect x-coordinates when the physical x-direction runs opposite to the image x-direction. |
Invert Ux
When the first overlap feature is to the left of the datum on Camera 1, the physical x-direction runs opposite to the image x-direction. The GUI auto-detects this from the relative positions of the origin and first feature, toggling the Flip X switch automatically. You can override this manually if needed.
When Invert Ux is active, the alignment process negates ux and UV_stress in all cameras' vector files, and reflects x-coordinates around the datum physical x-position in the coordinates file.
GUI Workflow
The Global Coordinates controls appear inline in the Calibration Image Viewer settings bar. Enable the toggle and use the inline buttons to pick points on calibration images.
| Step | Action |
|---|---|
| 1 | Open any calibration method tab (Dotboard, ChArUco, etc.) to access the Calibration Image Viewer. |
| 2 | Enable the "Global Coords" toggle in the settings bar. |
| 3 | On Camera 1, click "Set Origin" then click the datum point on the image. A green crosshair marks the origin. |
| 4 | Optionally adjust the physical X and Y coordinates (in mm) if your origin is offset from (0, 0). |
| 5 | Still on Camera 1, click "Pick F1" to select the feature shared with Camera 2. Click the overlap point on the image. |
| 6 | Navigate to Camera 2 using the camera arrows. Click "Pick F1" to select the same physical feature as seen by Camera 2. |
| 7 | For additional cameras, Camera 2 also needs "Pick F2" for the feature shared with Camera 3, and so on. |
| 8 | The Flip X toggle auto-detects based on the origin and first feature positions. Override manually if needed. |
| 9 | Run calibration ("Calibrate Vectors"). Global alignment is applied automatically. |
Camera Participation
Each camera picks features for the pairs it participates in:
| Camera | Features to Pick | Role |
|---|---|---|
| Camera 1 (datum) | Origin + F1 | Origin point, side A of pair 1-2 |
| Middle cameras | F1 + F2 | Side B of left pair, side A of right pair |
| Last camera | F1 | Side B of final pair |
Auto-applied: When global coordinates are enabled and configured, alignment is applied automatically after calibration completes in the GUI. No separate step is needed.
Feature markers are labelled C{cam}F{n} (e.g., C2F1 for Camera 2's first feature). The origin on Camera 1 is marked with a green"O". Blue markers show overlap features.
Global coordinate alignment is not supported for polynomial (LaVision XML) calibration. Use dotboard, ChArUco, or scale factor calibration methods instead.
CLI Usage
Two ways to apply global coordinate alignment via CLI:
Standalone Command
# Apply alignment to instantaneous data
pivtools-cli align-coordinates
# Apply to ensemble data
pivtools-cli align-coordinates -t ensemble
# Process specific paths
pivtools-cli align-coordinates -p 0,1
# Force re-alignment (skip idempotency guard)
pivtools-cli align-coordinates --forceCombined with Calibration
# Calibrate and align in one step
pivtools-cli apply-calibration --align-coordinates
# With specific method
pivtools-cli apply-calibration --method dotboard --align-coordinatesalign-coordinates Options
| Flag | Description | Default |
|---|---|---|
| --type-name, -t | Data type: instantaneous or ensemble | instantaneous |
| --active-paths, -p | Comma-separated path indices | From config |
| --force, -f | Force alignment even if already applied (will double shifts) | false |
Idempotency guard: Running align-coordinates twice without re-calibrating will be blocked to prevent doubling coordinate shifts. A sidecar marker file (alignment_applied.json) tracks whether alignment has already been applied. Fresh calibration automatically clears this marker. Use --force to override if needed.
Global coordinates must be configured in config.yaml before running the CLI command. Use the GUI to set up datum and overlap points, or edit the YAML directly.
Complete Workflow
# 1. Detect calibration targets
pivtools-cli detect-planar
# 2. Run PIV processing
pivtools-cli instantaneous
# 3. Calibrate vectors and align coordinates in one step
pivtools-cli apply-calibration --align-coordinates
# 4. Merge cameras
pivtools-cli merge
# 5. Compute statistics
pivtools-cli statisticsYAML Configuration
Global coordinate settings are stored under calibration.global_coordinates in config.yaml.
calibration:
global_coordinates:
enabled: true
datum_camera: 1 # Always 1 (not configurable)
datum_pixel: [512.0, 384.0] # Pixel position of origin on Camera 1
datum_physical: [0.0, 0.0] # Physical coordinates (mm) at datum
datum_frame: 1 # Calibration frame for datum selection
invert_ux: false # Negate ux + reflect x-coords
overlap_pairs:
- camera_a: 1
camera_b: 2
pixel_on_a: [950.0, 400.0] # Feature pixel on Camera 1
pixel_on_b: [120.0, 400.0] # Same feature pixel on Camera 2
frame_a: 1
frame_b: 1
- camera_a: 2
camera_b: 3
pixel_on_a: [930.0, 410.0]
pixel_on_b: [100.0, 405.0]
frame_a: 1
frame_b: 1Configuration Fields
| Field | Type | Description |
|---|---|---|
| enabled | bool | Enable global coordinate alignment |
| datum_camera | int | Camera that holds the origin (always Camera 1, not user-configurable) |
| datum_pixel | [x, y] | Pixel position of origin on datum camera image |
| datum_physical | [x, y] | Physical coordinates (mm) at datum point |
| datum_frame | int | Calibration frame used for datum point pixel-to-physical conversion |
| invert_ux | bool | Negate ux, UV_stress, and reflect x-coordinates |
| overlap_pairs | list | List of adjacent camera pair feature points |
| overlap_pairs[].camera_a | int | First camera in the pair |
| overlap_pairs[].camera_b | int | Second camera in the pair |
| overlap_pairs[].pixel_on_a | [x, y] | Feature pixel on camera_a image |
| overlap_pairs[].pixel_on_b | [x, y] | Same feature pixel on camera_b image |
| overlap_pairs[].frame_a | int | Calibration frame for camera_a |
| overlap_pairs[].frame_b | int | Calibration frame for camera_b |
Next: Create Videos
Visualise your aligned, calibrated velocity fields with animated videos.
Continue to Video Maker