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, ...)
* 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

The author wishes to acknowledge the following in the creation of this submission:
inpaint_nans, uipickfiles: uigetfile on steroids, ellipse.m, Robust spline smoothing for 1-D to N-D data, NaN Suite, Exportfig

• 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.

[Wouter M]

 

[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.

[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.
 

[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]

 

[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

[W Thielicke]

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

[Khaldon]

 

[Patrick]

Fantastic work!

[W 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.

[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.)

[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.

[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?

[W 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.

[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

[sid]

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

[Osman Mosa]

F A N T A S T I C

[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

[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?

[W 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]

@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?

[W 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.

[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

[W 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.

[Yuyang]

 

[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?

[W 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]

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

[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).

[W 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

[Kelly]

Is there any 3D version of this code?

[Hayder]

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

[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}

[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}

[W 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!

[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.

[W 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]

Thank you.

[R. Aragall]

 

[York]

 

[York]

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

[W Thielicke]

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

[Jan Neggers]

 

[chen]

good job.

[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

[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?

[W 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]

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

[W 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;

[Martin Richard]

I think that this tool is great!

[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.