File Exchange

image thumbnail

PIVlab - particle image velocimetry (PIV) tool with GUI

version 2.53 (17.4 MB) by William Thielicke
Easy to use, GUI based tool to analyze, validate, postprocess, visualize and simulate (micro) PIV data. Parallel computing is supported (opt


Updated 10 Jun 2021

From GitHub

View Version History

View license on GitHub

Editor's Note: Popular File 2018 2019 2020

This file was selected as MATLAB Central Pick of the Week

PIVlab is a GUI based particle image velocimetry (PIV) software. It 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) with the ability to control a PIV camera and a laser makes PIV data acquisition and data post-processing fast and efficient.

Video Explanation of the tool:

Example analyses & videos can be found on the PIVlab website:

Please ask your questions in the PIVlab forum:

Download the file 'PIVlab.mltbx', and run it on your computer. It will automatically add the PIVlab toolbox and app in your Matlab installation. Alternatively (my preferred method, but also the only way if your Matlab release is older than R2015b [8.6]), download the zip file from GitHub by going here: , click 'Source code (zip)' of the latest release and extract the contents to a new folder in your Matlab work directory. Then run PIVlab_GUI.m.

Main features:
* completely GUI based PIV tool
* multi-pass, multi grid window deformation technique
* parallel processing supported when the parallel computing toolbox is installed
* ensemble correlation e.g. for micro-PIV
* import bmp/ tiff/ jpeg image pairs/ series
* acquire PIV images and control a camera and laser directly in PIVlab (additional hardware required)
* 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, high-pass, intensity capping)
* two different sub-pixel estimators
* multiple vector validation methods
* magnitude/ vorticity/ divergence/ shear / ...
* data smoothing, vector field high-pass
* multiple color maps
* streamlines
* extensive data extraction tools/ integration via poly lines/ circles/ area
* statistics (histograms, scatter plot, 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, Tecplot...)
* main features accessible via command line scripting

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.

Cite As

William Thielicke (2021). PIVlab - particle image velocimetry (PIV) tool with GUI (, GitHub. Retrieved .

Thielicke, William, and Eize J. Stamhuis. “PIVlab – Towards User-Friendly, Affordable and Accurate Digital Particle Image Velocimetry in MATLAB.” Journal of Open Research Software, vol. 2, Ubiquity Press, Ltd., Oct. 2014, doi:10.5334/

View more styles

Thielicke, William. The Flapping Flight of Birds: Analysis and Application. PhD Thesis, Rijksuniversiteit Groningen, 2014, doi:10.13140/RG.2.2.18656.94728.

Comments and Ratings (280)

Masahiro Furuya

Ralph Eikenberg

Zachary Smith

@William Thielicke, @Ricardo Arturo Lopez de la Cruz
I think this error comes from the "filepath" variable listing the files in the current MATLAB directory, in addition to the images you are trying to load. A workaround is to make sure your current matlab directory has no files (only folders), then the image loading works properly. Hopefully this helps with the debugging! I noticed the self-same issue in the older PTVlab gui as well.

Jananee Dhanasekaran

Hi Dr. Williams! The 2.50 Version is super great and the parallel processing really helps with cutting down the processing time!
However, it throws an error when I try to calculate the correlation coefficient. Please let me know what I can do. Thanks!

William Thielicke

Hi Ricardo, I can try to debug this if you send your session file and the images. Please use the PIVlab forum for questions.

Hello, thanks for creating this add-on, it is very useful :)
However, I have a small issue. It is related to opening a saved session using a new location for the images.
I originally used PIVlab_GUI (with a Mac) for a set of images saved in harddrive 1 and saved the session afterwards. Then I made a copy of my whole hardrive 1 into hardrive 2. When I tried to open the saved session in a second computer (windows) using hardrive 2. I got a message asking me to select the path of the images. When I select the new path I get the following error:

Index in position 1 exceeds array bounds.
Error in PIVlab_GUI>sliderdisp (line 2536)
Error in PIVlab_GUI>load_session_Callback (line 8091)
Error while evaluating Menu Callback.

Do you know how can I fix this?

Thank you in advance.

William Thielicke

Hi Vivek, maybe.... Our synchronizer can do down to a pulse separation of 2 microseconds. If your camera can be used, depends on the availability of a SDK for Matlab or if it can be accessed using the image acquisition toolbox.

Vivek Lingan

Hello Dr. William, PIVlab is impressive! I'm using a High-speed camera for HS flow visualization. Can that be integrated (Image acquisition->select configuration) for controlling the hardware for doing PIV? Thanks.

thuyduyen buithi

Riza Inanda Siregar



Hello, Dr. William, Thank you very much for sharing pivlab. Will you consider add 2D-3C PIV algorithm in later update?Thanks for your kind attention and look forward your prompt reply.

Lubos Rampas

Hello, Dr. William, how can I display parametr of turbulence? Are there any ways, how can I do it?
Thank you

毅斌 张

Dyuman Joshi


yao zh

Nice work!Thanks.

威 刘


Andy Perrin

Kevin Du Clos

Pieter Boersma

Ulrich Müller

William Thielicke

Hi Shubham saini, there are many PIV experiment images included in the contribution.

Shubham saini

If someone can share some PIV experiment images (just 10) will work, I want to learn this software.

David Dalton

Really useful, thank you for the work!!


Very nice software!

Arashdeep Singh



Frederic Moisy

Excellent, thanks!

xin li

Excellent work

Xiaoyi Hu

大器 程

Hello, Dr. William, can you display the vector and cloud image separately when outputting the results,
1. Draw a vector graph on the original image (it can be done now);
2. Draw vector map on white background;
3. Display only color cloud image, not vector.

deniel weck

Wonderful info. thanks for sharing with us.

James Carly

Thanks for this great sharing. A software very recommended no doubt about.

William Thielicke

Hi Shantanu, actually no update was made, all changes on this website are just for migrating to github. That message you see appears every year only at this specific date... It was implemented a while ago :)


I downloaded the recent update and now when I launch PIVlab, it says "It's 15th of Oct.. Loving Lena since 15 years today!". Was that the only update made recently? :)

Gianluca Padula

Bo Pang

Hi! William,very powerful software! thank you!
I have a request. Can the displacement data of each picture be added to this software? If so, that would be great!

Hsing-Yu Huang

Hi! William, it is a really nice software!
I have a doubt and could you please help me clarify it ?
I plan to transform the planes in 'result_conv' into the normalized correlation coefficient planes and calculate the normalized correlation coefficient of each peak. Could you please tell me how to calculate the cross correlation coefficient from the parameter 'result_conv' or from the other parameters in the script ' piv_FFTmulti' ?
Thank you very much!

Bin Zhang

thank you!

Aneek Salman

Hello! William, That is an excellent representation of image processing. I would like to know can I use this program to calculate the mixing index of two different fluids by image processing?
If it is possible then could you tell me how can I do it?


Isa Onde

Bosong Lin

sdas gaur

Great stuff, thanks for sharing with us.

Kentaro Hoeger

Excellent program with good documentation and tutorial.

Sacchita Tiwari

Hi William. I am currently trying to use PIVlab for displacement in brain tissue. Does this program work efficiently if after deformation the particle not only displaced but distorted in shape as well. Also, what is the physical meaning behind simple strain rate. It would be awesome if you let me know what formula it uses to calculate this. Can we also get displacemnet map from this app.

Oliver Pearse

Great program! Have been using it extensively for my research. When setting up my model I did run into a problem regarding particle image density. How is the amount of particles on screen determined with relation to laser sheet thickness? I calculated the amount of particles necessary for a PID of 15 pixels per interrogation window, but the amount of particles in my PIV image depends (logically) on the laser sheet thickness. Is there a way of determining the amount of illuminted particles with a given laser sheet thickness and particle number?

Divna file

Awesome information, I appreciate your work.

avnish sharma

avnish sharma

Wonderful , I am searching for this information. Thanks for sharing with us.


Hi William
Can you add a variable to the display: Displacement(Modify data → Display Parameter)
Thank you

luisa di monaco


Hi, Thank you for developing such a great tool! It will be really nice if someone can answer my question:
In the post-processing, I used the option 'interpolate missing data', which filled out some orange vectors in the spaces where the data was missing. Is it possible to find out the percentage of these interpolated vectors in each frame?


very sorry! no problem, It is my wrong!
There's been a mistake when version2.3.1 work in matlab2014b, the color map(in Modify plot appearance)can't Appear, So it is recommended to use a higher version of Matlab.
当2.3.1版本在 matlab2014b 中工作时出现了一个错误,颜色指示条(在 Modify plot appearance中)不能显示,建议使用更高版本的 Matlab。


There's been a mistake when version2.3.1 work in matlab2014b, the color map(in Modify plot appearance)can't Appear, So it is recommended to use a higher version of Matlab.
当2.3.1版本在 matlab2014b 中工作时出现了一个错误,颜色指示条(在 Modify plot appearance中)不能显示,建议使用更高版本的 Matlab。

jianqing huang

Intesaaf Ashraf

Hi William

thanks for the software. it very useful in my research. But I unable to save the matfile of each frame. it is saving only one frame named "PIVlab"

Shivani Jariwala

Qionglan He


Regine Morgenstern

Hi again William. Thank you for your quick response! I have another question. Is it possible to somehow extract the data for the vectors out of PIVlab in order to plot their poles (i.e. the pole to a plane)? I see there is a heatmap for 'vector direction (degrees)' - is it possible to extract this data out in numeric format by any chance?

Nando Käslin


gautam singh

The best tool out there PIV Matlab.
Thanks William.


is there any provision for stereo PIV

William Thielicke

Hi, I don't fully get the question, but pivlab will give you recommendations for the interrogation area. Please use the forum for questions.

Shivani Jariwala

Hello William,

Is there a way where I can create the grid for the interrogation spot size and see if the displacement of particle within frame sets is less than 1/4 th of the spot size?


Michael Keeling

William Thielicke

Thanks Angel, I'll check that out.

Angel Palacios


I've been using PIVlab for a while now but I would like to point out that in windows is not possible to call a shared network directory, e.g. \\MySharedDirectory\Sub\Directory to localise the images. Is there any fix to this problem?
I know in Linux there is no such an issue because the shared location is mounted to a local directory, but I cannot see a solution in Windows even if I map the shared folder.

William Thielicke

Hi Regine, I would definitively give it a try! If you use the Pivlab forum for questions, I can also try to assist you with the analysis.

Regine Morgenstern

Hi there. Could you please tell me if PIVlab can deal with orthomosaics, or only single images? We generally capture landscape UAV imagery spaced at regular intervals as you would for a typical SfM photogrammetry model, then derive an orthomosaic from that. And we have multiple epochs of such orthomosaics for the same site – which is what we would like to develop the movement vectors for. Can the PIVlab tool deal with such large datasets? If so, are there any specific camera parameters that I should be aware of (e.g. -70 degree gimbal angle vs nadir; certain height restrictions; keeping a consistent ground sample distance across the different epochs; etc). If it can only handle single images, I assume the image would need to be taken from the same location every time for the pixel matching to work (i.e. same angle, distance, etc)? Thanks for your help, I'm excited to try out this tool!

William Thielicke

If you do not calibrate, then u and v directly represent the x and y displacement in pixels.



I'm using PIVLab for a background-oriented schlieren application. Could you offer any suggestions for converting the u and v vector components to particle displacements in x and y?

William Thielicke

Hi, please use the forum for asking questions and please also give more detail for your problem (what are you trying to do?)

khalid Elserfy

i am using pivlab 2.1 for analyzing different cases the issue is that x array every time starts form different location X{1,1}(1,1) , i am comparing specific location along x axis, so should i use X{1,1}(1,1) as my reference point and subtract the other point from that reference point ?

Dmitriy Bespalov

William Thielicke

@Deniel Weck: I don't get the problem, sorry...

deniel weck

I have the same error with 1.43 also.
I guess the error is due to something else that I need to figure out.
error closing file ..<fileName>.. the file may be corrupt.

HIgh Tech Man

xiao wang

Shweta Narayan

How are strain rates and shear rates calculated in this code?

Shweta Narayan


tengda qian

William Thielicke

Hi, this is not possible because this feature is experimental, and I want to prevent that people accidentally use the high-pass... But you can modify your data yourself: just lowpass your image with e.g. imfilter and then subtract it from the original data.

wu tiger

Hello, Impressive tool indeed! I would like to know how to save the vector data after Highpass vector filed is selected?

Niccolo Karwowski

Hello, I would like to know if it is possible to measure the displacement of the particles or not. I would also like to know if the accuracy of the results can be changed, so that the results may be read up to a factor of 0.001 for example.

William Thielicke

Yes, in the file selection dialogue you can choose the sequencing style.

Very nice tool !
Just one question : Is it possible to choose a parameter so that the frames are [Image001-Image002], [Image002-Image003], etc instead of [Image001-Image002], [Image003-Image004], etc ?

William Thielicke

Hi Tristan, thanks for your donation and comments!
1: some people requested this already, so I'll have a look. Tif stacks were not used by people using PIV when I was working with it. Where do these stacks come from is it a specific software / camera?
2: it's difficult to decide which are the main functions... I'll check if adding another toolbar makes sense. I can also make this optional, so the user decides if he wants to see it.
3: this is possible in v2.02
4: if you save your settings as pivlab_settings_default, then Pivlab will start with your settings (at least I think it should...)

Tristan Ursell

PS -- I'm sure you get suggestions all the time and I know it's always a lot of effort to make changes, but I have a few and I'm fairly experienced at software construction:

1) make it so one can read-in TIF stacks (as opposed to cumbersome folders full of individual images)
2) put the main operations (loading images, setting up masks, pre-processing and PIV settings, analyze) as foreground buttons, not buried in menu structures
3) once a mask has been drawn, have an option to save that mask to a mat-file, which can then be reloaded in subsequent sessions
4) have preferences files that can be saved, so that one can setup the program as one wants, save that state semi-permanently, and then *not* have to change settings or load settings files, each and every session


Tristan Ursell

Best tool out there PIV + matlab (and to boot, it's free!) Thanks William.

William Sweet

dlut gclx

Andrew Pollock

omid nematollahi male

Hello William
Thanks for the new update. May I ask what is the features of the new update?

William Thielicke

Hi Graham,
it's the fault of this website... It always takes 1-2 days to build the toolbox after I uploaded a new version. Just wait one day and try again.

Graham Belluz

since the new update the program will not add to my documents. i use a school computer where i have to download the app everyday.

Graham Belluz

omid nematollahi male

Hello. Such a great job. It is very helpful.
But I have two suggestion:
1. if it is possible to export all the frame of PIV experiment results in Tecplot as a time-resolved solution. currently, I will put one by one of the ASCI text to Tecplot.
2. If it is possible to add turbulence intensity and other turbulence properties to Tecplot export.

I will appreciate your future update.

William Thielicke

H. Birkan could you give more information on this in the PIVlab forum? Maybe including instructions to reproduce the error?
I just finished another major update, maybe I could include a fix before I release it.

H. Birkan

Experienced the same error with 1.43 also, I guess the error is due to something else that I need to figure out

error using save
error closing file ..<fileName>.. the file may be corrupt

H. Birkan

After version 1.43, I have started to experience the following error when saving the session:
error using save
error closing file ..<fileName>.. the file may be corrupt

So I have started to use the older version, v1.43 does not have this problem


Pragnyadipta Sen

Stefan Grandl

qiwen lin

Philipp Hennes

Hey William,
is it possible to analyse the point of "biggest" movement (time of highest velocity) using your Software?

I have about 1000 specle images of a shear experiment and need to figure out the moment in which the foil we are working with tears apart.

Many Thanks.
Your Software looks amazing.
I will for sure donate something if it can help me...

All the best

neetu tiwari

I use an old version of Matlab 2009.
How to install 'PIVlab.mlappinstall' in system?

siguo long

huifang liu

HI,May ask you a question that how can I receive the data of velocity by PIVlab,thank you



thank you for writing this tool,I use it to analysis my speckle image ,but the effect is poor,I think, maybe I need fix it.

William Thielicke

Everyone please ask your questions in the PIVlab forum!

Ming-Ze Kao

Hi everyone,
May I have a question about how to load image?
When I wanted to load images(tif format) on PIVlab, I met following error message.
Hope someone can help me!!!
Thanks a lot.
Error using image
Image CData must be an m-by-n-by-3 or m-by-n matrix.

Error in PIVlab_GUI>sliderdisp (line 387)
image(currentimage, 'parent',gca, 'cdatamapping', 'scaled');

Error in PIVlab_GUI>loadimgsbutton_Callback (line 891)
sliderdisp %displays raw image when slider moves

Error in gui_mainfcn (line 95)

Error in PIVlab_GUI (line 52)
gui_mainfcn(gui_State, varargin{:});

Error in>@(hObject,eventdata)PIVlab_GUI('loadimgsbutton_Callback',hObject,eventdata,guidata(hObject))
Error while evaluating UIControl Callback

Olja Barbir

Hi lovely people!
I have a small problem and would really appreciate your help.
I have analysed a sequence of frames (movement of ballast particles under certain frequencies) and would really like to obtain the average velocity of my particles (or frames). So - first idea - use the mean vector! This is where my problems started :)
The velocity in all of my analyzed frames is significantly (almost x10²) higher than the velocities shown in my mean vector frame. Does anyone have an idea what could have gone wrong?


Can I have a question ?
How can I make my video applicable to PIV? example images were binary and looks it need some steps to be analyzed.
I'm analyzing moving tracks of clothes in drying machine. and it is unapplicable for raw video frames to PIVlab_GUI.m
please, I beg your help...

jianlin li

William Thielicke

Oh wow, the Matlab website for PIVlab now displays videos directly... That is good, thanks Mathworks!

Xingpao Suo

Cara Burberry

I can't seem to install this correctly on the 2017b version of Matlab. Help!

Takemasa Hasegawa

Ashish Madan

is this compatible with 2017a version?

YL Zhou

Chun-Sheng Wang

Dear all,
I have contributed a parallel version of PIVlab in FileExchange.

Daniele Vigolo

Pooja Suresh


It is so good,and I would like to ask how the use of the PIV toolbox , there are any tutorials?

Sreekanth Madhavan



Can you skip more than 1 image?
For example I want to correlate image A-D, B-E, C-F etc...

Binh Nguyen


Ziwei Xu

Mandar Badve

Is there any limit on number of images that can be loaded? If yes can I increase that?
I have been trying to load 15000 images but image loader is only loading 10000 images.

Harold Fatzinger

Is it compatible with Matlab R2016b?

Aswin Muralidharan

Ferhat Karakas

Juan Camilo Coral

Aswin Muralidharan

I am writing to know if it is possible to read im7(LaVision Davis) images using the readimx package in matlab and use that along with this code? It would be of great help if it was possible

Marc D.

beautiful tool!
thanks for making my Masterthesis great (again)

hakan alper kamiloglu

Linus Schumacher

There is a superfluous space in line 155 of PIVlab_GUI that seems to prevent the default settings being read correctly on linux (but not on mac).

leo huang

how can i download this?

Shahar Grossbard


Oliver Eisermann

Delphine Dullin

E. Cheynet


First of all, thanks for writing and developing this tool! I mask some area that gives me NaNs. When I smooth or interpolate the vector field, these NaNs are replaced with some numbers that I can not distinguish them from the region of my interest. On the other hand, if I don't use interpolation, there are some other NaNs in the original regions. I was wondering is there any way to use interpolation or smoothing with excluding the masked area or I am doing something wrong?!

Bi Dianfang

Nicolas Castro

Please, provide a function that generates cross correlation maps of an user defined interrogation window.

Martin Teich

Sophie Roman

William Thielicke

The latest version is 10 to 30 times faster in processing. See the blog for details!

Melody Hathaway

Rebecca McAlpine


Ryan Baker

Jamie Mullin

William Thielicke

The latest version (PIVlab 1.4beta) is compatible with R2014b (and above, and below). This website will soon be updated with v1.4. Until then, download a copy @

William Thielicke

If you're using Matlab R2014b and considering to work with PIVlab, then please have a look at this post here:

William Thielicke

Dear Aahdi, please, as I mentioned in the e-mail, use the forum for questions, and give more detail, e.g. a drawing or example.
The forum is here:


I got one doubt in piv lab let me clarify please, what is the refererence distance in calibration , if we want to mention from river or any channel.

how frequency is described



i was sent to you through facebook. what is the actual meaning of 'ms' it is the capture time of images or camera specification. my camera gives 8fps. my mail id is




i was sent to you through facebook. my mail id is


William Thielicke

@Aadhi: That sounds like your calibration might be wrong. Did you note that you have to enter the distance in 'mm' and the time step in 'ms' during calibration? If that doesn't fix your problem, you could send me some example images.


hi @ William

here after my analysis i got the u velocity is 0.00025 m/s, but when i did manually in channel i got around 0.205 m/s, in my analysis i used Canon EOS 7D camera is used. here i got the error as 1/1000, please give any one exact explanation.

William Thielicke

@Sidaard: I don't know what file format your ".dat" file should be, but you could export to individual text files by using File -> save -> ASCII-file -> Export all frames


I was wondering how I would acquire individual vector files for all my image pairs.

I tried using DPIV software but I could not get individual .dat files for each of my image pairs. I need individual vector data files to calculate Reynolds stress.

Any helpful information will be greatly appreciated.




how the graphs and velocity maps are saved, i will get a problem in opening ASCII chart when i was save at any location

William Thielicke

@AADHI NARESH: Sorry, but I think I'd be way more fruitful if you'd give details about the problem first.




i have a problem with cross correlation process please give details about that

William Thielicke

@Dimitris: No, that is not really possible. PIVlab needs specific session files with the data organized in a specific way. I'd recommend to redo the analysis in PIVlab.


Is it possible to use the tool only for post-processing, as long as I already have the velocity field?

William Thielicke

@Kristine: There is no possibility to do this in the PIVlab GUI (because the velocity you want to subtract varies with time). But you could export the results to the workspace, measure (take the average of a region) the velocity and subtract it from the results. This can be automated I think.

---> comment nr. 100, yaay! Let's drink an ice-cold bottle of coffee on this!


our camera shaked a bit during one of the recordings. We know that some parts of the images are fixed while recording. Is there a possibility to set these 'fixed parts' as 'zero movement'? So the analysis finally gives the real movement of the moving particles without the shaking of the camera?
Thank you very much!


@William: Ah ha, thanks. That should help me solve my problem.


William Thielicke

@Adam: Yes, y = positive in downward direction, and x positive to the right. 0,0 is in the upper left corner of the input image. The coordinates of the ROI (xstart, ystart, width, height) are given in the ROI panel.


@William: So y is positive in the downward direction (in terms of the image)? From my own tests I think that it is, but I just thought I'd check.

Also, is x=0 y=0 set in the top left corner of the image, or the Region of Interest?

Danke Schön!

William Thielicke

@Adam: Thanks :-D. Concerning your question: It is the top-left corner (this seems to be the standard for image-based data). You can change that only by exporting data from PIVlab and then writing a custom script (shouldn't be that difficult however).


PIVlab is by far and away the best PIV software that I've used, even better than proprietary stuff that wants lots of money for the "full" version!

I have a question: I'm trying to convert Cartesian coordinates to polar coordinates. Where does PIVlab place x=0 y=0? At the bottom left hand corner? Is it possible to change the default location of 0,0? (As this would make converting easier.)


William Thielicke

@Petra: Yes that might work. But then you'll have to select the "A-B, B-C, ..." sequencing style, otherwise you might skip every 2nd image.

Petra S

I changed in the PIVlab_GUI.m in Line 1631 the "filepath{i}" to "filepath{1}".

I think this will do the trick.

Petra S

Thank you for your quick answer.

I would like to do the cross-correlation for a lot of images to the same reference image.

William Thielicke

@Petra: Yes, just select your reference image as "image A" for image pair.

Petra S

is it possible to do the cross-correlation to a fixed reference image?

Many thanks,

William Thielicke

@Joe: What you see is the vector validation between the passes. This doesn't really affect your end result. All vectors of the final pass are "real vectors", they are not interpolated.

@Elizabeth: You need texture in the medium that you want to track. As a rule of thumb: If your eyes can see a movement in the images, then PIVlab will also be able to do a cross-correlation.

@Edouard: I did something similar in my PhD project, but you need to do the calculations in Matlab. I can recommend Paraview for displaying the 3D data.

Dipin K K

Edouard Bahous


I have several PIV images at different cross-sectional angles of an axi-symmetric part and would like to interpolate between each image to create a 3D flow field. Does PIV lab have this capability?

Thank you


I need to construct a kind of flume experiment to measure soil erosion. It seems like this is a great tool to track soil movement. But do I have to use tracers to obtain the streamlines on water?

Joseph Decker

This is really good software expecially for free. I am using this for my senior project in college. I see that while it is running it discards vectors. I would like to run it for a while to get a nice average of vectors but it keeps deleting vectors that seem to be fine. Could you please advise me on where I can disable this feature so that it just dumps out all the raw data without discarding any vectors?



William Thielicke

Hi Roe,
to export the 2D vector data, go to file -> save -> ASCII File or MAT File or Paraview binary VTK (depending on the format you want it to have).
The documentation will be available this summer in my thesis and (hopefully) also in a journal...

Roe Burrell


First, please accept my thanks for developing such excellent software. I am finding is preferable to commercially available PIV programs for my PhD work (of course, you will be cited where appropriate).

My question - I'd like to export the full 2D velocity vector components (u,v). I've seen where I can export u or v along a line under the "Extractions" menu, but is there a function in the GUI to do this for the full 2D vector field over the entire ROI?

Finally, it is mentioned that documentation about the accuracy of the algorithms, etc. may be available by early 2014 pending publication of your thesis. Do you have any further information in this regard?

Many thanks,

William Thielicke

Hi Josephine,
it uses a cross correlation to determine the paticle displacement. You can select "direct cross-correlation" (in the spatial domain) or a "discrete Fourier transform" (in the frequency domain).


Hello, I would like to know what method of determination used PIVlab (
Phase correlation, block-based methods, Differential methods (Lucas-Kanade method, Horn-Schunck method, Buxton Buxton method, Black-Jepson method))
General variational methods, Discrete optimization methods). I write a master's thesis and can not use this code if I do not know what it does exactly.

Thank you in advence,


William Thielicke

Dear Ram, this is the PIVlab comment page and not the PTVlab page. Although the GUI from PTVlab is from our project, I can't help you with the bugs in PTVlab.


Nice code, but I am facing problem during run. When I open image per-prcossing and enable subtract means & click preview current frame then nothing happen. Instead program becomes unable/inactive. I have to shut down PTVLab. Can any one help me?
Thanks in advance!!!

William Thielicke

Dear Petra,
PIVlab uses uipickfiles.m to load the paths and filenames of image data. You could replace this function with a custom function that loads matrices from the Matlab workspace. See the documentation of uipickfiles.m to understand it's data structure.

Petra S

Hi William,

thanks for your great programm.

What I would like to know:
Is it possible to import the images (matrices) directly from the current Matlab-session without saving them to file?

Best regards

David Jessop

William Thielicke

@Uli: Thanks, I'll try not to forget to include it in the next release.

@Tobias: The "area mean flow direction" works on full cells: A cell is included in the average, if more than 50% of its area are within the area that you selected.
The "area mean value" uses exactly the area in your polygon. So this is more precise.


Hey William,
I love your program. It is truly sophisticated and quite easy to work with.
One thing appeared to me, however. If I extract the velocity magnitude from an area, I have two possibilities, right? - through "area mean value" -> "velocity magnitude" and through "area mean flow direction". Though, the results are different. I'm not a matlab-pro so it's hard for me to follow the source-code to where the exact difference is. Maybe you can give me an advice which possibility I could "trust" more ;)
Thanks for everything,

Uli Kleßinger

Dear William,
thanks for the great code.
I just tried it and it works great. However, i think i found a bug which might appear when images contain blank areas:
I then get an error in piv_FFTmulti (line 122).
You might add "~isempty(x) && ~isempty(y)" in that line to solve that problem.


Hi William,
Thank you very much for providing this useful tool. One quick follow-up question to the last user post regarding obtaining the correlation peak. Do we run PIV_FFTmulti.m separately or can it (correlation peaking specifically) be run from the GUI?

William Thielicke

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

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


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.


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.


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.

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,
Error in gui_mainfcn (line 96)
Error in PIVlab_GUI (line 32)
gui_mainfcn(gui_State, varargin{:});
Error in
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?


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

Konstantinos Margaris

Excellent work!

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



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:



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.


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?


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


good job.

Jan Neggers

William Thielicke

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


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


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:
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!


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}


PIVlab_GUI doesn't need start from it''s folder.Just change the Line 105 :

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


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


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


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


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.


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?


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


@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

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.


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



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.


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?


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.


Excellent tool!!!

Extremely user-friendly.
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.


Fantastic work!


William Thielicke

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

Shashi Thutupalli


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


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

Error in ==> PIVlab_GUI>loadimgs_Callback at 592

Error in ==> gui_mainfcn at 75

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

MATLAB Release Compatibility
Created with R2019b
Compatible with R2014b and later releases
Platform Compatibility
Windows macOS Linux

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!