piv2hdf

piv2hdf

Tool for the conversion of PIV measurements into HDF5 files

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/ directory:

• Converting snapshot data

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)
• OpenPIV (open-source, python) (currently only a forked version is supported)
• Davis (commercial, LaVision GmbH)

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:

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:

# 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)