/OpenPIV-Python-cxx

OpenPIV Python accelerated by c++

Primary LanguageJupyter NotebookGNU General Public License v3.0GPL-3.0

Platforms Statistics Health
Windows License Documentation Status
macOS Issues Build wheels
Linux Stars

OpenPIV

OpenPIV consists of Python modules for scripting and executing the analysis of a set of PIV image pairs.

Warning

The OpenPIV Python-c++ version is still in its developmental state. This means that there are a few bugs and the API may change.

Building from source

Setup environment

To build the package, first you need to satisfy the requirements for vcpkg. Here is a general requirements list:

  • a compiler (e.g. MSVC 2019 or on UNIX, apt install build-essentials)
  • cmake
  • git (could be installed with conda or pip)
  • (UNIX) pkg-config (apt install pkg-config)
  • (UNIX) curl, zip, unzip, tar (apt install curl, zip, unzip, tar)
  • (UNIX) ninja (apt install ninja-build)

Next, dowload and install a python environment manager, such as miniconda or edm.

Setup a virtual environment and activate it (with conda, use conda create --name python=3.8), (with edm is edm environments create --version=3.8 and then edm shell -e )

You can now install git through conda or pip (unless you want to install it differently). When using git to clone this repository, you must clone it recursively due to third-party packages used in this repository. So when cloning, use git clone --recursive https://github.com/ErichZimmer/OpenPIV-Python-cxx.git.

To build:

When building this package, set your current directory to this package in the terminal used to compile this package (e.g. cd ...). We need to install the build requirements and upgrade pip. To do this, execute the folowing line:

pip install --upgrade -r requirements/build.txt

Next, we can build the actual package with

python setup.py install .

or

pip install .

or if the compilation fails due to build isolation,

pip install --no-build-isolation .

Optional dependencies

To further increase accuracy and performance, some functions utilize extra third-party packages. For instance, the smoothing algorithm implented by references 1 and 2 use SciPy minimization functions. Here are some optional, but not needed dependencies:

  • scipy : all-in-one post processing algorithm (smoothn)
  • matplotlib : data visualization and creation of publication-ready plots
  • ffmpeg : loading and creating movies

These can be installed using pip install openpiv_cxx[full].

Optional dependencies

Documentation is inspired by openpiv_tk_gui Find the detailed documentation on readthedocs.io

To-do:

  • Full compatability with OpenPIV-Python (and subsequently openpiv_tk_gui)
  • Contour finding for mask images
  • dynamic/algorithmic masking
  • two-phase separation
  • FFTW double/single precision for much faster processing
  • Error correlation-based correction algorithm
  • Repeated correlation
  • 2D NxN subpixel centroid approximation
  • Image dewarping and transformations
  • spatial correlation (direct cross-correlation)
  • 5 point gaussian subpixel approximation
  • 2D 3x3 least squares gaussian subpixel approximation
  • 3D PIV?
  • PIV guided PTV?
  • transcribe repository to numba and pythran

Contributors

  1. Erich Zimmer
  2. Tim Dewhirst
  3. Alex Liberzon

Copyright statement: smoothn.py is a Python version of smoothn.m originally created by D. Garcia [https://de.mathworks.com/matlabcentral/fileexchange/25634-smoothn], written by Prof. Lewis and available on Github [https://github.com/profLewis/geogg122/blob/master/Chapter5_Interpolation/python/smoothn.py]. We include a version of it in the openpiv folder for convenience and preservation. We are thankful to the original authors for releasing their work as an open source. OpenPIV license does not relate to this code. Please communicate with the authors regarding their license.

References