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.
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
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)
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.
Navigate to Analysis -> Analyze! and click Analyze all frames. You will see how the vector resolution increases with every pass.
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.
If you have further questions, please use the forum.