PIV Processing

Configure multi-pass cross-correlation for instantaneous frame-pair or ensemble correlation averaging analysis.

Overview

PIVTools supports two distinct processing modes, each suited for different experimental scenarios. Choose the mode that best matches your analysis requirements.

Instantaneous PIV

Processes individual frame pairs to produce velocity fields for each time step. Ideal for time-resolved analysis and turbulent flow statistics.

Per-frame velocity vectors

Temporal statistics (mean, RMS, Reynolds stresses)

Live progress preview during processing

Peak finder algorithm selection

Ensemble PIV

Averages correlation planes across all frame pairs before peak detection. Produces high-fidelity mean flow fields with reduced noise.

Mean flow field only (no individual frames)

Higher spatial resolution with single mode

Resume processing from saved passes

Diagnostic plane storage for inspection

When to Use Each Mode

Use Instantaneous when:

You need time-resolved velocity data
Computing turbulence statistics
Analyzing unsteady/transient flows
Good particle seeding density

Use Ensemble when:

Only mean flow is needed
Low particle seeding density
Maximum spatial resolution required
Noisy or challenging image conditions

Window Configuration

Both processing modes use multi-pass refinement with configurable interrogation windows. Each pass uses the results of the previous pass to improve vector accuracy.

Multi-Pass Strategy

Window Size: The interrogation window dimensions in pixels [X, Y]. Larger windows capture more particles but reduce spatial resolution.
Overlap: Percentage of window overlap between adjacent vectors. 50% overlap doubles the vector grid density.
Store Flag: Toggle to save intermediate pass results. The final pass is always stored.
Pass Order: Processing starts with large windows and progressively refines to smaller windows for accuracy.

Instantaneous

Window Setup

Configure passes in the GUI using the pass table. Each row represents one refinement pass.

Window X

Window Y

Overlap %

Store

Actions

Pass #

128

Pass 1

Pass 2

Pass 3

Add Pass

config.yaml

instantaneous_piv:
  window_size:
  - [128, 128]   # Pass 1: Large windows for initial estimate
  - [64, 64]    # Pass 2: Medium refinement
  - [32, 32]    # Pass 3: Final high-resolution
  overlap:
  - 50          # 50% overlap for all passes
  - 50
  - 50
  runs:
  - 3           # Save final pass (pass 3)

Ensemble

Window Setup with Pass Types

Ensemble mode adds a Type column to select between standard and single correlation modes.

Window X

Window Y

Overlap %

Type

Store

Actions

Pass

128

Standard

Single

Standard (std)

Both Frame A and Frame B use identical window weighting. Standard cross-correlation at the specified window size.

Single

Asymmetric weighting for higher spatial resolution. Requires sum_window configuration. See next section for details.

config.yaml

ensemble_piv:
  window_size:
  - [128, 128]  # Pass 1: Standard mode
  - [64, 64]   # Pass 2: Standard mode
  - [16, 16]   # Pass 3: Single mode (high resolution)
  overlap:
  - 50
  - 50
  - 50
  type:
  - std        # Standard correlation
  - std        # Standard correlation
  - single     # Single-pixel accumulation
  runs:
  - 3          # Save final pass

Single Mode & Sum Window

Ensemble-Only Feature

When any pass uses "single" type, the Sum Window configuration appears. This enables a powerful technique for achieving higher spatial resolution while maintaining FFT efficiency.

How Single Mode Works

Single mode uses asymmetric window weighting between Frame A and Frame B:

Frame A: "singlepix"

Small window (e.g., 4×4) centered within the larger sum_window (16×16). Only the central 4×4 region has weight = 1, surrounding pixels = 0. This concentrates the measurement on a small spatial region.

Frame B: "bsingle"

Full sum_window (16×16) with uniform weight = 1 everywhere. Captures particles across the entire correlation domain, providing robust statistics for peak detection.

Example: window_size [4, 4] with sum_window [16, 16]

The correlation is computed at 16×16 resolution, but the effective measurement is concentrated at the central 4×4 region. This gives you the spatial resolution of a 4×4 window with the peak-fitting accuracy of a 16×16 correlation plane.

Higher spatial resolution: Effective measurement concentrated at small window size
FFT efficiency: Correlation computed at sum_window size (16×16 FFT, not 4×4)
Better peak definition: Larger correlation plane improves sub-pixel fitting accuracy
Ensemble robustness: Averaging reduces noise while maintaining resolution

Validation Requirement

The sum_window must be greater than or equal to the window_size for all single-type passes. For example, if window_size is [16, 16], sum_window must be at least [16, 16].

config.yaml

ensemble_piv:
  window_size:
  - [16, 16]    # Small window for single mode
  type:
  - single      # Enables sum_window
  sum_window:
  - 64          # Sum window width (X)
  - 64          # Sum window height (Y)

Camera Selection

Select which cameras to process. This is particularly useful for multi-camera setups where you want to process specific views independently.

Camera Selector

The GUI displays numbered chips for each available camera. Click to toggle selection. At least one camera must be selected.

Cameras to Process:

Click to select/deselect cameras

config.yaml

paths:
  camera_count: 3      # Total cameras available
  camera_numbers:      # Cameras to process
  - 1                  # Only process camera 1

Peak Finding

Instantaneous PIV Only: Peak finder algorithm selection is available in the Advanced PIV Settings. Ensemble PIV uses gauss6 by default for optimal accuracy with averaged correlation planes.

The peak finder algorithm determines how sub-pixel displacement is extracted from the correlation peak. Higher parameter counts provide better accuracy but require more computation.

gauss3

3-Parameter Gaussian

Fastest. Basic Gaussian fit for quick processing.

Speed: FastestAccuracy: Good

gauss4

4-Parameter Gaussian

Adds amplitude parameter. Better peak detection.

Speed: FastAccuracy: Better

gauss5

5-Parameter Gaussian

Includes elliptical shape. Good for anisotropic flows.

Speed: ModerateAccuracy: High

gauss6

6-Parameter Gaussian

Full 2D Gaussian with rotation. Maximum accuracy.

Speed: SlowestAccuracy: Highest

config.yaml

instantaneous_piv:
  peak_finder: gauss3   # Options: gauss3, gauss4, gauss5, gauss6

Ensemble-Specific Options

Ensemble PIV Only: These options are available in the collapsible "Ensemble Options" panel.

store_planes

Store Correlation Planes

Saves the auto-correlation (AA, BB) and cross-correlation (AB) planes to planes_pass_N.mat files. Useful for manual inspection of correlation quality or debugging.

Warning: Enabling this creates large output files. Use only when debugging or inspecting correlation quality.

save_diagnostics

Save Diagnostics

Saves debug information to a filters/ subdirectory:

Peak fitting inputs and outputs
Warped images for each pass
Filter application results (first batch, first pair)

resume_from_pass

Resume From Pass

Continue processing from existing results. Enter the pass number (1-based) to resume from.

Use Case: Adding a Finer Pass

If you've completed passes 1-3 with window sizes [128, 64, 32] and want to add a pass 4 at 16×16: set resume_from_pass: 4 to skip re-processing passes 1-3. Requires an existing ensemble_result.mat in the output directory.

Set to 0 for a fresh start (default).

config.yaml

ensemble_piv:
  store_planes: false      # Save AA, BB, AB correlation planes
  save_diagnostics: false  # Save debug images and data
  resume_from_pass: 0      # 0 = fresh start, N = resume from pass N

Performance Settings

Configure parallel processing resources. These settings affect both instantaneous and ensemble modes. Access via the "Performance & Compute Settings" collapsible panel.

Setting	Description	Default
omp_threads	OpenMP threads per worker for parallelized operations	2
dask_workers_per_node	Number of parallel Dask workers (typically = CPU cores)	4
dask_threads_per_worker	Threads each Dask worker can use	1
dask_memory_limit	RAM allocation per worker (e.g., "3GB", "4GB")	3GB
filter_worker_count	Workers dedicated to preprocessing filters	1

Filter Worker Count

The filter worker enables overlapped processing: while correlation workers process the current batch, the filter worker can preprocess the next batch.

Set to 1 for temporal filters (time, POD) to avoid memory issues
Set to 2+ for spatial-only filters for better throughput

config.yaml

processing:
  omp_threads: 2
  dask_workers_per_node: 4
  dask_threads_per_worker: 1
  dask_memory_limit: 3GB
  filter_worker_count: 1
  auto_compute_params: false  # Set true to auto-detect optimal values

Outlier Detection

Identify and mark spurious vectors for replacement. Multiple detection methods can be chained together. Enable/disable via the toggle in the "Outlier Detection" collapsible panel.

peak_mag

Peak Magnitude

Rejects vectors with weak correlation peaks below threshold.

threshold=0.3Minimum peak magnitude

Typically used in instantaneous only

median_2d

Median-Based

Compares each vector to the median of its 8 neighbors.

epsilon=0.2Regularization term

threshold=2.0Normalized residual threshold

Good for local outlier detection

sigma

Standard Deviation

Statistical outlier based on neighbor standard deviation.

sigma_threshold=2.0Std dev multiplier

Best for Gaussian-distributed errors

Different YAML Paths

Instantaneous and Ensemble use separate configuration sections. This allows different outlier detection strategies for each mode.

Instantaneous

config.yaml

outlier_detection:
  enabled: true
  methods:
  - type: peak_mag
    threshold: 0.3
  - type: median_2d
    epsilon: 0.2
    threshold: 2

Ensemble

config.yaml

ensemble_outlier_detection:
  enabled: true
  methods:
  - type: median_2d
    epsilon: 0.2
    threshold: 2

Infilling Methods

Replace outlier vectors (marked as NaN) with interpolated values. Infilling occurs in two phases:

Mid-Pass Infilling

Applied between multi-pass iterations. Always enabled to ensure smooth predictor fields for window deformation.

Final-Pass Infilling

Applied to the output after the last pass. Optional—can be disabled if you prefer to keep NaN markers.

local_median

Local Median

Fast, simple infilling using the median of neighboring vectors.

ksize=3Kernel size (3×3, 5×5, etc.)

Best for: Quick infilling, small gaps

biharmonic

Biharmonic Inpainting

Smooth PDE-based interpolation that respects local flow gradients.

Best for: High-quality results, larger gaps

knn

K-Nearest Neighbors

Distance-weighted regression using nearby valid vectors.

n_neighbors=32Number of neighbors

weights=distanceWeighting scheme

Best for: Sparse data, irregular gaps

Instantaneous

config.yaml

infilling:
  mid_pass:
    method: biharmonic
    parameters:
      ksize: 3
  final_pass:
    enabled: true
    method: biharmonic
    parameters:
      ksize: 3

Ensemble

config.yaml

ensemble_infilling:
  mid_pass:
    method: biharmonic
    parameters:
      ksize: 3
  final_pass:
    enabled: true
    method: biharmonic
    parameters:
      ksize: 3

Running PIV

Start processing from the Run PIV card. Both modes share common controls but differ in feedback display.

Common Controls

Select Source Path

Choose which dataset to process from the dropdown.

Click "Run PIV"

Starts processing. Button disabled while running.

Cancel (if needed)

Stops processing gracefully. Partial results may be saved.

Instantaneous Feedback

Progress bar with percentage complete
Live status image preview of processed frames
Variable selector (ux, uy, nan_mask, peak_mag)
Colormap and contrast controls
Console output with real-time logs

Ensemble Feedback

Simple status indicator (Processing.../Complete)
Console output with pass progress
No preview image (no interim frame data)
Batch progress shown in console logs

Why No Ensemble Preview?

Ensemble PIV processes all frames together to build averaged correlation planes before extracting vectors. Unlike instantaneous mode, there are no intermediate per-frame results to display. Monitor progress via the console output, which shows batch and pass completion.

config.yaml

# Enable instantaneous mode
processing:
  instantaneous: true
  ensemble: false

# OR enable ensemble mode
processing:
  instantaneous: false
  ensemble: true

Complete YAML Reference

Below is a complete reference of all PIV-related configuration options.

YAML Path	Inst.	Ens.	Description
*_piv.window_size	✓	✓	List of [X, Y] window sizes per pass
*_piv.overlap	✓	✓	Overlap percentages per pass
*_piv.runs	✓	✓	Passes to save (1-based list)
ensemble_piv.type	—	✓	Pass types: std or single
ensemble_piv.sum_window	—	✓	Sum window for single mode [X, Y]
ensemble_piv.store_planes	—	✓	Save correlation planes
ensemble_piv.save_diagnostics	—	✓	Save debug information
ensemble_piv.resume_from_pass	—	✓	Resume from pass N (0=fresh)
instantaneous_piv.peak_finder	✓	—	Peak algorithm: gauss3-6
outlier_detection.*	✓	—	Instantaneous outlier config
ensemble_outlier_detection.*	—	✓	Ensemble outlier config
infilling.*	✓	—	Instantaneous infilling config
ensemble_infilling.*	—	✓	Ensemble infilling config
processing.instantaneous	✓	—	Enable instantaneous mode
processing.ensemble	—	✓	Enable ensemble mode

config.yaml

# Complete PIV Configuration Example
# ===================================

# Processing mode (choose one)
processing:
  instantaneous: true   # Frame-pair mode
  ensemble: false       # Correlation averaging mode
  backend: cpu          # cpu or gpu
  omp_threads: 2
  dask_workers_per_node: 4
  dask_threads_per_worker: 1
  dask_memory_limit: 3GB
  filter_worker_count: 1

# Instantaneous PIV settings
instantaneous_piv:
  window_size:
  - [128, 128]
  - [64, 64]
  - [32, 32]
  overlap:
  - 50
  - 50
  - 50
  runs:
  - 3
  peak_finder: gauss3

# Ensemble PIV settings
ensemble_piv:
  window_size:
  - [128, 128]
  - [64, 64]
  - [16, 16]
  overlap:
  - 50
  - 50
  - 50
  type:
  - std
  - std
  - single
  runs:
  - 3
  sum_window:
  - 64
  - 64
  store_planes: false
  save_diagnostics: false
  resume_from_pass: 0

# Outlier detection (instantaneous)
outlier_detection:
  enabled: true
  methods:
  - type: peak_mag
    threshold: 0.3
  - type: median_2d
    epsilon: 0.2
    threshold: 2

# Outlier detection (ensemble)
ensemble_outlier_detection:
  enabled: true
  methods:
  - type: median_2d
    epsilon: 0.2
    threshold: 2

# Infilling (instantaneous)
infilling:
  mid_pass:
    method: biharmonic
    parameters:
      ksize: 3
  final_pass:
    enabled: true
    method: biharmonic
    parameters:
      ksize: 3

# Infilling (ensemble)
ensemble_infilling:
  mid_pass:
    method: biharmonic
    parameters:
      ksize: 3
  final_pass:
    enabled: true
    method: biharmonic
    parameters:
      ksize: 3

Need to Calibrate?

Convert pixel displacements to physical velocities with calibration.

Back to Quick Start