doc/C/rr.html

   1 <HTML><HEAD><TITLE>Manpage of </TITLE>
   2 </HEAD><BODY BGCOLOR="#FFFFFF">
   3 Name: <B>RR</B><BR>
   4 Section: Misc. Reference Manual Pages (n)
   5 <HR>
   6
   7 <A NAME="lbAB">&nbsp;</A>
   8 <H2>NAME</H2>
   9
  10 rr - correlates image pairs in order to obtain particle displacements
  11 for Digital Particle Image Velocimetry
  12 <A NAME="lbAC">&nbsp;</A>
  13 <H2>SYNOPSIS</H2>
  14
  15 <P>
  16 <B>rr</B> [<B>-ad_int | --ad_int</B>] [<B>-autokey</B>] [<B>-c </B><I>int</I>] [<B>-cf
  17 </B><I>int</I>] [<B>-cl </B><I>int</I>] [<B>-cp </B><I>int</I>][<B>-cmpr | --cmpr</B>] [<B>-f </B><I>filename</I>] [<B>-h</B>] [<B>-isi1 </B><I>int</I>] [<B>-isi_2 </B><I>int</I>] [<B>-ish </B><I>int</I>] [<B>-o</B>]  [<B>-ifit </B><I>-1/0/1/2/3</I>] [<B>-k | --k</B>] [<B>-p</B>] [<B>-peak </B><I>N</I>] [<B>-p_cov</B>] [<B>-p_iter</B>] [<B>-p_int</B>] [<B>-p_piv</B>] [<B>-point </B><I>f f</I>] [<B>-r </B><I>int</I>] [<B>-rf </B><I>int</I>] [<B>-rl </B><I>int</I>] [<B>-rp </B><I>int</I>] [<B>-v</B>] [<B>-x | --x</B>] [<B>-z | --z</B>] <I> &lt; inputfile &gt; outputfile </I>
  18 <P>
  19 <A NAME="lbAD">&nbsp;</A>
  20 <H2>DESCRIPTION</H2>
  21
  22 <P>
  23 <B>rr</B> co<I>rr</I>elates an image or image pair that is obtained from
  24 a fluid flow by the so-called Digital Particle Image Velocimetry
  25 (DPIV) technique. The image(s) are subdevided in interrogation areas
  26 at which the mean particle displacements are estimated. This is done
  27 by correlating the interrogation areas resulting into a
  28 two-dimensional covariance function. The covariance function is
  29 obtained by Fast Fourier Transformation (FFT) techniques. The location
  30 of the covariance peak then represent the mean particle image
  31 displacement within the interrogation area. Estimation of the
  32 covariance peak at sub-pixel level is possible by different
  33 interpolation schemes.  The program allows cross-correlation of
  34 single-exposed images on different frames or auto-correlation of
  35 multi-exposed single-frame images. Analyses with different sizes of
  36 interrogation areas between the first and second frame allows large
  37 dynamic ranges of the particle displacements. Zero off-setting of the
  38 interrogation areas by an iterative evaluation process allows high
  39 accuracy of the particle image displacements.
  40 <P>
  41 For cross-correlation of single-exposed multi-frame images, <B>rr</B>
  42 has to be fed by the (raw or ASCII) data of the images, the second
  43 image concatenated after the first one. If not stdin and stdout is
  44 used (with <B>-f </B><I>filename</I>), the images have to be called
  45 <I>filename</I><B>.1.r</B> and <I>filename</I><B>.2.r</B> (raw image format) for
  46 cross-correlation and <I>filename</I><B>.r</B> for auto-correlation. The
  47 number of rows and columns are read from the ASCII file
  48 <I>filename</I><B>.h</B>. Output will then be written to
  49 <I>filename</I><B>.piv</B>, containing the estimators of the particle
  50 displacements, <I>filename</I><B>.par</B> with the used parameters for
  51 <I>rr</I>, <I>filename</I><B>.cov</B> with covariance data (optional) and
  52 <I>filename</I><B>.1.int</B>, <I>filename</I><B>.2.int</B> with actual
  53 interrogation regions (optional). Particle displacements from a
  54 previous analysis (eventually obtained without sub-pixel estimation)
  55 may be used as local pre-shifts for further analysis. In that case the
  56 input file <I>filename</I><B>.piv</B> will be renamed to
  57 <I>filename</I><B>.old.piv</B>.
  58 <P>
  59 The parameters and options to be used for rr are subsequently searched
  60 in <B>rr.par</B> at local directory, at
  61 <I>~/.gpivrc</I> or at <I>/etc/gpivrc</I>. Each parameter is described by the program key (Rr)
  62 and the parameter name, separated by a dot (.), followed by its
  63 value. Some of the parameters are optional. The parameters may be
  64 defined in arbitrary order. Blank lines and comment (starting with a
  65 pound sign (#) at the first column) may be included in the parameter
  66 files.  Parameters may be overruled by the command line options,
  67 as explained below. If <B>-f</B> has been used, the used parameters are
  68 written to <I>filename</I><B>.par</B>. By renaming this file to
  69 <B>rr-2.2.par</B>, it may directly be re-used for identic analyses of
  70 other images.
  71 <P>
  72 <A NAME="lbAE">&nbsp;</A>
  73 <H2>Options </H2>
  74
  75 <DL COMPACT>
  76 <DT><B>-ad_int</B> <DD>
  77 Adaptive interrogation size; The size of the second interrogation
  78 region may be choosen larger than the first one in order to obtain
  79 high dynamic ranges. Though, this may result into low spatial
  80 resolutions of the PIV estimators. Only if <B>-z</B> has been set,
  81 <B>-ad_int</B> will adapt the size of the 2nd interrogation region to
  82 the first one after the first iteration step, resulting into higher
  83 spatial resolutions. See also <B>-col_start</B>, <B>-row_start</B> and
  84 <B>-int_size_2</B><I>N</I>.
  85 <DT><B>--ad_int</B> <DD>
  86 Supresses adaptive interrogation size.
  87 <DT><B>-autokey</B><DD>
  88 Sets automatically parameters that depend on others: zero_off is set to 1 if
  89 ad_int = 1 , weight is set to 0 if zero_off = 1 and weight is set to 1
  90 if zero_off = 0.
  91 <DT><B>-cmpr </B><I>N</I> <DD>
  92 Compresses the image with factor <I>N</I> by taking the mean value of
  93 the <I>N</I>x<I>N</I> pixel values. <I>N</I> has to be a power of
  94 2. <B>-cmpr</B> can only be used in combination with -fit equal to
  95 0. This option will speed up the image analyses by a factor
  96 <I>N</I>**2. The output, may be read as local pre-shift
  97 values in a next image evaluation, similar to <B>-z</B>.
  98 <DT><B>--cmpr</B> <DD>
  99 Suppresses image compression.
 100 <DT><B>-c </B><I>N</I> <DD>
 101 Specify the number of columns with <I>N</I> that
 102 contains the image.
 103 <DT><B>-cf </B><I>N</I> <DD>
 104 Specify the first column <I>N</I> in the image to interrogate. If <B>-ad_int</B> has been used, the first column has to be equal or larger than
 105 (<B>int_size_2</B> - <B>int_size_1</B>)/2.
 106 <DT><B>-cl </B><I>N</I><DD>
 107 Specify the last column <I>N</I> in the image to interrogate.
 108 <DT><B>-cp </B><I>N</I><DD>
 109 Pre-shift of <I>N</I> columns. This can be used if
 110 there is a common mean flow in x-direction in the area of
 111 observation. Relative small interrogation areas (allowing a high spatial
 112 resolution) may be used in that case with conservation of a high
 113 probability in finding the correct displacement peaks.
 114 <DT><B>-f </B><I>filename</I> <DD>
 115 Overrides stdin and stdout with <I>filename</I>.
 116 <DT><B>-h</B> <DD>
 117 Print a help message on standard output and exit successfully.
 118 <DT><B>-ifit </B><I>-1/0/1/2/3</I><DD>
 119 Interpolation model for peak maximum estimation at sub-pixel
 120 level. <I>-1</I>: Levenberg-Marquardt model parameter estimation:
 121 <I>0</I>: none, <I>1</I>: Gauss, <I>2</I>: Parabolic or <I>3</I> Centre of
 122 Gravity.
 123 <DT><B>-isi1 </B><I>N</I> <DD>
 124 Size of first interrogation area <I>N</I>, expressed in pixels. Must be
 125 a power of two.
 126 <DT><B>-isi2 </B><I>N</I> <DD>
 127 Size of second interrogation area <I>N</I>. Must be a power of two and
 128 must be equal or larger than <B>isi1</B>. Larger sizes of the 2nd
 129 interrogation area allows particle displacements larger than 1/4th of
 130 the first interrogation size (which is generally recommended in order
 131 to keep in-plane error at minimum), i.e. an increase of dynamical
 132 range. Though, the Signal to Noise Ratio (SNR) may decrease in that
 133 case, resulting in a lower probability in finding the correct
 134 displacement peak. It is adviced to keep the ratio of the second and
 135 first interrogation size below 4. In combination with <B>ad_int</B> the
 136 SNR and spatial resolution (i.e. independancy of neighbouring
 137 interrogation regions) may be increased significantly during a next
 138 iteration sweep.
 139 <DT><B>-ish </B><I>N</I><DD>
 140 Shift of adjacent interrogation areas <I>N</I>, expressed in pixels.
 141 <DT><B>-k</B><DD>
 142 Uses kernel weighting. This is applied in the calculation of the
 143 covariance function; the weighting of the image data decreases towards
 144 the edges of the interrogation region. Kernel weighting compensates
 145 this effect.
 146 <DT><B>--k</B><DD>
 147 Suppresses kernel weighting.
 148 <DT><B>-o</B> <DD>
 149 Reads an old output file from a previous evaluation with <B>rr</B>
 150 for further analysis. The data are used as individual pre-shifts for
 151 each interrogation area. Can only be used in combination with <B>-f
 152 </B><I>filename</I>
 153 <DT><B>-p</B><DD>
 154 Print parameters, command line options, progress of calculation and
 155 eventually used input and output filenames to stdout. The output is
 156 the same as <I>filename.par</I> if <B>-f</B> is used and it can be used as input
 157 parameters of <B>rr</B> for future analyses by re-directing stdout to
 158 rr-2.2.par (X-your-fingers).
 159 <DT><B>-peak </B><I>N</I><DD>
 160 Find the <I>N</I>-th maximum of the covariance peak. In case of
 161 auto-covariance the second peak is taken by default, as the first peak
 162 denotes the zero-shift of the particle displacements.
 163 <DT><B>-p_cov</B><DD>
 164 Print the covariance function.
 165 <DT><B>-p_int</B><DD>
 166 Print the interrogation region(s).
 167 <DT><B>-p_iter</B><DD>
 168 Print the iteration steps for the covariance peak search if <B>-z</B>
 169 has been used.
 170 <DT><B>-p_piv</B><DD>
 171 Print the piv results to stdout, even if <B>-f</B> has been specified.
 172 <DT><B>-point </B><I>x y</I><DD>
 173 Select a single area in the image to interrogate at location <I>x
 174 y</I>. This option is usefull for substitution of erroneous
 175 displacement vectors. A new estimation of the particle displacement
 176 with -peak may give a correct result. Mind to use <B>-p_piv</B>
 177 if <B>-f</B> is used; else the original data file will be overwritten
 178 with a single point analyses.
 179 <DT><B>-r </B><I>N</I><DD>
 180 Number of rows <I>N</I> that contains the image.
 181 <DT><B>-rf  </B><I>N</I><DD>
 182 Specify the first row <I>N</I> in the image to interrogate. If <B>-ad_int</B> has been used, the first row has to be equal or larger than
 183 (<B>int_size_2</B> - <B>int_size_1</B>)/2.
 184 <DT><B>-rl </B><I>N</I><DD>
 185 Specify the last row <I>N</I> in the image to interrogate.
 186 <DT><B>-rp </B><I>N</I><DD>
 187 Pre-shift of <I>N</I> rows. This can be used if
 188 there is a common mean flow in y-direction in the area of
 189 observation. Relative small interrogation areas (allowing a high spatial
 190 resolution) may be used in that case with conservation of a high
 191 probability in finding the correct displacement peaks.
 192 <DT><B>-v</B><DD>
 193 Print version information on standard output then exit successfully.
 194 <DT><B>-x</B><DD>
 195 Calculates cross-covariance function of two images.
 196 <DT><B>--x</B><DD>
 197 Calculates auto-covariance function of a single, double-exposed image.
 198 <DT><B>-z</B><DD>
 199 Searches (iteratively) the covariance peak for zero-offset use, until
 200 the top lies between (-1,-1) and (1,1). Then sub-pixel interrogation will be
 201 done.
 202 <DT><B>--z</B><DD>
 203 Supresses  zero-offset
 204 <P>
 205 </DL>
 206 <A NAME="lbAF">&nbsp;</A>
 207 <H2>SEE ALSO</H2>
 208
 209 batch-gp, dav2piv, err_vec, manipiv, hilo, rr, scale, s-avg, t-avg, peaklck,
 210 piv2vec,vorstra
 211 <P>
 212 <A NAME="lbAG">&nbsp;</A>
 213 <H2>NOTES</H2>
 214
 215 rr has been tested with artificial images and with PIV images from gas and
 216 liquid flows. Comparison with PIV data, obtained from different codes,
 217 and with literature results that similar data reliability and accuracy can
 218 be obtained with this program.
 219 <P>
 220 <A NAME="lbAH">&nbsp;</A>
 221 <H2>AUTHOR</H2>
 222
 223 Gerber Van der Graaf
 224 <P>
 225 <A NAME="lbAI">&nbsp;</A>
 226 <H2>BUGS</H2>
 227
 228 So far, no serious bugs have been found.
 229 <P>
 230
 231 <HR>
 232 <A NAME="index">&nbsp;</A><H2>Table of Contents</H2>
 233 <OL>
 234 <LI><A HREF="#lbAB">Name</A>
 235 <LI><A HREF="#lbAC">Synopsis</A>
 236 <LI><A HREF="#lbAD">Description</A>
 237 <LI><A HREF="#lbAE">Options </A>
 238 <LI><A HREF="#lbAF">See also</A>
 239 <LI><A HREF="#lbAG">Notes</A>
 240 <LI><A HREF="#lbAH">Author</A>
 241 <LI><A HREF="#lbAI">Bugs</A>
 242 </OL>
 243 </BODY>
 244 </HTML>