Image Configuration

Configure image paths, file formats, camera setup, and frame pairing. Found on the Setup tab in the GUI.

Quick Recipe

opinionated defaults — full reference below

1.Add one or more source_paths (raw images) with matching base_paths (outputs).
2.Set image_type (standard, cine, lavision_im7, or lavision_set) and image_format (e.g. B%05d.tif).
3.Set num_images to frame pairs per acquisition loop (not total files across loops).
4.Pick a pairing_preset from the table below — most users want A/B Format (separate _A/_B files) or Time Resolved (overlapping consecutive frames).
5.Save. Validation runs automatically: green = ready to process, yellow/red = check the filename pattern, start_index, and count.

Source & Base Directories

Source Path

Directory containing raw PIV images. Multiple source paths can be added for batch processing.

Base Path

Where processed results are saved (vector fields, statistics, videos, calibration). Each source path is paired with the base path at the same array index.

Batch Processing

Process multiple datasets sequentially by adding multiple source/base path pairs. Use active_paths to select which indices to process. All datasets in a batch must share the same image format, camera count, and PIV settings.

Image Type Selection

Select the format matching your image files. Auto-detected from file extension if not set explicitly.

Type	YAML value	Description
Standard	standard	Individual image files (.tif, .png, .jpg). One frame per file.
Phantom CINE	cine	High-speed camera container. One .cine file per camera, all frames inside.
LaVision SET	lavision_set	Single .set file with all cameras and timesteps.
LaVision IM7	lavision_im7	One .im7 file per timestep. May contain multiple cameras.

Platform Compatibility

LaVision formats (.im7, .set) are read by PIVTools' built-in pure-Python readers — no external dependencies, works on macOS, Windows, and Linux. Phantom CINE requires the pycine library.

Camera Configuration

Single Camera

Images directly in source path, no camera subdirectory.

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

Multi-Camera

Images in camera subfolders (default: Cam1, Cam2, ...). Override with camera_subfolders.

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

IM7 Camera Subfolder Mode

IM7 files can store multiple cameras in one file (use_camera_subfolders: false, default) or one camera per file in subdirectories (use_camera_subfolders: true).

Frame Pairing Modes

Frame pairing determines how images are grouped for cross-correlation. The GUI uses a Pairing Preset dropdown. The underlying config keys arestart_index,frame_stride, andpair_stride.

Preset	frame_stride	pair_stride	Pairing	100 images =
A/B Format	0	1	Separate A + B files per index	100 pairs
Pre-Paired	0	1	Container with A+B in one entry	100 pairs
Time Resolved	1	1	Overlapping: 1+2, 2+3, 3+4 ...	99 pairs
Skip Frames	1	2	Non-overlapping: 1+2, 3+4, 5+6 ...	50 pairs
Custom	N	M	User-defined stride values	varies

Frame Pair Formula

Pair count:

fs == 0: num_images
fs > 0: (num_images - 1 - fs) / ps + 1

Pair indices (1-based pair_number):

frame_a = start_index + (n-1) * pair_stride
frame_b = frame_a + frame_stride

A/B Format (Double-Frame)

Separate files for frame A and frame B with matching indices. Two filename patterns required.

B00001_A.tif + B00001_B.tif -- Pair 1
B00002_A.tif + B00002_B.tif -- Pair 2

Time-Resolved (Overlapping Pairs)

Sequential single-frame images. Each image serves as B for one pair and A for the next.

B00001.tif + B00002.tif -- Pair 1
B00002.tif + B00003.tif -- Pair 2

Skip Frames (Non-Overlapping Pairs)

Consecutive pairs from a single sequence, but each image used only once.

B00001.tif + B00002.tif -- Pair 1
B00003.tif + B00004.tif -- Pair 2

Backward compatibility: Old config keys (time_resolved,pairing_mode,zero_based_indexing) are automatically migrated to the new stride-based model on load. New configs should usepairing_preset,start_index,frame_stride, andpair_stride.

Filename Patterns

C-style format specifiers define how frame numbers appear in filenames.

Specifier	Example output	Description
%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

Supported File Formats

.tif/.tiff

TIFF (8/16-bit)

.png

PNG

.jpg/.jpeg

JPEG

.cine

Phantom Video

.im7/.set

LaVision

Start Index

Set start_index: 0 if files begin at 0 (e.g. B00000.tif). Default is 1.

Vector Output Pattern

Naming pattern for output .mat files.

Container Format Details

Container formats store multiple frames in a single file.

Format	Structure	Pattern	Notes
.cine	One file per camera, all frames inside	Camera%d.cine	%d = camera number, not frame
.im7	One file per timestep, may contain multiple cameras	B%05d.im7	Pre-paired: A+B in each file. TR: pair across files.
.set	Single file with all cameras and timesteps	experiment.set	source_path points to the .set file itself

Multi-Loop Acquisition

Some experiments record data across multiple acquisition loops — separate source folders that should be combined into a single dataset for processing. Set num_loops to tell PIVTools how many loops to stitch together. All loops must have the same number of frame pairs and use the same image format.

How It Works

PIVTools finds additional loop folders by incrementing the last number in the source path name. For example, if your source path is experiment_0/ and num_loops: 3, it will read from:

experiment_0/   # Loop 0 (the configured source_path)
experiment_1/   # Loop 1 (auto-discovered)
experiment_2/   # Loop 2 (auto-discovered)

Downstream code sees a single unified array. For example, 3 loops of 40 pairs each produces a 120-pair dask array. The GUI image viewer resolves global pair numbers back to the correct loop and local pair index automatically.

Setting	YAML Key	Description
Number of Loops	images.num_loops	How many acquisition loops to combine (default: 1 = single loop)
Num Images	images.num_images	Frame pairs per loop (not total). Total pairs = num_loops x per-loop pairs.

Works With All Image Types

Multi-loop works with every image type: standard files (separate folders), .set files (separate .set files), .cine (separate folders), and .im7 (separate folders). Batch size is automatically capped at the per-loop pair count to prevent cross-loop batches.

Naming Convention

The folder name must end with a number. PIVTools increments the last number in the path: run_0/ becomes run_1/, loop=0.set becomes loop=1.set. If your folders don't follow this convention, rename them or use separate source paths with active_paths instead.

File Validation

Validation runs automatically when you save changes. It checks that first/last frames exist and are readable for each camera.

Valid

All files found and readable

Warning

Processing subset of available files

Error

Missing files or configuration issue

Common Issues

-- Files not found: Check source path and filename pattern (capitalisation, padding, underscores).
-- Wrong count: Verify num_images matches actual file count.
-- First file missing: Check start_index (0 vs 1).
-- CINE on Mac: Phantom CINE format requires the pycine library.

Output Directory Structure

base_path/
├── uncalibrated_piv/{num_pairs}/Cam1/instantaneous/   # Raw vectors (px)
├── calibrated_piv/{num_pairs}/Cam1/instantaneous/     # Physical units (m/s)
├── calibrated_piv/{num_pairs}/Merged/instantaneous/   # Merged cameras
├── stereo_calibrated/{num_pairs}/Cam1_Cam2/           # Stereo 3D
├── statistics/{num_pairs}/...                         # Mean, TKE, etc.
├── videos/{num_pairs}/...                             # Animations
└── calibration/...                                    # Calibration models

The {num_pairs} subdirectory ensures processing different subsets does not overwrite previous results.

Complete Configuration Reference

GUI Control	YAML Field	Description
Source Path	paths.source_paths[]	Input directories
Base Path	paths.base_paths[]	Output directories
Active Paths	paths.active_paths[]	Indices to process (0-based)
Image Type	images.image_type	standard \| cine \| lavision_im7 \| lavision_set
Number of Images	images.num_images	Total image files or container entries
Camera Count	paths.camera_count	Total cameras
Pairing Preset	images.pairing_preset	ab_format \| pre_paired \| time_resolved \| skip_frames \| custom
Start Index	images.start_index	First file number (0 or 1)
Frame Stride	images.frame_stride	Gap between A and B in a pair
Pair Stride	images.pair_stride	Gap between starts of consecutive pairs
Filename Pattern(s)	images.image_format[]	Filename with %d specifier
Vector Pattern	images.vector_format[]	Output .mat filename pattern
IM7 Camera Subfolders	images.use_camera_subfolders	IM7: one file per camera in subfolders
Camera Subfolders	paths.camera_subfolders[]	Override default CamN names
Batch Size	batches.size	Image pairs per batch

paths:
  source_paths:
    - /data/experiment_01/raw_images
  base_paths:
    - /data/experiment_01/results
  active_paths: [0]
  camera_count: 2
  camera_numbers: [1, 2]
  camera_subfolders: []        # Empty = default Cam1, Cam2

images:
  num_images: 500
  image_type: standard
  pairing_preset: ab_format    # ab_format | pre_paired | time_resolved | skip_frames | custom
  start_index: 1               # 0 if files start at B00000
  frame_stride: 0              # 0 = pre-paired, 1 = consecutive
  pair_stride: 1               # 1 = overlapping, 2 = non-overlapping
  image_format:
    - B%05d_A.tif
    - B%05d_B.tif
  vector_format:
    - '%05d.mat'
  dtype: float32

batches:
  size: 25

logging:
  file: pypiv.log
  level: INFO
  console: true

Next: Set Up Your Mask

Define regions to exclude from PIV processing.

Continue to Masking