Image Configuration

Configure image paths, camera setups, file formats, and frame pairing for your PIV experiments. This section covers everything you need to tell PIVTools where your raw images are located and how they should be interpreted.

Getting Started

The Image Configuration panel is found on the Setup tab in the PIVTools GUI. It handles everything from locating your raw images to defining how frame pairs are formed. Proper configuration here ensures that PIVTools can correctly read your experimental data and produce accurate velocity fields.

1. Set Paths

Source & output directories

2. Choose Type

Standard, CINE, or LaVision

3. Configure

Cameras & pairing mode

4. Validate

Check files are found

Source & Base Directories

Start by telling PIVTools where your raw images are located and where to save results. These paths form the foundation of your processing pipeline. The source path points to your experimental image data, while the base path defines where all processed outputs (vector fields, statistics, videos, and calibration data) will be stored.

Source Path

The folder containing your raw PIV images. Click the folder icon or paste the path directly. This is where PIVTools will look for your image files based on the filename pattern you specify.

Tip: You can add multiple source paths and switch between them using the dropdown selector. This is useful when you have multiple experimental runs with the same settings.

Base Path

Where processed results will be saved. PIVTools creates a structured directory hierarchy here, organising outputs by camera, processing type, and pass number for easy navigation.

Results include: vector fields (.mat), statistics, videos, and calibration data. Each source path should have a corresponding base path at the same array index.

Batch Processing with Multiple Paths

PIVTools supports processing multiple experimental datasets sequentially by specifying arrays of source and base paths. This is ideal when you have several experiments with identical settings and file structures that you want to process in one run.

How it works:

1.Add multiple entries to both source_paths and base_paths arrays
2.Each source path is paired with the base path at the same array index (source_paths[0] → base_paths[0], etc.)
3.Use active_paths to select which path indices to process (0-indexed)
4.PIVTools processes each active path sequentially using the same configuration settings

Important: All datasets in a batch must share the same image format, camera count, pairing mode, and PIV settings. If your experiments have different configurations, process them separately.

paths:
  source_paths:
    - /data/run_001/raw_images    # Index 0
    - /data/run_002/raw_images    # Index 1
    - /data/run_003/raw_images    # Index 2
    - /data/run_004/raw_images    # Index 3
  base_paths:
    - /data/run_001/results       # Paired with source index 0
    - /data/run_002/results       # Paired with source index 1
    - /data/run_003/results       # Paired with source index 2
    - /data/run_004/results       # Paired with source index 3
  active_paths:
    - 0    # Process run_001
    - 2    # Process run_003
    # Indices 1 and 3 will be skipped

# All paths must have the same:
# - Image format and naming pattern
# - Camera count and subfolder structure
# - Number of images (or at least the minimum you want to process)

Image Type Selection

Select the format that matches your image files. This determines how PIVTools reads your data and what options are available. The image type affects how cameras are organized, how frames are paired, and which reader library is used to decode your files.

standard

Standard (TIFF/PNG/JPG)

Individual image files, one frame per file. This is the most common format for scientific cameras and exported data.

cine

Phantom CINE

High-speed camera container format. All frames from a single camera are stored in one .cine file. Multi-camera setups have one file per camera.

lavision_set

LaVision SET

Single .set file containing all cameras and all timesteps. The entire experiment is stored in one container file.

lavision_im7

LaVision IM7

One .im7 file per timestep. Each file may contain data from multiple cameras, or cameras may be in separate subfolders.

Platform Compatibility

LaVision formats (.im7, .set) require the ReadIMX library which is only available on Windows and Linux. The GUI will display a warning if you select these formats on macOS.

Phantom CINE files require the pycine library. Installation instructions are provided in the PIVTools documentation.

Camera Configuration

Configure how many cameras are in your setup and how their images are organized. PIVTools supports both single-camera and multi-camera configurations, with flexible options for custom directory structures.

Single Camera

Set Camera Count = 1. Images are expected directly in the source path with no camera subdirectory. This is the simplest configuration for 2D PIV setups.

source_path/
├── B00001_A.tif
├── B00001_B.tif
├── B00002_A.tif
├── B00002_B.tif
└── ...

Multi-Camera (Standard)

Set Camera Count = 2+. Images are organized in camera subfolders, with each camera's images in a separate directory. This is typical for stereo PIV or multi-view setups.

source_path/
├── Cam1/
│ ├── B00001_A.tif
│ └── B00001_B.tif ...
└── Cam2/
├── B00001_A.tif
└── B00001_B.tif ...

Custom Camera Subfolders

If your camera folders aren't named Cam1, Cam2, etc., you can specify custom names using the camera_subfolders array. Each entry corresponds to a camera number in order.

Example directory structure:

source_path/
├── View_Left/
│ └── frame_00001.tif ...
└── View_Right/
└── frame_00001.tif ...

Mapping:

Camera 1 → View_Left/

Camera 2 → View_Right/

IM7 Camera Subfolder Mode

LaVision IM7 files can be organized in two ways for multi-camera setups. Theuse_camera_subfolderssetting controls which mode PIVTools expects:

All cameras in one file (default)

Set use_camera_subfolders: false. Each .im7 file contains frames for all cameras. PIVTools extracts the specific camera using the camera_no parameter.

source_path/
├── B00001.im7 (contains Cam1+Cam2)
├── B00002.im7
└── ...

One camera per file

Set use_camera_subfolders: true. Each camera's .im7 files are in separate subdirectories, with each file containing only that camera's data.

source_path/
├── Cam1/B00001.im7
├── Cam1/B00002.im7
├── Cam2/B00001.im7
└── Cam2/B00002.im7

Frame Pairing Modes

Frame pairing determines how images are grouped for cross-correlation. The pairing mode affects the number of vector fields produced and must match how your images were acquired. The available options depend on your selected Image Type and experimental setup.

Mode 1

A/B Pair Format (Double-Frame)

Separate files for frame A and frame B with matching indices. This is the most common format for double-frame cameras where each acquisition captures two exposures. Frame A and frame B are saved as separate files with a suffix indicating which frame they are.

Example files:

B00001_A.tif + B00001_B.tif → Pair 1
B00002_A.tif + B00002_B.tif → Pair 2
B00003_A.tif + B00003_B.tif → Pair 3
...

100 image indices → 100 frame pairs

Each index produces exactly one vector field. The A and B patterns must have different suffixes to distinguish them.

GUI Setting: Keep "Time Resolved" OFF and enter two filename patterns (one for A frames, one for B frames). The GUI will show input fields for both patterns.

Mode 2

Time-Resolved (Overlapping Pairs)

Sequential images with overlapping pairs. Each image serves as frame B for one pair and frame A for the next. This mode is used with high-speed cameras that capture single frames in rapid succession. It provides maximum temporal resolution from your data.

Example pairing:

B00001.tif + B00002.tif → Pair 1
B00002.tif + B00003.tif → Pair 2
B00003.tif + B00004.tif → Pair 3
B00004.tif + B00005.tif → Pair 4
...

100 image files → 99 frame pairs

Formula: pairs = images - 1
The last image has no partner, so you get one fewer pair than images.

GUI Setting: Turn the "Time Resolved" toggle ON. Only one filename pattern is needed since all images use the same naming convention.

Mode 3

Skip Frames (Non-Overlapping Pairs)

Non-overlapping pairs from a single file sequence. Images are paired consecutively but each image is used only once. This mode is useful when you have a single image sequence but want independent (non-overlapping) frame pairs for statistical purposes.

Example pairing:

B00001.tif + B00002.tif → Pair 1
B00003.tif + B00004.tif → Pair 2
B00005.tif + B00006.tif → Pair 3
...

100 image files → 50 frame pairs

Formula: pairs = images ÷ 2
Each pair consumes two images, giving half as many pairs.

GUI Setting: Keep "Time Resolved" OFF and use a single filename pattern (not A/B patterns). This triggers skip-frame pairing mode.

Live Frame Pair Count

The GUI automatically calculates and displays the total number of frame pairs based on your configuration. Look for the "X frame pairs" indicator next to the Number of Images field. This calculation considers your image type, pairing mode, and time-resolved setting.

Quick Reference:

A/B Pairs

pairs = num_images

Time-Resolved

pairs = num_images - 1

Skip Frames

pairs = num_images ÷ 2

Filename Patterns

Define how frame numbers appear in your filenames using C-style format specifiers. These patterns tell PIVTools how to construct filenames for each frame index. The pattern must match your actual files exactly, including any prefixes, suffixes, and zero-padding.

Format Specifiers

Use C-style format specifiers to define how frame numbers appear in filenames. The % symbol marks where the frame number will be inserted:

%05d

→ B00001.tif, B00042.tif

5-digit, zero-padded

%04d

→ img0001.tif, img0042.tif

4-digit, zero-padded

%d

→ frame1.tif, frame42.tif

No padding (variable width)

Supported File Formats

.tif/.tiff

TIFF (8/16-bit)

.png

PNG

.jpg/.jpeg

JPEG

.cine

Phantom Video

.im7/.set

LaVision

Zero-Based Indexing

By default, PIVTools expects files to start at index 1 (e.g., B00001.tif). Enable Zero-based indexing if your files start at 0 (e.g., B00000.tif). This is common with some camera software and programming-generated sequences.

1-based (default):

B00001.tif, B00002.tif, B00003.tif ...

0-based:

B00000.tif, B00001.tif, B00002.tif ...

Vector Output Pattern

Define the naming pattern for output vector files. These are saved in the base path under the appropriate subdirectory structure. The format uses the same specifier syntax as image patterns.

Image Data Type

Specify the expected data type for your images. This affects memory allocation and processing precision. Most scientific cameras produce 16-bit images, but 8-bit and 32-bit float formats are also supported.

Container Format Details

Container formats store multiple frames in a single file, reducing filesystem overhead and simplifying data management. Here are the specifics for each supported format, including how frame pairing works within containers.

Phantom

.cine Files

One .cine file per camera containing all frames. The filename pattern uses %d for the camera number (not the frame number). PIVTools reads frames directly from the container using their internal indices.

Frame pairing modes:

• Time-resolved ON: Overlapping pairs (0+1, 1+2, 2+3...)
• Time-resolved OFF: Non-overlapping pairs (0+1, 2+3, 4+5...)

Note: CINE files use their internal FirstImageNo for indexing. PIVTools handles this translation automatically.

LaVision

.im7 Files

One file per timestep. Each file may contain frames for multiple cameras (multi-camera mode) or just one camera (when using camera subfolders). The internal structure depends on how the data was acquired in DaVis.

Pre-Paired (Standard PIV)

Each .im7 contains frame A and B for each camera (2 frames per camera). This is the default DaVis export for double-frame acquisitions.

GUI: Time-resolved OFF

Time-Resolved (TR-PIV)

Each .im7 contains one frame per camera. Pairs are formed across consecutive files (file N + file N+1).

GUI: Time-resolved ON

LaVision

.set Files

A single .set file contains all cameras and all timesteps. Just enter the filename—no pattern needed. This is the most compact format for large datasets but requires the full file to be accessible for random access.

Note: The internal structure is indexed by (camera_no, im_no) where im_no is the timestep. PIVTools handles all the internal navigation automatically.

File Validation

After configuring your settings, PIVTools validates that your files exist and are readable. The validation runs automatically when you save changes or click the validate button. This prevents processing errors by catching configuration issues early.

What's Checked

First frame exists and is readable for each camera
Last frame exists (based on num_images setting)
File count matches expected number of images
Index range matches zero_based_indexing setting
Container files are accessible and contain expected data
Image dimensions are consistent across frames

Status Indicators

Valid:All files found and readable

Warning:Processing subset of available files

Error:Missing files or configuration issue

Common Validation Issues

• Files not found: Check your source path and filename pattern match exactly. Pay attention to underscores, capitalisation, and number formatting.
• Wrong count: Verify the "Number of Images" matches your actual file count.
• First file missing: Check if you need zero-based indexing enabled (files start at 0 instead of 1).
• LaVision error on Mac: IM7 and SET formats require Windows or Linux. Export to TIFF for macOS processing.

Output Directory Structure

Processed PIV data is organised in a structured hierarchy under your base path. This organisation makes it easy to locate results, compare different processing runs, and manage large datasets. The structure is created automatically during processing.

Output Directory Structure

base_path/
├── uncalibrated_piv/              # Raw PIV results (pixel displacements)
│   └── {num_frame_pairs}/         # Organised by dataset size
│       ├── Cam1/
│       │   ├── instantaneous/     # Per-frame vector fields
│       │   │   ├── 00001.mat
│       │   │   ├── 00002.mat
│       │   │   └── ...
│       │   └── ensemble/          # Ensemble-averaged results
│       │       └── ensemble_result.mat
│       └── Cam2/
│           └── ...
│
├── calibrated_piv/                # Physical units (mm, m/s)
│   └── {num_frame_pairs}/
│       └── ...
│
├── merged/                        # Multi-camera merged fields
│   └── ...
│
├── statistics/                    # Statistical analysis results
│   └── ...
│
├── videos/                        # Generated animations
│   └── ...
│
└── calibration/                   # Calibration data and coefficients
    └── ...

Note: The {num_frame_pairs} subdirectory allows you to process different subsets of your data without overwriting previous results. For example, processing 100 pairs vs 500 pairs creates separate output directories.

Complete Configuration Reference

For power users who prefer direct YAML configuration, here's a complete reference with all available options. This example shows a multi-path batch processing setup with all image-related settings.

# config.yaml - Complete image configuration example
paths:
  # Multiple paths for batch processing
  source_paths:
    - /data/experiment_01/raw_images
    - /data/experiment_02/raw_images
    - /data/experiment_03/raw_images
  base_paths:
    - /data/experiment_01/results
    - /data/experiment_02/results
    - /data/experiment_03/results
  active_paths:
    - 0      # Process first dataset
    - 1      # Process second dataset
    # Index 2 will be skipped

  # Camera configuration
  camera_count: 2
  camera_numbers: [1, 2]
  camera_subfolders: []  # Empty = use default Cam1, Cam2

images:
  # Basic settings
  num_images: 500
  image_type: standard       # standard, cine, lavision_set, lavision_im7

  # Frame pairing
  time_resolved: false       # true for overlapping pairs
  pairing_mode: sequential   # sequential (default)
  zero_based_indexing: false # true if files start at 0

  # For IM7 only: camera organization
  use_camera_subfolders: false  # true for one-camera-per-file mode

  # Filename patterns
  image_format:
    - B%05d_A.tif   # Frame A pattern
    - B%05d_B.tif   # Frame B pattern
  vector_format:
    - '%05d.mat'    # Output filename pattern

  # Data properties
  dtype: float32   # uint8, uint16, float32, float64

batches:
  size: 25  # Process 25 image pairs per batch

logging:
  file: pypiv.log
  level: INFO      # DEBUG, INFO, WARNING, ERROR
  console: true    # Show log messages in terminal

GUI to YAML Field Mapping

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

GUI Control	YAML Field	Description
Source Path	paths.source_paths[]	Array of input directories
Base Path	paths.base_paths[]	Array of output directories
Active Paths	paths.active_paths[]	Which path indices to process (0-indexed)
Image Type	images.image_type	Format: standard, cine, lavision_im7, lavision_set
Number of Images/Frames	images.num_images	Total image files or frames in container
Camera Count	paths.camera_count	Total cameras in setup
Time Resolved toggle	images.time_resolved	Enable overlapping pairs
Zero-based Indexing	images.zero_based_indexing	Files start at 0 vs 1
IM7 Camera Subfolders	images.use_camera_subfolders	One .im7 per camera in subfolders
Raw Image Pattern(s)	images.image_format[]	Filename pattern(s) with %d specifier
Vector Pattern	images.vector_format[]	Output filename pattern
Custom Camera Subfolders	paths.camera_subfolders[]	Override default CamN names
Batch Size	batches.size	Images processed per batch

Next: Set Up Your Mask

Now that your images are configured, define regions to exclude from PIV processing. Masking helps improve results by removing areas with poor seeding or reflections.

Continue to Masking