Changes between Version 188 and Version 189 of UvmatHelp


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

--

Legend:

Unmodified
Added
Removed
Modified
  • UvmatHelp

    v188 v189  
    255255- '''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]''').
    256256
    257 - '''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]''').
     257- '''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]''').'''
    258258
    259259- '''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}).
     
    290290The second field can be removed by unselecting the check box '''[!SubField] '''.
    291291
    292 
    293292=== 4.6 Field transforms ===
    294293A 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].
     
    313312- '''Field calculation:''' a scalar can be calculated after projection, as selected by the menu '''[Fields]'''.
    314313
    315 - '''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.
    316  
    317 - '''Plotting:''' plot the results of projection, using the function ''plot_field.m''.
     314- '''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''.
    318315
    319316----
     
    437434These 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].
    438435
    439 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'''. 
     436When 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'''.
    440437
    441438The 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]'''.
     
    582579
    583580=== 8.2 The GUI geometry_calib.fig ===
    584 [[Image(geometry_calib.jpg)]] 
     581[[Image(geometry_calib.jpg)]]
    585582
    586583-''' 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.
     
    612609- ''' Import features''': by the menu bar tool '''[Import...]''', you can choose to import different data from a previous <!ImaDoc> file.
    613610
    614   * '''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'''.
    615 
    616   * '''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'''.
    617 
    618   * '''All''': imports the calibration points and the intrinsic parameters from a <!ImaDoc> file. We can see them in '''geometry_calib'''.
    619  
    620   * '''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.
    621 
     611 * '''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'''.
     612
     613 * '''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'''.
     614
     615 * '''All''': imports the calibration points and the intrinsic parameters from a <!ImaDoc> file. We can see them in '''geometry_calib'''.
     616
     617 * '''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.
    622618
    623619=== 8.3 Setting the reference plane(s) ===
    624 
    625620Deducing 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]'''.
    626621
     
    709704 * '''[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.
    710705
    711  * '''[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].'''
    712 
    713706 * '''[Help]''': displays this help file using the Matlab browser.
    714707
     
    735728The 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.
    736729
    737 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.
    738 
    739 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'').
     730The 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.
     731
     732When '''[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.
     733
     734For 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'').
    740735
    741736=== 10.7 Action functions of general use ===
     
    791786   * ''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.
    792787   * 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'.
    793    * series (Dj): same as series (Di) but with the j index. 
     788   * series (Dj): same as series (Di) but with the j index.
    794789 * '''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]'''.
    795790 * '''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]'''.
     
    820815A 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.
    821816
    822 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. 
     817The 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.
    823818
    824819  [[Image(11-2 CV1.png)]]
     
    826821The 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.
    827822
    828   [[Image(civ1_test.jpg)]]
    829 [[Image(Correlation for PIV.png)]]
     823  [[Image(civ1_test.jpg)]] [[Image(Correlation for PIV.png)]]
    830824
    831825The 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.
     
    836830
    837831=== 11.3 FIX ===
    838 The FIX operation is used after civ to mark false vectors, using different criteria:
    839 
    840 '''- Warning flags: ''' these are flags (vec_F) indicating problems with the image correlation process.
     832The FIX operation is used after civ to mark false vectors, using different criteria:
     833
     834'''- Warning flags: ''' these are flags (vec_F) indicating problems with the image correlation process.
     835
    841836 * 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.
    842  * vec_F=3: the optimisation of the correlation function is unstable  or  local Intensity rms of the image =0. Must be selected. 
    843  
    844 '''- 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. 
    845 
    846 '''- 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. 
     837 * vec_F=3: the optimisation of the correlation function is unstable  or  local Intensity rms of the image =0. Must be selected.
     838
     839 '''- 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.
     840
     841'''- 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.
    847842
    848843'''- Manual fix: ''' Interactive fixing with the mouse is also possible, see [#a4.2Contourplots section 4.2].
    849 
    850844
    851845=== 11.4 PATCH ===
     
    857851- '''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.
    858852
    859 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.
    860 
    861 - '''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).   
    862 
     853Image 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.
     854
     855- '''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).
    863856
    864857- '''PATCH2:''' like '''[PATCH1]'''. Using the '''[TEST]''' option, we can here accept a difference between '''[Civ2]''' and '''[Patch2]''' higher than 0.2.
     
    867860
    868861=== 11.6 Stereoscopic PIV === #sec11.6
    869 
    870862To obtain the three velocity components in a plane with stereoscopic PIV, use the following procedure:
    871863
    872864Install 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.
    873865
    874 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].
    875 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.
     866Make 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.
    876867
    877868Perform usual PIV for each image series.