Mpiv Doc
Mpiv Doc
July 2, 2009
1 Brief Introduction
‘mpiv’ is a PIV (Particle Image Velocimetry) toolbox written in MATLAB. The main purpose
of this toolbox is for educational and research. It is intended for both the undergraduate and
graduate students working on PIV methods, or need to use PIV for their study. It is also a
convenient and useful tool for engineers and scientists who use PIV in their research. Writing
the program in MATLAB is, in our opinion, believed to be easier to understand and use,
although it may be slower in computation. The project started in Fall 2002, and since then
several algorithms have been modified and added. Moreover several options have be included
for users of different levels. mpiv has also been tested and proved to be sufficient accuracy
and robust.
There are many PIV programs existing today. Some of the programs are written in
MATLAB and already available to users (e.g., URAPIV and MatPIV). These programs have
excellent capability for research propose and have many options for users of different level and
optimization for fast computation. In comparison, mpiv is more general and portable, and
easy to use and modify. It is the developers’ intention to keep the codes short and simple.
In brief, mpiv consists of two main programs (one for image processing and the other for
post-processing) and several external functions (.m files) while most of them are very short
and are based on simple algorithms. Thus, not only are the algorithms and codes of mpiv
easy to understand for undergraduate and graduate students, they are also quite general and
easy to modify for use in specific research area for engineers and scientists.
The present version of mpiv has the following features:
• Cross-correlation and MQD (Minimum Quadratic Difference)
1
• Free of charge
Note that the earlier versions of MATLAB may work fine as well though we did not test
the program on them, and MATLAB Image Processing and DACE Toolbox are necessary to
run the program. Image Processing Toolbox is the one of Toolbox developed by Mathworks,
while DACE Toolbox (see next section for more details) is a BSD based toolbox and can be
downloaded from http://www.imm.dtu.dk/˜hbn/dace/. In addition, you can use MATLAB
Compiler to reduce computational time, but it is not a must. The original images in this doc-
ument are taken from VSJ-PIV (the PIV Standard Project) distributed by the Visualization
Society of Japan (http://www.vsj.or.jp/).
mpiv has been tested (MATLAB 6.5.0.180913a, R13) on Linux platform running on Vine
Linux 2.6 (http://www.vinelinux.org/), equivalent to Red Hat Linux 7.2, and Microsoft Win-
dows 2000.
mpiv_gui.fig
func_findpeak2.m
func_histfilter.m
func_pivwindowsize.m
func_smooth.m
mpiv.m
mpiv_filter.m
mpiv_gui.m
mpiv_smooth.m
piv_cor.m
piv_crr.m
piv_crs.m
piv_mqd.m
piv_mqr.m
piv_mrs.m
2
vector_check.m
vector_exterp_linear.m
vector_filter_global.m
vector_filter_median.m
vector_filter_vecstd.m
vector_interp.m
vector_interp_kriging.m
vector_interp_kriging_local.m
vector_interp_linear.m
vector_interp_spline.m
vector_interp_NaN.m
image1.bmp
image2.bmp
In the package, mpiv.m is the main program of mpiv for image processing and veloc-
ity computation, mpiv filter.m and other mpiv XXX.m are the programs for post-processing,
piv XXX.m files are the main functions to compute velocity vectors using different algorithms,
and vector XXX.m are the functions to interpolate, extrapolate and validate velocity vectors.
The rest of programs are external functions called by mpiv.m and other programs. All .m
files have to be placed in the same directory or on the path of MATLAB. Two image files
(image1.bmp and image2.bmp) taken from VSJ-PIV Standard Project are for testing mpiv.
mpiv requires DACE (Design and Analysis of Computer experiments) Toolbox. DACE
Toolbox was developed by Hans Bruun Nielsen, Soren Nymand Lophaven and Jacob Sonder-
gaard at Technical University of Denmark. Download the toolbox from http://www.imm.dtu.dk/ hbn/dace/,
unzip it, and put all the files on the path of MATLAB (click on the ‘Set Path ...’ bottom
under ‘File’, or use ‘addpath’ command). After these procedure, you are ready to run mpiv.
Figure 1 shows the calculated velocity vectors using the cross-correlation algorithm with a
64 × 64 pixel window size, one time recursive (reducing the window size by one half) and
50% overlap between adjacent windows. The blue arrows in the figure indicate the estimated
3
0
y axis
10
15
0 2 4 6 8 10 12 14 16
x axis
Figure 1: Result from mpiv filter.m. Error vectors correction and interpolation: blue, original
output; red, interpolated after removing error vectors.
velocity vectors while the red arrows indicate the interpolated velocity vectors that replace
the eliminated spurious vectors by mpiv filter.m.
If your MATLAB version is higher than 6.5 (R13) running on MS Windows system, GUI
menu is available for demonstration.
>> mpiv_gui
GUI menu will be popped up. Please select adequate parameters for velocity estimation.
A typical flow chart for running mpiv can be summarized as follows.
3. Remove error vectors and replace them by interpolation using mpiv filter.m.
3 Basic Principles
The present version of mpiv includes some algorithms and techniques listed below. For more
details of PIV methods users should refer to Adrian (1991), Willert and Gharib (1991), and
Raffel, Willert and Kompenhans (1998).
4
3.1 Correlation Algorithm
The cross-correlation algorithm for PIV is the most conventional method to estimate velocity
vectors. The formula for two-dimensional cross-correlation of images f1 and f2 is as follow:
N X
X N h ih i
f1 (Xi , Yj ) − f1 f2 (Xi + ∆X, Yj + ∆Y ) − f2
i=1 j=1
C(∆X, ∆Y ) = v v (1)
u
uXN X
N h i2 u
uXN X
N h i2
t f1 (Xi , Yj ) − f1 t f2 (Xi + ∆X, Yj + ∆Y ) − f2
i=1 j=1 i=1 j=1
where f1 and f2 are the small windows from each image in the image pair, N is the window
size and the overbar denotes mean quantity. The location of the maximum value (peak) in C
is used as the mean particle displacement of this small area. In the program the calculated
displacement is retained as ‘valid’ only if the ratio of the values of the highest peak to the
second highest peak exceeds a preset threshold value, and the ratio of the values of the
highest peak to the r.m.s.(root-mean-square) noise also exceeds a preset (determine by trial
and error) threshold value.
The location of the minimum value in C is used as the particle displacement. Note that
MQD is sometimes referred as ‘gray level difference accumulation’. The criteria to retain the
calculated vectors is similar to that in the correlation algorithm, i.e., by checking the ratio
of the two highest peaks and the signal to noise ratio of the highest peak.
The accuracy of the cross-correlation algorithm and the MQD algorithm are almost the
same. However, the MQD algorithm may be more robust than the correlation algorithm
in certain situations. For example, the correlation algorithm does not work well for images
containing no particles such as speckle images. However, there is a price to pay - the MQD
algorithm is in general slower than the correlation algorithm.
5
mqd mqd
50 50
100 100
y pixel
y pixel
150 150
200 200
250 250
50 100 150 200 250 50 100 150 200 250
x pixel x pixel
50 50
100 100
y pixel
y pixel
150 150
200 200
250 250
50 100 150 200 250 50 100 150 200 250
x pixel x pixel
Figure 2: mpiv result from the recursive method with the ’cor’ option.
6
interpolate the removed error vectors from the previously obtained velocity field with a larger
window.
Figure 2 shows the estimated velocity vectors using the correlation algorithm (with the
‘cor’ option) with the recursive process. The MATLAB commands are listed below:
The window size started from 64×64 pixels and ended at 8×8 pixels. Similar results can also
be obtained if the MQD algorithm is used (using the ‘mqd’ option in mpiv).
4 Accuracy
To test the accuracy of mpiv, the PIV standard images were used. The images were taken
from VSJ-PIV (case 1 in PIV Standard Project) distributed by the Visualization Society of
Japan (http://www.vsj.or.jp/).
For comparison, figure 3 shows the dependence of the r.m.s. error on different algorithms
chosen in mpiv, and different window sizes used in the process. Basically, there is no significant
difference between choosing ‘cor’ or ‘mqd’ in terms of accuracy. The correlation algorithm is,
however, faster than the MQD method, while the MQD algorithm seems to be more robust
than the correlation method.
Step 1: Select control points For example, here is a orthogonal coordinate images as
’gird.bmp’ and taken calibration images ’calibration.bmp’. Using cpselect, we can relationship
between control points of pair images.
cpselect(’grid.bmp’,’calibration.bmp’)
The control points are landmarks that you can find in both images.
7
0.03
Standard Recursive
MQD:25% MQD:25%
MQD:50% COR:25%
0.025 COR:25%
COR:50%
1
0.02
RMSE [pixel]
0.015
0.01 3
2
0.005
0 10 20 30 40 50 60 70
window size [pixel]
The number of control points depends on which transformation will you used. The ‘pro-
jective’ transformation requires 4 pairs, the linear, second and third order polynomial trans-
formations require 2, 6, 10 pairs. After selection of pairs, please save the data.
Save control points by choosing the ‘File menu’, then the ‘Save Points’ to Workspace
option. Save the points, overwriting variables input points and base points.
Step 2: Making geometric transformation matrix The second step is making geo-
metric matrix as
t_concord = cp2tform(input_points,base_points,’projective’);
cp2tform will find the parameters of the distortion that best fits the stray input points and
base points you picked.
Step 3: Transform Image This is final step to get geometrical correction of distorted
image. imtransform can do that. Note that the choice of ‘XData’ and ‘YData’ values ensures
the registered image will be aligned with the orthophoto.
im1 = imread(’image1.bmp’);
info = imfinfo(’image1.bmp’);
registered = imtransform(im1,t_concord,...
’XData’,[1 info.Width], ’YData’,[1 info.Height]);
You can do Step 1-4 once. After that, t concord can be used repeatably.
The original source of this procedure is written by help of Image Processing Toolbox in
MATLAB. Please look and check in detail as you like.
8
Figure 4: GUI Menu
The C-complied .mex?? format files have higher preference than the original .m format files
when running MATLAB, even if they are both placed in the same directory.
The following is a list of CPU time-consuming functions in mpiv.
func_findpeak2.m
piv_mqd.m
piv_mqr.m
piv_mrs.m
9
piv_cor.m
piv_crr.m
piv_crs.m
vector_filter_median.m
xcorr2.m
The following is an example for running the C-complied mpiv using the sample images:
In this example, the CPU time was reduced from 29.7 second originally to 19.1 second with
the mex files piv mqd.m (on an AMD Athlon 2000+). Using the MATLAB-to-C complier,
mpiv saves 36% of time in comparison to the same MATLAB program without using the
compiler.
We would like to point out that the two-dimensional correlation algorithm in the program
uses the MATLAB function ‘xcorr2’ to compute the cross-correlation function. However,
xcorr2.m in MATLAB does not use fast Fourier transform (FFT) therefore it is relatively
slow. We replaced xcorr2.m to another faster routine for correlation computation applying
FFT, CPU time is found to be greatly reduced (we cannot include this file in the mpiv toolbox
due to copyright issue because it was directly modified from xcorr2.m).
8.1 mpiv.m
mpiv.m is the main routine of mpiv. mpiv.m is an external function (.m file) in MATLAB
with its format as following:
10
-> these two parameter also provide the search area
if ‘mqd’ is chosen
(A large value will increased CPU time dramatically).
dt : time separation between im1 and im2 (unit: second)
use ‘1’ to give output in pixel
piv_type : = ‘cor’: cross-correlation algorithm
= ‘mqd’: MQD algorithm
i_recur : number of recurrence to enhance vector resolution/accuracy
= 0 -> no recurrence
= 1 -> one recurrence with the same window size
= 2 -> reduce window size by one half
each increment (after 1) reduces the window size by one half
i_plot : = 1 -> plot the calculated results
otherwise -> no plot
Please mind the arrangement/orientation of the output arrays and matrices in the programs.
It normally requires matrix transpose for plotting.
11
The filter uses a small area (typically 3×3 to 9×9 vectors) to calculate the mean, median,
and standard deviation, and the number of valid vectors (with values other than NaN) in
the area. The size of the area is determined by a preset threshold value for the number of
valid vectors. The size of the area increases when the number of valid vectors is below this
value. It outputs NaN when reaching the preset maximum size while containing less than
the threshold vector number. In calculating the statistical values (e.g., mean, median, and
standard deviation), the vectors with a value outside the range of twice the r.m.s. value are
not included in the calculation to avoid the influence of these potential bad vectors with large
deviations.
The standard and median filters use the calculated mean, median, and standard deviation
to determine whether the vector of interest (called target vector hereafter) is spurious or not.
If the target vector is within the range of vec std × standard deviation from the mean or
median value (for standard and median filter, respectively), it is then considered as a good
vector. It is otherwise removed from the ‘valid vectors’ and replaced with NaN.
The interpolation is to assign a value for each NaN vectors. Similar to the filter, an
expandable small area is used to interpolate each vector if Kriging method is chosen. Note
that with more than one continuous NaN vectors neighboring to each other, only Kriging
method gives interpolated results (the other two interpolation methods keep NaN in the
output). Therefore the Kriging method is recommended in the filtering process for most
cases. However, Kriging is computational intensive. It may take a significant portion of time
in the PIV processing (if the recursive process is chosen) and post-processing.
The output of mpiv filter.m contains two sets of velocity vectors:
Note that all the error vectors in iu f and iv f as well as in other inputs and outputs throughout
mpiv are denoted as NaN.
12
8.3 mpiv smooth.m
mpiv smooth.m is a post-processing function of mpiv and is an external function (.m file) in
MATLAB with the format as following:
function [ uo ]=mpiv_smooth( ui )
13
11 Contributors to mpiv
1. Dr. D. F. Liang, who found typos in the document and provided comments to the
correlation function (Oct. 4, 2002).
2. Dr. K.-A. Chang, who joined as a major developer since June 2003.
12 References
Adrian, R. J. (1991) ‘Particle imaging techniques for experimental fluid mechanics’, Annual
Review of Fluid Mechanics, vol.23, pp. 261-304.
Raffel, M., C. Willert and J. Kompenhans (1998) ‘Particle Image Velocimetry’, Springer.
Willert, C. E. and Gharib, M. (1991) ‘Digital particle image velocimetry’, Experiments
in Fluids, vol. 10, pp. 181-193.
13 Update History
0.965 2004/12/21 Geometrical correction has been inserted.
0.96 2003/10/08 GUI menu, piv gui.m, has been added. (0.01)
0.95 2003/ 7/02 piv mqd.m(1.00) and piv mqr.m(0.53) are revised. piv mrs.m has been in-
serted. New definition of MMR have been added in func findpeak2.m.
0.93 2003/ 6/26 piv cor.m(0.73), piv crs.m(0.49) vector filter median.m(0.60), vector filter vecstd.m(0.60),
have been modified. func histfilter.m has been inserted.
0.91 2003/ 6/23 piv cor.m (0.66) and piv crs.m (0.46) have been modified.
0.90 2003/ 6/20 piv cor.m and piv crs.m have been modified.
0.82 2003/06/16 piv crs.m and vector interp kriging.m have been modified.
0.80 2003/06/12 Total package has been tuned and refined.. piv crs.m has been added.
Kriging interpolation has been added.
0.70 2003/06/11 Super-resolution PIV with correlation function, piv crr.m has been added.
Smoothing functions have been inserted by KAC.
0.52 2003/04/07 Peak search routines in piv mqr.m and piv mqd.m have been modified
0.50 2003/04/03 Super-resolution PIV, piv mqr.m has been modified. Three new functions
have been inserted and the some functions have been modified.
14
0.31 2003/03/27 piv mqd c.m has been added.
0.30 2002/12/04 piv mqd.m has been simplified and piv cor.m has been added.
14 mpiv is NOT
• Max-Planck Institute Gesellshaft (http://www.virtual-institute.de/)
15