piv2hdf 2.0.0a1
Tool for the conversion of PIV measurements into HDF5 files
Requires Python: <3.12,>3.9

# piv2hdf

Tool for the conversion of PIV measurements into HDF5 files

![Tests](https://github.com/matthiasprobst/piv2hdf/actions/workflows/tests.yml/badge.svg)
[![codecov](https://codecov.io/gh/matthiasprobst/piv2hdf/graph/badge.svg?token=JQ5PFN9X1D)](https://codecov.io/gh/matthiasprobst/piv2hdf)
![pyvers](https://img.shields.io/badge/python-%203.9%20%7C%203.10%20%7C%203.11%20-blue)




## Installation

```
pip install git+https://github.com/matthiasprobst/piv2hdf
```

or for development:

```
pip install -e git+https://github.com/matthiasprobst/piv2hdf
```

The conversion of davis files requires the package `lvpyio`. This can be installed by running:
```
pip install git+https://github.com/matthiasprobst/piv2hdf[davis]
```
**Note**, that Davis files cannot be converted on MacOS!

## TL;DR

Examples are provided as Jupyter Notebooks in the [examples/](./examples) directory:
- Converting [snapshot data](./examples/01_snapshot_pivview.ipynb) 

## Introduction and Documentation

This package provides a simple interface to convert PIV data into HDF5 files. It is designed to be easily extendable for
other PIV software. Currently, the following software is supported:

- [PIVview (commercial, PIVtec GmbH)](https://www.pivtec.com/)
- [OpenPIV (open-source, python)](https://github.com/matthiasprobst/openpiv-python-ext) (currently only a forked version
  is supported)
- [Davis (commercial, LaVision GmbH)](https://www.lavision.de/en/products/davis-software/)

Workflow: You have processed your PIV images with one of the above software. Then you use `piv2hdf` to convert the
result files into a single HDF5 file.

This file can then be used for further processing, sharing or archiving.

Click on the above links to jump to the individual README-files of the respective software, which give
additional information, remarks and example codes.

### Nomenclature:

Depending on the provided data, we distinguish between three PIV data cases, which all can be written into a single :
HDF5 file:

- *Snapshot*: A single PIV result (of an image pair)
- *Plane*: A list of multiple snapshots, i.e. a PIV result for a time series at one z-coordinate
- *MultiPlane*: A list of planes, i.e. the flow was traversed and the operation condition and PIV settings kept constant

Note, that in order to write a multiple planes into a single HDF file, the planes must have the grid and the time
vectors must identical or similar within a given tolerance. This is checked automatically.

### Examples

Say, your PIV files are located in "data/". The files are result files created by your favorite PIV-software. Say, they
were generated by the commercial software PIVview. Then the file format is `.nc`. For this case, the following lines
will convert those files into a single very handy HDF5 file:

```python
from piv2hdf import PIVPlane
from piv2hdf.pivview import PIVViewStereoNcFile
from datetime import datetime

# time info can be either a list of datetime objects corresponding 
# to the files or 
# the start datetime and the recording frequency in Hz can be provided:
time_info = (datetime(2023, 11, 6, 12, 13, 4), 4000)

plane_data_dir = 'data'
plane = PIVPlane.from_plane(plane_directory=plane_data_dir,
                            time_info=time_info,
                            pivfile=PIVViewStereoNcFile)
plane.to_hdf()
```

The class `PIVPlane` is the interface class for PIV plane data. You have to provide the implemented PIV software class,
in this case  `PIVViewStereoNcFile`. Also, the time vector or the recording frequency must be
provided (`recording_time_or_frequency`).

The module `pivview` provides the class `PIVViewNcFile` and `PIVViewStereoNcFile` which allows working with nc files
either containing 2D2C or 3D3C (stereo) data.

**Note:** Single files (so-called *snapshot* files) can be converted using `piv2hdf.PIVSnapshot`. Multiple planes can be
converted into a single HDF file by using `piv2hdf.PIVMultiPlane`.

**Note:** Currently, only the software PIVview (commercial), Davis (commercial) and OpenPIV (opensource) are supported.

### Configuration

Configurations are associated with `PIVSnaphsot`, `PIVPlane` and `PIVMultiPlane`:

```python
# Set the compression level to 9
plane.config['compression'] = 9

print(plane.config)
```

### PIV Flags

Every software uses different flags. This package uses the following flags, which are taken from PIVview (PIVTec GmbH).
For each software the flags must be converted which these flags:

|      Name      | Flag | Description                                                              |
|:--------------:|:----:|--------------------------------------------------------------------------|
|   `INACTIVE`   |  0   | The data is not valid, e.g. because it is outside the interrogation area |
|    `ACTIVE`    |  1   | The data is unmodified                                                       |
|    `MASKED`    |  2   | The data is masked out                                        |
|   `NORESULT`   |  4   | No result is available even after calculation                            |
|   `DISABLED`   |  8   | The data is disabled manually or by outlier detection                    |
|   `FILTERED`   |  16  | The data is modified through a filter operation                          |
| `INTERPOLATED` |  32  | The data is interpolated from neighboring data                           |
|   `REPLACED`   |  64  | The data is replaced by another correlation peak                         |
|  `MANUALEDIT`  | 128  | The data is manually modified                                                   |

## Troubleshooting

- `netCDF4-1.6.0` and `pytest-7.1.3` don't work together! Raises bizarre error including "frozen_import..."
- `netCDF4-1.6.0` only works up to `python 3.8` (info from 20.10.2022)