doc/C/gpiv.html

   1 <HTML><HEAD><TITLE>GPIV</TITLE>
   2 </HEAD>
   3 <BODY BGCOLOR="#FFFFFF">
   4 <BODY>
   5 <A href="index.html"> Contents </A>  <br>
   6 <A href="intro.html"> Previous </A>  <br>
   7 <A href="piv_intro.html"> Next </A>
   8 <P>
   9 <A NAME="gpiv.html"> <H1>2 GPIV</H1></A>
  10
  11 <A NAME="1"><H2>2.1 Starting up</H2></A>
  12
  13 By invoking "gpiv" the GPIV console will be launched that consists a
  14 menu bar, a toolbar, process toggle-buttons, a tabulator and a data
  15 buffer list (<a href="#fig1">Figure 2.1</A>). At the bottom of the
  16 console you can find an application bar that displays information of the
  17 highlighted item as well as a progress bar that displays the progress
  18 of the running process.
  19 <br>
  20 GPIV reads its default program parameters from ~/.gnome/gpiv following
  21 the GNOME conventions. These parameters can be defined by command line
  22 keys for the current session (invoke "gpiv --help" for information
  23 about the options) or in the settings->preferences from the console
  24 menu's. The variables that are used for interrogation, validation and
  25 post-processing are read from ~/.gpivrc or from the system-wide
  26 available gpivrc (mostly /etc/gpivrc under Unix/Linux) respectively.
  27 <br>
  28
  29
  30 <P>
  31 <P>
  32 <IMG SRC = "figures/gpiv-fig2.png"><br>
  33 <A NAME="fig1" id="gpiv-fig2">Figure 2.1 GPIV console with image inormation
  34 tabulator</A>
  35 <P>
  36
  37 <A NAME="2"><H2>2.2 Menu and toolbar</H2></A>
  38
  39 The menu bar consists general tasks for GPIV, like file-handling,
  40 preferences and help menus. Underlined characters represent the ALT
  41 short-hand key for launching the menus.
  42 <P>
  43 The "File" menu contains the menus "open", "save", "save as" for
  44 reading and storing data and "exit" for closing the application.
  45 <P>
  46 The settings menu contains the menus "gpiv buttons" and "tabulator" to
  47 (un)display these parts of the console and "preferences" for defining
  48 all GPIV settings. Closing the "preferences" menu
  49 with "OK" stores the settings for future sessions. "Apply" only
  50 affects the current session. "Cancel" undisplays the preferences menu
  51 without action.
  52 <P>
  53 The "help" menu contains "show tooltips" for obtaining additional
  54 help. Tooltips are small windows that pop up when an item is
  55 highlighted and contain more extended information about the item than
  56 can be displayed at the application bar. The "manual" menu shows this
  57 document. "about" gives short info about the application.
  58 <P>
  59
  60 The toolbar is a quick way for opening/saving images and data,
  61 executing/stopping processes that are enabled by the process toggle
  62 buttons below of the toolbar and for exiting the program.
  63
  64
  65
  66 <A NAME="3"><H2>2.3 Process toggle-buttons</H2></A>
  67
  68 The process toggle-buttons may be switched on in order to define a
  69 chain of processes that include interrogation, validation and
  70 post-processing. The settings of the processes are defined in the
  71 tabulator below. The chain is invoked by the "Execute" button on the
  72 toolbar and, eventually, interrupted by the "Stop" button.
  73
  74
  75 <A NAME="4"><H2>2.4 Data buffer list and display window</H2></A>
  76
  77 The data buffer list contains a number and the base name of the image
  78 (without its extesion). A single buffer may be selected by pointing to
  79 it and left mouse clicking. Several buffers may be selected by
  80 clicking the first and last buffer while holding the "Shift" key. An
  81 execution of a process will than be performed on every selected
  82 buffer.
  83 <P>
  84
  85 For each buffer a display window is launched that contains the
  86 image (not visible in this version of GPIV), squared frames that
  87 represent the interrogation areas of the first and the second image
  88 (in different colors), vectors representing PIV estimators and derived
  89 scalars that are obtained from the PIV estimators by post
  90 processing. The interrogation areas are highlighted when the pointer
  91 is moving over them. At the bottom of the diplay window an application
  92 bar shows the position of the pointer, centre point of the highlighted
  93 inetrrogation area and, eventually, values of the PIV estimators and
  94 its derived quantities. The same information is diplayed in the
  95 application bar of the GPIV console as well. When clicking the right
  96 mouse button when it points at the display window, a menu pops for
  97 in-and outzooming the window, (un)displaying features and choosing
  98 vector lenght.
  99
 100
 101
 102 <A NAME="5"><H2>2.5 Tabulator</H2></A>
 103
 104 The tabulator contains image header data, image evaluation, validation
 105 and post-processing parameter settings and buttons to invoke the
 106 individual processes.
 107
 108 <A NAME="5.1"><H3>2.5.1 Image info</H3></A>
 109
 110 The most left tabulator 'Image Info' (<a href="#fig1">Figure 2.1</A>)
 111 shows information of the image. The image dimensions are defined in
 112 gpiv_gtk.h and can not be changed during execution of GPIV. In case
 113 different dimensions will have to be researched, its definition has to
 114 be changed and gpiv will have to be recompiled. Time scaling, spatial
 115 scaling, the positions of row #0 and column #0 (related to a typical
 116 location in the experiment) are the same as in the Post processing
 117 tabulator.  These parameters are used for scaling and positioning the
 118 PIV data. The image header items "Project", "Creation date", "Place",
 119 and "Comment" are optional.
 120
 121
 122 <A NAME="5.2"><H3>2.5.2 Evaluation</H3></A>
 123
 124 The 'Evaluation' tab (<a href="#fig2">Figure 2.2</A>) shows all the
 125 settings for interrogation a image (pair).
 126 <P>
 127 <P>
 128 <IMG SRC = "figures/gpiv-fig3.png"><br>
 129 <A NAME="fig2" id="gpiv-fig3">Figure 2.2 GPIV console with Evaluation
 130 tabulator</A>
 131 <P>
 132 <P>
 133
 134 - The upper-left corner of the image represents pixel # (0,0). The
 135 starting point (first col/row) and the end-point (last col/row) of the
 136 image to be interrogated may be defined in the entry-fields as well as
 137 a global pre-shift in horizontal (pre-shift col) and vertical
 138 (pre-shift row). The first column and row, as defined in the entrys will
 139 always be included in the interrogations. The last column/row of the image
 140 to be analysed depends on Interrogation Area sizes and shifts, but
 141 will never exceed the last column/row as defined in the
 142 entry-fields.
 143 <P>
 144
 145 - The size of the interrogation area and the shift of adjacent area's,
 146 expressed in image pixels, are defined by entrys (for arbitrary
 147 dimensions) or or by radio-buttons (for power of 2 dimensions)
 148 'Int. Size 1', 'Int. Size 2' and 'Shift'. As the size of the second
 149 interrogation area has to be equal or larger than the first one, some
 150 of the settings in the entries and of the radio buttons may be disabled
 151 for manipulations.
 152 <P>
 153
 154 - "Mouse select":
 155 <P>
 156
 157 "None" disables mouse activitiy within the viewer window.
 158 <P>
 159
 160 Enabling "Area", entering a viewer window, pressing the right mouse
 161 button and moving the mouse creates a rectanglar frame that defines the area
 162 to be interrogated. This is an alternative for using the entries "first/last
 163 col/row". The entry values will be updated automatically.
 164 <P>
 165
 166 Enabling "Single int.", entering a viewer window and clicking the right mouse button
 167 invokes a new interrogation at the highlighted interrogation area. Already existing
 168 estimators will be conserved.
 169 <P>
 170
 171 Enabling "Single point", entering a viewer window and clicking the right mouse
 172  button invokes a new interrogation at an arbitrary point.
 173 Already existing estimators will be thrown away!
 174 <P>
 175
 176 Enabling "Drag int." and entering a viewer window causes to displace
 177 (drag) the highlighted interrogation area. An adjacent interrogation
 178 area is highlighted and dragged in case the pointer is closer to its
 179 centre point. Clicking the right mouse button invokes an interrogation
 180 at the centre point of the (displaced) interrogation area. Already
 181 existing estimators will be conserved.
 182 <P>
 183
 184 With "Vert. line" a vertical line in the image may be defined at which
 185 a single column of interogation areas are to be drawn. Interrogation
 186 of the line has to be performed by clicking the "piv" button at the
 187 bottom of the "Evaluation" tabulator or by enabling the "piv" process
 188 button and pressing the "Execute" button on the toolbar.
 189 <P>
 190 With "Hor. line" a horizontal line in the image may be defined at which a
 191 single row of interogation areas are to be drawn.Interrogation
 192 of the line has to be performed by clicking the "piv" button at the
 193 bottom of the "Evaluation" tabulator or by enabling the "piv" process
 194 button and pressing the "Execute" button on the toolbar.
 195 <P>
 196
 197 - "Interpolation scheme": interpolation scheme for estimating the correlation
 198 peak at sub-pixel level.
 199 <P>
 200
 201 - Peak #: normally the highest correlation peak is used (or the
 202 second highest in case of auto-correlation, which is done automatically
 203 if auto-correlation has been enabled). An erroneous velocity
 204 vector, though, might be caused by a high noise peak in the correlation
 205 function that overwhelmes the 'true' particle displacemnt peak. Searching
 206 the second or third highest peak may result in a correct estimation.
 207 <P>
 208
 209 - Interrogation with: a linear weight kernel in order to correct for
 210 biasing effects that is generated by the estimation of the correlation
 211 function. In case zero offset is enabled, i.e. a second interrogation
 212 is performed with a pre-shift of the local estimator, the new
 213 correlation peak is found between -1 and +1 pixels. In that case
 214 kernel weighting will over-correct and, therefore, is disabled. If
 215 zero-offsetting is enabled, the 'classic' forward interrogation scheme
 216 is choosen or a central differential scheme may be used.
 217 Interrogation following the central differential scheme is done by
 218 displacing the interrogation area of the first image with half the
 219 magnitude of the pre-shift value in negative direction and displacing
 220 the interrogation area of the second image in positive direction (of
 221 identic magnitude).
 222 <P>
 223
 224 - "Correlation"; in case recordings have been
 225 performed on separate image frames ("Auto") or on one single frame ("Cross").
 226 <P>
 227
 228 - "Interrogation areas and correlation": displays interrogation areas and
 229 correlation function, together with the estimated displacement vector
 230 by enabling the "Display" button. Though, this uption
 231 is unstable, yet.
 232 <P>
 233
 234 - At the bottom of the "Evaluation" tabulator the "piv" button may be
 235 invoked to interrogation the image. The function of this button is
 236 similar to the command line program <A href="rr.html"> rr </A> of
 237 gpivtools.
 238
 239
 240 <A NAME="5.3"><H3>2.5.3 Validation </H3></A>
 241
 242 <P>
 243 <IMG SRC = "figures/gpiv-fig4.png"><br>
 244 <A NAME="fig3" id="gpiv-fig4">Figure 2.3 GPIV console with Validation
 245 tabulator</A>
 246 <P>
 247 <P>
 248
 249 - "Disable data": to put PIV data into  (in)active state for further processing.
 250 At inactive state the vector color will be displayed red.
 251 <P>
 252 activate "Enable/Disable point" to put in active/inactive state by pointing
 253 and clicking a single PIV estimator.
 254 <P>
 255 activate "Enable/Disable area" to put in active/inactive state a rectangular
 256 area containing PIV data. The starting corner of the area (upper-left) to be
 257 disables is defined by pressing the right mouse button. The opposite corner
 258 is defined by moving the mouse with pressed button and realxing the button at
 259 the location of the opposite corner. A rectangular frame is drawn during the
 260 operation.
 261 <P>
 262
 263 -"peak lock" displays a histogram of sub-pixel estimators of the PIV
 264 dataset. This button is similar to the command line program <A
 265 href="peaklck.html"> peaklck </A> of gpivtools.
 266 <P>
 267
 268 "residu statistics" displays the (log) inverse histogram of median residus. The
 269 critical residu value for accepting/rejecting outliers is determined by the
 270 slope of the straight line. The critical value is calculated and displayed in
 271 the "Threshold" entry. This button is similar to the command line program <A
 272 href="errvec.html"> errvec </A> of gpivtools.
 273 <P>
 274
 275 Activating the "validate on velocity gradient" button puts all vectors
 276 into red color if they exceed the critical value of the velocity
 277 gradient over an interrogation area. The critical value is defined in
 278 libgpiv/include/gpiv/valid.h: GRADIENT_THRESHOLD and is set to 2
 279 pixels, i.e. identic to the optimum particle image diameter. This
 280 quantity is choosen in order to prevent a too wide, or even a
 281 splitting up of the highest correlation peak.
 282 <P>
 283
 284 "Outliers" defines the parameters for testing and substituting on
 285 erroneous vectors.  The type of residus may be choosen between "Snr"
 286 or "Median". The "Data yield" has to be filled in manually and should
 287 be obtained from the mean number of particles within an interrogation
 288 area. The critical threshold may be filled in manually or may be
 289 obtained by invoking "residu statistics" button. Outliers are
 290 substituted by the local mean value of surrounding vectors, by the
 291 median value of surrounding vectors or by interrogating the area with
 292 a next highes correlation peak. Finally, the validation on outliers is
 293 performed by pressing the "validate on outliers" button. This button
 294 is similar to the command line program <A href="errvec.html"> errvec
 295 </A> of gpivtools, too.
 296
 297
 298
 299 <A NAME="5.4"><H3>2.5.4 Post processing </H3></A>
 300
 301 The "Post processing" tab (<a href="#fig4">Figure 2.4</A>) contains
 302 tools to apply modifications on PIV estimators and to calculate
 303 derived quantities from the PIV estimators.
 304 <P>
 305
 306 spatial scaling is calculated by measuring the number of pixels per
 307 mm. For the moment, this measuring has to be performed with different
 308 image visualization tools. The time scale represents the time between
 309 two succesive image recordings (mostly the separation time between two
 310 laser flashes). The location of the image within an experiment is
 311 defined by the position of column and row #0, related to a marker
 312 point in the experiment. Enabling the "Apply" button will display the
 313 scaled data in the application bars of the buffer window and of the
 314 console, including their positions in the experiment. This will not
 315 affect the original data set itself, yet. The conversion of the data
 316 is performed during storage execution. So, disabling the "Apply"
 317 button will display the original (unscaled) estimators and their
 318 position in the image, expressed in pixels. This button is similar to
 319 the command line program <A href="scale.html"> scale </A> of the
 320 gpivtools distribution.
 321 <P>
 322
 323 Vorticity, shear and normal strain may be derived from the PIV
 324 estimators with different numerical schemes; Central differential
 325 scheme, Least squares, Richardson and the Circulation method (only for
 326 the calculation of vorticity). This button is similar to the command
 327 line program <A href="vorstra.html"> vorstra </A> of the gpivtools
 328 distribution.
 329
 330 <P>
 331 <IMG SRC = "figures/gpiv-fig5.png"><br>
 332 <A NAME="fig4" id="gpiv-fig5">Figure 2.4 GPIV console with Post processing
 333 tabulator</A>
 334 <P>
 335 <P>
 336 <A href="index.html"> Contents </A>  <br>
 337 <A href="intro.html"> Previous </A>  <br>
 338 <A href="piv_intro.html"> Next </A>
 339 </BODY>
 340
 341
 342 </HTML>