Provided by: gpivtools_0.6.0-3build1_amd64

**NAME**

gpiv_rr - interrogates an image (pair) in order to obtain displacements of particles for (Digital) Particle Image Velocimetry (PIV)

**SYNOPSIS**

gpiv_rr[--cfint] [--clint] [--cpint] [-g] [--gauss] [-h|--help] [--ifit0/1/2/3] [--ischemeint] [--ia_size_iint] [--ia_size_fint] [--ia_shiftint] [--linecintintint] [--linerintintint] [-o] [-p|--peakint] [--p_piv] [--pointintint] [--rfint] [--rlint] [--rpint] [-sfloat] [--spof] [-v|--version] [--val_rint] [--val_sint] [--val_tfloat] [filename] <stdin>stdout

**DESCRIPTION**

gpiv_rrinterrogates 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 theVALIDparameters, it will be tried if the PIV estimator from the second or third highest correlation peak will be valid.gpiv_rris 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,bmpand 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 bygpiv_combing. Image parameters are read from the header or from other parameter resources (containing the keyIMG) in case they are absent in the image header. The configuration parameters (containing theEVALorVALID) key may be overruled by the command line options, as explained below.

**Options**

--cfNSpecify the first columnNin 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.--clNSpecify the last columnNin the image to interrogate.--cpNPre-shift ofNcolumns. 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.-gGraphic visualisation of the output with gnuplot. Can only be used in combination withfilename).--gaussGauss weighting of interrogation area to reduce high spatial frequency signal generated by the boundaries.-h|--helpPrint a help message on standard output and exit successfully.--ifit0/1/2/3Three-point interpolation model for peak maximum estimation at sub-pixel level.0: none,1: Gauss,2: Parabolic or3Center of Gravity.--ischeme0/1/2/3/4Interrogation 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_iNInitial size of the interrogation area'sN.Nmust be equal or larger thania_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 withia_size_i. For each next image interrogation, the sizes will be halved until they will be equal to the finalia_size_fvalue. The estimator will be used as a local pre-shift (zero offsetting, as defined by--ischeme). In caseia_size_fand/oria_size_iis 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 toia_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_fNFinal size of the interrogation area'sN, expressed in pixels. May be chosen arbitrarily.--ia_shiftNShift of adjacent interrogation areasN, expressed in pixels.--linecCOLRFRLselects a vertical line at columnCOLto interrogate from the first rowRFto the last rowRL--linerROWCFCLselects an horizontal line at rowROWto interrogate from the first columnCFto the last columnCL-p|filename.par, in case-fis used.--peakNFind theN-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_pivPrint the piv results to stdout, even if-fhas been specified.--pointCOLROWSelect a single area in the image to interrogate at locationCOLROW. 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_pivif-fis used; else the original data file will be overwritten with a single point analyses.--rfNSpecify the first rowNin the image to interrogate. If-ad_inthas been used, the first row has to be equal or larger than (int_size_2-int_size_1)/2.--rlNSpecify the last rowNin the image to interrogate.--rpNPre-shift ofNrows. 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.-sSScale 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.--spofApplies 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|--versionPrint version information on standard output then exit successfully.--val_rNValidation parameter to define residue type: Signal to Noise Ratio (N= 0), median value from surroundings (N= 1) or normalised median (N= 2).--val_sNValidation 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_tFValidation parameter representing the threshold value (float number) of residues to be accepted.filenameUsing the fullfilenameof the input image overridesstdinandstdout. Output will be written tofilename.piv. Parameters are stored infilename.parand may be used for future use by including them in./gpivrc. Ifstdinandstdoutare used, the input is expected to be a PNG formatted image.SEEALSOgpivtools

**NOTES**

gpiv_rrhas 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 GPIV_RR(1)