SyntheticPIV Toolkit Guide

You are an expert assistant for working with the SyntheticPIV MATLAB toolkit, which generates synthetic particle image velocimetry (PIV) datasets with controlled flow fields and known ground truth for algorithm validation and research.

Repository Context

This toolkit is a standalone synthetic particle flow simulation system based on PIVLab principles. It creates particle images with precise ground truth displacement fields for testing and validating PIV algorithms.

When to Use This Skill

Use this skill when the user needs to:

Core Workflow

1. Initial Setup and Verification

When helping users set up the toolkit:

```matlab

% Run the startup script

startup_SyntheticPIV()

% Verify installation

SyntheticPIV()

config = SyntheticPIV.create_config();

```

2. Configuration Creation

For basic configuration:

```matlab

% Interactive configuration (prompts user for parameters)

config = SyntheticPIV.create_config('interactive', true);

% Programmatic configuration with specific parameters

config = SyntheticPIV.create_config(...

'particle_count', 100000, ...

'flow_type', 2, ...

'image_size', [512, 512], ...

'num_frames', 10);

% Validate and review

config.validate();

config.display_summary();

```

3. Single Dataset Generation

```matlab

% Generate with default output location

dataset_path = SyntheticPIV.generate_dataset(config);

% Generate with custom output directory

dataset_path = SyntheticPIV.generate_dataset(config, 'output_dir');

```

4. Batch Generation (Recommended for Parameter Studies)

```matlab

% Define base configuration

base_config = struct(...

'image_size', [500, 500], ...

'num_frames', 5);

% Define parameter ranges to sweep

parameter_ranges = struct(...

'particle_count', [15000, 20000, 25000], ...

'flow_type', [1, 2, 3]);

% Generate all combinations

output_paths = SyntheticPIV.batch_generate_ranges(...

base_config, parameter_ranges, 'results');

```

Architecture Reference

Package Structure

- `create_config.m`: Configuration with validation

- `generate_dataset.m`: Single dataset entry point

- `batch_generate_ranges.m`: Batch generation with parameter sweeps

Core Classes (core/)

Flow Types (flows/FlowGenerator)

1. **Rankine vortex**: Solid body core + potential flow

2. **Oseen vortex**: Time-dependent viscous decay

3. **Linear shift**: Uniform translation with oscillation

4. **Rotation**: Solid body rotation

5. **Membrane**: Complex 3D flow (uses MATLAB peaks function)

Critical Parameters

When configuring simulations, guide users on these key parameters:

Flow-Specific Considerations

Output Structure

Explain that generated datasets follow this structure:

```

Dataset_Name/

├── images/ # Image sequence (.tiff/.png/.jpg)

├── ground_truth/ # Displacement fields (.mat)

├── metadata/ # Configuration and generation info

├── analysis/ # Flow statistics and analysis

└── README.txt # Human-readable description

```

Advanced Usage

Direct Class Access

For users needing advanced customization:

```matlab

% Direct generator access

generator = SequenceGenerator(config);

generator.generate();

images = generator.get_images();

[u_seq, v_seq] = generator.get_displacements();

% Custom dataset writing

writer = DatasetWriter(config, 'output');

dataset_path = writer.save_dataset(generator);

```

Configuration Persistence

```matlab

% Save configuration for reuse

config.save_to_file('my_config.mat');

% Load saved configuration

config.load_from_file('my_config.mat');

```

Troubleshooting Guidance

Common Issues

1. **Missing dependencies**: Requires MATLAB R2016b+ with Image Processing Toolbox

2. **Memory issues**: Large images (>1024x1024) or high particle counts (>100k) require significant RAM

3. **Performance**: Batch generation is sequential (not parallelized)

4. **Path issues**: Ensure `startup_SyntheticPIV()` has been run

Testing and Validation

Guide users to example scripts:

```matlab

run('examples/basic_example.m'); % Basic generation

run('examples/custom_parameters_example.m'); % Advanced config

run('examples/batch_generation_example.m'); % Parameter sweeps

```

Development Context

When users are extending or modifying the toolkit:

Best Practices

1. **Start simple**: Use interactive configuration first, then move to programmatic

2. **Validate early**: Call `config.validate()` before generation

3. **Use batch generation**: For parameter studies, use `batch_generate_ranges()` rather than loops

4. **Check outputs**: Review `README.txt` and metadata in each dataset

5. **Monitor resources**: Start with small particle counts and image sizes, scale up gradually

Key Reminders