PIVlab tutorial
Updated website on http://PIVlab.de
Video tutorials
In addition to the text tutorial (see below), there are three video tutorials available: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. A bunch of hardware has been developed for PIVlab, so PIVlab can additionally be used to control pulsed light sources (Lasers, LEDs), grab images from a camera, control seeding generators and camera lenses. The following video shows an overview of some of these features. I developed this hardware for OPTOLUTION Messtechnik GmbH, the company I am working for. Hence this hardware can be bought here: https://www.optolution.com/en/products/piv/Setup
The easiest way is to download PIVlab from MATLAB File exchange:
Double-click on the file 'PIVlab.mltbx' to install PIVlab as a Toolbox (with App included) in your MATLAB installation. It will then appear in the 'Apps-Toolstrip' in MATLAB:
Alternatively (the only way if your Matlab release is older than R2015b [8.6]), download the zip file and extract the contents to a new folder in your Matlab work directory. Then run PIVlab_GUI.m.
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.The coordinate system is defined as follows: The standard coordinate system of image data has its origin at the top left. PIVlab uses this coodinate system too. Velocities in the horizontal direction (x) are called 'u' and velocities in the vertical direction (y) are called 'v'. Positive u is top-to-bottom, and positive v is left-to-right. This coordinate system can be adjusted / modified after calibration (see below).
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 uses "tool tips" everywhere. When you would like to see more information on a setting or a parameter, simply hover 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 left side of the screen.
Select the images PIVlab_Karman_01.bmp till PIVlab_Karman_04.bmp that you can find in the PIVlab/Examples folder. Set the sequencing style to 'time resolved' and click Add, then Import.
The images are loaded in PIVlab. The image list on the panel on the left 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 left 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 Image 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. First, you should zoom into this black circle a bit, so it is easier to draw a mask. Click the magnifier icon to enable zooming, then drag a zooming rectangle around the rod:
Click Draw mask(s) for current frame and use the left mouse button to create a polygon mask around the rod. Double click in the center of your mask (or right click, that depends on your Matlab version) to end mask editing mode.
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 Image 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. Always remember to apply your selection by clicking "Apply and preview current frame". The filters will be automatically applied to all frames in your current PIVlab session. You can also move your mouse over the check boxes to see some tool tips with more information on the filters:
PIV settings (optional)
Proceed to Analysis -> PIV settings to setup the cross-correlation for your image data. PIVlab features three different correlation algorithms, DCC (single pass direct cross correlation), FFT window deformation (direct Fourier transform correlation with multiple passes and deforming windows) and Ensemble correlation. The FFT window deformation algorithm is enabled by default, and in most situations, it delivers the best results. By selecting 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 left and right 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. Finally, you need to click 'Apply' to activate the calibration.
Now, you can set up your coordinate system if you like. You can specifiy offsets of the coordinate system (e.g. if you want that the cylindrical rod has the coordinates x = 0 m and y = 0 m). You can also reverse the direction of the coordinate system. Click 'Set x offset', then click at the centre of the rod. PIVlab asks you for the true x position of this point, enter "0" to set the centre of the rod as the origin of your coordinate system. Repeat this for the y-axis. Finally, click 'Apply calibration' again to apply also the offsets.
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/filtering (optional)
Some erroneous vectors might 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 -> Velocity based validation. There are several ways to filter your data. Start by setting velocity limits: Vectors outside of these limits will be rejected. Enable '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:
You should enable the standard deviation filter (set to n = 8) and the local median filter:
Click on Apply to all frames to perform the velocity based validation/filtering. There are additional powerful filters in Post processing -> Image based validation. They do not filter data using the velocity vectors, but they use the raw input images to control filtering. That is why these filters need more computation time and take some time to calculate. You could e.g. suppress vectors in bright regions (e.g. caused by reflections), or in regions that have a low contrast (e.g. shadows or areas without seeding particles). Experiment with the settings if you like:
Finally, click Apply to all frames again and scan through all the frames (by using the slider on the lower left) to check if all data looks good. Interpolated vectors will be displayed in orange. You can also disable interpolation. You should always aim for having only a very small amount of orange vectors, as these are not measured displacements / velocities, but just interpolated data! 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 in the Velocity based validation panel.
Displaying derivatives (optional)
To display the vorticity in the flow, select Plot -> Spatial: 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.
The limits of the colormap can be adjusted (by default, they are calculated automatically for each frame):
You can also calculate the average velocity of several frames:
Navigate to Plot -> Temporal: Derive parameters and click Calculate mean. 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 of the vectors can be set to automatic mode, or vector display may be suppressed. 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:
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.
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 -> Export 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.
Expert example: 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.
