added 'Substitute all FNAME occurrences' option

[gpivtools.git] / man / gpiv_rr.1

.TH GPIV_RR 1 "3 November 2006"
.SH NAME
gpiv_rr \- interrogates an image (pair) in order to obtain displacements of particles 
for (Digital) Particle Image Velocimetry (PIV)
.SH SYNOPSIS

\fBgpiv_rr\fP 
[\fB--cf \fIint\fR] 
[\fB--cl \fIint\fR] 
[\fB--cp \fIint\fR] 
[\fB-g\fR] 
[\fB--gauss\fR] 
[\fB-h\fR | \fB--help\fR]
[\fB--ifit \fI0/1/2/3\fR] 
[\fB--ischeme \fIint\fR] 
[\fB--ia_size_i \fIint\fR] 
[\fB--ia_size_f \fIint\fR] 
[\fB--ia_shift \fIint\fR]
[\fB--linec \fIint\fR \fIint\fR \fIint\fR] 
[\fB--liner \fIint\fR \fIint\fR \fIint\fR] 
[\fB-o\fR]
[\fB-p\fR | \fB--print\fR] 
[\fB--peak \fIint\fR]
[\fB--p_piv\fR] \
[\fB--point \fIint int\fR] 
[\fB--rf \fIint\fR]
[\fB--rl \fIint\fR] 
[\fB--rp \fIint\fR] 
[\fB-s \fIfloat\fR] 
[\fB--spof\fR]
[\fB-v\fR | \fB--version\fR] 
[\fB--val_r \fIint\fR] 
[\fB--val_s \fIint\fR] 
[\fB--val_t \fIfloat\fR] 
[\fIfilename\fR] 
< \fIstdin\fR > \fIstdout\fR

.SH DESCRIPTION

\fBgpiv_rr\fR inte\fIrr\fRogates 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 \fBVALID\fR parameters, it
will be tried if the PIV estimator from the second or third highest
correlation peak will be valid.

\fBgpiv_rr\fR is fed with images of the following formats: Portable
Network Graphics (\fIfilename\fB.png\fR), raw binary data
(\fIfilename\fB.r\fR) that is accompanied by an ASCII header file
(\fIfilename\fB.h\fR), HDF5 (\fIfilename\fB.hdf\fR), \fBtif\fR,
\fBgif\fR, \fBpgm\fR, \fBbmp \fRand LaVision's (tm) uncompressed image
format (\fIfilename\fB.img\fR). 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 \fBgpiv_combing\fR. Image parameters
are read from the header or from other parameter resources (containing
the key \fBIMG\fR) in case they are absent in the image header.

The configuration parameters (containing the \fBEVAL\fR or
\fBVALID\fR) key may be overruled by the command line options, as
explained below.


.SH Options 

.TP 
\fB--cf \fIN\fR 
Specify the first column \fIN\fR 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.

.TP 
\fB--cl \fIN\fR
Specify the last column \fIN\fR in the image to interrogate.  

.TP
\fB--cp \fIN\fR
Pre-shift of \fIN\fR 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.

.TP 
\fB-g\fR 
Graphic visualisation of the output with gnuplot. Can only be used in 
combination with \fIfilename\fR).

.TP 
\fB--gauss\fR
Gauss weighting of interrogation area to reduce high spatial frequency
signal generated by the boundaries.

.TP
\fB-h\fR | \fB--help\fR 
Print a help message on standard output and exit successfully.

.TP 
\fB--ifit \fI0/1/2/3\fR
Three-point interpolation model for peak maximum estimation at sub-pixel
level. \fI0\fR: none, \fI1\fR: Gauss, \fI2\fR: Parabolic or \fI3\fR Center of
Gravity.

.TP
\fB--ischeme \fI0/1/2/3/4\fR
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 \fB-ifit\fR.

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.

.TP
\fB--ia_size_i \fIN\fR 
Initial size of the interrogation area's \fIN\fR. \fIN\fR must be
equal or larger than \fBia_size_f\fR. 

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 \fBia_size_i\fR. For each next image
interrogation, the sizes will be halved until they will be equal to
the final \fBia_size_f\fR value. The estimator will be used as a local
pre-shift (zero offsetting, as defined by \fB--ischeme\fR). In case
\fBia_size_f\fR and/or \fBia_size_i\fR 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 \fBia_size_f\fR. During the last interrogation, the estimator
will be between (-1,-1) and (1,1).  Then, sub-pixel displacement will
be calculated as defined by \fB--ifit\fR.

.TP
\fB--ia_size_f \fIN\fR
Final size of the interrogation area's \fIN\fR, expressed in
pixels. May be chosen arbitrarily.

.TP
\fB--ia_shift \fIN\fR
Shift of adjacent interrogation areas \fIN\fR, expressed in pixels.

.TP
\fB--linec \fICOL RF RL\fR 
selects a vertical line at column \fICOL\fR to interrogate from the first
row \fIRF\fR to the last row \fIRL\fR

.TP
\fB--liner \fIROW CF CL\fR 
selects an horizontal line at row \fIROW\fR to interrogate from the first
column \fICF\fR to the last column \fICL\fR

.TP
\fB-p\fR | \fB--print\fR
Print parameters, command line options, progress of calculation and 
eventually used input and output filenames to stdout. The output is 
identic of \fIfilename\fB.par\fR, in case \fB-f\fR is used.

.TP
\fB--peak \fIN\fR
Find the \fIN\fR-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.

.TP
\fB--p_piv\fR
Print the piv results to stdout, even if \fB-f\fR has been specified.

.TP
\fB--point \fICOL ROW\fR
Select a single area in the image to interrogate at location \fICOL
ROW\fR. This option might be useful for substitution of erroneous
displacement vectors. A new estimation of the particle displacement
with \fR--peak\fR, then, may give a correct result. Mind to use \fB--p_piv\fR
if \fB-f\fR is used; else the original data file will be overwritten
with a single point analyses.

.TP
\fB--rf  \fIN\fR
Specify the first row \fIN\fR in the image to interrogate. If \fB-ad_int\fR has been used, the first row has to be equal or larger than 
(\fBint_size_2\fR - \fBint_size_1\fR)/2.

.TP
\fB--rl \fIN\fR
Specify the last row \fIN\fR in the image to interrogate.

.TP
\fB--rp \fIN\fR
Pre-shift of \fIN\fR 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.

.TP
\fB-s \fIS\fR
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.

.TP
\fB--spof\fR
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).

.TP
\fB-v\fR | \fB--version\fR
Print version information on standard output then exit successfully.

.TP
\fB--val_r \fIN\fR
Validation parameter to define residue type: Signal to Noise Ratio
(\fIN\fR = 0), median value from surroundings (\fIN\fR = 1) or
normalised median (\fIN\fR = 2).

.TP
\fB--val_s \fIN\fR
Validation parameter to substitute an erroneous vector by: nothing
(\fIN\fR = 0), local mean from the surroundings (\fIN\fR = 1), the
median of the surroundings (\fIN\fR = 2) or the estimation from the
next highest correlation peak (\fIN\fR = 3).

.TP
\fB--val_t \fIF\fR
Validation parameter representing the threshold value (float number)
of residues to be accepted.

.TP
\fIfilename\fR 
Using the full \fIfilename\fR of the input image overrides \fIstdin\fR
and \fIstdout\fR. Output will be written to
\fIfilename\fB.piv\fR. Parameters are stored in \fIfilename\fB.par\fR
and may be used for future use by including them in \fI./gpivrc\fR.
If \fIstdin\fR and \fIstdout\fR are used, the input is expected to be
a PNG formatted image.

.TP

.SH SEE ALSO
gpivtools

.SH NOTES

\fBgpiv_rr\fR 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.

.SH AUTHOR
Gerber Van der Graaf

.SH BUGS
The program seems to work fine. Though as the PIV technology itself is
subject of research, this program is constantly under development.