Vector Transforms

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

When to Use Transforms

Transforms are essential when your cameras have different orientations or when you need to align vector fields before merging. They're also useful for converting between unit systems (e.g., m/s to mm/s).

Alignment

Match camera orientations

Correction

Fix mirrored views

Conversion

Change units

Overview

Vector transforms modify the spatial arrangement and/or values of your PIV data. They are applied directly to the .mat files containing your vector fields, making the changes permanent. This is intentional - transformed data can then be used by other operations like merging and statistics.

Key Features

  • Geometric transforms (rotate, flip)
  • Velocity component operations
  • Coordinate and velocity scaling
  • Automatic transform simplification
  • Backup of original data

Requirements

  • Calibrated vector data only
  • Instantaneous or merged data
  • Not applicable to ensemble results
  • Not applicable to statistics output

Important: Transforms are Permanent

Transforms modify your .mat files directly. Original data is backed up with an_original suffix, but you should ensure you have backups before applying transforms to production data.

Available Operations

PIVTools provides a comprehensive set of transform operations. These can be combined in sequence, and redundant operations are automatically simplified.

Geometric Transforms

OperationDescriptionEffect on Data
flip_udFlip vertically (upside down)Spatial flip + velocity component adjustment
flip_lrFlip horizontally (left-right)Spatial flip + velocity component adjustment
rotate_90_cwRotate 90 degrees clockwiseSpatial rotation + velocity vector rotation
rotate_90_ccwRotate 90 degrees counter-clockwiseSpatial rotation + velocity vector rotation
rotate_180Rotate 180 degreesEquivalent to flip_ud + flip_lr

Velocity Component Operations

OperationDescriptionEffect on Data
swap_ux_uySwap ux and uy componentsux becomes uy, uy becomes ux
invert_ux_uyNegate velocity componentsux = -ux, uy = -uy

Scaling Operations

OperationDescriptionExample Use
scale_velocity:factorMultiply all velocities by factorscale_velocity:1000 converts m/s to mm/s
scale_coords:factorMultiply all coordinates by factorscale_coords:0.001 converts mm to m

Automatic Simplification

PIVTools automatically simplifies redundant operations. For example:

flip_ud + flip_ud(no operation)
rotate_90_cw x 4(no operation)
flip_lr + flip_udrotate_180
scale_velocity:1000 + scale_velocity:0.5scale_velocity:500

GUI Workflow

The GUI provides an interactive way to preview and apply transforms to your data. Follow these steps to transform your vector fields:

1

Open the Results Viewer

Navigate to the Results Viewer and select your calibrated instantaneous data source. Ensure you have the correct base path and camera selected.

2

Expand the Transforms Panel

Click the "Transforms" button to expand the transforms control panel. This reveals all available transform operations and the current transform queue.

3

Add Transform Operations

Click on transform buttons to add operations to the queue. Each click adds the operation to the pending list. The current frame preview updates immediately to show the effect.

4

Preview the Result

Check the transformed view in the main display. Navigate through frames to verify the transform looks correct across your dataset. Use "Clear List" to reset if needed.

5

Apply to All Frames

Once satisfied, click "Apply to All Frames" to permanently apply the transforms to all frames in the dataset. A progress bar shows the operation status.

Preview Mode

Adding transforms updates the current frame preview immediately. This lets you verify the orientation before committing changes to all frames.

Undo Frame

Use "Undo Frame" to restore the original data for the current frame. This reverts to the backed-up data stored with _original.

CLI Usage

For batch processing across multiple datasets, use the command-line interface. The CLI processes all paths listed in active_paths, making it ideal for production workflows.

Transform CLI Command
# Apply transforms configured in config.yaml pivtools-cli transform # Apply specific transforms via command line pivtools-cli transform -o flip_ud,rotate_90_cw # Transform specific camera only pivtools-cli transform --camera 1 # Transform merged data pivtools-cli transform --source-endpoint merged -o flip_lr # Transform stereo 3D data pivtools-cli transform --source-endpoint stereo -o flip_ud # Process specific paths pivtools-cli transform -p 0,1 # The CLI will: # 1. Read transforms.cameras configuration (or use -o flag) # 2. Process each camera's operations in order # 3. Apply to ALL frames in selected paths # 4. Show progress for each path/camera combination

GUI vs CLI Comparison

GUI Mode
  • - Interactive preview before applying
  • - One base_path at a time
  • - Ideal for testing and setup
  • - Visual verification of results
CLI Mode
  • - Batch processing all active_paths
  • - No interaction required
  • - Configure once, run on many datasets
  • - Suitable for automated pipelines

Batch Processing Warning

CLI transforms are applied immediately to all active paths without preview. Test your transform configuration on one dataset using the GUI first, then use CLI for batch processing.

YAML Configuration

Transform operations are configured per-camera in the transformssection of config.yaml. Each camera can have its own list of operations.

transforms: base_path_idx: 0 # Which base_path to use (GUI only) type_name: instantaneous # Temporal type: "instantaneous" or "ensemble" source_endpoint: regular # Data source: "regular", "merged", or "stereo" cameras: 1: operations: - flip_ud # First: flip vertically - rotate_90_cw # Then: rotate 90 degrees 2: operations: - flip_lr # Camera 2: flip horizontally only 3: operations: - scale_velocity:1000 # Convert m/s to mm/s - scale_coords:0.001 # Convert mm to m # Note: Operations are applied in order, top to bottom # Redundant operations are automatically simplified # For stereo data, transforms are applied to the combined 3D field

Configuration Parameters

ParameterTypeDescription
base_path_idxintegerIndex into base_paths array (0-indexed)
type_namestringTemporal type: "instantaneous" or "ensemble"
source_endpointstringData source: "regular" (per-camera), "merged", or "stereo"
camerasdictPer-camera transform configuration
cameras.N.operationslistList of transform operations for camera N

Important Notes

Keep these important considerations in mind when working with transforms:

Statistics Must Be Recalculated

After applying transforms, any previously calculated statistics are no longer valid. You must recalculate statistics using the Statistics panel to get correct results with the transformed data.

Transforms Modify Files Permanently

Transform operations write directly to your .mat files. While original data is backed up with _original suffix, you should maintain your own backups of important data.

Transform Before Merging

If you plan to merge multi-camera data, apply transforms before merging. Ensure all cameras have the same orientation before running the merge operation.

Coordinate Files Updated Automatically

When you apply geometric transforms (rotate, flip), the associatedcoordinates.mat file is also transformed to maintain consistency.

Next: Merge Multi-Camera Data

Now that your cameras are aligned, learn how to merge vector fields from multiple cameras into a single seamless field.

Continue to Merging