Main Features:
* userfriendly and GUI based PIV tool
* multi-pass, multi-grid window deformation technique
* import bmp/ tiff/ jpeg image pairs/ series
* multiple image sequencing styles
* individual image masking and region of interest
* image pre-processing
* 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
* statistics
* synthetic PIV image generator
* Many data export features
* main features accessible via comand line scripting

PIVlab tutorial

Please ask your questions in the forum!
Preface
PIVlab is an open-source particle image velocimetry (PIV) software that does not only calculate the velocity distribution within 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.

Setup
The easiest way is to double-click on the file 'PIVlab.mlappinstall' to install PIVlab as an 'App' in MATLAB.

Alternatively, you can also setup PIVlab manually by extracting all files of the PIVlab archive to a folder in your MATLAB work directory. The folder should be added to the MATLAB search paths. PIVlab is started by entering "PIVlab_GUI" in the command window (or by running the 'App'). When running PIVlab, your current directory should always be the folder where PIVlab_GUI.m is stored. You can also create a shortcut for PIVlab by adapting the following command:
"C:\Program Files\MATLAB71\bin\win32\MATLAB.exe" -nosplash -minimize -r PIVlab_GUI

General remarks
A "frame" is defined as a pair of images including any derived parameters. Single analyses consist of one single frame (one image pair + results); a time-resolved analysis consists of multiple frames (several image pairs + results). A "session" is defined as a collection of single or multiple frames including any derived parameters and all the settings of the GUI. Sessions can be saved and reloaded in PIVlab.
When creating masks, manually rejecting vectors, selecting areas/ poly-lines etc., the left mouse button performs the desired task, whereas the right mouse button ends this task. The GUI is menu-based; selecting a menu item will change the panel that is displayed on the right hand side. When doing PIV analyses, the work flow should start at the left side of the menu, and continue to the right side.
PIVlab features "tool tips". When you would like to see more information on a setting or a parameter, simply move your mouse over the feature. A tool tip will appear and give you more detailed information.

Example: Analyzing a series of images
This example will show you how to process a series of image pairs. Some of the possibilities of PIVlab will be demonstrated.

Import images (required)
First, load some images by selecting File -> New session. Click Load images in the panel that appears on the right side of the screen. Select the images PIVlab_Karman_01.bmp till PIVlab_Karman_04.bmp that you can find in the PIVlab folder. Set the sequencing style to 1-2, 2-3, 3-4, ... and click Add, then Import. The images are loaded in PIVlab. The image list on the panel on the right side displays the images that you selected. The letters 'A' & 'B' denote the first and the second image of one image pair (= one "frame"). In the lower right corner, you will find a slider to navigate through all frames, and a button (Toggle A/B) to toggle between the individual images within one frame.

Setting a region of interest and a mask (optional) 
In the menu, continue to Analyses settings -> Exclusions (ROI, Mask). If you want to analyze the whole image, you don't need to set a region of interest. Additionally, you can apply a mask to exclude areas in the image from the analysis. In this particular image, a mask should be applied to exclude the dark object (a cylindrical rod) from the analyses. Click Draw mask(s) for current frame and use the left mouse button to create a circular mask around the rod. Double click in the center of your mask (or right click, that depends on your Matlab version) to end editing mode. Note that you can use the zoom button (lower right corner) to magnify the rod before drawing the mask. Because the cylindrical rod doesn’t move from one frame to the other, you can apply the mask to all frames of the current session by clicking Apply current mask(s) to frames... 1:end. You can always draw more than one mask if necessary, just click again on Draw mask(s) for current frame.

Image pre-processing (optional)
PIVlab offers a number of image pre-processing techniques, that can significantly enhance the quality of your analyses. Click on Analyses settings -> Image pre-processing. Contrast-limited adaptive histogram equalization (CLAHE) is enabled by default. This filter locally enhances the contrast in the images. The other pre-processing filters can be handy as well, but will not be used in this example. Move your mouse over the check boxes to see some tool tips with more information on these filters.

PIV settings (optional)

Proceed to Analyses settings -> PIV settings to setup the cross-correlation for your image data. PIVlab features two different correlation algorithms, DCC (single pass direct cross correlation) and FFT window deformation (direct Fourier transform correlation with multiple passes and deforming windows). The latter algorithm is enabled by default, and in most situations, it delivers the more accurate results. Using this algorithm, your data will be analysed in several passes: The first pass uses relatively large interrogation areas to calculate the displacement of your image data reliably. The larger the interrogation areas, the better the signal-to-noise ratio, and the more robust is the cross correlation. But large interrogation areas will only give a very low vector resolution ("vectors per frame"). That is why you should decrease the size of the interrogation windows in the following passes. The displacement information of the first pass is used to offset the interrogation areas in the second pass and so on. This procedure yields a high vector resolution, a high signal-to-noise ratio, and a high dynamic velocity range. The interrogation areas of later passes are not only displaced, but they are also deformed. Read my paper for more information on this.
The general recommendation is to use about three passes (the more passes you use, the better will be the result, but it will also take a while to compute...). Start with big interrogation areas (e.g. 128 pixels) and decrease gradually in the following passes (e.g. 64 pixels in pass 2, 32 pixels in pass 3). You don't need to use 'power of two' numbers for the size of the areas (this is because MATLAB uses FFTW for the correlation, and that can handly arbitrary sizes). Now, everything is ready for the PIV analysis.
One further general remark on the choice of the interrogation area size: In a number of publications that use PIVlab for research, I noticed that extremely small interrogation areas are used in the last pass. While this will increase the resolution of the vector map, it will also significantly increase noise and the amount of erroneous correlations. In many cases, high vector map resolutions are not really important. Think about this and make the interrogation areas as large as possible: You will get more accurate and more reliable results.


Analysis (required)
Navigate to Analysis -> Analyze! and click Analyze all frames. You will see how the vector resolution increases with every pass.

Calibration (optional)

You can calibrate (tell PIVlab how many pixels are one meter, and the time step between the images of one frame) whenever you want, but it is wise to do it before validating the data (see next step). Until now, the units in PIVlab are "pixels per frame": Click on a vector to have its "velocity" and coordinates displayed in the lower right corner of the program (Current point: u: xxx [px/fr] etc.)
The units can be converted to real-world units by navigating to Calibration -> Calibrate using current or external image. Usually, you would now load your calibration image (forgot to record the calibration...? Uhoh...), then click on two points with a known distance within that image. But in this example, we don't have a calibration image - someone forgot to record it. However, the calibration can also be done by using the currently displayed image: Click Select reference distance and click on the upper and lower edge of the cylinder. Now, you can enter the real diameter of the cylinder in the field Real distance [mm] (the diameter was 30 mm) and the time step in time step [ms] (the frame rate was 400 Hz = 2.5 ms). The precision of this kind of calibration is pretty low, so external calibration images should really be used. If you again click on some vectors, the velocity will be displayed in real units (m/s). The free flow velocity in this experiment was around -0.2 m/s (the negative sign means that the flow is from right-to-left).

Data validation (optional)
Some erroneous vectors will show up due to poorly illuminated regions in the image or strong out-of-plane flow. They can be removed and interpolated by selecting Post processing -> Vector validation. There are several ways to filter your data. Start by setting velocity limits: Vectors outside of these limits will be rejected. Click on display all frames in scatterplot to display all vectors of all frames of the current session in the following step. Then click Select velocity limits. Draw a rectangle (click + hold left mouse button and drag the mouse) over the vectors that you would like to keep. Additionally, you can enable the standard deviation filter (set to n = 9). Then click on Apply to all frames to perform the validation. Scan through all the frames (by using the slider on the lower right) to check if all data looks good. Interpolated vectors will be displayed in orange. You should aim for having only a very small amount of orange vectors. If there are remaining erroneous vectors, try changing the velocity limits, or the other validation filters. You can also reject individual vectors by clicking Manually reject vector. Then click on the bad vectors, end manual validation by clicking the right mouse button. Apply the validation by clicking Apply to current frame.

Displaying derivatives (optional)
To display the vorticity in the flow, select Plot -> Derive parameters/ modify data. Select Vorticity in the upper pop-up menu. You can smooth the data by enabling the check box next to Smooth data and dragging the slider a bit to the right. You can change the frame of reference by subtracting the free flow velocity from all vectors. In Subtract flow, enter "-0.2" in u [m/s], and click Apply to all frames. You can also calculate the average velocity of several frames. In Calculate means, enter "1:end" in the field Used frames to calc mean and click Calculate mean vectors. Now, an additional frame will be automatically added to your session. It contains the mean velocity field. All masks of the frames you used to calculate this average will be combined. Vectors will be orange in the average frame, if more than half of the original vectors at that spot were interpolated before.


Modifying plot appearance (optional)
The scaling of vectors can be modified by selecting Plot -> Modify plot appearance. The scaling can also be set to automatic mode. You can enable a color bar when you want to have a reference for the colors displayed e.g. by vorticity. Additionally, you can change the colors of the vectors, and have only every nth vector plotted.

Further processing (optional)
PIVlab features a number of data processing options. Here are some examples: To have a look at the u-velocity profile behind the cylinder, go to Extractions -> Parameters from poly-line, select u component from the pop-up menu and click Draw! to draw a vertical line behind the cylinder. Clicking Plot data will open a new window that displays the u-velocity along that line and also the integral of the that u-velocity. You can also draw circles (by setting Type: to Circle) around vortices and plot the tangential velocity.



Parameters from user-selected areas can also be derived. Click Extractions -> Parameters from area, select Velocity magnitude and click Area mean value. When drawing an area behind the cylinder, you can derive the average velocity magnitude behind the cylinder.

Data export (optional)
Data can be exported to a number of formats, image types, movies and also to the Matlab workspace. Have a look at File -> Save for the options.
If you often do analyses with similar settings, you can save your preferred PIVlab settings by selecting File -> Save -> Current PIVlab settings. If you decide to save the current session, please notice that the source image files are not included in the resulting MAT file! Only the absolute file paths of the images are stored.

This is the end of the PIVlab tutorial and only a small amount of all the possibilities could be shown. Please leave a comment if you have problems during analysis, or if you would like me to explain further features.



Calculating the circulation of a vortex in PIVlab
PIVlab features the possibility to calculate the circulation of a vortex by integrating tangential velocity of a path around the vortex. Choosing the optimal path is often problematic. For a Rankine vortex, the circulation increases with radius inside the rotational core, and stays constant outside the vortex core.
 The optimal path for the integration of tangential velocity is hence the boundary of the vortex core. In real vortices, the vortex core is sometimes hard to identify (due to dissipation caused by viscosity and the limited resolution of PIV). Therefore, PIVlab can calculate the circulation for a series of paths with increasing diameter, the maximal circulation will be found close to the boundary of the vortex core.
To calculate the circulation of a vortex, follow these steps: Analyze your image pair, and let PIVlab display vorticity. Go to Extractions -> Parameters from poly-line, and select Tangent velocity as parameter and Circle series as type. Click Draw!, then click into the centre of the vortex, and then again somewhere outside of the potential vortex core. PIVlab will draw a series of 30 circles with increasing diameter.
Next, click Plot data to make PIVlab calculate the circulation of each circle. A new plot will appear with circle diameter on the x-axis and circulation on the y-axis. Maximal circulation will be found at the boundary of the vortex core. PIVlab also highlights the circle with maximal circulation in blue. You can also click on the points in the circulation plot to highlight the corresponding circle in the main window.



If you have further questions, please use the forum.