Context Navigation

Changes between Version 188 and Version 189 of UvmatHelp

Timestamp:: Jan 29, 2015, 1:25:45 AM (9 years ago)
Author:: sommeria
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

UvmatHelp

-                      v188
+                      v189
 - '''Warning flags''': they indicate a vector resulting from a dubious image correlation process, but not removed from the data set. They are displayed in black by default. This feature can be desactivated by selecting the check box '''hide warn''' ('''[!CheckHideWarning]''').
 - '''Error flags''': they mark vectors considered as false. These vectors are kept in the data set so that their elimination can be reversed, but they must not be taken into account for data processing. These false vectors are displayed in magenta. They can be also removed from the plot by selecting the check box '''hide false''' ([!CheckHideFalse]''').
+- '''Error flags''': they mark vectors considered as false. These vectors are kept in the data set so that their elimination can be reversed, but they must not be taken into account for data processing. These false vectors are displayed in magenta. They can be also removed from the plot by selecting the check box '''hide false''' ([!CheckHideFalse]''').'''
 - '''Associated scalar: '''  for PIV velocity fields, the color  represents by default the image correlation '''C''', ranging from 0 to 1.  The red values correspond to poor correlations, green to fair values, and blue to good ones. The value range covered by each of the three colors is set by the pair of sliders  '''[Slider1]''' and '''[Slider2]''', or equivalently by the edit boxes '''[num_ColCode1]''' and '''[num_ColCode2]'''. Other color representations can be specified. '''[!ColorScalar]''' sets the scalar used for color representation, for instance the vector norm 'norm_vec' or vorticity 'vort' (the list of available scalars is set by the function {calc_scal.m}).
 …
 The second field can be removed by unselecting the check box '''[!SubField] '''.
 === 4.6 Field transforms ===
 A transform can be systematically applied after reading the input field, for instance the transform 'phys' which takes into account geometric calibration. This transform can possibly combine two input fields, for instance to substract a background from an image. The processing function is chosen  by the popup menu '''[transform_fct]''' on the left, and its path is displayed in the box '''[path_transform]'''. Select the option 'more...' to browse new functions. The same functions can be called in data processsing using the GUI '''series.fig'''. A few functions are provided in the folder /transform_fct, see the list in  [#overview the function overview].
 …
 - '''Field calculation:''' a scalar can be calculated after projection, as selected by the menu '''[Fields]'''.
+- '''Field comparison''': when two fields of the same nature are introduced, the difference is taken. This is skipped if the transform function has already led to a single field.
+- '''Plotting:''' plot the results of projection, using the function ''plot_field.m''.
+- '''Field comparison''': when two fields of the same nature are introduced, the difference is taken. This is skipped if the transform function has already led to a single field.   - '''Plotting:''' plot the results of projection, using the function ''plot_field.m''.
 ----
 …
 These are geometrical objects used to define cuts along lines or planes, to interpolate fields on a regular grid, to restrict the analysis or visualisation to field subregions. The projection of fields on objects is performed by the function ''proj_field.m'', which can be used as well in data processing outside the GUI '''UVMAT''', using for instance [#a10-Processingfieldseries series.fig].
 When a 2D or 3D field is opened by '''uvmat.fig''', a default projection object called 'plane' is created, so that all field plots (in 2D and 3D) are considered as the result of a projection. New objects are created by the menu bar command  '''[Projection object]''' in the GUI '''uvmat'''.  The creation of a new object ('''points''', '''line'''....) can be initiated by selecting the corresponding item in the menu. In each case an auxiliary GUI '''set_object.fig''' describing the object properties appears, see next [#a6.2Objectproperties sub-section] for their definitions. This GUI can be directly edited and object coordinates can be set by mouse drawing on the plot, see [#a6.4Objectrepresentation section 6.4]. To validate edition on the GUI '''set_object.fig''', refresh the plots by pressing '''[REFRESH]'''. Objects can be saved as xml files with the (upper right) button '''[SAVE]''' of '''set_object.fig'''. The object  can be later opened by the menu option '''[browse...]''' in the menu bar command '''[Projection object]''' of the GUI '''uvmat'''.
+When a 2D or 3D field is opened by '''uvmat.fig''', a default projection object called 'plane' is created, so that all field plots (in 2D and 3D) are considered as the result of a projection. New objects are created by the menu bar command  '''[Projection object]''' in the GUI '''uvmat'''.  The creation of a new object ('''points''', '''line'''....) can be initiated by selecting the corresponding item in the menu. In each case an auxiliary GUI '''set_object.fig''' describing the object properties appears, see next [#a6.2Objectproperties sub-section] for their definitions. This GUI can be directly edited and object coordinates can be set by mouse drawing on the plot, see [#a6.4Objectrepresentation section 6.4]. To validate edition on the GUI '''set_object.fig''', refresh the plots by pressing '''[REFRESH]'''. Objects can be saved as xml files with the (upper right) button '''[SAVE]''' of '''set_object.fig'''. The object  can be later opened by the menu option '''[browse...]''' in the menu bar command '''[Projection object]''' of the GUI '''uvmat'''.
 The names of the created objects are listed in the menu '''[!ListObject]'''. The properties of the object selected in this menu can be viewed by activating the check box '''[!CheckViewObject]'''. Check '''[!CheckEditObject]''' to allow object editing with '''set_object.fig'''.  The selected object is plotted in magenta, while the inactive ones are in blue. The field plot resulting from projection can be viewed in the GUI '''view_field''' by activating '''[!CheckViewField]'''. This option is automatically selected when a new object is created. Then the projection object used for the main plotting window in UVMAT can be selected by the menu '''[!ListObject_1]''' which reproduces the list of available objects. The active objects are plotted in magenta, while the inactive ones are in blue. The object can be deleted by pressing '''[!DeleteObject]'''.
 …
 === 8.2 The GUI geometry_calib.fig ===
 [[Image(geometry_calib.jpg)]]
+[[Image(geometry_calib.jpg)]]
 -''' Opening the GUI: ''' it is made visible  from the GUI '''uvmat.fig''' by  the menu bar command '''[!Tools/Geometric calibration] '''.  If calibration data already exist in the current file <!ImaDoc>, the corresponding parameters and the list of reference points are displayed in the table '''[!ListCoord]'''. The three first columns indicate the physical coordinates and the two last ones the corresponding image coordinates (in pixels). The physical unit is imposed as centimeter by the menu '''[!CoordUnit]''' to avoid mistakes. Calibration points can be alternatively introduced by opening any XML file <!ImaDoc> with the menu bar command '''[Import]''' of '''geometry_calib.fig'''. It is possible to import the whole information, option 'All', the calibration point coordinates only, or the calibration parameters only.
 …
 - ''' Import features''': by the menu bar tool '''[Import...]''', you can choose to import different data from a previous <!ImaDoc> file.
+  * '''Calibration points''': imports the calibration poins of a previous grid saved as a <!ImaDoc> file, the points and their coordinates will then appear in '''uvmat''' and '''geometry_calib'''.
+  * '''Intrinsic parameters''': as explained above it imports the intrinsic parameters from a previous grid saved as a <!ImaDoc> file. The parameters will appear in '''geometry_calib'''.
+  * '''All''': imports the calibration points and the intrinsic parameters from a <!ImaDoc> file. We can see them in '''geometry_calib'''.
+  * '''Grid file''':imports the <!ImaDoc> file in '''Point Lists''' in '''geometry_calib''' but none of the data appears in the coordinate table or the intrinsic parameter frame.
+ * '''Calibration points''': imports the calibration poins of a previous grid saved as a <!ImaDoc> file, the points and their coordinates will then appear in '''uvmat''' and '''geometry_calib'''.
+ * '''Intrinsic parameters''': as explained above it imports the intrinsic parameters from a previous grid saved as a <!ImaDoc> file. The parameters will appear in '''geometry_calib'''.
+ * '''All''': imports the calibration points and the intrinsic parameters from a <!ImaDoc> file. We can see them in '''geometry_calib'''.
+ * '''Grid file''':imports the <!ImaDoc> file in '''Point Lists''' in '''geometry_calib''' but none of the data appears in the coordinate table or the intrinsic parameter frame.
 === 8.3 Setting the reference plane(s) ===
 Deducing the physical coordinates from image coordinates requires information on the section plane. The default assumption is that the objects in the image are in the plane used for calibration, but '''uvmat''' can handle volume scanning by a laser plane. A set of section planes can be defined by their origin positions and rotation angle vectors. Theses planes are labelled by a ''z index'', assumed to be the frame index j (case of volume scan), or the index i modulo the number of slices !NbSlice (case of 'multilevel' scan). These settings are stored in the xml file <!ImaDoc> as part of the section <!GeometryCalib> and can be edited from '''uvmat.fig''' with the menu bar command '''[Tools/set slice]'''. A dialog box '''set_slices''' appears for entering the first and last section plane positions ''z'', as well as the number of slices and the option 'volume_scan' ('multilevel' otherwise). In the absence of 3D scan put twice the same value for first and last z.  Finally a tilt angle of the laser sheet, around the ''x'' and ''y'' axis, can be introduced, with a possible angular scanning from first to last section planes. After introduction of the plane position information, the z-index is displayed in the frame '''[!FileIndices]''' of '''uvmat.fig'''. The local ''z'' position of the mouse pointer, assumed to lay on the current section plane, is then displayed in '''[text_display]'''.
 …
  * '''[Inport Config]''': reads the XML configuration file of a previous computation (placed in a subfolder /0_XML), and fills the GUI with its content, so the calculation can be repeated.
- * '''[Inport Param]''': does the same as '''[Inport Config] '''but without refreshing the input file table and indices. This is useful to repeat a previous calculation for a new series, keeping the same parameters (note however that some processing parameters may be inconsistent with the current input files, so it is less reliable than''' [Inport Config].'''
  * '''[Help]''': displays this help file using the Matlab browser.
 …
 The action function is first activated when it is selected in the menu '''[!ActionName]'''. This first activation checks input data and sets the visibility of input GUI uicontrols.
+The actual start of the processing is triggered by pressing the button '''[RUN]'''. It can be run in local mode, i.e. on the current Matlab session, or as ''background'', by selecting this option in '''[!RunMode]'''. In mode ''background'', calculation is performed in a new Matlab session (without graphics) so that the current Matlab session is free for new operations. If a cluster system has been detected, a third option ''cluster'' appears in the menu, allowing to dispatch parallel computations on a computer cluster.
+For the cluster option, a compiled version of the action function is useful, to avoid installing Matlab on each node of the cluster. This is achieved by selecting the option ''.sh'' in the menu '''[!ActionExt]'''. If the compiled version is not yet available, or outdated, the GUI proposes a new compilation of the selected function (launching the function ''compile.m'' requiring the Matlab compilator toolbox). The use of compiled function on the cluster requires a file '!RunTime' whose address needs to be specified  in the parameter file PARAM.xml of the package UVMAT. The commands in '''series''' are set for the system 'oar', but adding the equivalent commands for another cluster system is straightforward (this must be done in the sub-function ''RUN_Callback'' of ''series.m'').
+The actual start of the processing is triggered by pressing the button '''[RUN]'''. It can be run in local mode, i.e. on the current Matlab session, or as ''background'', by selecting this option in '''[!RunMode]'''. In mode ''background'', calculation is performed in a new Matlab session (without graphics) so that the current Matlab session is free for new operations. If a cluster system has been detected, a third option 'cluster' appears in the menu, allowing to dispatch parallel computations on a computer cluster.
+When '''[RUN]''' is activated the information from the GUI '''series''' is transcripted to a file .xml in a subfolder '0_XML' of the folder containing the result files. Therefore the operation parameters are preserved, and can be retrieved in the GUI''' series''' by the menu bar command '''[Open config]'''. In the modes 'background' or 'cluster', input information for the calculation is transmitted by this xml file. In the mode 'cluster', the calculation is split into sub-calculations, with an xml file for each. A sub-folder '''/0_LOG''' then contains the messages sent by the computation as a replacement of the work window display of the usual interactive Matlab mode.
+For the option 'cluster', a compiled version of the action function is useful, to avoid installing Matlab on each node of the cluster. This is achieved by selecting the option ''.sh'' in the menu '''[!ActionExt]'''. If the compiled version is not yet available, or outdated, the GUI proposes a new compilation of the selected function (launching the function ''compile.m'' requiring the Matlab compilator toolbox). The use of compiled function on the cluster requires a file '!RunTime' whose address needs to be specified  in the parameter file PARAM.xml of the package UVMAT. The commands in '''series''' are set for the system 'oar', but adding the equivalent commands for another cluster system is straightforward (this must be done in the sub-function ''RUN_Callback'' of ''series.m'').
 === 10.7 Action functions of general use ===
 …
    * ''pair j1-j2:'' selects a given j index pair (sometimes denoted by letter index) for the whole time series. This is the most common case for PIV. Pair selection is performed in the menu '''[!ListPairCiv1]''' and '''[!ListPairCiv2]''' for the second iteration Civ2, see below. If timing from an XML file <!ImaDoc> has been detected, this is indicated in the edit box '''[!ImaDoc]''' and the corresponding time intervals are indicated (in ms). For some applications, this time interval may evolve in time, so that reference indices ref_i and ref_j are chosen for the display.
    * series (Di): selects a given  index interval for the i index, around a set of reference i indices. The intervals are denoted Di=0|1, -1|1, -1|2, -2|2 ... , corresponding to the index pairs i|i+1, i-1|i+1, i-1|i+2, i-2|i+2 ...around each reference index i. Pair selection is then performed in the menu '''[!ListPairCiv1]''' and '''[!ListPairCiv2]''' like for 'pair j1-j2'.
    * series (Dj): same as series (Di) but with the j index.
+   * series (Dj): same as series (Di) but with the j index.
  * '''displacement''': compare the current image to a fixed reference frame, as needed to measure the displacement with respect to this reference. The reference index (i index) is set by an edit box '''[num_OriginIndex]'''.
  * '''PIV volume''' performs PIV in volumes for frame sequences with two indices i and j. The second index j is assumed to represent a position in a volume laser scan, while i represents time. Therefore PIV volume requires the selection '''series (Di)''' for '''[!ListPairMode]'''.
 …
 A parameter '''[num_CorrSmooth]''' controls the smoothing of the image corelation curves used in civ, the default value 1 is generally used. Its value is set according to [https://servforge.legi.grenoble-inp.fr/projects/soft-uvmat/attachment/wiki/UvmatHelp/Nobach%26Honkanen%282005%29.pdf Nobach & Honkanen work (2005)], '''[num_CorrSmooth]'''=1 means it will be a 2x3-point regression (3 points on the ''x'' axis and 3 points on the ''y'' axis) whereas '''[num_CorrSmooth]'''=2 means it will be a 9-point regression.
 The search parameters ('''[!SearchBoxSize]''', '''[!SearchBoxShift]''') can be estimated using the press button '''[search range]'''. First introduce the estimated minimum and maximum values of each velocity component u and v (expressed in pixel displacement). The result depends on the time interval of the image pair.
+The search parameters ('''[!SearchBoxSize]''', '''[!SearchBoxShift]''') can be estimated using the press button '''[search range]'''. First introduce the estimated minimum and maximum values of each velocity component u and v (expressed in pixel displacement). The result depends on the time interval of the image pair.
   [[Image(11-2 CV1.png)]]
 …
 The button '''[TEST]''' allows the user to witness the correlation as a live plot. It first opens the source image in a new figure '''view_field'''. By moving the mouse in the figure, the local correlation box and the corresponding search box are drawn in the image, and the 2D correlation result then appears in a new figure 'Figure1 Image Correlation' which automatically pops up. It is possible to freeze the current correlation plot by left mouse selection. The figure belows shows the correlation process and the '''[!SearchBox]''' and '''[!CorrBox]''' explained before.
+  [[Image(civ1_test.jpg)]]
+[[Image(Correlation for PIV.png)]]
+  [[Image(civ1_test.jpg)]] [[Image(Correlation for PIV.png)]]
 The grid determines the positions of measured velocity vectors: it sets the central positions of the correlation boxes (in pixels) for the first image. A default regular grid can be set by the meshes '''[num_Dx] ''' and '''[num_Dy]''' (in pixels). Alternatively a custom [#a9.2Grids grid] can be stored in a text file and selected by the check box '''get grid'''. This is convenient to limitate the processing to a subregion or to fine tune the resolution.
 …
 === 11.3 FIX ===
+The FIX operation is used after civ to mark false vectors, using different criteria:
+'''- Warning flags: ''' these are flags (vec_F) indicating problems with the image correlation process.
+The FIX operation is used after civ to mark false vectors, using different criteria:
+'''- Warning flags: ''' these are flags (vec_F) indicating problems with the image correlation process.
  * vec_F=-2: select to eliminate vectors for which the maximum of the correlation function is close to the border of the search box (at a distance of two pixels or less), so that its maximum cannot be reliably obtained.
  * vec_F=3: the optimisation of the correlation function is unstable  or  local Intensity rms of the image =0. Must be selected.
+'''- Threshold on the image correlation:  ''' (vec_C) can be introduced by the edit box '''[num_!MinCorr]''' (value between 0 and 1). It removes vectors with poor correlation.
 '''- Threshold on the velocity modulus: ''' (expressed in pixels). It can remove either excessive values (threshold set by '''[num_MaxVel]''') or too small values (threshold set by '''[num_MinVel]'''). Erratic zero velocity vectors, produced by a fixed image background, can be eliminated by the latter criterium.
+ * vec_F=3: the optimisation of the correlation function is unstable  or  local Intensity rms of the image =0. Must be selected.
+ '''- Threshold on the image correlation:  ''' (vec_C) can be introduced by the edit box '''[num_!MinCorr]''' (value between 0 and 1). It removes vectors with poor correlation.
+'''- Threshold on the velocity modulus: ''' (expressed in pixels). It can remove either excessive values (threshold set by '''[num_MaxVel]''') or too small values (threshold set by '''[num_MinVel]'''). Erratic zero velocity vectors, produced by a fixed image background, can be eliminated by the latter criterium.
 '''- Manual fix: ''' Interactive fixing with the mouse is also possible, see [#a4.2Contourplots section 4.2].
 === 11.4 PATCH ===
 …
 - '''CIV2:''' provides a refined calculation of the velocity field, using the civ1 result as previous estimate. The civ1 field provides an estimated shift for each measurement point, so there is no edit box to enter shift parameter. The other parameters, in particular '''[!CorrBoxSize]''' and '''[!SearchBoxSize]''', have the same meaning as for Civ1. The image pair for civ2 ( set by the menu '''[!ListPairCiv2]''', can be different than the one used in civ1. It is generally advised to use a moderate time interval for civ1, to provide a first estimate avoiding false vectors, and to take a larger intervel for civ2, in order to optimize precision. As civ2 already knows where to look and takes into account image strain and rotation (with the option 'deformation') it allows for higher time intervals.
+Image deformation and rotation can be introduced before calculating the correlations, by selecting '''[!CheckDeformation]'''. This option  is useful in the presence of strong shear or vorticity.
+- '''FIX2:''' like '''[FIX1]''', except for a new possible flag value vec_F=4 which indicates that the difference between the estimator and the result is more than 1 pixel. This should be selected for excellent data (otherwise it may be too strict).
+Image deformation and rotation can be introduced before calculating the correlations, by selecting '''[!CheckDeformation]'''. This option  is useful in the presence of strong shear or vorticity.
+- '''FIX2:''' like '''[FIX1]''', except for a new possible flag value vec_F=4 which indicates that the difference between the estimator and the result is more than 1 pixel. This should be selected for excellent data (otherwise it may be too strict).
 - '''PATCH2:''' like '''[PATCH1]'''. Using the '''[TEST]''' option, we can here accept a difference between '''[Civ2]''' and '''[Patch2]''' higher than 0.2.
 …
 === 11.6 Stereoscopic PIV === #sec11.6
 To obtain the three velocity components in a plane with stereoscopic PIV, use the following procedure:
 Install two cameras viewing a common field with angle about 45 ° on each side. A system of titled objective lenses (Sheimpflug) allows to optimize the focus in the whole image.
+Make a careful geometric calibration, by taking the images of a grid positioned in the plane of the laser sheet used for particle illumination, as described in section [#GeometryCalib section 6].
+This calibration model is valid in air or with an interface air-water perpendicular to the line of sight for each camera. Otherwise, the calibration problem is more complex.
+Make a careful geometric calibration, by taking the images of a grid positioned in the plane of the laser sheet used for particle illumination, as described in section [#GeometryCalib section 6]. This calibration model is valid in air or with an interface air-water perpendicular to the line of sight for each camera. Otherwise, the calibration problem is more complex.
 Perform usual PIV for each image series.