shrediquette / pivlab

Particle Image Velocimetry for Matlab, official repository

PIVlab - particle image velocimetry (PIV) tool with GUI

PIVlab is a graphical user interface (GUI) based particle image velocimetry (PIV) software. It can be used to control OPTOLUTION's lasers, cameras and synchronizers, and of course it calculates the velocity distribution within imported (or captured) particle image pairs. It can also be used to derive, display and export multiple parameters of the flow pattern. The simple, GUI makes PIV data acquisition and data post-processing fast and efficient.

---

PIVlab comes with it's own unique hardware: Pulsed lasers, LEDs, synchronizers and cameras are available here: Optolution.com

---

Video tutorial 1/3: Quickstart guide https://youtube.com/watch?v=g2hcTRAzBvY

Video tutorial 2/3: Pre-processing, analysis and data validation https://youtube.com/watch?v=15RTs_USHFk

Video tutorial 3/3: Data exploration and data export https://youtube.com/watch?v=47NCB_RFiE8

PIVlab controlling cameras, lasers, etc. https://youtu.be/8B5M31NWlJc

Installation: https://github.com/Shrediquette/PIVlab/wiki#installation-instructions

Please ask your questions in the PIVlab forum: http://pivlab.blogspot.de/p/forum.html

Software documentation is available in the wiki: https://github.com/Shrediquette/PIVlab/wiki

---

Code contributors:

• Main: William Thielicke (http://william.thielicke.org)
• Name spaces / packages: Mikhil from MATHWORKS (https://github.com/Mikhil11)
• Vectorization in piv_fftmulti: Sergey Filatov (http://www.issp.ac.ru/lqc/people.html)
• GUI parallelization: Chun-Sheng Wang, ParaPIV (https://de.mathworks.com/matlabcentral/fileexchange/63358-parapiv)
• Command line parallelization: Quynh M. Nguyen (https://github.com/quynhneo)
• Speed, memory and general optimizations: Maarten (https://github.com/mkbosmans) via VORtech.nl via MathWorks

---

We would like to acknowledge Uri Shavit, Roi Gurka & Alex Liberzon for sharing their code for 3-point Gaussian sub-pixel estimation. Thanks to Nima Bigdely Shamlo for allowing me to include the LIC function. Thanks to Raffel et al. for writing the book "Particle Image Velocimetry, A Practical Guide", which was a very good help. Thanks to the thousands of publications that use PIVlab for research!

Visit Matlabs File exchange site for PIVlab:

PIVlab can be run online using MATLAB online. MATLAB online is free (after registration) with a limited usage time per user (20 hrs/month):

pivlab's Issues

Banded colormap

In plot settings, in derived parameters appearance. Add checkbox that reduces amount of colormap entries using interp1, nearest.

Vorticity direction?

Check if vorticity has the standard rotational sense.

Polyline in "Extract parameters from polyline" shouldn't be cleared

When users scroll through frames, the polyline should always be redrawn until it is cleared. So users can extract data using the same polyline in different frames.

Add PNG export

Clean up session loading

Try catch for every setting / item for better backwards compatibility. Stack exchange has a solution (google "sequential try catch end block for matlab").

Bitmaps as masks...?

PIVlab uses polygons to store masks. These are converted to BW just before the PIV analysis. Maybe it is feasible to change all the mask handling to pure bitmaps? That would make it much easier and straight forward for users to draw their own masks.

Include correlation coefficient in mat file export

Remove efmenu from Quickview figure in GUIDE

Throws error message, seems to have installed itself silently...

Automatic GUI testing

Try if this works with PIVlab somehow:
https://sites.google.com/site/matpihome/matlab-gui-framework/unit-test-gui

Add correlation coefficient as derivative

corr2 should be used. however, the calculation probably takes quite some time for calculation for every interrogation area... So is it feasible to be implemented?

Add option to remove red "x" in masked areas

Should probably be added in "Modify plot appearance". But this panel is quite full already...

Support for multi layer tiffs

Support for multi layer tiffs should be added. However, I never used these kind of tiffs, so I don't know how many different types exist. Ideally, someone would provide several multi layer tiffs from different origins, so I can test this.

Copy settings to clipboard

Add button that copies all relevant settings of PIVlab to the clipboard, so it can be shared / cited more easily.

Free units?

Maybe it would make sense to enable the user to use free units, and not only m/s.

Add new sequencing style

A--B, A--C, A--D

Add correlation coefficient

Many people are asking for the correlation coefficient. I am not really sure what the correlation coefficient can tell you, as it can't discriminate between a strong background signal or a strong particle image correlation. However, I am currently implementing it like this:

    if lastpass==1 && get_correlationmap == 1 % geht nicht bei nur 1 pass
        correlation_map=zeros(size(typevector));
        for cor_i=1:size(image1_cut,3)
            correlation_map(cor_i)=corr2(image1_cut(:,:,cor_i),image2_cut(:,:,cor_i));
        end
        correlation_map = permute(reshape(correlation_map, [size(xtable')]), [2 1 3]);
    end

The challenge is to integrate this in the GUI in a suitable way....

Issue in ANALYZE all frames

Only first frame get analyzed if I do the analyze all frame option, remaining frames didn't analyzed and then I had to do it one by one which is time consuming. Please resolve this.

Add polyline coordinates by hand

But how...? Popup window where the user can enter a list of coordinates?

Add checkbox in Plot appearance to disable vectors

This checkbox might just write "inf" to the existing vector skip edit box.
Helpful for BOS and also for optical flow.

version: should be 2.37?

PIVlab/PIVlab_GUI.m

Line 224 in 8754e44

current_url = 'http://william.thielicke.org/PIVlab/latest_version.txt';

Change background subtraction

Currently, the background subtraction tool subtracts the background from every image and saves the resulting image. This generates a lot of unnecessary data.
It should be changed, so that only the background images are saved, and they are subtracted on the fly in the GUI.

Add "pass zero" ...?

Maybe it makes sense to add a "Pass zero". That will just correlate the full image A with the full image B. That will result in a global shift of the full image. This could be applied as the result of the first pass, and makes it possible to start the multipas approach with smaller initial windows even if there are HUGE displacements.
In the past, there was quite a number of useers that had a way too large displacement, and that hence didn't get results. A pass zero could help to get rid of this typical issue.

Clean up Sliderdisp function

Sliderdisp is a very ugly function that needs to be split up in several sub-functions for a better overview. I think that speed can also be optimized. This will have a direct effect on the overall performance (including data export, data exploration etc).

PIVlab_commandline issues

https://github.com/Shrediquette/PIVlab/blob/main/PIVlab_commandline.m is not ready to run, for example https://github.com/Shrediquette/PIVlab/blob/main/PIVlab_commandline.m#L16 has s=cell(11,2) but should be s=cell(13,2) since version 2.01 , or it doesn't save the results, etc. Anyway I have modified the script to make it standalone program, with parallel processing options (which was critical because I had a TB of images to process). If pull requests are welcome, I will submit one.

Status indicator

Show an indicator that tells the user whether PIVlab is currently doing something or not.

DCC gives error in 2.38 (correlation map)

Rescale maps has an issue when step is larger than int area and single pass

Search for line: disp('temp workaround')
Something with the calculation goes wrong when step is larger than int area

how to generate 10000 synthetic pics？

If i want to generate 10000 pairs of synthetic pictures，which func should i use?

Add video import functionality

Videos should be possible to read in PIVlab. Best option imho: Add button next to the "Load Images" button: "Load Video". That should open a small window where a filename can be selected, and something like "skip n frames" to reduce the frame rate. The video must be treated the same way that currently image files are treated.
Current situation:

            if strcmp(ext,'.b16')
                currentimage=f_readB16(filepath{selected});
            else
                currentimage=imread(filepath{selected});
            end

Add sth like:
If is_video == true currentimage = read(videoobject,selected); end

videoreader function was introduced in R2010b, so this feature cannot be available in R2010a

Parallelization of post-processing

limit peak search area fails in old matlab releases

Because "mean" does not accept multiple dimensions in older releases:
??? Error using ==> sum
Dimension argument must be a positive integer scalar within indexing range.

Error in ==> mean at 30
y = sum(x,dim)/size(x,dim);

Error in ==> piv_FFTmulti at 655
bg_sig=(1-emptymatrix).*mean(result_conv,1:2); %zeros in middle, average
correlation value in the remaining space

Error in ==> PIVlab_GUI>AnalyzeSingle_Callback at 4689
[x, y, u, v, typevector,correlation_map] = piv_FFTmulti
(image1,image2,interrogationarea, step, subpixfinder, mask,
roirect,passes,int2,int3,int4,imdeform,repeat,mask_auto,do_pad);

??? Error while evaluating uicontrol Callback

Add correlation matrix output bit

In FFT multi. Writes correlation matrix to workspace

Check what needs to be changed if no image processing toolbox is available

...so people without the toolbox can use PIVlab.

Ensemble correlation via command line

Provide an example script to use ensemble correlation with the command line.

Implement *.b16 in background subtraction GUI

Add PNG to image filter list

Loading previous session with videoreader: If video was moved to different path, let user choose new file location.

Experiment with realtime PIV

PIVlab already has image capturing implemented. With a fast computer and the parallel computing toolbox (splitting an image pair into four or eight so subregions) it could be possible to do 1-5 Hz realtime PIV. I'll soon buy a nice Asus ROG Flow X13 as my birthday present and test this. Might be helpful to tune the experimental setup on the fly.

B16 and ensemble correlation

... doesn't work, because piv_fftensemble uses imread. Must be replaced.

Add optical flow

From Openopticalflow-PIV, as discussed with the author.

Auto-ignore low contrast regions?

Maybe it is possible to automatically ignore regions with low contrast (that wouldn't give any reasonable correlation matrix anyway). Maybe, before analysis, we can find the standard contrast per interrogation area (slightly lowpass the int area, then subtract min intensity from max intensity). Interrogation areas that are below 5% of the average contrast level are automatically assigned a mask (or simply assigned NaN). This could save a lot of work masking images.
I think the best way would be to have an extra function that is run before cross-correlation, and that automatically generates a mask. But this enhancement will be slow I think.

Implement Q-criterion

As nicely shown in invariant2_factor.m
in https://github.com/Tianshu-Liu/OpenOpticalFlow

Implement PIV uncertainty quantification

https://doi.org/10.1088/0957-0233/24/4/045302 , page 6 shows the process:
After image deformation: multiply images, then threshold. White pixels represent particles tht are present in A and B. Use subpixel estimator to find displacement of each particle in A and B. The "mismatch" is then a measure for the uncertainty (after some statistical stuff that I still have to look at).
Matlab code is available here:
http://piv.de/uncertainty/UncertaintyCodes/ParticleDisparity_Code.zip
... but it is probably better to code on my own to understand whats going on.

Add MP4 export instead of compressed avi

Can Matlab do this? Does it depend on the codecs that are installed on the specific computer?

Disable autocorrelation: Use mean and not zero for the mask

Add button to display background image

...so it can be used as a guide to draw a mask or select a ROI.

PIVlab Quickviewer

The Quickviewer is a tool that can help during PIV data acquisition. It is used to quickly validate that the recording settings (exposure, pulse seperation etc.) are good. I am adding this because I need it for our PIV measurement campaigns. It allows the user to load an imagepair (shortcut 'l' <-- this is a small letter "L"), to perform a PIV analysis of the selected ROI (shortcut 'p'), or to maximize the ROI (shortcut 'm'). Histogram, correlation coefficient and vector map are displayed.

This is how it will look like:

Preprocessing: Highpass seems to be broken in latest release

Verify

Implement temporal stdev calculation

But the question is how it is implemented best... It doesn't fit into the GUI right now, because it is a operation that processes a series of frames, but the result is a statially resolved scalar...

Issue warning after uipickfiles when image size inconsistent

add loop to check image dimension. How mcuh time does that take...?