Metadata-Version: 2.4
Name: synpivimage
Version: 1.0.0a9
Summary: Tool to build synthetic Particle Image Velocimetry (PIV) images
Author-email: Matthias Probst <matth.probst@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/MatthiasProbst/synpivimage
Project-URL: Repository, https://github.com/MatthiasProbst/synpivimage
Project-URL: Issues, https://github.com/MatthiasProbst/synpivimage/issues
Keywords: piv,particle image velocimetry,synthetic images,scientific computing
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 3 - Alpha
Requires-Python: <3.13,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pathlib
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: tqdm
Requires-Dist: matplotlib
Requires-Dist: python-dotenv
Requires-Dist: opencv-python
Requires-Dist: scipy
Requires-Dist: pydantic
Requires-Dist: ontolutils<0.28.0,>=0.27.0
Requires-Dist: ssnolib==2.2.0.3
Requires-Dist: pivmetalib<3.1.1.0,>=3.1.0.1
Requires-Dist: pivimage
Requires-Dist: pint
Provides-Extra: test
Requires-Dist: h5py; extra == "test"
Requires-Dist: pytest>=7.1.2; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: gui
Requires-Dist: PyQt5; extra == "gui"
Requires-Dist: xarray; extra == "gui"
Provides-Extra: doc
Requires-Dist: sphinx>=4.5.0; extra == "doc"
Requires-Dist: sphinx_book_theme; extra == "doc"
Requires-Dist: sphinx-copybutton; extra == "doc"
Requires-Dist: scikit-image; extra == "doc"
Requires-Dist: scikit-learn; extra == "doc"
Requires-Dist: sphinx-design; extra == "doc"
Requires-Dist: myst-nb; extra == "doc"
Requires-Dist: nbsphinx; extra == "doc"
Requires-Dist: sphinxcontrib-bibtex; extra == "doc"
Requires-Dist: sphinx-math-dollar; extra == "doc"
Requires-Dist: h5rdmtoolbox<2.6.0,>=2.5.4; extra == "doc"
Requires-Dist: xmltodict; extra == "doc"
Provides-Extra: dev
Requires-Dist: synpivimage[doc,test]; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Provides-Extra: complete
Requires-Dist: synpivimage[doc,gui,test]; extra == "complete"
Dynamic: license-file

# synpivimage - A transparent way of generating synthetic PIV images

![Tests](https://github.com/matthiasprobst/synpivimage/actions/workflows/tests.yml/badge.svg)
![DOCS](https://codecov.io/gh/matthiasprobst/synpivimage/branch/dev/graph/badge.svg)
![pyvers](https://img.shields.io/badge/python-%203.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue)

This tool lets you generate synthetic Particle Image Velocimetry (PIV) images based on methods described in
literature (mainly based on "Particle Image Velocimetry: A Practical Guide" by Raffel et
al. (https://doi.org/10.1007/978-3-319-68852-7)).

## Highlights

- The user has full control over the parameters.
- Data and metadata can be stored in a single HDF5 file or classically in TIF files.
- The metadata (camera and laser settings) can be stored in a separate JSON-LD file, which adheres to the state of the
  art way of storing metadata, allowing for easy integration into any other software or database.

## Installation

### Manual installation

Clone the repository

```cmd
git clone https://github.com/matthiasprobst/synpivimage
```

Then navigate into the repo directory and install the package:

```cmd
cd synpivimage/
pip install .
```

For **development** adjust the installation to:

```cmd
pip install -e .
```

**Other installation options:**
For running tests:
    
```cmd
pip install .[test]
```

For using the GUI (experimentally at this stage!!! see [gui doc section](#gui)):
```cmd
pip install .[gui]
```

For installing everything:
```cmd
pip install .[all]
``` 

### Via pypi

*Not yet available*

## Documentation

A comprehensive documentation can be found [here](https://synpivimage.readthedocs.io/en/latest/).

### Minimal example:

```python
import numpy as np

import synpivimage

cam = synpivimage.Camera(
    nx=256,
    ny=256,
    bit_depth=16,
    qe=1,
    sensitivity=1,
    baseline_noise=50,
    dark_noise=10,
    shot_noise=False,
    fill_ratio_x=1.0,
    fill_ratio_y=1.0,
    particle_image_diameter=4  # px
)

laser = synpivimage.Laser(
    width=0.25,
    shape_factor=2
)

n = 100
particles = synpivimage.Particles(
    x=np.random.uniform(-3, cam.nx - 1, n),
    y=np.random.uniform(-4, cam.ny - 1, n),
    z=np.zeros(n),
    size=np.ones(n) * 2,
)

imgA, partA = synpivimage.take_image(laser,
                                     cam,
                                     particles,
                                     particle_peak_count=1000)

displaced_particles = partA.displace(dx=2.1, dy=3.4)

imgB, partB = synpivimage.take_image(laser,
                                     cam,
                                     displaced_particles,
                                     particle_peak_count=1000)

with synpivimage.Imwriter(case_name="test_case",
                          camera=cam,
                          laser=laser) as iw:
    iw.writeA(0, imgA, partA)
    iw.writeB(0, imgB, partB)

with synpivimage.HDF5Writer(filename='data.hdf',
                            n_images=1,
                            camera=cam,
                            laser=laser) as hw:
    hw.writeA(0, imgA, partA)
    hw.writeB(0, imgB, partB)
```

## GUI
Is experimental and more for demonstrating and debugging purposes.


Go to `synpivimage/gui` and run `python core.py` to start the GUI.

## Developers

### Testing

Call the following inside the package directory to run the tests (with coverage)

```bash
pytest --cov=synpivimage --cov-report html
```

### Contributing

Contributions are welcome! Please open an issue or a pull request.

## License

This project is licensed under the MIT License.
