Image Masking

Define regions to exclude from PIV processing using polygon masks or pixel borders. Masking prevents erroneous vectors in areas with poor seeding, reflections, or model boundaries.

Getting Started

The Masking panel is found on the Setup tab in the PIVTools GUI, below Image Configuration. Use it to exclude walls, model supports, reflections, or image edges from PIV analysis. Masked regions produce zero-valued vectors in the output fields.

1. Choose Mode

Polygon or Pixel Border

2. Define Regions

Draw polygons or set pixel values

3. Enable Mask

Toggle 'Apply Mask for PIV'

Masking Modes

PIVTools supports two masking modes. Select the mode from the Masking Mode dropdown in the Masking panel. Both modes can be toggled on or off for PIV processing using the Apply Mask for PIV switch.

Polygon Mode

Draw custom polygon shapes to mask irregular regions like model supports, walls, or reflections. Multiple polygons can be combined into a single mask. Polygons auto-save when completed, so your work is preserved automatically.

Best for: Complex shapes, angled surfaces, irregular boundaries, non-rectangular regions

Pixel Border Mode

Quickly mask fixed pixel borders from the top, bottom, left, and right edges of the image. Ideal for cropping noisy edges or removing fixed boundary regions. Values are stored directly in config.yaml.

Best for: Edge artifacts, fixed boundary regions, quick setup, uniform borders

Enable Masking: Toggle the "Apply Mask for PIV" switch to activate masking during processing. When enabled, masked regions will be set to zero in the output vector fields. The toggle affects both polygon and pixel border modes—whichever is currently selected.

Polygon Mask Editor

When Polygon mode is selected, an interactive canvas appears for drawing mask regions directly on your PIV images. The editor supports multiple polygons, edge snapping for precise boundary alignment, and a magnifier tool for accurate point placement.

How to Draw Polygons

Load an image

Select your source path, camera, and image index from the controls at the top of the Masking panel, then click Load Image. The image will appear in the editor canvas with adjustable contrast.

Click to add points

Click on the image to place polygon vertices. Points appear in green for the active polygon. Each click adds a new vertex, and lines are drawn between consecutive points.

Close the polygon

After placing at least 3 points, the starting point shows as a larger red circle with a transparent halo indicating the click radius. Click within this circle to close the polygon. Once closed, the polygon turns orange/yellow and a new empty polygon is automatically started.

Add more polygons

After closing, a new polygon starts automatically. You can also click New Polygon to start one manually at any time. All closed polygons are combined into a single mask.

Automatic Saving

Masks are saved automatically whenever you:

Complete a polygon by clicking the starting point
Delete a polygon using the Delete button
Clear all polygons using the Clear Mask button

No manual save action is required—your work is preserved automatically to mask_CamN.mat.

Edge Snapping

Click in the padding area outside the image boundaries to automatically snap points to the nearest edge or corner. This is essential for creating masks that extend precisely to the image boundary without leaving gaps.

How it works:

• The editor has padding around the image
• Clicking in the padding snaps to the nearest edge
• Corner snapping works at image corners
• Snapped points are clamped to 0 or max-1

Visual Indicator

When the magnifier is enabled, its border turns orange when you're in the snap zone outside the image. This confirms that your next click will snap to an edge.

Magnifier Tool

Enable the magnifier for precise point placement. A 2.5× zoomed circular view follows your cursor, showing crosshairs at the exact click position. The magnifier displays both the base image and any drawn polygons.

Toggle with the 🔍 button in the toolbar
2.5× zoom factor for fine detail work
Crosshairs indicate exact click position
Orange border when in edge-snap zone
Works in both image and padding areas

Contrast Controls

Adjust image contrast to see mask regions and boundaries more clearly. The contrast controls appear above the polygon editor when an image is loaded.

Dual-handle slider for min/max values
Values shown as percentages (0-100%)
Auto Scale toggle for automatic 1st-99th percentile
Works with any bit depth (8-bit, 16-bit)
Adjusting disables auto-scale automatically

Editor Toolbar

The toolbar above the canvas provides controls for polygon management, navigation, and export options:

New Polygon

Start a fresh polygon (auto-finishes current)

Undo Point

Remove the last point added to active polygon

Delete

Delete the currently selected polygon

Prev / Next

Navigate between polygons in the list

Polygon Dropdown

Select any polygon by name

🔍 Magnifier

Toggle the 2.5× zoom magnifier tool

Save PNG

Download mask as a PNG image file

🗑️ Clear Mask

Remove all polygons and reset mask

Status Indicators

The editor shows helpful status messages above the canvas:

Loading existing mask... — Checking for saved mask file

Loaded 3 polygon(s) — Existing mask loaded successfully

No existing mask found — Start clicking to create polygons

💡 Tips — Helpful hints about edge snapping and auto-closing

Pixel Border Mode

Pixel border mode provides a quick way to mask fixed rectangular regions at the image edges without drawing polygons. Simply enter the number of pixels to exclude from each edge. This is ideal for removing noisy edges, cropping fixed boundary artifacts, or creating a uniform border mask.

Configuration

Enter pixel values for each edge in the input fields. The preview updates live as you type, showing masked regions as a semi-transparent red overlay with red border lines at the mask boundaries.

Top

Pixels from top edge

Bottom

Pixels from bottom edge

Left

Pixels from left edge

Right

Pixels from right edge

Live Preview: Load an image first to see the mask overlay update in real-time as you adjust values. The preview shows exactly which regions will be excluded from PIV processing.

Red Overlay: Semi-transparent red regions show areas that will be excluded from PIV processing. Solid red lines mark the exact mask boundary for precise verification.

Automatic Saving: Pixel border values are saved automatically to config.yaml when you change them. No separate save action is needed.

Preview Information

The pixel border preview displays helpful information:

Current values: Shows Top, Bottom, Left, Right pixel values above the preview
Image size: Displays the native image dimensions (width × height in pixels)
Contrast adjustment: Works with auto-scale for optimal visibility

masking:
  enabled: true
  mode: rectangular    # 'rectangular' = pixel border mode
  rectangular:
    top: 64            # Mask 64 pixels from top edge
    bottom: 64         # Mask 64 pixels from bottom edge
    left: 0            # No left masking
    right: 0           # No right masking

# All values are in pixels
# Same settings apply to all cameras

Mask Storage & Loading

Polygon masks are saved as MATLAB .mat files containing both the binary mask array and the polygon vertex coordinates (for re-editing). Pixel border settings are stored directly in config.yaml.

Polygon Masks

Saved to your source directory as mask_Cam1.mat, mask_Cam2.mat, etc. The file contains both the binary mask and the polygon coordinates.

Binary mask array at full image resolution
Polygon vertices stored for re-editing
Polygon names preserved for reference
One file per camera
Auto-saved when polygons change

Pixel Borders

Stored in config.yaml under the masking.rectangular section. Applied at runtime during PIV processing—no separate file needed.

Saved automatically when you change values
Same settings apply to all cameras
No separate mask file required
Computed on-the-fly during processing
Values in pixels from each edge

Auto-Loading Masks

When you open the Masking tab or change cameras, PIVTools automatically attempts to load any existing polygon mask for the selected camera. The editor shows the loading status with clear indicators:

⏳ Loading...✓ Loaded 3 polygon(s)No existing mask found✗ Error loading mask

Loaded polygons can be edited, deleted, or added to—changes are auto-saved back to the mask file.

Per-Camera Masks

Each camera has its own polygon mask file. In stereo PIV setups, you'll need to create separate masks for Cam1 and Cam2 to account for different viewing angles. Switch cameras using the Camera dropdown in the image loader, then draw and save each mask independently. The correct mask is loaded automatically when you switch cameras.

Export Options

While masks auto-save for PIV processing, you can also export them in additional formats for documentation or use with external tools.

Auto-Save (MAT)

Primary save mechanism. Polygon masks are automatically saved to disk as.mat files whenever you complete, delete, or clear polygons.

Saves to source_path/mask_CamN.mat
Contains binary mask at full resolution
Stores polygon coordinates for re-editing
Polygon names preserved
Automatically loaded during PIV runs

Save PNG

Downloads a PNG image of the mask for documentation, reports, or use with external tools. Click the Save PNG button in the toolbar.

Full native resolution (same as source image)
Binary format (white = masked regions)
Named with camera, index, and frame info
Useful for reports or external software
Downloaded directly to your browser

Note: Pixel border settings don't require any manual save—they're stored inconfig.yaml automatically when you change the values. Just make sure the Apply Mask for PIV toggle is enabled before processing.

Complete Configuration Reference

For power users who prefer direct YAML configuration, here's the complete masking reference with all available options and their descriptions.

# config.yaml - Complete masking configuration
masking:
  enabled: true                      # Toggle masking on/off for PIV processing
  mode: file                         # 'file' (polygon) or 'rectangular' (pixel border)
  mask_file_pattern: mask_Cam%d.mat  # Filename pattern for polygon masks
  mask_threshold: 0.01               # Threshold for mask application (fraction of window)
  rectangular:                       # Only used when mode: rectangular
    top: 64                          # Pixels to mask from top edge
    bottom: 64                       # Pixels to mask from bottom edge
    left: 0                          # Pixels to mask from left edge
    right: 0                         # Pixels to mask from right edge

# Note: The GUI uses 'polygon' and 'pixel_border' internally,
# which map to 'file' and 'rectangular' in the YAML config.

GUI to YAML Mapping

This table shows how GUI controls correspond to YAML configuration fields:

GUI Control	YAML Field	Values
Apply Mask for PIV toggle	masking.enabled	true / false
Masking Mode dropdown	masking.mode	'file' (polygon) / 'rectangular' (pixel border)
Top (pixels)	masking.rectangular.top	integer ≥ 0
Bottom (pixels)	masking.rectangular.bottom	integer ≥ 0
Left (pixels)	masking.rectangular.left	integer ≥ 0
Right (pixels)	masking.rectangular.right	integer ≥ 0
Mask file location	masking.mask_file_pattern	Pattern with %d for camera number
Mask threshold	masking.mask_threshold	float (default 0.01)

Next: Pre-Processing Filters

Apply temporal and spatial filters to enhance your images before PIV processing. Filters can improve correlation quality by removing background, reducing noise, or normalising intensity.

Continue to Pre-Processing