PIVlab - time-resolved particle image velocimetry (PIV) tool

A GUI based tool to preprocess, analyze, validate, postprocess, visualize and simulate PIV data.

Description

PIVlab is a time-resolved particle image velocimetry (PIV) software that does not only calculate the velocity distribution within particle image pairs, but can also be used to derive, display and export multiple parameters of the flow pattern. A user-friendly graphical user interface (GUI) makes PIV analyses and data post-processing fast and efficient.

Screen-capture video of the tool:
http://vimeo.com/10090907

Example analyses & videos can be found on the PIVlab website:
http://PIVlab.blogspot.com

Main features:
* completely GUI based PIV tool
* multi-pass, multi grid window deformation technique
* import bmp/ tiff/ jpeg image pairs/ series
* image sequencing styles A-B, C-D, ... or A-B, B-C, ...
* individual image masking and region of interest (ROI) selection
* image pre-processing (contrast enhancement, highpass, intensity capping)
* two different sub-pixel estimators
* multiple vector validation methods
* magnitude/ vorticity/ divergence/ shear / ...
* data smoothing, vector field highpass
* multiple colormaps
* streamlines
* extensive data extraction tools/ integration via poly lines/ circles/ area
* statistics (histograms, scatterplot, mean & stdev)
* precise particle image pair generation with user-defined parameters and several flow simulations (synthetic PIV image generator)
* data export (matlab, ascii, movie file, image, Paraview, ...)
* main features accessible via comand line scripting

In addition to the acknowledgements to MATLAB fex submissions, we would like to acknowledge Uri Shavit, Roi Gurka & Alex Liberzon for sharing their code for 3-point gaussian sub-pixel estimation ( http://www.openpiv.net ).
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.

See the file "thirdparty.txt" in the zip archive for licenses and references.

If you use our work, please leave a comment and a rating.

Acknowledgements

Inpaint Nans, Uipickfiles: Uigetfile On Steroids, Ellipse.M, Easy 'N Fast Smoothing For 1 D To N D Data, Na N Suite, and Exportfig inspired this file.

This file inspired Pt Vlab (Particle Tracking Velocimetry Lab).

• Required Products: Image Processing Toolbox
• MATLAB release: MATLAB 7.1.0 (R14SP3)
• Other requirements: Multi-core processors in combination with a recent Matlab version speed up the analyses enormously.

[William Thielicke]

The correlation result is here:
piv_FFTmulti.m
result_conv=result_conv/max(max(result_conv))*255; %normalize, peak=always 255

[Konstantinos Margaris]

Dear William,

How can I plot the correlation peak for an interrogation window?

[Sina Tebianian]

Many thanks for your precious help. I will send you some of the snapshots.

[William Thielicke]

Dear Sina,
Images are not binarized. PIVlab however only uses intensity information from the images.
There should be minimally around 6 particle pairs in the last pass. The larger the interrogation area is, the better are the individual vectors. But you lose resolution of course.
When there are no particles in a region, then PIV doesn't work... The challenge usually is to optimally set up the experiment , but I guess thiss will be hard in your case... Please send me some images, ans I can have a look.

[Sina Tebianian]

Dear William,
Thank you for the amazing PIV code that you created. I am working with a series of images obtained in a dense fluidized bed made of many particles. Some questions that arose while I started working with your PIV lab are:
1. Does the program binarize all the images once I do the image pre-processing?
2. There are regions where there is no particle but I see that there are many velocity vectors that should be avoided somehow.
3. How should I choose Pass1, 2 and 3? Is there a certain criteria for that?

I'll be happy to send you some of the images too.

Best regards
Sina

[Vincent]

 

[William Thielicke]

Dear Ian,
PIVlab uses a cross correlation of sub images to find the displacements. Please see Raffel et al.: "Particle Image Velocimetry, A Practical Guide" for information on PIV. That book also gives an overview on the size of interrogation areas in flows with high displacements and multi-pass algorithms.

[Ian]

Thank you for the excellent PIV algorithm that you created. I've used a few now and this appears the most user-friendly in my opinion.
Thank you for your reply to my previous question. I found that there was obvious flickering of the video i analysed before, which would introduce artefacts.

Say if i have particles flowing in a fluid, does PIVlab generate vectors on the basis of particle tracking or is more of a textural analysis algorithm?

If it is particle tracking, i might have more issues with determining vectors as i'm currently working with smaller ROI's hence if i increase the bulk flow rate, soon i would have to increase the interrogation window size to some unreasonable value and i might lose valuable information.

[William Thielicke]

Dear Ian, the amount of erronoeus vectors depends on your image quality. Image noise or compression artifacts can really become a problem. You can filter erroneous vectors semi-automatically by applying e.g. the stdev filter, the normalized median test, or a global velocity threshold. You can also send me some of your images so I can have a look.

[Ian]

Hi I want to generate streamlines of fluid flow around a structure in an enclosed flow channel. To aid in the tracking of fluid flow and its velocity i have added micro-particles to the fluid. So I'm using this GUI to generate the streamlines for me.

The problem i have is that when i play the video of the fluid flow, i can easily see the net direction of the flow. But when i analyse a few frames of it using PIVlab, i get a fair few errant vectors that are pointing in the wrong direction. Other than manually eliminating this every time for every frame that i analyse, is there something else i could do?
Thank you for considering my question.

[William Thielicke]

Dear Konstantinos,
1: the commandline script is not intended to produce PIVlab session files. But you could analyze 2-3 images in the GUI, then save the session and have a look at the resulting .mat file. The variable "resultslist" contains the x,y,u,v,typevector information.
2: I am using the exportfig function to export the figure. You could search for "exportfig" in the PIVlab_GUI.m and modifiy the figure before it is saved.

[Konstantinos Margaris]

I got the following error when applying intensity capping in my images:

Error using median (line 28)
First input must be single or double.
Error in PIVlab_preproc (line 24)
up_lim_im_1 = median(in_roi(:)) + n*std2(in_roi); % upper limit for
image 1
Error in PIVlab_GUI>preview_preprocess_Callback (line 1502)
out = PIVlab_preproc (img,roirect,clahe,
clahesize,highp,highpsize,clip,clipthresh,intenscap);
Error in gui_mainfcn (line 96)
feval(varargin{:});
Error in PIVlab_GUI (line 32)
gui_mainfcn(gui_State, varargin{:});
Error in
@(hObject,eventdata)PIVlab_GUI('preview_preprocess_Callback',hObject,eventdata,guidata(hObject))
Error while evaluating uicontrol Callback

The issue is solved if one converts the argument in the median function to a double. I am not sure if it is a general bug or just my images (8-bit Tiff).

Also if you could help me out with a couple of things I would be grateful:

1. What will be the command to save a mat file with the results, using the command line script, in order to load it to the GUI for preprocessing?

2. I am using an edge detection algorithm to detect and mask boundaries in my images. I'd like to plot the edges in the GUI and also save them on the images when I export images or videos. Could you point me to the image variables that are saved so I can add the detected edges?

[Susanne]

 

[William Thielicke]

Dear Konstantinos, you can save your session, and then extract the masks from the saved session using this piece of code that Eileen sent to me a while ago:
function ReadSaveMasksFromSession(filename, outfile)
% filename is the name of the PIVlab session file
% outfile is the name for the MATLAB file to be saved
% This function saves the x- and y- coordinates for a mask from PIVlab
% previously saved to a session file. It only does the first image slice,
% but that can be copied to the other images from within PIVlab.
% If the user wishes to run PIVlab on other images with the same
% orientation, the outfile from this program can be loaded into PIVlab.
% Eileen M. McMahon, PhD, May, 2012
masks = load(filename, '-mat', 'maskiererx', 'maskierery');
xmask = masks.maskiererx{1,1};
ymask = masks.maskierery{1,1};
save(outfile,'xmask','ymask');
return;

[Konstantinos Margaris]

Excellent work!

Is there a way to save masks drawn in PIVlab, in order to reuse them in different sessions?

[Amy]

 

[John]

This has been great. For my first time using PIV, this code has been very helpful. I was wondering though what the matrix 'typevector' represents when I save results to a .mat. Does it display which vectors are the original and which ones are replaced after vector validation?

[William Thielicke]

@Emil: I am using Matlabs built in streamline function. As far as I can see, it will only draw streamlines in one direction from the point. I'll look for alternatives for the next release.

[Emil Rozbicki]

It's very good. Just been wondering if there is any way to display streamline not only "starting from the point" but also "ending at the point" or if there would be a way to display the "full" streamline that passes through the given point.

[Martin Richard]

I think that this tool is great!

[William Thielicke]

It's not complicated, here's a quick and dirty parabolic flow:

[v,u]=meshgrid(1:800,-300:299);
v=zeros(600,800);
u=(1-u.^2/max(max(u.^2)))*5;

[Alok]

Hi,
Thanks for the quick reply. I'll give it a shot, although it does look complicated.

[William Thielicke]

Hi Alok,
in line 3636 in PIVlab_GUI.m, you can find the code to generate a uniform displacement flow. You can put your parabola flow profile here, you just need a u and v displacement matrix for all pixels in the image.

[Alok]

Picking up from my previous question, is there a way I can specify the displacement in terms of the equation of a parabola and generate particle images out of it in PIVLab?

[Alok]

This is an amazing tool. I have tried a lot of alternatives before finding PIVLAb. Good job!! I have a query, though. I dont seem to be able to generate images for simple parabolic flows like Poiseuille flow in a channel. Am I missing something? Thanks

[chen]

good job.

[Jan Neggers]

 

[William Thielicke]

@York: yes, just disable the "autoscale map" feature in "Plot -> derive parameters"

[York]

Quick question, is there a way that I can fix the range of the colorbar for the entire sequence of images?

[York]

 

[R. Aragall]

 

[Bhavin Dalal]

Thank you.

[William Thielicke]

@Bhavin: You could open pivlab_gui.m and search for "vectorcolor='g'". Replace this with e.g. 'r' for red or 'k' for black.
When you want to modify the vector colors that are plotted during displaying derivatives (e.g. vorticity or magnitude etc.), search for vectorcolor='k' and replace it with a color of your choice. I will add the possibility for changing vector colors in a next release.

@ALL: If you miss some features, please add your comment/wish here:
http://pivlab.blogspot.com/2011/07/pivlab-12-windows-deformation.html
Otherwise I might forget to add the desired features in the next release (I have quite a number of projects, and it's hard to keep track of everything..).

[Bhavin Dalal]

Very good program. Robust, fast and easy to use. One question, Is there any way I can change the color of the arrows from Green to say Black or Red? I am using color image for demonstration.

[William Thielicke]

@XP Wu:
Thanks for your feedback.
The lines 1605-1607 are correct in my opinion. They set the value of the checkboxes (value==1 means checkbox checked, value==0 means checkbox not checked). And the variables pass2, pass3, pass4 are 0 respectively 1. This works fine.
Your second change makes much sense, and I'll include it in the next release. Thanks!

[XP Wu]

Great work!
And some bugs should be fixed.
See the line 1605 to 1607:

set(handles.checkbox26, 'value',pass2);
set(handles.checkbox27, 'value',pass3);
set(handles.checkbox28, 'value',pass4);
Because checkbox has no property named 'value',so these code should be as follows:

%% {Modefied by XP wu
set(handles.checkbox26, 'String','Pass 2:');
set(handles.checkbox27, 'String','Pass 3:');
set(handles.checkbox28, 'String','Pass 4:');
%% 2011-12-15}

[XP Wu]

PIVlab_GUI doesn't need start from it''s folder.Just change the Line 105 :
read_settings('PIVlab_settings_default.mat',pwd);

could be as follows ::
%% {Modefied by XP Wu
% read_settings ('PIVlab_settings_default.mat',pwd);
psdfile=which('PIVlab_settings_default.mat');
dindex=strfind(psdfile,filesep);
read_settings ('PIVlab_settings_default.mat',psdfile(1:(dindex(end)-1)));
%% 2011-12-15}

[Hayder]

Excellent code. Very friendly and accurate.
I am using it in all my PhD work

[Kelly]

Is there any 3D version of this code?

[William Thielicke]

Hi thefourtheye,
if some areas are completely black, my tool will not be able to calculate a velocity in that areas. So the velocity is not zero in these areas, but it is "not measurable". That is why the tool puts "NaNs" in these areas. In the vector validation, all missing data (=NaNs) is interpolated. I just modified the file piv_FFTmulti.m so that a "0" is placed in black areas instead of a "NaN". If you want me to send you the file, please write an email to
P I V l a b @ g m x . c o m

[thefourtheye]

Hello W Thielicke, your tool is awesome. Thanks for posting it! I have a question about vector validation. I am running your program for wound healing analysis. Before analysis, I apply a binary threshold to my images to decrease noise. When I run the program, there are vectors for the cells, aberrant vectors from cell division, and dots on the denuded areas where no movement occurred. When I select velocity limits and apply them to the frames, the aberrant vectors are replaced by smaller orange vectors, but now the denuded area that should have no movement between frames has small orange vectors too. Why are areas on no movement being assigned vectors when I limit the velocity range? I take care to center my limits on (0,0) on the scatter plot (I will select the area between (-1,1) and (1,-1), for example).

[Gareth]

Yes, I've added in a statement to send the data to the workspace and I can now access the data. Thanks!

[William Thielicke]

@Gareth: The histograms and the other statistics plots are done in line 3019 of PIVlab_GUI.m . Just enter the "keyboard" command below this line, and you have access to the data. Is this what you meant? You can also add the assignin command here, so that the data is always sent to your workspace.

[Gareth]

Hi, this is a great tool, thanks. I have a question though. Not only do I want to see the histograms and graphs that PIV Lab generates, but I'd like get the data it used to generate them. So, if it used axes x and y to generate a histogram, I want those data vectors. Is this possible?

[Yuyang]

 

[William Thielicke]

Hi there, I have good news: The last days I programmed a multi-pass window deformation PIV algorithm. the results look fantastic, noise is reduced dramatically, peak-locking is reduced, and large gradients and very small interrogation areas are less of a problem. Have a look at http://pivlab.blogspot.com for first results. I will do some final tests and upload the update soon.

[Erman Celik]

PIV Lab is the most efficient program that I have ever used. User friendly interface and operation instructions are very useful for quick process. Thanks for this efficient code. Sincerely

[William Thielicke]

I think loading analyses from external programs will not be possible. Is there no way to decrease the displacement in your analyses? If your flow is more or less homogeneous, you could try to shift the images prior to the analysis. Could you send me some example recordings? Maybe I'll find some time to play around with multipass again, and then I'd need some images where multipass has an advantage.

[K.Wager]

@W Thielicke:
Thanks for your fast answer.
The reason why I need to use multipass is due to my flow conditions (µ-PIV, velocities above 15 m/s).

I am wondering if I could do the cross correlation with my commercial software and load the data afterwards in PIVlab. Is this possible via load PIVlab session? Which format and data are needed?

[William Thielicke]

@K.Wager:
I did some preliminary multi-pass tests a while ago. I did a normal analysis as first pass, and got a displacement in x and y. In the next pass, I shifted the interrogation areas of the second image using the integer displacement of the first pass and redid the analysis. The result of the analysis didn't change at all after two passes. I think the reason is that I am using a DCC approach for the analysis, but I am not yet sure about this. Maybe, if I'd use a FFT approach, the result would be better with a multipass analysis. Also, if i'd decrease the interrogation area in the second pass, the results would probably not become better, because the analysis would then be based on less pixel information, which might increase noise.

In the latest release (not uploaded yet), I added a feature to draw streamlines in the analyses. Maybe this will be interesting to some of you.

[K.Wager]

I just started to work with PIVlab, but I already think it's way better than the commercial software!

Is there a possibility to do a multipass interrogation with decreasing window size?

[João Brás]

Fantastic work!! your software, work way better than other commercial software in many ways. very useful!

Thank you

João Brás

[Osman Mosa]

F A N T A S T I C

[sid]

Thanks a lot!! This will help in rejecting some vectors manually.

[Liran Oren]

Fantastic work!!!
I am getting the same results that the $15k Davis software (from LaVision) gives. Kudos!
How would you compute the pressure field from the results? It seems like the OpenPIV group started working on it, but never finished... Solving the N-S and Poisson equations will give you a ball park that can be good enough for some applications

[William Thielicke]

Where does it round to zero? In the tools panel when you click on a vector? The velocity display in this panel is just meant for information, not to measure something. But you can search for this line in PIVlab_GUI.m:

set(handles.u_cp, 'String', ['u:' num2str(round((u(info(1,1),info(1,2))*retr('caluv')-retr('subtr_u'))*1000)/1000)]);

and replace the "1000" with a "10000" to get more precise information.

[sid]

Very nice tool to work with!!!
Only one problem I faced. It gives values of velocity components zero when the velocities are below or around 0.002 m/s.
Is there any round off error which is causing this problem? How should I solve it?

[Amitesh]

Good work! I hope you can add the option "apply to all frames" in the Statistics and Extractions sections too. When one is trying to extract data using polyline, area, area integral series etc, it would be very useful to be able to do so to all the loaded frames at once automatically. Thank you.

[David]

Excellent tool!!!

Extremely user-friendly.
Fast.
All the useful output variables avaiable.
All the useful data output formats available.

Definitely one of the best tools I've seen in file-exchange. (I felt compelled to register myself, just to place this comment.)

[William Thielicke]

@all: If you experience problems with this tool, please contact me. I only have two computers (Win7) and one MATLAB version to test it with. The software became pretty complex by now, so it is impossible to me to predict potential problems on all of the possible hardware / OS / MATLAB release combinations.
Nevertheless, I can't promise that I'll always have enough free time to instantly solve your problems.

[Patrick]

Fantastic work!

[Khaldon]

 

[William Thielicke]

Hi Shashi, I am currently working on the next release, and I will add a possibility to change vector thickness.

[Shashi Thutupalli]

Hi,

This is really nice and works very well for me. Is there a way I can modify the thickness of the vectors etc.

Best,
Shashi

[Hadi Mohammadi]

 

[Hadi Mohammadi]

I got another problem, which is the compiling time, I'm just want to plot the velocity profile in sample of code, but it takes too much time and I just cut it off, meanwhile I'm using a new brand laptop and desktop, any idea?

[Hadi Mohammadi]

Hi I was going to use this GUI for tracking the particles and I was succeeded to use it for the first try, then I encountered with an error when I wanted to run it again, the error in MATLAB command line says:
*******************
??? Error using ==> guihandles
H must be the handle to a figure or figure descendent.

Error in ==> PIVlab_GUI>switchui at 149
handles=guihandles(getappdata(0,'hgui'));

Error in ==> PIVlab_GUI>loadimgs_Callback at 592
switchui('multip01')

Error in ==> gui_mainfcn at 75
feval(varargin{:});

Error in ==> PIVlab_GUI at 25
gui_mainfcn(gui_State, varargin{:});

??? Error while evaluating uimenu Callback.

error saving last directory
********************
It would be great if any one can help me to fix this bug.

[Wouter M]

Very nice. I am new to this field of study. I was getting frustrated by the 'professional' software. I tried a few other Matlab PIV-toolboxes, but this one is the best imho.

Again: very nice work! I have two suggestions which I think will be useful. Suggestions: 1) Make all commands available for use in command-line or scripting and add a short documentation. 2) Add possibility to calculate mean flow field and turbulence velocity of a timeseries of images.

[Wouter M]