Vector Transforms

Rotate, flip, and scale PIV vector fields to correct camera orientations, align multi-camera setups, or convert between unit systems.

Overview

Transforms modify .mat files directly. The original data is kept for undo as a sibling key inside the same file --piv_result_original,ensemble_result_original,coordinates_original -- not as a separate file.

Requirements

Calibrated instantaneous, ensemble, or merged data
Not applicable to statistics output or stereo (3C) fields

Key Behaviours

Coordinates file updated alongside vector data
Ensemble stresses (UU, VV, UV) handled correctly
Redundant operations automatically simplified

Transforms are Permanent

Transforms write directly to your .mat files. Apply transforms before merging and statistics. After transforming, recalculate any existing statistics.

Operations

Operation	Description	Effect
flip_ud	Flip vertically	Spatial flip of all fields
flip_lr	Flip horizontally	Spatial flip of all fields
rotate_90_cw	Rotate 90 degrees clockwise	Spatial + coordinate rotation
rotate_90_ccw	Rotate 90 degrees counter-clockwise	Spatial + coordinate rotation
rotate_180	Rotate 180 degrees	Equivalent to flip_ud + flip_lr
swap_ux_uy	Swap ux and uy components	UU_stress <-> VV_stress for ensemble
invert_ux_uy	Negate ux and uy	Stresses unchanged (variance is sign-invariant)
invert_ux	Negate ux only	UV_stress sign flips; UU, VV unchanged
invert_uy	Negate uy only	UV_stress sign flips; UU, VV unchanged
scale_velocity:<factor>	Multiply velocities by factor	Stresses scaled by factor squared
scale_coords:<factor>	Multiply coordinates by factor	Only x, y grids affected

Automatic Simplification

Redundant operations are reduced using algebraic group properties:

flip_ud + flip_ud(no operation)

rotate_90_cw x 4(no operation)

scale_velocity:1000 + scale_velocity:0.5scale_velocity:500

GUI Workflow

In the Results Viewer, expand the Transforms panel to add, preview, and apply operations.

Step	Action
1	Select a calibrated instantaneous, ensemble, or merged data source.
2	Expand the Transforms panel and click operation buttons to build a queue.
3	The current frame preview updates immediately. Navigate frames to verify.
4	Click "Apply to All Frames" to write transforms to all .mat files.
5	Use "Clear Transforms" to restore the original data and empty the pending queue.

CLI Usage

The CLI processes all active_paths without preview. Test your configuration in the GUI first.

Transform CLI

# Apply transforms from config.yaml
pivtools-cli transform

# Override operations via command line
pivtools-cli transform -o flip_ud,rotate_90_cw

# Transform specific camera
pivtools-cli transform --camera 1

# Transform merged data
pivtools-cli transform --source-endpoint merged -o flip_lr

# Process specific paths only
pivtools-cli transform -p 0,1

No Preview in CLI

CLI transforms are applied immediately to all active paths. Always test on one dataset via the GUI first.

Configuration

Transform operations are configured per-camera in config.yaml.

transforms:
  base_path_idx: 0          # Which base_path (GUI only)
  type_name: instantaneous  # "instantaneous" or "ensemble"
  source_endpoint: regular  # "regular", "merged", or "stereo"
  cameras:
    1:
      operations:
        - flip_ud
        - rotate_90_cw
    2:
      operations:
        - flip_lr
        - scale_velocity:1000
        - scale_coords:0.001

Parameter	Type	Description
base_path_idx	int	Index into base_paths (0-indexed, GUI only)
type_name	string	"instantaneous" or "ensemble"
source_endpoint	string	"regular" (per-camera), "merged", or "stereo"
cameras.N.operations	list	Ordered list of transforms for camera N

Next: Merge Multi-Camera Data

Combine vector fields from multiple cameras into a single seamless field with blended overlaps.

Continue to Merging