Image Configuration

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

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) require Windows or 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

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).
-- LaVision on Mac: IM7/SET require Windows or Linux.

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