.TH GPIV_ERRVEC 1 "23 May 2005"
.SH NAME
gpiv_errvec \- Searches erroneous vectors in a PIV data file and substitutes
with new values.
.SH SYNOPSIS

\fBgpiv_errvec\fP 
[\fB-a\fR] 
[\fB-b \fR]
[\fB-g\fR][\fB-h\fR]
[\fB-h\fR | \fB--help\fR]
[\fB-i\fR | \fB--image_type\fP \fIS\fR]
[\fB-n \fIN\fR] 
[\fB--no_b \fR] 
[\fB-p\fR | \fB--print\fR] 
[\fB-r \fIN\fR] 
[\fB-s \fIN\fR] 
[\fB-t \fIF\fR] 
[\fB-u\fR | \fB--surround\fR]  
[\fB-v\fR | \fB--version\fR]  
[\fIfilename\fR]
< \fIstdin\fR > \fIstdout\fR

\fP

.SH DESCRIPTION
\fBgpiv_errvec\fP searches erroneous outliers in a PIV data stream and
substitutes with new values, if possible, i.e. if (the majority) of its
surroundings are non-erroneous.  Evaluation of erroneous vectors is
done by looking up the Signal to Noise Ratio (SNR) value in the PIV
data file or by calculating the median residu of the vector with its
surroundings. A new displacement is obtained by the mean value of the
surrounding values or by the location of the next higher peak in the
covariance function.

PIV data validation is not needed anymore while this is now done
during image interrogation with \fBgpiv_rr\fP. Though using
\fBgpiv_errvec\fP will not harm.

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

.SH Options 
.TP
\fB-a\fP 
Automatic threshold; calculates threshold value from residu histogram.

.TP
\fB-b\fP
Calculate statistics of the median residues and print a histogram of 
\fIN\fR bins.

.TP
\fB-g\fP
Graphical visualization of residu statistics with gnuplot (needs 
\fIfilename\fR). \fB-b\fR is not required as this option will be 
set automatically.

.TP
\fB-h\fR | \fB--help\fP 
On-line help.

.TP
\fB-i\fR | \fB--image_type\fP \fIS\fR
Image type or format to be used if particle displacements will have to
be re-estimated at the next highest correlation peak. \fIS\fR may be
png, tif, gif, bmp, pgm, r or gpi. Default: png.

.TP
\fB-n \fIN\fR
Defines number of histogram of bins \fIN\fR for \fB-b\fR or \fB-a\fR

.TP 
\fB--no_b \fIN\fP
suppresses printing median residu histogram

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

.TP
\fB-r \fIN\fP 
Erroneous vector determined by SNR of the correlation function (\fIN\fR
= 0), median residu (\fIN\fR = 1) or normalized median (\fIN\fR = 2),
i.e. the ratio between median residu with current datapoint included
and between median residu of surroundigs (with datapoint excluded).

.TP
\fB-s \fIN\fR
Substitution of the erroneous vectors by (\fIN\fR = 0) nothing, the
local mean from the surrounding values (\fIN\fR = 1), median (\fIN\fR
= 2) or next highest covariance peak (\fIN\fR = 3, needs
\fIfilename\fR).

.TP
\fB-t \fIF\fP 
Threshold value \fIF\fP of SNR or median residu to
determine validity of particle displacement.

.TP
\fB-u\fR | \fB--surround\fP
Odd number representing the surrounding grid points to be used
for local mean and median values.

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

.TP
\fIfilename\fR
Full name of PIV data file for input. Substitutes stdin and
stdout. Output will be written to \fIfilename\fB.erv.piv\fR. The
parameters will be written or appended to \fIfilename\fB.par\fR and
may be used for future use by including them in \fI./gpivrc\fR. If
particle displacements will have to be re-estimated at the next
highest correlation peak, \fIfilename\fR is required.


.SH SEE ALSO
gpivtools

.SH AUTHOR
Gerber Van der Graaf

.SH BUGS
The program has been tested for artificial generated DPIV images. So far, no
serious bugs have been found.