SynthPix: A lightspeed PIV images generator 🌊

SynthPix is a synthetic image generator for Particle Image Velocimetry (PIV) with a focus on performance and parallelism on accelerators, implemented in JAX. SynthPix supports the same configuration parameters as existing tools but achieves a throughput several orders of magnitude higher in image-pair generation per second, enabling comprehensive validation and comparison of PIV algorithms, rapid experimental design iterations, and the development of data-hungry methods.

In a nutshell, if you need many synthetic PIV images and you do not want to wait ages, you are better off with SynthPix 😄. Below are the performances (image pairs per second) with and without GPU for different batch sizes B.

SynthPix is also fairly easy to use:

import synthpix

sampler = synthpix.make(config_path)
for i, batch in enumerate(sampler):
   """batch contains images1, images2, flow_fields, params"""
sampler.shutdown()

See src/main.py for a fully working example. For long-running training, check out our Checkpointing Guide to ensure bit-perfect reproducibility 💾.

Getting started 🚀

Alright, now that hopefully we convinced you to try SynthPix, let's get to it. Don't worry, installing it is even easier than using it:

uv add synthpix

If you have CUDA GPUs,

uv add "synthpix[cuda12]"

If you have issues with CUDA drivers, please follow the official instructions for cuda12 and cudnn (Note: wheels only available on linux). Make sure that LD_LIBRARY_PATH is not set; see the JAX docs:

unset LD_LIBRARY_PATH

Check out our instructions for installing SynthPix from source. You can of course also use pip.

To generate the images, you need flow data. We provide two scripts to download the commonly used PIV datasets:

sh scripts/download_piv_1.sh <output_folder> <configs_directory>

sh scripts/download_piv_2.sh <output_folder> <configs_directory>

These scripts will automatically save also one configuration file each in <configs_directory>. You can use these paths as in the example above.

For more examples and tutorials to use custom flow data or real-world data, check out our tutorials page.

Configuring the synthetic images ⚙️

Configuration is handled through a YAML file, organized into four main groups. Here’s a quick guide to what each set of parameters does:

1. Dataset Parameters

These parameters allow you to customize how flow field extraction works and the shape of the output batch.

2. Image Generation Parameters

Define the look and realism of your synthetic PIV images.

For diameter_ranges, intensity_ranges, and rho_ranges, each parameter is a list of possible ranges. For every image pair, one range is randomly selected (uniformly) from each list, and then the particle parameters are sampled from these selected ranges.

Each *_var parameter controls how much the property of each particle can change between the first and second image of a pair. The change is applied as Gaussian noise with zero mean and variance given by the corresponding *_var value.

Here’s what each *_var parameter controls:

diameter_var: Simulates changes in particle size between frames, making the effect of focus, depth movement, or slight deformations more realistic.

Effect of diameter_var on particle size

Low Medium High

diameter = 2.0 diameter = 2.5 diameter = 3.0

_{Increasing diameter_var makes particles appear larger and more diffuse.}

intensity_var: Models natural brightness changes due to variations in illumination, camera response, or particles moving in and out of the light sheet mimicking out-of-plane motion.

Effect of intensity_var on particle brightness

Low Medium High

intensity = 50 intensity = 150 intensity = 255

_{Raising the intensity_var parameter produces brighter particles (higher signal-to-noise).}

rho_var: Adds variability to the shape and orientation (elongation/rotation) of particles between frames.

Effect of rho_var on particle shape:

Too Low Negative Zero Positive Too High

ρ = -0.9 ρ = -0.5 ρ = 0.0 ρ = 0.5 ρ = 0.9

_{Increasing the absolute value of rho (correlation coefficient) makes particle spots more elliptical and/or rotated.
Very high values (|ρ| > 0.5, leftmost and rightmost) lead to elongated, line-like particles that are not realistic for PIV images.
For best results, keep rho in the range -0.5 ≤ ρ ≤ 0.5.}

Note: The example above uses particles with diameter 2.5. The visual effect of ρ also depends on particle size, larger diameters make elongation more noticeable. As a result, the recommended "safe range" for realistic particle shapes may vary depending on your chosen diameter_ranges.

3. Flow generation parameters

Examples:

4. Flow field parameters

Describe which region of your flow field is captured, and its velocity bounds.

Note: min_speed_x/y and max_speed_x/y are not absolute cutoffs, but define the full expected velocity range (positive and negative) along each axis.

These bounds are used to estimate the maximum particle displacement over time (dt). A larger intermediate image is generated accordingly, and the final image pair is cropped from this larger region. This ensures that particles entering the visible frame (image 2) have realistic origins — possibly outside the region of interest in image 1 — making particle "appearance" at the boundaries realistic.

Hugging Face Hub integration 🤗

SynthPix ships an optional integration to push and pull built PIV datasets through a Hugging Face Hub dataset repository, with the on-disk layout preserved byte-for-byte. See the Hugging Face Hub integration guide for installation, authentication, the CLI / Python / build-script workflows, and the license-aware safety gate that defaults to private hosting.

Contributing 🤗

Contributions are more than welcome! 🙏 Please check out our how to contribute page, and feel free to open an issue for problems and feature requests⚠️.

Citation 📈

If you use this code in your research, please cite our paper:

   @article{terpin2026synthpix,
        title={SynthPix: A lightspeed PIV images generator},
        author={Antonio Terpin and Alan Bonomi and Francesco Banelli and Raffaello D'Andrea},
        journal={SoftwareX},
        volume={34},
        pages={102642},
        year={2026},
        doi={10.1016/j.softx.2026.102642},
        url={https://doi.org/10.1016/j.softx.2026.102642},
    }