Video Maker

Create MP4 videos from instantaneous PIV data with customisable colormaps, resolution, and encoding quality.

GUI Usage

The Video Maker tab provides controls for data selection, colour limits, and encoding settings. A test mode renders the first 50 frames for quick preview.

Step	Action
1	Select base path, camera, data source, and variable.
2	Set colour limits (leave blank for auto 5th-95th percentile scaling).
3	Choose colormap, resolution (1080p / 4K), and FPS.
4	Click "Test Video" (50 frames) to preview, or "Create Video" for all frames.
5	Use the Browse Videos tab to play back or manage existing videos.

Browse Videos

The Browse tab lists all MP4/AVI/MOV/MKV files in the base path'svideos/ directory, sorted newest-first with in-browser playback.

CLI Usage

Command-line flags override values from config.yaml.

Video CLI

# Create video with config.yaml defaults
pivtools-cli video

# Specify variable and data source
pivtools-cli video --variable mag --data-source calibrated

# Custom resolution, quality, and colormap
pivtools-cli video --resolution 4k --crf 10 --cmap viridis

# Set colour limits
pivtools-cli video --variable vorticity --lower -100 --upper 100

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

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

Flag	Description
--camera, -c	Camera number (1-based)
--variable, -v	ux, uy, uz, mag, vorticity, etc.
--run, -r	Pass number (default: 1)
--data-source, -d	calibrated, uncalibrated, merged, stereo, inst_stats
--fps	Frame rate 1-120 (default: 30)
--crf	Quality 0-51 (default: 15, lower = better)
--resolution	1080p or 4k
--cmap	Colormap name (default: bwr)
--lower / --upper	Colour limits (blank = auto)
--test	Render first 50 frames only
--active-paths, -p	Comma-separated path indices

Data Sources

Only instantaneous (per-frame) data can be used for videos. Ensemble data produces a single field with no temporal sequence.

Source	Description	Path
calibrated	Physical-unit velocity fields	calibrated_piv/{n}/Cam{c}/instantaneous/
uncalibrated	Raw pixel displacements	uncalibrated_piv/{n}/Cam{c}/instantaneous/
merged	Multi-camera Hanning-blended fields	calibrated_piv/{n}/merged/Cam1/instantaneous/
stereo	3D velocity (ux, uy, uz)	stereo_calibrated/{n}/Cam1_Cam2/instantaneous/
inst_stats	Per-frame computed statistics	statistics/{n}/Cam{c}/.../instantaneous_stats/

Available Variables

Variables are auto-detected from the first frame file. Statistics variables (vorticity, stresses, gamma) require the statistics module to have been run first.

Variable	Description	Source
ux	Velocity in x	PIV
uy	Velocity in y	PIV
uz	Velocity in z (stereo only)	PIV
mag	Velocity magnitude sqrt(ux^2 + uy^2 [+ uz^2])	Computed
u_prime	Fluctuating velocity in x	Statistics
v_prime	Fluctuating velocity in y	Statistics
uu_inst	Reynolds normal stress (x)	Statistics
vv_inst	Reynolds normal stress (y)	Statistics
uv_inst	Reynolds shear stress	Statistics
vorticity	Out-of-plane vorticity	Statistics
divergence	Velocity divergence	Statistics
gamma1	Swirling strength criterion	Statistics
gamma2	Vortex core identification	Statistics

Colormaps

Default colormap is bwr (blue-white-red), which auto-adjusts: symmetric around zero for diverging data, half-map for all-positive or all-negative ranges.

Colormap	Style
default (bwr)	Diverging blue-white-red (auto)
viridis	Perceptually uniform
plasma	Warm perceptually uniform
inferno	Dark perceptually uniform
cividis	Colourblind-friendly
jet	Classic rainbow
hot	Black-red-yellow-white
twilight	Cyclic
gray	Greyscale

YAML Configuration

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

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

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

Output

Videos are saved under videos/ with filenames encoding the pass, camera, variable, and data source.

Output Directory

base_path/
  videos/{num_frame_pairs}/
    Cam1/
      run1_Cam1_ux.mp4
      run1_Cam1_mag.mp4
      run1_Cam1_ux_test.mp4         # Test video (50 frames)
      stats/
        run1_Cam1_vorticity_inst_stats.mp4
    merged/
      run1_Cam1_ux_merged.mp4
    stereo/
      run1_Cam1_Cam2_uz_stereo.mp4

Filename Pattern

run{pass}_Cam{camera}_{variable}[_{source}][_test].mp4— suffixes added for uncalibrated, merged, stereo, inst_stats, and test mode.

Video Quality

H.264 encoding with FFmpeg, optimised for scientific visualisation.

Setting	Value
Codec	libx264
Pixel format	yuv420p
Preset	slow
Tune	stillimage (optimised for smooth gradients)
Default CRF	15 (near-lossless)
LUT resolution	4096 levels (reduces colour banding)
Faststart	Enabled (streaming playback)

CRF Range	Quality
0-15	Near-lossless (large files)
15-23	High quality (recommended)
23-28	Medium quality
28+	Lower quality (small files)

Back to Results Viewer

Return to the Results Viewer to explore all viewing and post-processing options.

Results Viewer