Provided by: gpivtools_0.6.0-3build1_amd64 bug


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


       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


       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

       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.


       --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 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

              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

              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

              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

       --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.

              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.

              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


       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.


       Gerber Van der Graaf


       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)