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 inte
rrogates 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 chosen 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 useful 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.