NAME
gpiv_rr - interrogates an image (pair) in order to obtain displacements
of particles for (Digital) Particle Image Velocimetry (PIV)
SYNOPSIS
gpiv_rr [--cf int] [--cl int] [--cp int] [-g] [--gauss] [-h | --help]
[--ifit 0/1/2/3] [--ischeme int] [--ia_size_i int] [--ia_size_f int]
[--ia_shift int] [--linec int int int] [--liner int int int] [-o] [-p |
--print] [--peak int] [--p_piv] [--point int int] [--rf int] [--rl int]
[--rp int] [-s float] [--spof] [-v | --version] [--val_r int] [--val_s
int] [--val_t float] [filename] < stdin > stdout
DESCRIPTION
gpiv_rr interrogates an image or image pair that is obtained from a
fluid flow by the so-called Digital Particle Image Velocimetry (DPIV)
technique. Therefore, image(s) are sub-divided into interrogation areas
on a rectangular grid. At each interrogation area the mean (or most
probable) particle displacement is estimated. This is done by
correlating the belonging interrogation areas of an image-pair by means
of the Fast Fourier Transformation (FFT) technique, resulting into a
two-dimensional correlation function. The location of the highest
function peak, then, represents the mean or most probable displacement
of the particle images that have been resident within the interrogation
areas. Estimation of the correlation peak at sub-pixel level may be
calculated by different interpolation schemes. The program allows
cross-correlation of single-exposed images on different frames or auto-
correlation of a multi-exposed single-frame image. Interrogation areas
of arbitrary sizes may be used in order to obtain an optimum spatial
resolution. Adaptive sizes of interrogation areas allow for large
dynamic ranges of the particle displacements. Zero offsetting of the
interrogation areas by an iterative interrogation process results into
higher accuracy/lower biases of the particle image displacements. A
central differential interrogation scheme than might be applied. This
may result into improved estimators, compared with the ’classical’
forward interrogation scheme, especially in case of strong shear strain
and vorticity of the flow. Most accurate results, however, are obtained
by deforming the images towards each other by using the PIV estimators.
As a convergence criterium for these iterative procedures, the
cumulative difference (defined by GPIV_CUM_RESIDU_MIN = 0.25) between
the PIV estimators from the current and the previous iteration is used.
After each interrogation the PIV estimators are validated. Before
outliers are substituted as defined by the VALID parameters, it will be
tried if the PIV estimator from the second or third highest correlation
peak will be valid.
gpiv_rr is fed with images of the following formats: Portable Network
Graphics (filename.png), raw binary data (filename.r) that is
accompanied by an ASCII header file (filename.h), HDF5 (filename.hdf),
tif, gif, pgm, bmp and LaVision’s (tm) uncompressed image format
(filename.img). For cross-correlation the second image frame has to be
concatenated after the first one into a single image file. This might
be performed by gpiv_combing. Image parameters are read from the header
or from other parameter resources (containing the key IMG) in case they
are absent in the image header.
The configuration parameters (containing the EVAL or VALID) key may be
overruled by the command line options, as explained below.
Options
--cf N Specify the first column N in the image to interrogate. If
--ad_int has been used, the first column has to be equal or
larger than (int_size_2 - int_size_1)/2.
--cl N Specify the last column N in the image to interrogate.
--cp N Pre-shift of N columns. This can be used if there is a common
mean flow in x-direction in the area of observation. Relative
small interrogation areas (allowing a high spatial resolution)
may be used in that case with conservation of a high probability
in finding the correct displacement peaks.
-g Graphic visualisation of the output with gnuplot. Can only be
used in combination with filename).
--gauss
Gauss weighting of interrogation area to reduce high spatial
frequency signal generated by the boundaries.
-h | --help
Print a help message on standard output and exit successfully.
--ifit 0/1/2/3
Three-point interpolation model for peak maximum estimation at
sub-pixel level. 0: none, 1: Gauss, 2: Parabolic or 3 Center of
Gravity.
--ischeme 0/1/2/3/4
Interrogation scheme: no correction (0),
linear kernel weighting (1); This is applied to the calculation
of the correlation function; the weighting of the image data
decreases towards the edges of the interrogation region. Kernel
weighting compensates this effect. Will be disabled if
interrogation area size of image 2 differs from image 1.
zero offset (2); Searches (iteratively) the correlation peak by
zero offsetting the interrogation area’s, until the peak maximum
lies between (-1,-1) and (1,1). The images are interrogated by
the ’classic’ forward differential scheme. During the last
iteration step, sub-pixel displacement will be calculated as
defined with -ifit.
Zero offset with central differential (3); The images are
interrogated by the central differential scheme. This is done by
displacing the interrogation area of the first image with half
the (integer) magnitude of the pre-shift value in negative
direction and displacing the interrogation area of the second
image in positive direction (of identic magnitude).
Image deformation (4); The images of a pair are deformed
following the particle displacements obtained from the initial
PIV estimators or from the previous iteration step. The first
image is deformed in positive direction with half the (float)
magnitudes of the estimators and the second image in negative
direction. In this way, both deformed images will show the
particle positions at the moment in-between the recordings.
After the iteration has been converged and -p option has been
used, the deformed images are stored (defined by
GPIV_DEFORMED_IMG_NAME = gpiv_defimg) in TMPDIR (/tmp for UNIX-
like systems), which may be used as a check.
--ia_size_i N
Initial size of the interrogation area’s N. N must be equal or
larger than ia_size_f.
The sizes must be choosen in such a way that the particle
displacements remain within 1/4th of the interrogation area’s in
order to keep the in-plane errors at minimum.
Choosing larger sizes of the initial interrogation area’s allows
high dynamic ranges of the estimators. In that case, the largest
particle displacements may contribute adequately to the
calculation of the estimators, while the estimators of the
smallest flow scales are not smoothed by the large, initial,
dimensions of the interrogation area’s. The dimensions of the
interrogation area’s of the first and second image start with
ia_size_i. For each next image interrogation, the sizes will be
halved until they will be equal to the final ia_size_f value.
The estimator will be used as a local pre-shift (zero
offsetting, as defined by --ischeme). In case ia_size_f and/or
ia_size_i is not a power of two, the sizes of the interrogation
area’s will be reduced with the appropriate factor during the
last (iterative) interrogation in order to set them equal to
ia_size_f. During the last interrogation, the estimator will be
between (-1,-1) and (1,1). Then, sub-pixel displacement will be
calculated as defined by --ifit.
--ia_size_f N
Final size of the interrogation area’s N, expressed in pixels.
May be chosen arbitrarily.
--ia_shift N
Shift of adjacent interrogation areas N, expressed in pixels.
--linec COL RF RL
selects a vertical line at column COL to interrogate from the
first row RF to the last row RL
--liner ROW CF CL
selects an horizontal line at row ROW to interrogate from the
first column CF to the last column CL
-p | --print
Print parameters, command line options, progress of calculation
and eventually used input and output filenames to stdout. The
output is identic of filename.par, in case -f is used.
--peak N
Find the N-th maximum of the correlation peak. In case of auto-
correlation, the second peak is taken by default, as the first
peak denotes the zero-shift of the particle displacements.
--p_piv
Print the piv results to stdout, even if -f has been specified.
--point COL ROW
Select a single area in the image to interrogate at location COL
ROW. This option might be useful for substitution of erroneous
displacement vectors. A new estimation of the particle
displacement with --peak, then, may give a correct result. Mind
to use --p_piv if -f is used; else the original data file will
be overwritten with a single point analyses.
--rf N
Specify the first row N in the image to interrogate. If -ad_int
has been used, the first row has to be equal or larger than
(int_size_2 - int_size_1)/2.
--rl N Specify the last row N in the image to interrogate.
--rp N Pre-shift of N rows. This can be used if there is a common mean
flow in y-direction. Relative small interrogation areas
(allowing a high spatial resolution) may be used in that case
with conservation of a high probability in finding the correct
displacement peaks.
-s S Scale factor for graphical output with gnuplot. This will only
affect the length of the vectors that represent the particle
image displacement magnitude, but not the PIV data itself. In
order to adapt the scaling of the data, see gpiv_scale.
--spof Applies symmetric phase only filtering. This option may
drasticly improve the SNR with higher and thinner covariance
peak. Especially usefull when there is flare or high reflections
(from boundaries, for example) in one of the two image frames
from a PIV image pair. (Werner, Meas. Sci. Technol., 16,
601-618).
-v | --version
Print version information on standard output then exit
successfully.
--val_r N
Validation parameter to define residue type: Signal to Noise
Ratio (N = 0), median value from surroundings (N = 1) or
normalised median (N = 2).
--val_s N
Validation parameter to substitute an erroneous vector by:
nothing (N = 0), local mean from the surroundings (N = 1), the
median of the surroundings (N = 2) or the estimation from the
next highest correlation peak (N = 3).
--val_t F
Validation parameter representing the threshold value (float
number) of residues to be accepted.
filename
Using the full filename of the input image overrides stdin and
stdout. Output will be written to filename.piv. Parameters are
stored in filename.par and may be used for future use by
including them in ./gpivrc. If stdin and stdout are used, the
input is expected to be a PNG formatted image.
SEE ALSO
gpivtools
NOTES
gpiv_rr has been tested with artificial images and with PIV images from
gas and liquid flows. Comparison with PIV data, obtained from different
algorithms, and with literature results that similar data reliability
and accuracy may be obtained with this program.
AUTHOR
Gerber Van der Graaf
BUGS
The program seems to work fine. Though as the PIV technology itself is
subject of research, this program is constantly under development.
3 November 2006