This graphical user interface provides an efficient workflow for evaluating and postprocessing particle image velocimetry (PIV) images. OpenPivGui relies on the Python libraries provided by the OpenPIV project.
You may use Pip to install OpenPivGui:
pip3 install openpivgui
Launch OpenPivGui by executing:
python3 -m openpivgui.OpenPivGui
Spend less than eight minutes to learn how to use and extend OpenPivGui:
https://video.fh-muenster.de/Panopto/Pages/Viewer.aspx?id=309dccc2-af58-44e0-8cd3-ab9500c5b7f4
- Press the top left button »select files« and choose some images. Use Ctrl + Shift for selecting mutliple files.
- To inspect the images, click on the links in the file-list on the right side of the OpenPivGui window.
- Walk through the riders, select the desired functions, and edit the corresponding parameters.
- Press »start processing« to start the evaluation.
- Inspect the results by clicking on the links in the file-list.
- Use the »back« and »forward« buttons to inspect intermediate results. Use the »back« and »forward« buttons also to list the image files again, and to repeat the evaluation.
- Use »dump settings« to document your project. You can recall the settings anytime by pressing »load settings«. The lab-book entries are also restored from the settings file.
First, get the source code. There are two possibilities:
- Clone the git repository:
git clone https://github.com/OpenPIV/openpiv_tk_gui.git
- Find out, where pip3 placed the source scripts and edit them in place:
pip3 show openpivgui
In both cases, cd into the subdirectory openpivgui and find the main scripts to edit:
OpenPivParams.pyOpenPivGui.py
Usually, there are two things to do:
- Adding new variables and a corresponding widgets to enable users to modify its values.
- Adding a new method (function).
Open the script OpenPivParams.py. Find the method __init__(). There, you find a variable, called default of type dict. All widgets like checkboxes, text entries, and option menues are created based on the content of this dictionary.
By adding a dictionary element, you add a variable. A corresponding widget is automatically created. Example:
'corr_window': # key
[3020, # index
'int', # type
32, # value
(8, 16, 32, 64, 128), # hints
'window size', # label
'Size in pixel.'], # help
In OpenPivGui.py, you access the value of this variable via p['corr_window']. Here, p is the instance name of an OpenPivParams object. Typing
print(self.p['corr_window'])
will thus result in:
32
The other fields are used for widget creation:
- index: An index of 3xxx will place the widget on the third rider (»PIV«).
- type:
None: Creates a new notebook rider.bool: A checkbox will be created.str[]: Creates a listbox.text: Provides a text area.float,int,str: An entry widget will be created.
- hints: If hints is not
None, an option menu is provided withhints(tuple) as options. - label: The label next to the manipulation widget.
- help: The content of this field will pop up as a tooltip, when the mouse is moved over the widget.
Open the script OpenPivGui. There are two main possibilities, of doing something with the newly created variables:
-
Extend the existing processing chain.
-
Create a new method.
Find the function definition start_processing(). Add another if statement and some useful code.
Find the function definition __init_buttons(). Add something like:
ttk.Button(f,
text='button label',
command=self.new_func).pack(
side='left', fill='x')
Add the new function:
def new_func(self):
# do something useful here
pass
Try pip instead of pip3 or try the --user option:
pip install --user openpivgui
Did you read the error messages? If there are complaints about missing packages, install them prior to OpenPivGui.
pip3 install missing-package
Ensure, you are running the latest version:
pip3 install --upgrade openpivgui
Start OpenPivGui from the command line:
python3 -m openpivgui.OpenPivGui
Check the command line for error messages. Do they provide some useful information?
If the GUI does not look like the screenshot on Github, it may hide some widgets. Toggle to full-screen mode or try to check the compact layout option on the »General« rider.
All output files are stored in the same directory as the input files. To display a clean list of a single processing step, the content of the working directory can be filtered. The »back« and »forward« buttons change the filter. The filters are defined as a list of comma separated regular expressions in the variable »navigation pattern« on the »General« tab.
Examples:
png$ Show only files that end on the letters »png«.
piv_[0-9]+\.vec$ Show only files that end on »piv_«, followed by a number and ».vec«. These are usually the raw results.
sig2noise_repl\.vec$ Final result after applying a validation based on the signal to noise ratio and filling the gaps.
You can learn more about regular expressions by reading the Python3 Regular Expression HOWTO.
Close OpenPivGui, find the file .open_piv_gui.json in your home directory, remove it, and restart OpenPivGui. All variables should be reset. Because of the leading dot, this file is hidden on Mac OS and Linux. Use ls -l in your terminal to see it or select »show system files« or the like in your file browser.
This happens, when a PIV evaluation is started and the file list contains vector files instead of image files. Press the »back« button until the file list contains image files.
This happens, when PIV evaluation is NOT selected and the file list contains image files. Either press the »back button« until the file list contains vector files or select »direct correlation« on the PIV rider.
- If not done, install Git and configure it:
git config --global user.name "first name surname"
git config --global user.email "e-mail address"
-
Create a Github account, navigate to the OpenPivGui Github page and press the fork button (top right of the page).
-
Clone your own fork, to get a local copy:
git clone https://github.com/your_user_name/openpiv_tk_gui.git
- Your fork is independent from the original (upstream) repository. To sync changes in the upstream repository with your fork, specify the upstream repository:
cd openpiv_tk_gui
git remote add upstream https://github.com/OpenPIV/openpiv_tk_gui.git
git remote -v
- Write actual changes of the upstream repository into your local fork:
git fetch upstream
- If not done, install Git and configure it:
git config --global user.name "first name surname"
git config --global user.email "e-mail address"
- Clone the git repository:
git clone https://github.com/OpenPIV/openpiv_tk_gui.git
- Create a new branch and switch over to it:
cd openpiv_tk_gui
git branch meaningful-branch-name
git checkout meaningful-branch-name
git status
- Change the code locally and commit changes:
git add .
git commit -m 'A meaningful comment on the changes.'
- Push branch, so everyone can see it:
git push --set-upstream origin meaningful-branch-name
-
Create a pull request. This is not a Git, but a Github feature, so you must use the Github user-interface, as described in the Github documentaton on creating a pull request from a branch.
-
After discussing the changes and possibly additional commits, the feature-branch can be merged into the main branch:
git checkout master
git merge meaningful-branch-name
-
Eventually, solve merge conflicts. Use
git statusandgit difffor displaying conflicts. Git marks conflicts in your files, as described in the Github documentation on solving merge conflicts. -
Finally, the feature-branch can safely be removed:
git branch -d meaningful-branch-name
- Go to the Github user-interface and also delete the now obsolete online copy of the feature-branch.