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	'4k' or WIDTHxHEIGHT (e.g. 1920x1080); other values fall back to 1920x1080
--cmap	Colormap name (config default: viridis; 'default' = auto 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 blended fields	calibrated_piv/{n}/Merged/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
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	Graftieaux Γ1 vortex-centre criterion	Statistics
gamma2	Vortex core identification	Statistics

Colormaps

The config default is viridis. The special value default selects an auto-adjusting bwr (blue-white-red): 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
  source_endpoint: regular     # regular, merged, or stereo

  cmap: viridis                # Colormap name, or "default" for auto bwr
  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", "4k", or "native"
  source_endpoint: regular     # regular | merged | stereo

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}_{cmap}_{limits}[_{source}][_test].mp4-- the colormap and colour limits are baked into the name, so re-rendering the same field with a different scale will not overwrite the earlier video. Suffixes are 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	veryslow
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