Results Viewer
Visualise PIV vector fields with interactive controls. The Results Viewer is the central hub for inspecting data, applying transforms, merging cameras, and computing statistics.
Overview
The Results Viewer displays colour-mapped vector fields from any data source. It is a GUI-only feature -- there is no CLI equivalent for interactive viewing.
- Frame-by-frame navigation with slider, arrow buttons, and Play/Pause animation
- Adjustable colormaps and colour limits (manual or auto-calculated)
- Hover data display: coordinates plus velocity at cursor position
- Axis limits, coordinate offsets, and custom plot titles
- One-click image download and clipboard copy
- Access to Transforms, Merging, and Statistics panels from the viewer
Data Types
The data source selector determines which vector files are loaded and which post-processing operations are available.
| Data Source | View | Transforms | Merge | Statistics |
|---|---|---|---|---|
| Calibrated Instantaneous | ||||
| Calibrated Ensemble | - | |||
| Uncalibrated Instantaneous | - | - | ||
| Uncalibrated Ensemble | - | - | - | |
| Merged Instantaneous | - | |||
| Merged Ensemble | - | - | ||
| Stereo Instantaneous | - | - |
Uncalibrated Data
Transforms and merging require calibrated data with physical coordinates. Statistics are not view-only here though: uncalibrated instantaneous data is the only source that can run the correlation-quality diagnostics, because the quality channels are dropped when calibration is applied. On an uncalibrated source the Statistics button reads Calculate Diagnostics.
Stereo Merging
Merging is blocked for stereo data. Stereo calibration already combines both camera views into a single 3D field.
Viewing Controls
Controls for customising the display. All settings are saved to config.yaml automatically.
| Control | Description |
|---|---|
| Colormap | default, viridis, plasma, inferno, magma, cividis, jet, gray, and more |
| Lower / Upper Limit | Manual colour bounds. Leave blank for automatic scaling per frame. |
| Auto-Calculate | Samples up to 50 frames and returns 5th/95th percentile limits. |
| Frame Slider | Drag to any frame. Arrow buttons step +/-1. Play/Pause animates through frames as fast as they load (capped at ~3 FPS). |
| Run / Pass | Select which multi-pass PIV run to display (highest = most refined). |
| Axis Limits | X min/max, Y min/max. Blank = auto from coordinate data. |
| X / Y Offset | Shift displayed coordinates without modifying data. |
| Plot Title | Custom title shown above the colour-mapped image. |
Interactive Tools
The viewer toolbar provides interactive tools for inspecting and exporting your data.
| Tool | Description |
|---|---|
| Magnifier | Circular 2.5x zoom lens that follows the cursor. Toggle on/off with the magnifier button. Useful for inspecting individual vectors and fine details. |
| Box Zoom | Drag a rectangle over the field to zoom to it. Toggle off to return to normal cursor behaviour. |
| Hover Info | Displays coordinates (x, y in mm) and velocity components (ux, uy, uz if stereo) at the cursor position. Over a NaN vector it also decodes why that vector was rejected. Updates in real time as you move the mouse. |
| NaN Reason Legend | Colours each rejected vector by the reason it failed and lists those reasons beside the field. The instantaneous and ensemble pipelines use different code tables, so the legend switches to match the data you are viewing. An unrecognised code is rendered loudly rather than silently ignored. |
| Wall Units | Enter a friction velocity and kinematic viscosity to redraw the axes in wall units (y+ and u+). This affects the display only and never modifies the stored data. Calibrated sources only. |
| Download Image | Saves the current vector field view as a PNG image file. |
| Copy to Clipboard | Copies the current view directly to the clipboard for pasting into documents or presentations. |
| Datum Setting | Click "Set New Datum" to interactively choose a new coordinate origin. The cursor changes to a crosshair -- click any point to set (0, 0) there. Available in the Coordinates panel. |
| Corner Coordinates | Displays the physical coordinates of the four corners of the current field. Useful for verifying alignment after global coordinate adjustment. |
Keyboard shortcuts: Use arrow keys to step through frames. Play/Pause animates through frames as fast as they load; there is no separate speed selector.
Variables
The variable dropdown is populated automatically from the data files. Variables are prefixed to indicate their source.
| Prefix | Source | Example Variables |
|---|---|---|
| inst: | Instantaneous frame data | ux, uy, uz, velocity_magnitude, b_mask, peak_mag |
| inst_stat: | Per-frame calculated statistics | vorticity, divergence, uu_inst, vv_inst, uv_inst, gamma1, gamma2 |
| mean: | Time-averaged statistics | ux, uy, uu, vv, uv, tke, vorticity, divergence |
| ens: | Ensemble-averaged results | ux, uy, UU_stress, VV_stress, UV_stress |
Display Labels
Some variables use mathematical notation in the dropdown for clarity:
u'u'
UU Reynolds stress
v'v'
VV Reynolds stress
u'v'
UV shear stress
TKE
Turbulent kinetic energy
omega
Vorticity
div u
Divergence
gamma1
Gamma 1 criterion
gamma2
Gamma 2 criterion
Configuration
Viewer settings are stored under the video key in config.yaml. The GUI updates this file automatically when you change settings.
video:
base_path_idx: 0 # Which base path to use (0-indexed)
camera: 1 # Camera number (1-based)
data_source: calibrated # calibrated, uncalibrated, merged, stereo, inst_stats
variable: ux # Variable to display
run: 1 # Run/pass number (1-based)
piv_type: instantaneous # instantaneous or ensemble
cmap: viridis # Colormap name
lower: '' # Lower colour limit (blank = auto)
upper: '' # Upper colour limit (blank = auto)GUI Mode
Processes one base_path at a time with interactive controls. Ideal for exploration and verifying settings.
CLI Mode
Transforms, merging, statistics, and video commands process all active_paths. Configure once in the GUI, then batch process via CLI.
Next: Transform Your Data
Rotate, flip, and scale your vector fields to correct camera orientations or convert between unit systems.
Continue to Transforms