Vector Merging

Combine vector fields from multiple cameras into a single seamless field, extending your measurement domain with smooth overlap blending.

Extend Your Measurement Domain

Multi-camera PIV setups often capture overlapping regions to cover large experimental domains. Merging combines these fields into one unified vector field with smooth transitions in the overlap regions using Hanning window blending.

Multi-Camera

2 or more cameras

Hanning Blend

Smooth overlaps

Extended FOV

Larger domain

Overview

Vector merging creates a unified coordinate grid spanning all cameras and interpolates velocity data onto this grid. In overlap regions where multiple cameras contribute, a distance-based Hanning window weighting ensures smooth transitions without visible seams.

Key Features

Automatic overlap detection
Hanning cosine window blending
Unified coordinate grid generation
Support for any number of cameras
Parallel frame processing

Output

Single merged .mat file per frame
Unified coordinates.mat file
Compatible with statistics calculation
Standard piv_result format

Requirements & Restrictions

Merging has specific requirements that must be met. Understanding these restrictions will help you plan your workflow correctly.

Requirements

2+ Cameras

Merging requires at least two cameras. Single-camera setups have nothing to merge.

Calibrated Data

Physical coordinates are required to align and merge fields. Run calibration first.

Overlapping FOV

Cameras should have overlapping regions for smooth blending. Non-overlapping cameras are also supported.

Critical Restriction

No Stereo (3D) Data

Merging is blocked for stereo PIV setups. When auz (out-of-plane velocity) component is detected in your data, the merge button will be disabled.

Why?

Stereo calibration already combines both camera views into a single 3D velocity field. The concept of "merging" doesn't apply because the cameras are not looking at adjacent regions - they're looking at the same region from different angles to reconstruct the third velocity component.

Other Restrictions

Instantaneous or Ensemble Only

Merging works on calibrated_instantaneous or calibrated_ensemble data sources. Statistics output cannot be merged (recalculate after merging instead).

Same Run Structure

All cameras must have the same number of runs and frames. Mismatched datasets cannot be merged.

Hanning Blend Algorithm

The merging algorithm creates a smooth combined field by using distance-based Hanning window weighting in overlap regions. Here's how it works:

Detect Stacking Direction

The algorithm determines if cameras are arranged horizontally or vertically based on their center coordinates. This affects how overlap regions are blended.

Create Unified Grid

A new coordinate grid is generated that spans the full extent of all cameras. Grid spacing matches the original data resolution.

Interpolate Each Camera

Each camera's velocity field is interpolated onto the unified grid. Points outside a camera's domain are marked as NaN.

Apply Hanning Weights

In overlap regions, each camera receives a weight based on its distance from the boundary. The Hanning cosine function provides smooth transitions:

weight = 0.5 * (1 + cos(pi * normalised_distance))

Combine Fields

The weighted contributions from all cameras are summed and normalised. The result is a seamless field with no visible boundaries.

Understanding Hanning Blending

Camera 1 Region

Weight = 1.0 (full contribution)

Overlap Region

Weights blend from 1.0 to 0.0

Camera 2 Region

Weight = 1.0 (full contribution)

The Hanning window ensures that at any point in the overlap, the weights sum to 1.0, preventing brightness discontinuities or velocity jumps.

GUI Workflow

The GUI provides a simple interface for merging your multi-camera data. Follow these steps to create merged vector fields:

Open the Results Viewer

Navigate to the Results Viewer and select "Calibrated Instantaneous" as your data source. The merge option only appears for calibrated, multi-camera, non-stereo data.

Expand the Merging Panel

Click the "Merging" button to expand the merge controls. If this button is not visible, check that you have 2+ cameras configured and are not using stereo data.

Select Cameras to Merge

Check the boxes for each camera you want to include in the merge. At least 2 cameras must be selected. The merge will only use the selected cameras.

Merge Current Frame or All Frames

Use "Merge Frame N" to test on a single frame, or "Merge All" to process the entire dataset. A progress bar shows completion status.

View Merged Results

After merging completes, select "Merged Instantaneous" from the data source dropdown to view the combined field. The merged data appears as a single camera view.

Camera Selection Saved

Your camera selection is saved to config.yaml automatically. This selection is used for both GUI merging and CLI batch processing.

CLI Usage

For batch processing multiple datasets, use the CLI. It processes all paths listed in active_paths.

Merging CLI Command

# Merge vectors for all active paths
pivtools-cli merge

# Merge specific cameras only
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

# The CLI will:
# 1. Read merging configuration from config.yaml
# 2. Process each active_path (or selected paths with -p)
# 3. Merge all frames for each path
# 4. Save results to merged/ subdirectory

GUI vs CLI Comparison

GUI Mode

- One base_path at a time
- Interactive camera selection
- Test single frames first
- Immediate visualisation

CLI Mode

- All active_paths processed
- Uses saved camera selection
- Batch processing
- Suitable for automation

YAML Configuration

Merging settings are stored in the mergingsection of config.yaml.

merging:
  base_path_idx: 0          # Which base_path to use
  type_name: instantaneous  # instantaneous or ensemble
  cameras: [1, 2]           # Cameras to merge (saved from GUI selection)

paths:
  active_paths:
    - 0    # CLI processes all these
    - 1
    - 2
  camera_numbers: [1, 2, 3]  # Available cameras in setup

images:
  num_frame_pairs: 100      # Total frames to process
  vector_format:
    - '%05d.mat'            # Output filename pattern

Configuration Parameters

Parameter	Type	Description
merging.base_path_idx	integer	Index into base_paths array (GUI only)
merging.type_name	string	Vector type: "instantaneous" or "ensemble"
merging.cameras	list	Camera numbers to merge (e.g., [1, 2])

Output Structure

Merged vector fields are saved in a mergedsubdirectory under your calibrated_piv path.

Output Directory Structure

base_path/
├── calibrated_piv/
│   └── {num_frame_pairs}/
│       ├── Cam1/
│       │   └── instantaneous/      # Original camera 1 data
│       │       ├── 00001.mat
│       │       ├── 00002.mat
│       │       └── coordinates.mat
│       │
│       ├── Cam2/
│       │   └── instantaneous/      # Original camera 2 data
│       │       └── ...
│       │
│       └── merged/                 # MERGED OUTPUT
│           └── Cam1/               # Single "virtual" camera
│               └── instantaneous/
│                   ├── 00001.mat   # Merged frame 1
│                   ├── 00002.mat   # Merged frame 2
│                   ├── ...
│                   └── coordinates.mat  # Unified grid

Merged Frame Files

Each merged .mat file contains the combined velocity field in standard piv_result format. Compatible with all downstream operations.

Unified Coordinates

A single coordinates.mat file defines the unified grid covering the combined domain of all merged cameras.

Next: Calculate Statistics

Now that your fields are merged, calculate mean velocities, Reynolds stresses, and turbulence quantities across your time series.

Continue to Statistics