Vector Merging

Combine vector fields from multiple cameras into a single seamless field using Hanning window blending for smooth overlap transitions.

Overview

Merging creates a unified coordinate grid spanning all cameras and interpolates velocity data onto it. In overlap regions, a distance-based Hanning cosine window provides smooth, seam-free transitions.

Supports both instantaneous and ensemble data
Automatic overlap detection and stacking direction
Unified coordinate grid matching original data resolution
Hanning cosine blending: weight = 0.5 * (1 + cos(pi * d))
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. Hanning weights	In overlap regions, each camera receives a distance-based weight: w = 0.5 * (1 + cos(pi * d_normalised)).
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.

Output Directory

base_path/
  calibrated_piv/{num_frame_pairs}/
    Cam1/instantaneous/       # Original camera 1
    Cam2/instantaneous/       # Original camera 2
    merged/
      Cam1/instantaneous/     # Single "virtual" camera
        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