Vector Merging

Combine vector fields from multiple cameras into a single seamless field, with smooth transitions across the overlap regions.

Overview

Merging creates a unified coordinate grid spanning all cameras and interpolates velocity data onto it. In overlap regions, each camera's contribution is weighted by how far inside its own valid area a point sits, giving smooth, seam-free transitions.

Supports both instantaneous and ensemble data
Automatic overlap detection and stacking direction
Unified coordinate grid matching original data resolution
Distance-weighted edge tapering across overlaps, with weights summing to 1.0
Output in standard piv_result .mat format

Requirements

Requirement	Detail
2+ cameras	At least two adjacent cameras must be selected as a continuous range
Calibrated data	Physical coordinates needed to align fields
Planar (2D) only	Stereo data with uz component is blocked
Same frame count	All cameras must have matching runs and frames

No Stereo (3D) Merging

Stereo calibration already combines both camera views into one 3D velocity field. When uz is detected, the merge button is disabled.

Algorithm

Step	Description
1. Detect direction	Determines horizontal or vertical camera arrangement from center coordinates.
2. Create grid	Generates a unified coordinate grid spanning all cameras at original resolution.
3. Interpolate	Each camera's velocity is interpolated onto the unified grid. Points outside a camera's domain are NaN.
4. Weight	Each camera gets a weight from how far inside its own valid region a point lies. The weight is flat at 1.0 through the centre of each field and tapers to 0 only near the edges, so a vector well inside one camera keeps that camera's value rather than being averaged with its neighbour.
5. Combine	Weighted contributions are summed and normalised. Weights always sum to 1.0 in overlaps.

GUI Workflow

Step	Action
1	Select a calibrated data source (Instantaneous or Ensemble) in the Results Viewer.
2	Expand the Merging panel (visible only for 2+ cameras, non-stereo).
3	Select the camera range using the From and To dropdowns. At least 2 adjacent cameras must be included.
4	Click "Merge Frame N" to test on one frame (instantaneous only), or "Merge All" for the full dataset.
5	The viewer automatically switches to the merged data source after completion.

CLI Usage

The CLI processes all active_paths using the camera selection saved in config.yaml.

Merge CLI

# Merge all active paths
pivtools-cli merge

# Merge specific cameras
pivtools-cli merge --cameras 1,2,3

# Merge ensemble data
pivtools-cli merge --type-name ensemble

# Process specific paths
pivtools-cli merge -p 0,1

Output

Merged data is saved in a Merged/ subdirectory under calibrated_piv, alongside the per-camera directories. There is no camera level beneath it -- the merged field replaces the per-camera ones rather than becoming another camera.

Output Directory

base_path/
  calibrated_piv/{num_frame_pairs}/
    Cam1/instantaneous/       # Original camera 1
    Cam2/instantaneous/       # Original camera 2
    Merged/instantaneous/
      00001.mat               # Merged frame 1
      00002.mat               # Merged frame 2
      ...
      coordinates.mat         # Unified grid

merging:
  base_path_idx: 0          # Which base_path (GUI only)
  type_name: instantaneous  # "instantaneous" or "ensemble"
  cameras: [1, 2]           # Camera numbers to merge

Next: Calculate Statistics

Compute mean velocities, Reynolds stresses, and turbulence quantities across your time series.

Continue to Statistics