Changes between Version 174 and Version 175 of UvmatHelp


Ignore:
Timestamp:
Jan 23, 2015, 10:53:36 AM (9 years ago)
Author:
vaillant1p
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UvmatHelp

    v174 v175  
    2626The present on-line document is the reference document for the version currently available on the svn server. Features not yet implemented or tested (in particular 3D features) are marked by **. The document is accessible within Matlab by help buttons in the GUIs.
    2727
    28 A short comment about  each GUI element, called ''uicontrol'' (push buttons, edit boxes, menus..), as well as the ''tag name'' of this ''uicontrol'', is provided as a tool tip window by moving the mouse over it. In the present help document, the tag of a GUI element is quoted as '''[ tag]''', a file name in the package is enhanced as ''fct name.m'', and commands on the Matlab workspace as  '>> command’. The tag name can be also obtained by pressing the right hand mouse button on the element.
     28A short comment about  each GUI element, called ''uicontrol'' (push buttons, edit boxes, menus..), as well as the ''tag name'' of this ''uicontrol'', is provided as a tool tip window by moving the mouse over it. In the present help document, a GUI element is quoted as '''GUI''', its tags as '''[tag]''', a file name in the package is enhanced as ''fct name.m'', and commands on the Matlab workspace as  '>> command’. The tag name can be also obtained by pressing the right hand mouse button on the element.
    2929
    3030Information is also provided as comments in each function. Type '>>help fct_name'  to get it, or open it with an editor.
     
    172172   * Intensity < 20: ('black mask') the vector in this place will be set to zero.
    173173   * 20 < Intensity < 200:('gray mask') the vector in this place will be absent.
    174    * Intensity>200  the vector will be computed  The mask corresponding to an image or velocity field can be displayed in the GUI '''uvmat''' by selecting the check box '''[view_mask]([!CheckMask])''' on the upper left. Images with appropriate name can be automatically recognised by '''uvmat''' and civ functions, see [#a9-Masksandgrids section 9.1]. Otherwise file selection by a browser is proposed when '''[view_mask]''' is selected.
     174   * Intensity>200  the vector will be computed  The mask corresponding to an image or velocity field can be displayed in the GUI '''uvmat''' by selecting the check box '''[view_mask]''' ('''[!CheckMask]''') on the upper left. Images with appropriate name can be automatically recognised by '''uvmat''' and civ functions, see [#a9-Masksandgrids section 9.1]. Otherwise file selection by a browser is proposed when '''[view_mask]''' is selected.
    175175
    176176 * ''' Grid:''' List of numbers (in ASCII text) specifying the set of points where the PIV processing is performed. It specifies the number of points n and a corresponding list of x and y coordinates expressed in image pixels, as follows
     
    200200}}}
    201201
    202  * '''.cmx''' ASCII text files containing the parameters sent by the GUI '''civ''' to the CIV fortran programmes. Each velocity field named *.nc results from a parameter file *.cmx. It can be opened by the browser of the GUI '''uvmat'''. In a later version of CIVx**, the .cmx file is replaced by a .xml ’!CivDoc’ file.
     202 * '''.cmx''' ASCII text files containing the parameters sent by the GUI '''civ_input''' to the CIV fortran programmes. Each velocity field named *.nc results from a parameter file *.cmx. It can be opened by the browser of the GUI '''uvmat'''. In a later version of CIVx**, the .cmx file is replaced by a .xml ’!CivDoc’ file.
    203203
    204204 * '''.log''' ASCII text files, containing information about processing in batch mode. Each velocity field named *.nc is associated with a  file *.log. A file *_patch.log is similarly produced by the ’patch’ program.  These files can be opened by the browser of the GUI '''uvmat'''.
    205205
    206206=== 3.7 Data organisation in a  project ===
    207 The package is designed to foster a good data organisation. The raw data from a project should be organised as:[[BR]]   '''!Project/Campaign/Experiment/DataSeries/data files'''.
     207The package is designed to foster a good data organisation. The raw data from a project should be organised as:[[BR]] '''[!Project/Campaign/Experiment/DataSeries/data files]'''.
    208208
    209209 * '''Project''' contains all information on a project.
     
    294294A 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].
    295295
    296 These functions can transform fields into polar coordinates, do image filtering, Fourier transform, signal analysis for a 1D input field... Other functions can be easily written using those as templates.  The  general form of such functions is  !DataOut=transform_fct(!DataIn,!XmlData,!DataIn_1,!XmlData_1) where Data is an input field object, as described in [#a5.2FieldrepresentationasMatlabstructure section 5.2], and !XmlData the content of the XML file Imadoc, as stored in the UVMAT GUI. !XmlData contains in particular the element .[wiki:GeometryCalib] containing the calibration parameters, see  [#a8.2TheGUIgeometry_calib.fig section 8.2].
     296These functions can transform fields into polar coordinates, do image filtering, Fourier transform, signal analysis for a 1D input field... Other functions can be easily written using those as templates.  The  general form of such functions is  !DataOut=transform_fct(!DataIn,!XmlData,!DataIn_1,!XmlData_1) where Data is an input field object, as described in [#a5.2FieldrepresentationasMatlabstructure section 5.2], and !XmlData the content of the XML file Imadoc, as stored in the UVMAT GUI. !XmlData contains in particular the element [!GeometryCalib] containing the calibration parameters, see  [#a8.2TheGUIgeometry_calib.fig section 8.2].
    297297
    298298=== 4.7 Succession of operations: ===
     
    320320== 5 - Field structures ==
    321321=== 5.1 Griding of data ===
    322 Physical fields can be defined either on regular grids, either scattered on an unstructured set of positions. Some measurements techniques, like PIV or particle tracking, provided unstructured data, while most methods of analysis require data  on a regular grid. This can be done by interpolation, defining a projection on a plane (with !ProjMode='interp...', see  [#ProjObject next section]).  The three possibilities of griding are defined as follows:
    323 
    324 -'''Regular grid:'''
     322Physical fields can be defined either on regular grids, either scattered on an unstructured set of positions. Some measurements techniques, like PIV or particle tracking, provided unstructured data, while most methods of analysis require data  on a regular grid. This can be done by interpolation, defining a projection on a plane (with '''[!ProjMode='interp...']''', see  [#ProjObject next section]).  The three possibilities of griding are defined as follows:
     323
     324- '''Regular grid:'''
    325325
    326326Each field is then a multi-dimensional array whose dimensions match the space dimensions.  Because of the grid regularity, the set of positions is fully defined by the coordinate value for the first and last index along each dimension of the array.
    327327
    328 -'''Structured orthogonal grid''':
     328- '''Structured orthogonal grid''':
    329329
    330330Each field is again a multi-dimensional array V whose dimensions match the space dimensions, but the coordinates may not be regularly spaced, so they are represented as a monotonic 1D array variable with the same length as the corresponding dimension of V.  This is called a ''coordinate variable'' (see [#a7.1TheNetCDFformat section 7.1]).
    331331
    332 -'''Unstructured coordinates:'''
     332- '''Unstructured coordinates:'''
    333333
    334334Fields may be alternatively obtained on a unstructured (grid-less) set of positions. The coordinates are then described by coordinate arrays X(nb_points), Y(nb_points), Z(nb_points). The corresponding field values are then represented as variables U(nb_point),V(nb_point) for each vector component, or alternatively by V(nb_points, j, i), where i, j possibly stand for vector or tensor components.
    335335
    336 -'''Thin plate shell (tps) interpolation:'''
     336- '''Thin plate shell (tps) interpolation:'''
    337337
    338338This is a multi-dimensional generalisation of the spline interpolation/smoothing, an optimum way to interpolate data with minimal  curvature of the interpolating function. The result at an interpolation position vector ${\bf r}$ is expressed in the form, (see ThinPlateShell)
     
    372372
    373373=== 5.3 Conventions for attributes in field objects: ===
    374 -'''Global attributes active in UVMAT''': those are used for plot settings or data processing.
     374- '''Global attributes active in UVMAT''': those are used for plot settings or data processing.
    375375
    376376 * 'Conventions':
     
    383383 * '!TimeUnit': character string representing the unit of time (consistently for Time, Dt and velocity).
    384384
    385 -'''Global attributes , unactive''' those are merely used for information purpose
     385- '''Global attributes , unactive''' those are merely used for information purpose
    386386
    387387 * Project: recalls the project name.
     
    394394 * 'long_name':(convention from [unidata->http://www.unidata.ucar.edu:]) a long descriptive name, could be used for labeling plots, for example. If a variable has no long_name attribute assigned, the variable name should be used as a default.
    395395
    396 -'''Attributes of variables:'''
     396- '''Attributes of variables:'''
    397397
    398398 * Mesh: suggested step value to discretize the values of the variable, used to define the bins for histograms.
     
    400400 * Unit or 'units' (convention from [unidata->http://www.unidata.ucar.edu:]) : char string giving the unit of a variable, used  in plot axis labels (overset by global attributes '!CoordUnit' and '!TimeUnit' if defined).
    401401
    402 -'''The attribute 'Role':''' the following options are used for the attribute 'Role':
     402- '''The attribute 'Role':''' the following options are used for the attribute 'Role':
    403403
    404404 * 'ancillary': information of secondary use, indicating for instance an error estimate of field variables within a field cell (omitted in plotting).
     
    437437These 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].
    438438
    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'''.
     439When 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'''.
    440440
    441441The 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]'''.
     
    461461 * ''' Angle: '''three component rotation vector which defines the orientation of the object coordinate axis, for 'plane' and 'volume'. In 2D, this rotation vector has only one component along z, defining a rotation angle in the plane (expressed in degrees). This applies also to the main axis of 'ellipse' and 'rectangle'. In 3D, line objects ('line', 'polyline','rectangle','polygon','ellipse') are assumed contained in a plane, and 'Angle' defines the orientation of this plane.
    462462
    463  * ''' RangeX ''', ''' RangeY ''', ''' RangeZ: ''' bounds defining a range of projection along each coordinate with respect to the object. These ranges have one or two values depending on the object type.
     463 * ''' RangeX''', ''' RangeY''', '''RangeZ:''' bounds defining a range of projection along each coordinate with respect to the object. These ranges have one or two values depending on the object type.
    464464   * 'points': the only relevant range is RangeX, with one value (a radius around the point).
    465465   * 'lines': the only relevant range is RangeY, with one value, a radius transverse to the line.
     
    469469   * 'volume': RangeX, RangeY, RangeZ (two values each) define a selected volume in the data set.
    470470
    471  * ''' DX ''', ''' DY ''', ''' DZ: '''mesh  along each coordinate defining a grid for interpolation.
     471 * ''' DX''', ''' DY''', ''' DZ: '''mesh  along each coordinate defining a grid for interpolation.
    472472
    473473 * ''' Coord: ''' matrix with two (for 2D fields) or three columns defining the object position.
     
    481481
    482482=== 6.3 Projection modes ===
    483 Each field variable yields a corresponding variable with the same name in the projected field. Integral quantities (circulation, flux...) can be also calculated. The result of projection depends on the object type, the nature of the coordinates, the ''Role'' of field variables and on the projection mode '''!ProjMode''':
     483Each field variable yields a corresponding variable with the same name in the projected field. Integral quantities (circulation, flux...) can be also calculated. The result of projection depends on the object type, the nature of the coordinates, the ''Role'' of field variables and on the projection mode '''[!ProjMode]''':
    484484
    485485 * ''' !ProjMode = 'projection':  '''  this is a normal projection  of the field data in a range of action around the object, as defined by the parameters '''[RangeX], [RangeY], [RangeZ]'''. The projection of an input variable defined on unstructured coordinates therefore remains unstructured. By contrast, an input variable defined on a regular grid always yields a projected variable on a regular grid (for instance on a line or plane). Data marked as false are projected, with their error flag, only for 'plane' or 'volume'.
     
    540540
    541541=== 7.2 The GUI get_field ===
    542 This GUI '''get_field.fig''' is aimed at browsing a NetCDF file, showing all its variables, attributes and variable dimensions. Variables can be selected for input in '''uvmat''' or '''series'''. The GUI is opened by selecting the option '''get_field...''' in the menu '''[!FieldName]''' of '''uvmat''' or '''series'''. This option is automatically selected when the input NetCDF file is not recognised as CIV data.
     542This GUI '''get_field.fig''' is aimed at browsing a NetCDF file, showing all its variables, attributes and variable dimensions. Variables can be selected for input in '''uvmat''' or '''series'''. The GUI is opened by selecting the option '''[get_field...]''' in the menu '''[!FieldName]''' of '''uvmat''' or '''series'''. This option is automatically selected when the input NetCDF file is not recognised as CIV data.
    543543
    544544[[Image(7-2 The GUI get_field.png)]]
     
    546546When a NetCDF input file opened, its full name, including path, is displayed in the upper window '''[inputfile]'''. The names and value of the global attributes are listed in the left column '''[attributes]''', the list of variables in the central column '''[variables]''', and the list of dimension names and values in the right column '''[dimensions]'''. By selecting one of the variables in the central column, the corresponding variable attributes and dimensions are displayed in the left and right columns respectively. Note that the whole content of the NetCDF file can be obtained by the function ''nc2struct.m''. Input fields can be selected according to three options, chosen by the menu '''[!FieldOption]'''.
    547547
    548 -'''1D plot:''' to plot a simple graph, ordinate versus abscissa. Select by the menu '''[ordinate]''' the variable(s) to plot as ordinate (use the key '''Ctrl''' for multiple selection). Then select the corresponding abscissa in the column '''[abscissa]'''.  If the variable is indexed with more than one dimension, each component is plotted versus the first index (like with the plot Matlab function ''plot.m''). If the option '''[matrix index]'''('''[!CheckDimensionX]''') is selected, the ordinate variable is plotted versus its index.
     548-'''1D plot:''' to plot a simple graph, ordinate versus abscissa. Select by the menu '''[ordinate]''' the variable(s) to plot as ordinate (use the key '''Ctrl''' for multiple selection). Then select the corresponding abscissa in the column '''[abscissa]'''.  If the variable is indexed with more than one dimension, each component is plotted versus the first index (like with the plot Matlab function ''plot.m''). If the option '''[matrix index]''' ('''[!CheckDimensionX]''') is selected, the ordinate variable is plotted versus its index.
    549549
    550550-'''scalar:''' to plot scalar fields as images. The variable representing the scalar is selected in the first column '''[scalar]''', with coordinates respectively selected in '''[Coord_x] ''' and '''[Coord_y]'''. Alternatively, matrix index can be used as coordinate if the options '''[matrix index]'''('''[CheckDimensionX]''' and '''[CheckDimensionY]''') are selected.
     
    565565The ''physical coordinates'' are defined from the experimental set-up. The correspondance with images is obtained by identifying a set of calibration points whose positions are known in the physical coordinate system. A cartesian calibration grid covering the whole image is the best option, but any set of calibration points can be used. We handle three kinds of transforms:
    566566
    567 -'''rescale''': linear rescaling along ''x'' and ''y'' + translation (no rotation nor deformation).
    568 
    569 -'''linear''': general linear transform, including translation and rotation (but no projection effects).
    570 
    571 -'''3D_linear:''' this transform handles projection effects, needed if the observed plane is not perpendicular to the line of sight. It involves a 3D calibration needed to account for the depth effects occuring in volume scan.
    572 
    573 -'''3D_quadr:''' this is like 3D_linear, but takes also into account a quadratic deformation by the optics which occurs for wide fields of view (small focal lengths).
    574 
    575 -'''3D_extrinsic:''' this is like 3D_quadr, but uses intrinsic parameters of the camera, as explained below.
     567- '''rescale''': linear rescaling along ''x'' and ''y'' + translation (no rotation nor deformation).
     568
     569- '''linear''': general linear transform, including translation and rotation (but no projection effects).
     570
     571- '''3D_linear:''' this transform handles projection effects, needed if the observed plane is not perpendicular to the line of sight. It involves a 3D calibration needed to account for the depth effects occuring in volume scan.
     572
     573- '''3D_quadr:''' this is like 3D_linear, but takes also into account a quadratic deformation by the optics which occurs for wide fields of view (small focal lengths).
     574
     575- '''3D_extrinsic:''' this is like 3D_quadr, but uses intrinsic parameters of the camera, as explained below.
    576576
    577577The 3D options involve a full 3D calibration relying on the [attachment:3D_view.pdf pinhole camera  model]. The method was first proposed by R.Y. Tsai, 'An Efficient and Accurate Camera Calibration Technique for 3D Machine Vision'. Proceedings of IEEE Conference on Computer Vision and Pattern Recognition, Miami Beach, FL, pp. 364-374 (1986). We use a more recent version, with the toolbox [->http://www.vision.caltech.edu/bouguetj/calib_doc/] . 3D calibrations are done in two steps. The camera'' intrinsic parameters'', which are the focal length and the quadratic deformation coefficient, are first determined by different views of the same grid observed at different angles. Then the ''extrinsic parameters'', which represent the rotation angles and translation of the physical coordinates with respect to the camera, are obtained with a single image of the grid positioned in a known plane $z=cte$. The option 3D_extrinsic allows the user to do only the second step from known intrinsic parameters. Those depend only on the camera with its objective lens and focus adjustement. Note that these 3D options require a calibration grid, with a sufficient number of calibration points covering the whole image.
     
    604604To reproduce the same calibrationn for image series, open one of the image in the series, and apply again the calibration with the same points, keeping the GUI geometry_calib opened.
    605605
    606 To calibrate at once a set of experiments, a better alternative is the command '''[REPLICATE]'''. Open a folder  '''Campaign''', parent of the folders '''Experiment''' to treat. The GUI '''data_browser.fig''', also described in [#a3.7Dataorganisationinaproject section 3.7], then pops up. A two-column display appears, with the list of '''Experiments''' on the left and the list of corresponding '''[!DataSeries]''' on the right. Select the list of experiments to calibrate, and a single camera name in '''[!DataSeries]''', then validate by pressing '''OK'''.
    607 
    608 -'''3D calibration''': 3D projection is handled by the options in '''[calib_type]''' '3D_lin' or '3D_quad' (if non-linear distortion is significant). By default, the set of calibration points is assumed to be contained in a single plane ''z''=0. For a correct determination of the 3D features, the normal to this plane must be tilted with respect to the line of view. Otherwise this problem of indetermination can be resolved by using a set of (typically 5-10) calibrations images using a plane grid with different tilting angles (for precision the grid must cover a large area of the view field). On each image, get calibration points with the tool '''[!Tools/Detect grid]''', introducing the appropriate grid mesh. Do not fill info on ''z'' coordinates. Store the points each time (without applying calibration at this stage), which fills the list [!ListCoordFiles] of file names. Then introduce a last grid image which will be considered as defining the orientation of the ''z'' axis, perpendicular to the grid. Detect points on this last image, but instead of storing them, apply the calibration with the option 3D_linear or 3D_quadr. A non-zero ''z'' position of this grid can be introduced by a z translation performed with '''!Tools/Translate points'''.
    609 
    610 -'''Intrinsic parameters''': the previous procedure first determines the extrinsic parameters which characterize the camera optics (focal lengths and nonlinear deformation parameter). Then the extrinsic parameters, translation and rotation of the camera with respect to the reference grid, are determined on the last grid image. If the same optics is used in a new experiment, it is possible to skip the multiplane detection, importing the intrinsic parameters from a previous <!ImaDoc> file by the menu bar tool '''[!Import/Intrinsic]''' parameters, then applying the calibration with the option '3D_extrinsic' with the reference grid image only.
    611 
    612 -'''Section planes:''' 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]'''.
    613 
    614 -'''Refraction effect:''' refraction effect can be accounted for if calibration was done in air by selecting the check box refraction, and introducing the water height (assumed at ''z''=cte) and refraction index. The apparent distance reduction for objects below the water height will be then taken into account.
     606To calibrate at once a set of experiments, a better alternative is the command '''[REPLICATE]'''. Open a folder  '''Campaign''', parent of the folders '''Experiment''' to treat. The GUI '''data_browser.fig''', also described in [#a3.7Dataorganisationinaproject section 3.7], then pops up. A two-column display appears, with the list of '''Experiments''' on the left and the list of corresponding '''[!DataSeries]''' on the right. Select the list of experiments to calibrate, and a single camera name in '''[!DataSeries]''', then validate by pressing '''[OK]'''.
     607
     608-''' 3D calibration''': 3D projection is handled by the options in '''[calib_type]''' '3D_lin' or '3D_quad' (if non-linear distortion is significant). By default, the set of calibration points is assumed to be contained in a single plane ''z''=0. For a correct determination of the 3D features, the normal to this plane must be tilted with respect to the line of view. Otherwise this problem of indetermination can be resolved by using a set of (typically 5-10) calibrations images using a plane grid with different tilting angles (for precision the grid must cover a large area of the view field). On each image, get calibration points with the tool '''[!Tools/Detect grid]''', introducing the appropriate grid mesh. Do not fill info on ''z'' coordinates. Store the points each time (without applying calibration at this stage), which fills the list [!ListCoordFiles] of file names. Then introduce a last grid image which will be considered as defining the orientation of the ''z'' axis, perpendicular to the grid. Detect points on this last image, but instead of storing them, apply the calibration with the option 3D_linear or 3D_quadr. A non-zero ''z'' position of this grid can be introduced by a z translation performed with '''[!Tools/Translate points]'''.
     609
     610-''' Intrinsic parameters''': the previous procedure first determines the extrinsic parameters which characterize the camera optics (focal lengths and nonlinear deformation parameter). Then the extrinsic parameters, translation and rotation of the camera with respect to the reference grid, are determined on the last grid image. If the same optics is used in a new experiment, it is possible to skip the multiplane detection, importing the intrinsic parameters from a previous <!ImaDoc> file by the menu bar tool '''[!Import/Intrinsic]''' parameters, then applying the calibration with the option '3D_extrinsic' with the reference grid image only.
     611
     612-''' Section planes:''' 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]'''.
     613
     614-''' Refraction effect:''' refraction effect can be accounted for if calibration was done in air by selecting the check box refraction, and introducing the water height (assumed at ''z''=cte) and refraction index. The apparent distance reduction for objects below the water height will be then taken into account.
    615615
    616616[[Image(browse_data_small.jpg)]] [[Image(set_slices_small.jpg)]]
     
    655655== 9 - Masks and grids ==
    656656=== 9.1 Masks ===
    657 Mask files are used to restrict the domain of CIV processing, to take into account fluid boundaries or invalid image zones. They must be stored as .png images with 8 bits, as described in [#MaskGrids section 3.6].  Mask files are automatically recognised by '''uvmat.fig''' and '''civ.fig''' if they are named [filebase '_xxmask_' 'filenumber' '.png'], where xx is the number of masks (nbslices) used when the series of fields corresponds physically to a set of nbslices positions. The mask filenumber used is the image field number modulo nbslices. Use xx=1 in the default case of a fixed position and a single mask. Masks can be made by pressing the menu bar '''[!Tools/Make mask]''' on the GUI UVMAT. The mask is created interactively with the mouse on the current image.
     657Mask files are used to restrict the domain of CIV processing, to take into account fluid boundaries or invalid image zones. They must be stored as .png images with 8 bits, as described in [#MaskGrids section 3.6].  Mask files are automatically recognised by '''uvmat.fig''' and '''civ.fig''' if they are named [filebase '_xxmask_' 'filenumber' '.png'], where xx is the number of masks (nbslices) used when the series of fields corresponds physically to a set of nbslices positions. The mask filenumber used is the image field number modulo nbslices. Use xx=1 in the default case of a fixed position and a single mask. Masks can be made by pressing the menu bar '''[Tools/make mask]''' on the GUI UVMAT. The mask is created interactively with the mouse on the current image.
    658658
    659659First open an input image file name with the browser, or the edit box and carriage return. From the image name, a corresponding mask name is proposed in the lower edit box. It should be edited if a series of masks is made, in case of mutipositions (number nbslices) of the laser sheet in a series. The names must be [filebase '_xxmask' 'filenumber' '.png'], where xx is the number of masks (nbslices). The mask filenumber used is the image field number modulo nbslices. The filenumber can be incremented by the NEXT press button.
     
    675675The root path, subdirectory, root file name and extension are introduced in the different columns of the table '''[!InputTable]'''. The nomenclature for file indexing is represented in the column '''[!NomType]''', the index extension for the first file in the series.
    676676
    677 Several input file series can be introduced simultaneously with the upper menu bar, or filling manually the successive lines of '''!InputTable'''. To get a new line, press the 'down' keyboard arrow after selecting the last existing line (this copies by default the last line content to the new line). A line can be suppressed by selecting it and pressing the key 'Suppress'. Press the button '''[REFRESH]''' to validate the input (checking the existence of the file series) after any editing.
     677Several input file series can be introduced simultaneously with the upper menu bar, or filling manually the successive lines of '''[!InputTable]'''. To get a new line, press the 'down' keyboard arrow after selecting the last existing line (this copies by default the last line content to the new line). A line can be suppressed by selecting it and pressing the key 'Suppress'. Press the button '''[REFRESH]''' to validate the input (checking the existence of the file series) after any editing.
    678678
    679679The panel '''[!IndexRange]''' specifies the range of input file or field indices to process while the panel Action specifies the processing function. New processing functions can be added by the user. The files resulting from the processing are put in a folder with the same path !RootPath as the folder !SubDir containing the input files. The name of this output folder  is defined in '''[!OuputSubdir]''': the default name is the input folder ''!SubDir'', followed by an extension depending on the processing function.
     
    688688The menu bar at the top of the GUI contains the following buttons:
    689689
    690  * '''[Open]''': Open or browse input files. It operates like for the GUI UVMAT, except that there are now two possibilities: '''browse...'''  or '''browse_append...''' The latter appends a new input line to the table '''[!InputTable]''' while the former refreshes the table.
     690 * '''[Open]''': Open or browse input files. It operates like for the GUI UVMAT, except that there are now two possibilities: '''[browse...]'''  or '''[browse_append...]''' The latter appends a new input line to the table '''[!InputTable]''' while the former refreshes the table.
    691691
    692692 * '''[Open campaign]''':  does the same as '''[Open]''' but scans the data organised as a project/campaign, see [https://servforge.legi.grenoble-inp.fr/#a3.7Dataorganisationinaproject section 3.7].
     
    711711
    712712=== 10.5   Field transform, projection object and mask ===
    713 A transform function can be introduced by the menu '''[!TransformName]''' in the frame '''[!FieldTransform]'''. New transform functions can be introduced by the option 'more....'. Its path is then recorded and displayed in '''[!TransformPath]. Transform '''functions act field by field to modify the input (for instance transforming image to physical coordinates), like in the GUI UVMAT, while the '''Action''' functions act on the whole series.
     713A transform function can be introduced by the menu '''[!TransformName]''' in the frame '''[!FieldTransform]'''. New transform functions can be introduced by the option 'more....'. Its path is then recorded and displayed in '''[!TransformPath]. Transform '''functions act field by field to modify the input (for instance transforming image to physical coordinates), like in the GUI UVMAT, while the '''[Action]''' functions act on the whole series.
    714714
    715715A projection object can be introduced by selecting the check box '''[!CheckObject]'''. If a projection object has been already created the  opened interface '''set_object.fig''' will be used. Otherwise a browser appears to open an object file (XML). It is possible to view the current projection object by pressing '''[view]''', edit it by selecting '''[edit]''', or delete it by pressing '''[delete]'''.
    716716
    717 Similarly the check box '''[!CheckMask]''' can be used to select a mask option. These different menus only appear if they are needed as input of the currently selected '''Action''' function.
     717Similarly the check box '''[!CheckMask]''' can be used to select a mask option. These different menus only appear if they are needed as input of the currently selected '''[Action]''' function.
    718718
    719719=== 10.6 The frame [Action] ===
    720 The processing function is chosen in the menu '''[!ActionName]'''. The first option ''check_data_files'' lists the selected input file series and checks their existence. This is a good first test before starting a processing operation since all actions operate on the same input file series. The option ''aver_stat'' calculates  a global average on the successive fields, while ''time_series'' provides a time series. The option ''merge_proj'' is used to project a whole series on a given grid, or to create a file series by concatenation of different fields. These processing functions are described with more details in next sub-sections. The option ''civ_series'' gives access to the PIV processsing, see section [#Civ: section 11].  Finally any additional function can be called and included in the menu by selecting the option ''more...'' . The corresponding path is displayed in '''!ActionPath'''.
     720The processing function is chosen in the menu '''[!ActionName]'''. The first option ''check_data_files'' lists the selected input file series and checks their existence. This is a good first test before starting a processing operation since all actions operate on the same input file series. The option ''aver_stat'' calculates  a global average on the successive fields, while ''time_series'' provides a time series. The option ''merge_proj'' is used to project a whole series on a given grid, or to create a file series by concatenation of different fields. These processing functions are described with more details in next sub-sections. The option ''civ_series'' gives access to the PIV processsing, see section [#Civ: section 11].  Finally any additional function can be called and included in the menu by selecting the option ''more...'' The corresponding path is displayed in '''[!ActionPath]'''.
    721721
    722722The 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.
    723723
    724 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.
    725 
    726 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'').
     724The 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.
     725
     726For 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'').
    727727
    728728=== 10.7 Action functions of general use ===
     
    730730
    731731 * ''check_data_files:'' gives the series of files selected for processing and checks their existence. The oldest modified file is indicated, which is useful to detect whether any file in a civ processing is missing (then the oldest file is not updated). For NetCDF files, the last operation made (civ1, fix1, patch1, civ2, fix2, patch2) is indicated. The details of each NetCDF file can be dispalyed by selecting it with the mouse in the list.
    732  * ''aver_stat'': this option provides any average over the processed files. If '''[!NbSlice]''' is not equal to 1, the average is performed slice by slice, providing !NbSlice results.   If a projection object is selected (check box '''[!CheckObject]'''), the field is projected before averaging. For unstructured coordinates varying for successive fields, the data is linearly interpolated on the coordinates of the first field in the series. It is then advised to project the fields on a regular grid, creating a projection object of type '''plane''' with projection mode '''interp_lin''' or '''interp_tps'''. With a projection mode 'inside' or 'outside', the global histogram of field variables on the selected region will be obtained. In the case of two input files series, the field difference will be performed like with the interface uvmat.fig. It is not possible to use more than two input series for this function.
     732 * ''aver_stat'': this option provides any average over the processed files. If '''[!NbSlice]''' is not equal to 1, the average is performed slice by slice, providing !NbSlice results.   If a projection object is selected (check box '''[!CheckObject]'''), the field is projected before averaging. For unstructured coordinates varying for successive fields, the data is linearly interpolated on the coordinates of the first field in the series. It is then advised to project the fields on a regular grid, creating a projection object of type '''plane''' with projection mode '''[interp_lin]''' or '''[interp_tps]'''. With a projection mode 'inside' or 'outside', the global histogram of field variables on the selected region will be obtained. In the case of two input files series, the field difference will be performed like with the interface uvmat.fig. It is not possible to use more than two input series for this function.
    733733 * ''time_series:'' this action provides a time series of the input field, possibly projected . Thus projection on 'points' lead to time series of the projected variable(s) for each point, projection by interpolation on a line will (x,time) field, while projection on a plane gives a 3D matrix, whose first index corresponds to time. Note that for a vector field, projection on a tilted line or plane yields the vector components longitudinal and normal to the object. To preserve the original ''x'' and ''y'' components, introduce them as ''scalar'', not ''vectors''. In the case of two input files series, the field difference will be perfomed like with the interface '''uvmat.fig'''. It is not possible to use more than two input series for this funtion.
    734734 * ''merge_proj'': this option allows to merge several field series in a single one. This is useful to merge fields obtained with different cameras. Select the different series, using the input option ''append''. In this case, it is generally useful to interpolate the fields on a single grid. For that purpose select a projection object of type 'plane' with projection mode 'interp_lin', or 'interp_tps' to get spatial derivative. Since the different views have their own calibration, it is important to use the option 'phys' (menu menu_coord), and to create the grid in phys coordinates.
    735735 * ''civ_series'': does PIV processing, see section [#Civ: section 11].
    736736
    737 === 10.8 Other functions Action... ===
    738 With the option ''more...'' in !ActionName, a browsers pops up to choose an Action function. Some examples of  functions are in the subdirectory ''{/series}'' of the folder containing '''''umat'''''. A few more examples (less reliable) are in the subfolder ''{/series/usr_fct }'', a good place to put your own functions.
     737=== 10.8 Other functions Action ===
     738With the option '''[more...]''' in [!ActionName], a browsers pops up to choose an Action function. Some examples of  functions are in the subdirectory ''{/series}'' of the folder containing '''''umat'''''. A few more examples (less reliable) are in the subfolder ''{/series/usr_fct}'', a good place to put your own functions.
    739739
    740740 * ''sub_background.m'': used to removed a mean background to the images. This is useful before CIV processing when some fiked features are visible in the background (when the laser sheet is close to the bottom).
    741  * ''ima_levels.m'': provides images with modified grey scale intensity to avoid blinking effects on particles.''''''''''
     741 * ''ima_levels.m'': provides images with modified grey scale intensity to avoid blinking effects on particles.
    742742 * ''ima2vol.m'' produce volume images for 3D3C PIV.
    743743 * ''turb_stat.m'': produces turbulent statistics (Reynolds stress tensor).
    744744
    745 These can be used as template to create other functions. The general input of these functions in Matlab structure 'Param' which contains all the input parameters as given by the GUI series (see comments in the function for details). For batch operations, as needed for the cluster, this input is replaced by the name of an XML file which contains these parameters (this is the file produced in the floder '''/0_XML''' under the result directrory Output Subdir ). The first part of the function must give some options for the requested input information and may interactively introduce specific parameters needed for the function. The second part of the function, where the processing itself takes place, is then free from any input (so the operation can be easily dispatched to a remote computer).
    746 
    747 The first part of the function is activated when the function is selected in the menu !ActionName of the GUI '''series''', which yields the input !Param.Action.RUN=0. It is aimed at setting the GUI configuration appropriate for the specific function, and to provide all the needed input parameters. The second part is activated by the action RUN and should not contain any interactive input to allow for batch mode outside the current Matlab session.
     745These can be used as template to create other functions. The general input of these functions in Matlab structure 'Param' which contains all the input parameters as given by the GUI '''series''' (see comments in the function for details). For batch operations, as needed for the cluster, this input is replaced by the name of an XML file which contains these parameters (this is the file produced in the floder '''/0_XML''' under the result directrory Output Subdir). The first part of the function must give some options for the requested input information and may interactively introduce specific parameters needed for the function. The second part of the function, where the processing itself takes place, is then free from any input (so the operation can be easily dispatched to a remote computer).
     746
     747The first part of the function is activated when the function is selected in the menu '''[!ActionName]''' of the GUI '''series''', which yields the input Param.Action.RUN=0. It is aimed at setting the GUI configuration appropriate for the specific function, and to provide all the needed input parameters. The second part is activated by the action '''[RUN]''' and should not contain any interactive input to allow for batch mode outside the current Matlab session.
    748748
    749749The settings of the GUI ''' series''' are controlled by the following parameters (fields of the Matlab structure 'Param'):
    750750
    751 ||'''name'''||'''values'''||'''default'''||'''role'''||
     751||'''Name'''||'''Values'''||'''Default'''||'''Role'''||
    752752||.!WholeIndexRange||'off'/'on'||'off'||prescribes the file index ranges from min to max (the whole file series is needed)||
    753753||.!AllowInputSort||'off'/'on'||'off'||for multiple lines in the input file table, provides an automatic alphabetic sorting of the list of input files  !SubDir (so that the order of intput file series used does not depend on the order of introduction)||
     
    776776
    777777 * '''PIV''': makes image comparisons on sliding index pairs, as usual for measuring velocities by particle displacements. A second menu '''[!ListPairMode]''' in the panel '''[!PairIndices]''' then selects one among three possibilities (not always available depending on the file indexing):
    778    * ''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 [#a3.5Imagedocumentationfiles.xml <!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.
     778   * ''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 [#a3.5Imagedocumentationfiles.xml <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.
    779779   * 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'.
    780780   * series (Dj): same as series (Di) but with the j index.
     
    803803  Examples of XML files are provides in /XML_SCHEMAS/ImaDoc_templates.
    804804
    805 ('''[num_!CorrBoxSize_1,_2,_3])''' set the size (in pixels) of the 'correlation box', the sliding window used to get image correlations. '''[num_!SearchBoxSize_1,_2,_3]''' set the size of the 'search box' in which image correlation is calculated, see figure.  This search box can be shifted with respect to the correlation box by parameters  ([num_!SearchBoxShift_1,_2,_3]). This is useful in the presence of a known mean flow. The default value !SearchBoxSize=(25,25) is generally good, use a larger size for images with few particles, use an elongated box , e.g. (11,41), to optimise the resolution in one direction (for instance in a boundary layer).
     805('''[num_!CorrBoxSize_1,_2,_3])''' set the size (in pixels) of the 'correlation box', the sliding window used to get image correlations. '''[num_!SearchBoxSize_1,_2,_3]''' set the size of the 'search box' in which image correlation is calculated, see figure.  This search box can be shifted with respect to the correlation box by parameters  ('''[num_!SearchBoxShift_1,_2,_3]'''). This is useful in the presence of a known mean flow. The default value '''[!SearchBoxSize]'''=(25,25) is generally good, use a larger size for images with few particles, use an elongated box , e.g. (11,41), to optimise the resolution in one direction (for instance in a boundary layer).
    806806
    807807A parameter '''[num_CorrSmooth]''' controls the smoothing of the image corelation curves used in civ, the default value 1 is generally used.
    808808
    809 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.
     809The 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.
    810810
    811811[[Image(11-2 CV1.png)]]
    812812
    813 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.
     813The 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.
    814814
    815815[[Image(civ1_test.jpg)]]
    816816[[Image(Correlation for PIV.png)]]
    817817
    818 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 [#MaskGrid 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.
     818The 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.
    819819
    820820A subregion can be alternatively selected by a mask image, selecting the edit box '''[Mask]'''. If a mask image with an appropriate name is found in the image directory, it wil be detected, and the indication 'xxmask' appears in the edit box. (xx is the number of slices, equal to 1 for a single mask). Otherwise a browser appears to select a (single) mask file.
     
    825825The FIX operation is used after civ to mark false vectors, using different criteria:
    826826
    827 ''' Warning flags: ''' these are flags (vec_F) indicating problems with the image correlation process.
     827'''- Warning flags: ''' these are flags (vec_F) indicating problems with the image correlation process.
    828828 * 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.
    829829 * vec_F=3: the optimisation of the correlation function is unstable  or  local Intensity rms of the image =0. Must be selected.
    830830 
    831 ''' 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. 
    832 
    833 ''' 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.
    834 
    835 ''' Manual fix: ''' Interactive fixing with the mouse is also possible, see [#a4.2Contourplots section 4.2].
     831'''- 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. 
     832
     833'''- 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.
     834
     835'''- Manual fix: ''' Interactive fixing with the mouse is also possible, see [#a4.2Contourplots section 4.2].
    836836
    837837
     
    840840
    841841=== 11.5 CIV2 ===
    842 -'''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.
     842- '''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.
    843843
    844844Image 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.
    845845
    846 -'''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).   
    847 
    848 
    849 -'''PATCH2:''' like PATCH1
     846- '''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).   
     847
     848
     849- '''PATCH2:''' like '''[PATCH1]'''
    850850
    851851Further iterations: improvements can be obtained by further iterations of the civ2-fix2-patch2 process. Open again the interface, and consider the previous civ2 result as the prior guess civ1. It will be recopied and relabelled as civ1 in the new NetCDF file produced.
     
    862862Perform usual PIV for each image series.
    863863
    864 For PIV near a staigth wall, it is advised to create a grid for each image series, corresponding to a common array of physical positions. This can be done by the upper menu bar option '''!Tools/Make Grid''' in the GUI '''uvmat'''( see section [#a9.2Grids Grids]).
     864For PIV near a staigth wall, it is advised to create a grid for each image series, corresponding to a common array of physical positions. This can be done by the upper menu bar option '''[!Tools/Make Grid]''' in the GUI '''uvmat'''( see section [#a9.2Grids Grids]).
    865865
    866866Combine PIV fields: TO UPDATE**.
     
    871871Several fields, corresponding to the successive operations 'civ1', 'fix1', 'patch1', 'civ2', 'fix2', 'patch2' are stored in the same .nc file. When a third or higher order civ iteration is performed, a new .nc file is created, containing the two last iterations as civ1 and civ2.
    872872
    873 -'''List of constants (global attributes):''',
     873- '''List of constants (global attributes):''',
    874874
    875875  Conventions 'uvmat/civdata'.
     
    902902||Civ2_CheckDeformation||=1 if image deformation option is used||
    903903
    904 -'''List of variables:'''
     904- '''List of variables:'''
    905905
    906906Conventions 'uvmat/civdata'.
     
    926926||Civ1_W_tps||tps weights for z vel component||
    927927
    928 -'''List of constants, old CIVx conventions:'''
     928- '''List of constants, old CIVx conventions:'''
    929929
    930930 * nb_coord: =2 for PIV in a plane, =3 for PIV in a volume.
     
    951951 * ro2_patch: smoothing coefficient rho used for patch2.
    952952
    953 -'''List of field variables (old CIVx conventions):''' a set of velocity vectors is defined by a 1D array of position coordinates x, y, and z for 3D civ, and a corresponding array for each of the velocity components u, v, and w for 3C civ. The field is therefore defined on an arbitrary set of point, without restriction to a regular mesh. Additional arrays are used to keep track of the quality of the PIV process leading to each vector. The image correlation maximum is represented by vec_C (a real number between 0 and 1). A flag vec_F represents a warning on the vector quality (see the list of values below). Another flag FixFlag marks false vectors: !FixFlag=0 for good vectors, and FixFlag is set to a non-zero value when it has been detected as false (using a 'fix' operation).
     953- '''List of field variables (old CIVx conventions):''' a set of velocity vectors is defined by a 1D array of position coordinates x, y, and z for 3D civ, and a corresponding array for each of the velocity components u, v, and w for 3C civ. The field is therefore defined on an arbitrary set of point, without restriction to a regular mesh. Additional arrays are used to keep track of the quality of the PIV process leading to each vector. The image correlation maximum is represented by vec_C (a real number between 0 and 1). A flag vec_F represents a warning on the vector quality (see the list of values below). Another flag FixFlag marks false vectors: !FixFlag=0 for good vectors, and FixFlag is set to a non-zero value when it has been detected as false (using a 'fix' operation).
    954954
    955955The names of the fields (variables) resulting from each operation are given in the following table. Each column corresponds to an operation. 'filter1' and 'interp1' both result from the patch1 interpolation on the same points, with and without smoothing respectively. The first line is the name of the constant representing the number of vectors (the dimension of the arrays). The next successive lines indicate the variable names for the position and velocity components, the image correlation 'c', the 'flag' about civ quality and 'fix' flag (only available for civ1 and civ2), and the spatial derivatives obtained from the patch operations.
    956956
    957 -*Names of field variables for civ1 and patch1
     957- '''Names of field variables for civ1 and patch1'''
    958958
    959959||'''   '''||civ1||'''interp1'''||'''filter1 '''||
     
    973973||dv/dy||||vec_patch0_DVDY||vec_patch_DVDY||
    974974
    975 -*Names of field variables for civ2 and patch2
     975- '''Names of field variables for civ2 and patch2'''
    976976
    977977same as previous, replacing 'vec' by 'vec2'.