Video Maker

Create high-quality MP4 videos from your PIV data. Visualise velocity fields, derived statistics, and merged stereo data with customisable colormaps and resolution.

Overview

The Video Maker creates animated visualisations of your PIV velocity fields. It supports instantaneous PIV data, computed statistics (vorticity, Reynolds stresses), and merged stereo fields. Videos are encoded using FFmpeg with H.264 for maximum compatibility.

1. Select Data

Camera, source, variable

2. Configure

Limits, colormap, resolution

3. Create

Test or full video

4. Browse

View and manage videos

GUI Usage

The Video Maker panel in the GUI provides a streamlined interface for creating PIV visualisation videos. It automatically detects available data sources and variables, making it easy to create professional-quality animations of your experimental data.

Data Selection

Base Path

Select the experiment directory from the dropdown if multiple paths are configured, or browse to a directory manually. The Video Maker looks for processed PIV data in the standard output structure.

Camera

Select which camera's data to visualise. For single-camera setups, this defaults to Camera 1. For stereo setups, you can create videos from individual cameras or use merged data.

Data Source

The Video Maker automatically detects which data types are available:

Calibrated: Physical units (mm, m/s)
Uncalibrated: Pixel displacements
Merged: Combined multi-camera fields
Stereo: 3D stereo-reconstructed fields (ux, uy, uz)
Inst Stats: Per-frame calculated statistics (vorticity, etc.)

Tip: The GUI shows frame counts for each available data source, helping you verify the correct dataset is selected.

Variable Selection

Variables are organised into groups based on their source. The dropdown automatically shows only variables available in your processed data.

Instantaneous Variables

Direct PIV output from frame correlation:

uxuyuzmag

Calculated Per-Frame

Computed statistics (requires statistics processing):

u'v'u'u'v'v'u'v'vorticitydivergence

Note: The mag (velocity magnitude) variable is always available and computed as sqrt(ux² + uy²). For stereo data, uz is included in the magnitude calculation.

Video Settings

Run Selection

If your PIV was processed with multiple runs (passes), select which run to visualise. The highest run number typically contains the most refined results.

Color Limits

Set lower and upper bounds for the colormap. Leave blank for auto-detection using 5th-95th percentiles across all frames for consistent scaling.

Colormap

Choose from matplotlib colormaps. "Default" uses bwr (blue-white-red) for diverging data, automatically adjusting for positive/negative ranges.

Resolution

Output video resolution:

1080p: 1920×1080 (Full HD)
4K: 3840×2160 (Ultra HD)

Aspect ratio is preserved; the video fits within the selected resolution.

Frame Rate (FPS)

Set the playback speed. Default is 30 FPS. Higher values create smoother playback; lower values extend video duration. Range: 1-120 FPS.

Creating Videos

Test Video (50 frames)

Creates a short preview using the first 50 frames. Use this to:

Verify color limits are appropriate
Check the colormap looks correct
Confirm the correct variable/run is selected
Preview output quality before full render

Create Full Video

Renders all frames into a complete video. Processing time depends on:

Number of frames (shown in data source info)
Output resolution (4K takes longer)
CPU performance and available memory

Progress Tracking

A progress bar shows the current frame being processed. You can cancel video creation at any time using the Cancel button. Completed videos appear in the result panel with inline playback controls.

Browse Videos Tab

The Browse Videos tab lists all existing videos in the current base path's videos/ directory. Select any video from the dropdown to preview it directly in the browser.

Automatic detection of MP4, AVI, MOV, and MKV files
Videos sorted by modification time (newest first)
In-browser playback with standard video controls
Refresh button to update the list after creating new videos

CLI Usage

The Video Maker can be run from the command line for batch processing or integration into automated workflows. It reads default parameters from config.yamlwith command-line overrides available for all options.

Running from Command Line

Basic Usage

# Create video with settings from config.yaml
pivtools-cli video

# Specify variable to visualise
pivtools-cli video --variable mag

# Override camera and run
pivtools-cli video --camera 1 --run 2

# Set data source
pivtools-cli video --data-source merged

# Custom resolution and quality
pivtools-cli video --resolution 4k --crf 10

# Custom color limits
pivtools-cli video --variable vorticity --lower -100 --upper 100

# Use specific colormap
pivtools-cli video --cmap viridis

# Test mode (50 frames only)
pivtools-cli video --test

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

CLI Options

Flag	Description
--camera, -c	Camera number
--variable, -v	ux, uy, mag, vorticity, etc.
--run, -r	Run number (default: 1)
--data-source, -d	calibrated, uncalibrated, merged, stereo, inst_stats
--fps	Frame rate (default: 30)
--crf	Quality 0-51 (default: 15, lower=better)
--resolution	e.g., 1920x1080 or 4k
--cmap	Colormap name
--lower	Lower color limit
--upper	Upper color limit
--test	Test mode: 50 frames only
--active-paths, -p	Comma-separated path indices

Config File Defaults

All options default to values in config.yaml under thevideo section. Command-line flags override config settings.

VideoMaker Class

For programmatic use, import and instantiate the VideoMaker class:

Python API Usage

from pathlib import Path
from pivtools_gui.video_maker.video_maker import VideoMaker
from pivtools_core.config import get_config

# Load configuration
config = get_config()

# Create VideoMaker instance
maker = VideoMaker(
    base_dir=Path("/path/to/results"),
    camera=1,
    config=config,
)

# Create a video
result = maker.process_video(
    variable="ux",           # Variable to visualise
    run=1,                   # Run number (1-based)
    data_source="calibrated",# calibrated, uncalibrated, merged, stereo, inst_stats
    fps=30,                  # Frame rate
    crf=15,                  # Quality factor
    resolution=(1080, 1920), # Output resolution (H, W)
    cmap="viridis",          # Colormap (None for auto)
    lower_limit=None,        # Color limits (None for auto)
    upper_limit=None,
    test_mode=False,         # Quick test with 50 frames
    test_frames=50,
)

if result["success"]:
    print(f"Video created: {result['out_path']}")
    print(f"Color limits: {result['vmin']:.3f} to {result['vmax']:.3f}")
    print(f"Frames: {result['frames']}, Time: {result['elapsed_sec']:.1f}s")
else:
    print(f"Error: {result['error']}")

Return Value

The process_video() method returns a dictionary containing:

success: bool

out_path: str (video file path)

vmin, vmax: float

actual_min, actual_max: float

effective_run: int

frames: int

elapsed_sec: float

error: str (if failed)

Progress Callbacks & Cancellation

For long-running video creation, you can provide a progress callback and cancellation event:

Progress Tracking

import threading

# Create a cancellation event
cancel_event = threading.Event()

def progress_callback(current_frame, total_frames, message=""):
    percent = int(current_frame / total_frames * 100)
    print(f"Progress: {percent}% ({current_frame}/{total_frames}) {message}")

result = maker.process_video(
    variable="mag",
    run=1,
    data_source="calibrated",
    fps=30,
    progress_callback=progress_callback,
    cancel_event=cancel_event,  # Set this event to cancel
)

# To cancel from another thread:
# cancel_event.set()

Data Sources

The Video Maker supports multiple data sources, each stored in a specific location within the output directory structure. Understanding these sources helps you choose the right data for visualisation.

calibrated

Calibrated PIV

Velocity fields in physical units (mm/s or m/s) after applying spatial calibration. This is typically the preferred source for final visualisation.

base_path/calibrated_piv/{n}/Cam{c}/instantaneous/

uncalibrated

Uncalibrated PIV

Raw pixel displacements before calibration. Useful for debugging or when calibration is not available.

base_path/uncalibrated_piv/{n}/Cam{c}/instantaneous/

merged

Merged Multi-Camera

Multi-camera merged 2D velocity fields using Hanning blend. Created from overlapping camera views (ux, uy only).

base_path/calibrated_piv/{n}/Merged/instantaneous/

stereo

Stereo 3D PIV

3D velocity fields from stereo reconstruction. Includes all three velocity components (ux, uy, uz) from two camera views.

base_path/stereo_calibrated/{n}/Cam1_Cam2/instantaneous/

inst_stats

Instantaneous Statistics

Per-frame computed statistics including fluctuations, Reynolds stresses, vorticity, and divergence. Requires statistics processing to be run first.

base_path/statistics/{n}/Cam{c}/instantaneous/instantaneous_stats/

Important: Ensemble Data

Ensemble-averaged data cannot be used for video creation. Ensemble averaging produces a single mean field with no temporal sequence. To create a video, you must use instantaneous or merged data which contains per-frame information.

Available Variables

The Video Maker can visualise any 2D field stored in your PIV data files. Variables are automatically detected from the first frame file and grouped by source type.

Variable	Display Label	Description	Source
ux	ux	Velocity component in x-direction	PIV
uy	uy	Velocity component in y-direction	PIV
uz	uz	Velocity component in z-direction (stereo)	PIV
mag	Velocity Magnitude	sqrt(ux² + uy² [+ uz²])	Computed
u_prime	u'	Fluctuating velocity in x	Statistics
v_prime	v'	Fluctuating velocity in y	Statistics
uu_inst	u'u'	Reynolds normal stress (x)	Statistics
vv_inst	v'v'	Reynolds normal stress (y)	Statistics
uv_inst	u'v'	Reynolds shear stress	Statistics
vorticity	ω (Vorticity)	Out-of-plane vorticity component	Statistics
divergence	∇·u (Divergence)	Velocity divergence	Statistics
gamma1	γ₁	Swirling strength criterion	Statistics
gamma2	γ₂	Vortex core identification	Statistics

Auto-switching: When you select a statistics variable (like vorticity), the Video Maker automatically switches to the inst_stats data source. This ensures the correct files are loaded without manual intervention.

Colormaps

Choose from a variety of matplotlib colormaps to best represent your data. The default colormap (bwr) is designed for diverging data like velocity components that can be positive or negative.

default

Auto (bwr for diverging)

viridis

Perceptually uniform

plasma

Warm perceptually uniform

inferno

Dark perceptually uniform

magma

Dark-to-bright

cividis

Colorblind-friendly

jet

Classic rainbow

hot

Black-red-yellow-white

cool

Cyan-magenta

twilight

Cyclic colormap

gray

Grayscale

bone

Blue-tinted grayscale

Default Colormap Behavior

When set to "default", the colormap is selected automatically:

Diverging data (min < 0 < max): Uses bwr (blue-white-red), symmetric around zero
All positive: Uses the upper half of bwr (white-to-red)
All negative: Uses the lower half of bwr (blue-to-white)

YAML Configuration

Video settings can be configured in config.yaml under the video block. The GUI automatically updates these settings when you make changes.

video:
  # Data selection
  base_path_idx: 0           # Index into paths.base_paths array
  camera: 1                  # Camera number (1-based)
  data_source: calibrated    # calibrated, uncalibrated, merged, stereo, inst_stats
  variable: ux               # Variable to visualise
  run: 1                     # Run number (1-based)
  piv_type: instantaneous    # Must be instantaneous for videos

  # Visual settings
  cmap: default              # Colormap name or "default" for auto
  lower: ""                  # Lower color limit ("" for auto)
  upper: ""                  # Upper color limit ("" for auto)

  # Output settings
  fps: 30                    # Frame rate (1-120)
  crf: 15                    # Quality factor (0-51, lower = better)
  resolution: 1080p          # "1080p" or "4k"

  # Batch processing (optional)
  active_paths: [0]          # Which path indices to process
  cameras: [1, 2]            # Cameras for batch processing
  include_merged: false      # Include merged data in batch

GUI to YAML Field Mapping

GUI Control	YAML Field	Type
Base Path dropdown	video.base_path_idx	int
Camera selector	video.camera	int
Data Source dropdown	video.data_source	string
Variable dropdown	video.variable	string
Run selector	video.run	int
Colormap dropdown	video.cmap	string
Lower limit input	video.lower	string
Upper limit input	video.upper	string
FPS input	video.fps	int
Resolution dropdown	video.resolution	string

Output Structure

Videos are saved in a structured directory hierarchy under your base path. The filename includes the run number, camera, variable, and data source for easy identification.

Video Output Directory Structure

base_path/
└── videos/
    └── {num_frame_pairs}/
        ├── Cam1/
        │   ├── run1_Cam1_ux.mp4
        │   ├── run1_Cam1_ux_test.mp4      # Test videos
        │   ├── run1_Cam1_mag.mp4
        │   ├── run1_Cam1_uy_uncalibrated.mp4
        │   └── stats/                      # Statistics videos
        │       ├── run1_Cam1_vorticity_inst_stats.mp4
        │       └── run1_Cam1_uv_inst_inst_stats.mp4
        ├── Cam2/
        │   └── ...
        ├── merged/                         # Merged multi-camera videos
        │   ├── run1_Cam1_ux_merged.mp4
        │   └── run1_Cam1_mag_merged.mp4
        └── stereo/                         # Stereo 3D videos
            ├── run1_Cam1_Cam2_ux_stereo.mp4
            ├── run1_Cam1_Cam2_uz_stereo.mp4
            └── run1_Cam1_Cam2_mag_stereo.mp4

Filename Convention

Video filenames follow the pattern:

run{run}_Cam{camera}_{variable}[_{source}][_test].mp4

_test: Added for test videos (50 frames)
_uncalibrated: Added for uncalibrated data
_merged: Added for merged multi-camera data
_stereo: Added for stereo 3D PIV data
_inst_stats: Added for instantaneous statistics

Video Quality Settings

The Video Maker uses FFmpeg with H.264 encoding optimised for scientific visualisation. These settings ensure sharp, artifact-free videos suitable for publication.

Encoding Settings

Codec:libx264

Pixel format:yuv420p

Default CRF:15

Preset:slow

Tune:stillimage

Quality (CRF) Guide

CRF (Constant Rate Factor) controls quality vs file size. Lower values = higher quality.

0-15Near-lossless (large files)

15-23High quality (recommended)

23-28Medium quality

28+Lower quality

Optimisations for Scientific Data

The Video Maker includes special optimisations for smooth gradient visualisation:

High LUT resolution (4096 levels): Reduces color banding
Adaptive quantization: Preserves smooth gradients
stillimage tuning: Optimised for slow-changing content
faststart flag: Enables streaming playback

Ready to Visualise Your Data

Create compelling visualisations of your PIV experiments. Start with a test video to verify your settings, then generate the full animation.

Learn About Statistics Processing