Man Linux: Main Page and Category List


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


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

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

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

       -v | --version
              Print  version  information  on  standard   output   then   exit

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