Tutorial / Particle Image Velocimetry

Open again the first example of image pair in UVMAT_DEMO01_pair. (accessible on ​http://servforge.legi.grenoble-inp.fr/pub/soft-uvmat/).

Starting PIV

Visual check

Particle Image Velocimetry (PIV) measures the displacement of features in a pair of images. Visual evidence of feature displacement between the two images is a prerequisite for the success of the computation. To observe this motion, write the file indices 1 and 2 in the boxes [i1] and [i2] respectively, in the frame [File Indices] on the left. Then push the red button [<-->] in the frame [Navigate], see figure. The image then alternatively switches from 1 to 2. The speed of motion can be adjusted with the slider [speed]. Press [STOP] to stop the motion.

Launching PIV

The PIV computation is accessed from uvmat by the upper bar command [Run/PIV], or from series by selecting the function civ_series. The name 'CIV' means Correlation Imaging Velocity to stress that the method relies on image correlation, which evaluates the displacement of image textures, not necessarily from particles. Note that an older GUI 'civ' is also available, but it is obsolete and not used here.

A new GUI 'civ_input' now appears. In the menu [ListCompareMode], keep the default option 'PIV'. Keep also the default option 'Di=0|1' for the image pair (menu tag [!ListPairCiv1]). Keep also the default parameters in the frame CIV1 and press OK.

The PIV operation depends on several parameters, but the default values proposed by the GUI provide a good first approach in many cases. Press [RUN] to get the result. The button is then colored in grey until the computation is finished. The operation produces a file with format netcdf, extension .nc, in a subdirectory called 'CIV' by default. The file name ends with index string '_1-2' indicating that it results from images 1 and 2. The file name and its status is indicated in a new figure civ_status. Press the file name to open it with uvmat, or use the browser of uvmat.

Monitoring PIV results

Visualizing the velocity fields

In 'uvmat' velocity vectors are displayed in the central window, while the histograms of each component are in the lower left windows, see Fig. [uvmat_fig]. The arrow length is automatically set by default. It can be adjusted by the edit box [VecScale] in the frame [Vectors] on the right hand side.

The vector color indicates the quality of the image correlation maximum leading to each vector, blue is excellent, green average, red poor. The thresholds for such color display can be adjusted from 0 to 1 (perfect image correlation) in the frame [Vectors], using the boxes [!ColCode1] and [!ColCode2], or equivalently by the corresponding sliders [Slider1] and [Slider2] .

The black color indicates warning in the PIV calculation process. In this example, black vectors are indeed located on the edge, in zones outside the area of flow visualisation (this display can be desactivated by unselecting the box hide warn (tag [CheckHideWarning]) in the frame Vectors).

The position (x,y) and velocity components (U,V) can be displayed in the upper right text display window by moving the mouse over it. The correlation 'C' and warning flag 'F' are also indicated. The warning flag is equal to 0 for good vectors while non-zero values indicate different cases of calculation problems.

Histograms

The global histograms of the vector components are available in the lower left windows. Histograms limited to a sub-region can be extracted by the menu bar tool [Projection object], selecting either [rectangle], [ellipse] or [polygon] to define the sub-region (see projection objects)

Profiles

The velocity profile along a line can be obtained by creating a line with the upper menu bar [Projection object/line], like for image luminosity (see projection objects). Press (and release) the left hand side mouse button, draw the line, and pres it again for the end of the line. The transverse and longitudinal velocity components along this line are then plotted in a new figure view_field.

Other vector color representations

Vector color can also represent another quantity, as chosen in the menu [ColorScalar] in the frame [Vectors]. For instance the vector length 'norm(U,V)' can be used. Then a color continuous 64 color code is appropriate, as set in the menu [ColorCode]. The color codes values between the valuies set by [MinVec] and [MaxVec].

Derived fields

Other field representations are available, selected in the menu [Fields] at the top of the GUI. For instance the option 'u' provides a (false) color map of the x wise velocity component. A contour plot can be obtained instead of a color map by selecting the option 'contour' in the menu [ListContour] in the frame [Scalar] . Then select the contour interval, for instance 0.5. The result is shown in the following figure.

To get the vorticity field, 'vort' , and other spatial derivatives, you need to come back to the GUI CIV, select the check boxes [FIX1] and [PATCH1] , and press [RUN]. This will produce an interpolated velocity field and their spatial derivatives in the same netcdf file. After this operation vorticity can be visualized in the GUI uvmat, selecting the option [vort] in the popup menu [Fields]. The color code can be adjusted by the edit box [MinA] (saturated blue color below this value) and [MaxA] (saturated red color beyond this value).

Superposing image and vectors

It can be useful to visually superpose the images to the velocity field. This is done by selecting the option 'image' in the popup menu [Fields_1], located just under the popup menu [Fields] in the upper frame [Input]. To remove the image, select the blank option in [Fields_1] .

Similarly, the velocity vectors can be superposed to the vorticity field, selecting [vort] in [Fields_1] instead of [image .

From pixel displacement to velocity

So far all PIV results have been expressed as image displacement expressed in pixels. Conversion to velocity requires geometric calibration and timing information. Calibration is described in geometric calibration. The result of calibration is stored in an xml file.

The time interval between the two images, Dt=0.02 s, must be introduced in this xml file by adding a section <Camera>, using a text editor:

<ImaDoc>
  <Camera>
           <TimeUnit>s</TimeUnit>
           <BurstTiming>
                   <Dti>0.02</Dti>
                   <NbDti>1</NbDti>
           </BurstTiming>
  </Camera>
</ImaDoc>

This input is preferably introduced automatically by the computer which controls the camera, or for videos, directly encoded in the movie file.

When this xml file is present in the image directory, the time of each frame (with t=0 by default at the first frame) is displayed in the box [time] of the Input frame at the top right of the GUI. The velocity field is then displayed in terms of physical velocity. To come back to the image coordinates, use the box [transform_fct] on the left : select to blank or ’px’ instead of ’phys’.

Note that the netcdf file has not been by changed by calibration, whose rescaling is introduced after reading the file. This means that calibration can be provided, and possibly updated, after the PIV processing.

The main PIV parameters

The first parameter to adjust is the time interval between images, which should be sufficiently long to provide a displacement of a few pixels. The measurement precision is typically 0.2 pixel, so that a displacement of 4 pixels, as in the example, provides a relative precision of 5 %. A larger displacement would be preferable in terms of precision but may yield to poor image correlation and ’false vectors’.

Once the image pair has been chosen, the main parameters are the size of the correlation box in both directions ([Bx], [By]) and the size of the search box, ([SearchX],[SearchY]), expressed in pixels. For each velocity vector, the correlation box is moved within the search box to optimise the image correlation between the two sub-images inside the correlation box. To allow for a displacement of d pixels, the search box size must exceed the correlation box by at least d+2 on both sides, so 2d+4. A systematic shift [ShiftX],[ShiftY] can be also introduced to minimise the search area in the presence of a mean flow.

The parameter [Rho(image)] is used to fit the correlation data with a smooth function to obtain the maximum with sub-pixel precision. We generally keep the default value 1.

The parameters [Dx] and [Dy] define the mesh of the measurement grid, in pixels. Reduce them to get more vectors, but keep in mind that the spatial resolution is limited by the width of the correlation box.

The PIV operation is conveniently visualised by pressing the button [TEST_civ1] in the GUI civ. Then the image appear in a new GUI view_field, in which the mouse motion displays the correlation function, which appears in a secondary window, see figure. The resulting vector is shown as a line pointing to the correlation maximum. The corresponding correlation and search boxes are shown in the image. Let us run again PIV with Search x,y=(31,31). Many black vectors are obtained...

Masks

Spurious vectors are observed outside the fluid domain, which particularly disturbing when spatial derivatives are calculated.

This can be avoided by using a mask, which is an image of the same size as the images used for PIV. Grey color in the mask indicate regions excluded from measurement.

To produce the mask, first create a polygon by the menu bar command [Projection object/mask polygon]. Draw the mask with the mouse by moving around regions to exclude. Left mouse button to initiate the plot and produce new boundary points, press right hand button to finalise the polygon. By default mask is set inside the polygon, but it can be made outside by selecting the option ’mask_outside’ in the menu [ProjMode] of the GUI set_object.

Then the mask itself is produced by the menu bar command [Tools/Make mask]. The corresponding image is then displayed and stored by default in the directory of the initial image. Note that if several mask polygons have been initially created, as listed in [ListObject] (bottom right of the GUI uvmat), they will be merged as dark regions in the resulting mask (useful in case of multiple ’holes’).

The mask image can be seen as a mask by selecting [view_mask] at the upper left of the GUI uvmat. For checking purpose, it can be also opened by the browser of uvmat like any image. In the GUI civ, the mask is introduced by the selecting the green check box [Mask]. Vectors under the mask are not calculated in the resulting velocity data.

Refined PIV

To improve the results, come back to the GUI CIV, and follow these successive steps, corresponding to a sequence of operations. Optimizing the Civ1 parameters

Select the [CIV1] check box so the corresponding parameters show up. Improve the spatial resolution by selecting smaller correlation boxes in the civ1 menu, for instance [Bx],[By] to 19 and 13 (image pixels). This is possible because of the good image quality and high particle density. The use of a smaller box in y allows to optimize the resolution in this direction, to deal with the strong vertical shear. It is now possible to adjust the search range, using knowledge on extremal velocities, see histograms displayed by uvmat in phys coordinates. We introduce estimated bounds on each velocity component, [min] to -2 and [max] to 6 for ’u’ and (-3, 3) for ’v’, and press the button [Search Range]. The optimum search ranges and shifts are now displayed. In consistency with higher resolution, we set the grid mesh to [Dx] and [Dy] to 10. Finally select the Mask option : the mask name should be displayed in the corresponding edit box, else a browser leads to the appropriate mask file.

FIX1

Select the ’FIX1’ operation, which eliminates some false vectors using several criteria. Use the default parameters.

PATCH1

Select the ’PATCH1’ operation, to interpolate the vectors on a regular grid and calculate spatial derivatives. Select a high resolution [nx]=100, [ny]=30, number of grid points in which the velocity will be interpolated. These values correspond to dx=dy=10 pixels for an image 1000x300. Choose the default value 10 for the smoothing parameter ’rho’. You can later try different values, the smoothing effect increasing with rho. Keep the default values for the other parameters.

CIV2

Select the ’CIV2’ operation to improve the correlation results, using the information on local image deformation, provided by the previous knowledge on velocity spatial derivatives (calculated in patch1). Use a finer grid dx= dy=5 than for civ1. The spatial resolution can be slightly improved by decreasing the correlation box, using for instance Bx,By=(15,11). The search range is determined automatically using the prior knowledge on velocity, obtained with the civ1 and patch1 operations. Note that ’civ2’ corresponds to a new measurement from the images, the previous civ1 and patch operations being used only as an initial guess for the search of optimal correlations.

Then select ’FIX2’ and ’PATCH2’ with the same parameters as ’FIX1’ and ’PATCH1’.

Running the calculation

Press [RUN] to run the calculation. The results are stored in a new subdirectory, CIV_1, so the previous results are not erased (you can also set the name of the subdirectory in the GUI, by the edit boxes [SubDirCiv1] and [SubDirCiv2]. The existing subdirectories are listed above.

The status of the calculation is displayed in a new window which refreshes automatically. Close it to avoid blocking of new Matlab operations. This status window can be opened again by pushing the button [STATUS] in the GUI civ. Do not close civ until the calculation is finished.

The parameters of a CIV computation are stored in a xml file with extension ..CivDoc?.xml created in the directory containing the velocity files. These parameters can retrieved, opening this xml file with the browser of the GUI civ. Then the image file itself needs to be opened (the select again the check boxes for the operations beyond civ1 hidden by default).

The result can be improved again by performing a third civ iteration, civ3. For that purpose, select only the ’civ2’, ’fix2’ and ’patch2’ operations with the same parameters as previously. The previous result is now considered as ’civ1’, so set CIV as the subdirectory in the edit window [SubDirCiv1]. Select a new subdirectory name, for instance ’CIV3’ in the edit window [SubDirCiv2]. Further iterations could be similarly performed, but the improvement becomes negligible.

The following figure shows the final vorticity field, in which the vorticity roll up in the wake of the sphere is clearly visible. A zoom near a vortex shows the vorticity superposed with velocity vectors.

Fix and patch

Civ2

Civ3