Package: opyf
AboutOpyFlow : Python package for Optical Flow measurementsOpyflow is a basic image velocimetry tool to simplify yourvideoorframe sequencesprocessing.It is based onopencvandvtklibraries to detect Good Features to Track (GFT), calculate their displacements by the Lukas Kanade method and interpolate them on a mesh. This method is sometimes called Feature Image Velocimetry or Feature Tracking. It is an alternative to the classical cross-correlation techniques employed in Particle Image Velocimetry (PIV). Compared to this technique, GFT+OpticalFlow may result in better performance when image qualities are poor for velocimetry, i.e. when velocity information on frames is non-uniform.For flow calculations, the process is mainly inspired by the openCV python samplelktrack.py.The package also contains some rendering tools built with matplotlib. Velocities can be exported (csv, tecplot, vtk, hdf5).Author: Gauthier RousseauCorresponding e-mail :gauthier.rousseau@gmail.comQuick StartTo quickly get started with OpyFlow, follow these steps:Ensure you have Python installed in your environment.Open your terminal and run the following command to install OpyFlow and its main dependencies (matplotlib, vtk, and opencv):pipinstallopyfAlternatively, if you have the OpyFlow repository cloned locally, you can run:python3-mpipinstall./This will automatically install the OpyFlow library and its dependencies.To analyze a frame sequence (e.g., PNG, BMP, JPEG, TIFF), use the following code:importopyfanalyzer=opyf.frameSequenceAnalyzer("folder/toward/images")For analyzing a video (e.g., MP4, AVI, MKV), use the following code:analyzer=opyf.videoAnalyzer("video/file/path")To perform your first analysis, run the following code:analyzer.extractGoodFeaturesAndDisplacements()OpyFlow package includes two frames and one video for testing and self-practice:The two frames were extracted from the frame sequence of the Test case A of thePIV Challenge 2014:When applied to the entire dataset, OpyFlow can produce the above result (seeTest PIV Challenge 2014 - Case Afor details on the procedure).The video is a bird's eye view video of a stream river taken by a drone, from which surface velocities can be extracted (see thistutorialfor different possible procedures or the followingpython file):A guide is also provided to obtain the free surface velocity in a river from two amateur videos:Stabilization, orthorectification (bird's eye view transformation), and free surface velocity estimation on the Brague river with OpyFlowContentsThis repository is organized as follows:The setup file:setup.pyThe package Folder opyf:opyfAnalyzer.pyTrack.pyInterpolate.pyFiles.pyFilters.pyRender.pyTools.pycustom_cmap.py (based on Chris Slocum file)testTest_case_PIV_Challenge_2014Test_land_slide_youtube_videoTest_NavizenceTest_Brague_floodA test on synthetic images is still required.Installation with anacondaThe package requires python and basic python package: csv, numpy, matplotlib, tqdm, hdf5. Main dependencies are: OpenCV and VTK.If thepip install opyfcommand above does not work for you, an alternative way to deal with dependencies is using miniconda or anaconda.When miniconda/anaconda is installed you may create an environment (here calledopyfenv). To create the environment type in the terminal:condacreate-nopyfenvpython=3.11This command line will install an environment with python 3.11 and the main dependencies.You can access to your environment by typing:condaactivateopyfenvInstallation using the standard python protocol to create a virtual environmentYou can also use the standard python protocol (run the command where you want to put the environment):python-mvenvopyfenvsourceopyfenv/bin/activateFrom you environment, you should be able to install opyf withpip install opyf.For development mode, you may also install the libraries individually with pip:pipinstallipythonvtkopencv-pythontqdmh5pymatplotlibscipyipykernelPyQt6And set the opyf repository in your PATH or in the beginning of your python script using:importsyssys.path.append("path/toward/opyf/src")Tested on:Python: 3.11VTK: 9.2.6OpenCV: 4.7NumPy: 1.24Matplotlib: 3.7.1CitationThis package has been developed in the course of my PhD at EPFL to studyTurbulent flows over rough permeable beds. Outputs are visible in the manuscript as well as in thisVideowhere paraview animations have been rendered thanks to opyf outputs.@PhdThesis{rousseau2019turbulent,
title={Turbulent flows over rough permeable beds in mountain rivers: Experimental insights and modeling},
author={Rousseau, Gauthier},
year={2019},
institution={EPFL}
}An article published inExperiments in Fluidsis available in Open Access :Scanning PIV of turbulent flows over and through rough porous beds using refractive index matchingFollow thislinkto directly access to the annex of the article presenting the opyf algorithms and tests.@article{rousseau2020scanning,
title={Scanning PIV of turbulent flows over and through rough porous beds using refractive index matching},
author={Rousseau, Gauthier and Ancey, Christophe},
journal={Experiments in Fluids},
volume={61},
number={8},
pages={1--24},
year={2020},
publisher={Springer}
}Contributors : Hugo Rousseau, Mohamed Nadeem, LHE team and othersCredits for UAV video : Bob de GraffenriedCredits for 2019 flood video on Brague River (Biot, French Riviera) : Pierre Brigode