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

Operation	Description	Effect on Data
flip_ud	Flip vertically (upside down)	Spatial flip + velocity component adjustment
flip_lr	Flip horizontally (left-right)	Spatial flip + velocity component adjustment
rotate_90_cw	Rotate 90 degrees clockwise	Spatial rotation + velocity vector rotation
rotate_90_ccw	Rotate 90 degrees counter-clockwise	Spatial rotation + velocity vector rotation
rotate_180	Rotate 180 degrees	Equivalent to flip_ud + flip_lr

Velocity Component Operations

Operation	Description	Effect on Data
swap_ux_uy	Swap ux and uy components	ux becomes uy, uy becomes ux
invert_ux_uy	Negate velocity components	ux = -ux, uy = -uy

Scaling Operations

Operation	Description	Example Use
scale_velocity:factor	Multiply all velocities by factor	scale_velocity:1000 converts m/s to mm/s
scale_coords:factor	Multiply all coordinates by factor	scale_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:

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.

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.

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.

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.

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

Parameter	Type	Description
base_path_idx	integer	Index into base_paths array (0-indexed)
type_name	string	Temporal type: "instantaneous" or "ensemble"
source_endpoint	string	Data source: "regular" (per-camera), "merged", or "stereo"
cameras	dict	Per-camera transform configuration
cameras.N.operations	list	List 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