Changes between Version 61 and Version 62 of UvmatHelp


Ignore:
Timestamp:
Jun 11, 2013, 2:25:51 PM (7 years ago)
Author:
sommeria
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UvmatHelp

    v61 v62  
    2525
    2626=== 1.3 Documentation and help ===
    27 The 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. 
    28 
    29 A short comment about  each GUI ''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 uicontrol is quoted as '''[uicontrol tag]''', a file name in the package is quoted as ''fct name.m'', and commands on the Matlab workspace as  '>> command’. 
     27The 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.
     28
     29A short comment about  each GUI ''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 uicontrol is quoted as '''[uicontrol tag]''', a file name in the package is quoted as ''fct name.m'', and commands on the Matlab workspace as  '>> command’.
    3030
    3131Information is also provided as comments in each function. Type '>>help fct_name'  to get it, or open it with an editor.
     
    4040UVMAT is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See theGNU General Public License (file {COPYING.txt}) for more details.
    4141
     42----
    4243== 2 Overview of the GUI uvmat.fig ==
    4344=== 2.1 Opening the GUI ===
     
    7475
    7576 * '''[Run] ''':
    76    * '''[Field series]''': gives access to the GUI [#a10-Processingfieldseries '''series.fig'''] for processing field series.
    77    * '''[CivX(Fortran)]''':  gives access to the GUI [#a11-PIV:ParticleImagingVelocimetry '''civ.fig'''] for Particle Imaging Velocimetry (CivX version in Fortran).
     77   * '''[Field series]''': gives access to the GUI [#a10-Processingfieldseries "''series.fig''"] for processing field series.
     78   * '''[CivX(Fortran)]''':  gives access to the GUI [#a11-PIV:ParticleImagingVelocimetry "''civ.fig''"] for Particle Imaging Velocimetry (CivX version in Fortran).
    7879
    7980 * '''[Help] ''': displays this help file using the Matlab browser.
     
    103104 * '''Extracting data''' as Matlab arrays. Information stored in the GUI uvmat  (as ''!UserData'' in the figure) can be extracted in the Matlab work space by the menu bar command  '''[Export/field in workspace]''' (or by pressing the right mouse button on the GUI). Type '>>Data_uvmat.Field' to get the current input field as a Matlab structure. An image or scalar matrix is for instance obtained as Data_uvmat.Field.A.
    104105
     106--------------------
    105107== 3 Input files and navigation with uvmat ==
    106108=== 3.1  Input data formats ===
     
    114116
    115117=== 3.2 Selecting fields from CIV ===
    116 To update...
    117 The package uvmat recognizes the NetCDF fields obtained from the CIVx software.  This includes the velocity fields and their spatial derivatives, as well as information about the CIV processing (image correlation values and flags). The vorticity, divergence, or strain are read in the same NetCDF files, but are available only after a PATCH operation has been run in the CIVx software,  see [#a11-PIV:ParticleImagingVelocimetrys section 11].
     118To update... The package uvmat recognizes the NetCDF fields obtained from the CIVx software.  This includes the velocity fields and their spatial derivatives, as well as information about the CIV processing (image correlation values and flags). The vorticity, divergence, or strain are read in the same NetCDF files, but are available only after a PATCH operation has been run in the CIVx software,  see [#a11-PIV:ParticleImagingVelocimetrys section 11].
    118119
    119120<doc71|center>
     
    132133-'''Double index series: ''' they are labeled by two integer indices i and j. This double index labeling is commonly used for bursts of images (index j or equivalently a letter appendix 'a', 'b') separated by longer time intervals (index i).  It can be also used for successive volume scanning by a laser sheet, with index j representing the position in the volume and i the time. For a set of indexed movies (or multimage  files), the index i labels the files while the index j labels the frames  within a file.
    133134
    134 -'''Pair  indexing:''' new file series can result from the processing of primary series. For a sequential processing limited to a single file, the output index naturally reproduces  the input index. Other processing functions involve pairs of input files, for instance Particle Imaging Velocity from image pairs. In a simple series, the result from the two primary fields *_i1 and *_i2 is then labeled as *_i1-i2 with the file extension indicating  the output format. More generally,  the result from any processing involving a range of primary indices from  i1 to i2  is  labeled as _i1-i2.  If i1=i2 or j1=j2, the two indices are merged in a single label i, or j respectively.
    135 
    136 -'''Nomenclature types:''' The ''nomenclature type'' is defined as the character string representing the index (or indices) for the first file  in the series, for instance '_1' for a ''single indexing'' and '_1-2' for a  ''pair indexing'', '_1_1' for a ''double index'' series. The second index j can be also represented as a letter suffix, for instance '01a'.  For a field series in a single file, like a movie, the  nomenclature type is defined as '*'. The functions ''fullfile_uvmat.m'' generates a file name from a root name, four numerical indices i1,i2,j1,j2 and  the ''nomenclature type''. The reverse operation, splitting a name into a root and indices while detecting the ''nomenclature type'', is performed by the function ''fileparts_uvmat.m''. The function ''find_file_series.m'' is also needed to scan the whole file series, leading to a possible adjustement of the nomenclature type (for instance distinguishing '_001' from '_1' when the file with index 1000 has been opened). Once the nomenclature type has been detected by the browser of '''uvmat.fig''', it is displayed in the edit box '''[!NomType]''' and used to generate all the file names when the series is scanned.
     135-'''Pair  indexing:''' new file series can result from the processing of primary series. For a sequential processing limited to a single file, the output index naturally reproduces  the input index. Other processing functions involve pairs of input files, for instance Particle Imaging Velocity from image pairs. In a simple series, the result from the two primary fields *_i1 and *_i2 is then labeled as *_i1-i2 with the file extension indicating  the output format. More generally,  the result from any processing involving a range of primary indices from  i1 to i2  is  labeled as _i1-i2.  If i1=i2 or j1=j2, the two indices are merged in a single label i, or j respectively.
     136
     137-'''Nomenclature types:''' The ''nomenclature type'' is defined as the character string representing the index (or indices) for the first file  in the series, for instance '_1' for a ''single indexing'' and '_1-2' for a  ''pair indexing'', '_1_1' for a ''double index'' series. The second index j can be also represented as a letter suffix, for instance '01a'.  For a field series in a single file, like a movie, the  nomenclature type is defined as '*'. The functions ''fullfile_uvmat.m'' generates a file name from a root name, four numerical indices i1,i2,j1,j2 and  the ''nomenclature type''. The reverse operation, splitting a name into a root and indices while detecting the ''nomenclature type'', is performed by the function ''fileparts_uvmat.m''. The function ''find_file_series.m'' is also needed to scan the whole file series, leading to a possible adjustement of the nomenclature type (for instance distinguishing '_001' from '_1' when the file with index 1000 has been opened). Once the nomenclature type has been detected by the browser of '''uvmat.fig''', it is displayed in the edit box '''[!NomType]''' and used to generate all the file names when the series is scanned.
    137138
    138139=== 3.4 Navigation among field indices ===
     
    183184 * '''.fig''' Matlab figures represent plots but also Graphic User Interfaces (GUI). In that case Matlab functions (callbacks) are attached to the graphic objects in the figure and can be activated by the mouse. Matlab figures can be directly opened by the browser of '''uvmat.fig'''.
    184185
    185  * ''''.civ' ''' (obsolete)  ascii text file containing the list of image times and the scaling in pixels/cm. This is an obsolete version of the xml image documentation file. It is stored in the same directory as the corresponding series of images, with name ''root .civ'' (instead of {root.xml}). It is automatically sought by '''uvmat.fig''' and '''civ.fig''', in the absence of an xml file !ImaDoc. (it is read by the function ''read_imatext.m''). The following example is from an experience with 19 bursts of 4 images, named aa001a,aa001b,aa001c,aa001d,aa002a,aa002b,...,aa019c,aa019d, with an extension .png. The corresponding .civ file is named aa.civ. Comments (not included in the file) are indicated with %... 
     186 * ''''.civ' ''' (obsolete)  ascii text file containing the list of image times and the scaling in pixels/cm. This is an obsolete version of the xml image documentation file. It is stored in the same directory as the corresponding series of images, with name ''root .civ'' (instead of {root.xml}). It is automatically sought by '''uvmat.fig''' and '''civ.fig''', in the absence of an xml file !ImaDoc. (it is read by the function ''read_imatext.m''). The following example is from an experience with 19 bursts of 4 images, named aa001a,aa001b,aa001c,aa001d,aa002a,aa002b,...,aa019c,aa019d, with an extension .png. The corresponding .civ file is named aa.civ. Comments (not included in the file) are indicated with %...
    186187
    187188{{{
     
    213214
    214215'''Mirror data trees''' can be created to process a source data set in read only mode, to preserve the safety of the data source, and to allow several users to work in parallel without interference. This is done by opening the source Campaign with the menu bar option Open/browse campaign from uvmat. Select the source campaign directory with the browser. Then the GUI 'browse_data' appears. Then press 'create_mirror' and select the directory which must contain the mirror Campaign. A set of directory is then created for each experiment, in which are created symbolic  links to the !DataSeries directories. Data processing then results in real !DataSeries directories created in the Experiment directory.  An xml mirror.xml is created inside the directory mirror to mark its role; This xml file contains  the path and name of the source directory under the label <!SourceDir>. The mirror directory can be regularly updated by pressing the button 'update_mirror'.
    215 
     216----------------------------
    216217== 4 Scalar and vector display ==
    217218The uvmat interface primarily reads and visualises two-dimensional fields, which can be images or scalars, or vector fields.
     
    278279
    279280=== 4.6 Succession of operations: ===
    280 The following succession of operations is performed by '''uvmat.fig''': 
     281The following succession of operations is performed by '''uvmat.fig''':
    281282
    282283-'''File identification:''' the nomenclature type and file type (for instance image, movie, or Netcdf file) are identified from the opened file (using the function ''find_file_series.m'').
     
    284285-'''File Reading:''' the input field is first read from the input file by the Matlab function ''read_field.m''.
    285286
    286 -'''Second file reading:'''  The second input field is similarly read if selected. Note that it is kept in memory, so it is not read again if the file is unchanged (this is useful in the case of substraction of a fixed background for instance). 
    287 
    288 -'''Transform:''' by default the 'phys' option transforms each of the input fields from pixel to physical coordinates. This operation can also combine two input field structures into a single field structure. 
    289 
    290 -'''Histogram:''' This is obtained from the input field in transformed coordinates, or if applicable from the fields resulting from the two input fields. 
     287-'''Second file reading:'''  The second input field is similarly read if selected. Note that it is kept in memory, so it is not read again if the file is unchanged (this is useful in the case of substraction of a fixed background for instance).
     288
     289-'''Transform:''' by default the 'phys' option transforms each of the input fields from pixel to physical coordinates. This operation can also combine two input field structures into a single field structure.
     290
     291-'''Histogram:''' This is obtained from the input field in transformed coordinates, or if applicable from the fields resulting from the two input fields.
    291292
    292293-'''Projection:''' on  the projection object selected in the menu '''[!ListObject_1]''', see [#ProjObject section 6]. A second projection, on the object selected by '''[!ListObject]''', can be plotted in the ancillary figure '''view_field.fig'''. Projection is performed by the function ''proj_field.m''.
    293294
    294 -'''Field calculation:''' a scalar can be calculated after projection, as selected by the menu '''[Fields]'''. 
    295 
    296 -'''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.   
     295-'''Field calculation:''' a scalar can be calculated after projection, as selected by the menu '''[Fields]'''.
     296
     297-'''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.
    297298
    298299-'''Plotting:''' plot the results of projection, using the function ''plot_field.m''.
    299 
     300----------------------------
    300301== 5- Field structures ==
    301302=== 5.1 Griding of data ===
     
    318319This 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 http://coriolis.legi.grenoble-inp.fr/spip.php?article73)
    319320
    320 $$\label{sol_gene} f({\bf r})=\sum S_i \phi({\bf|r-r_i}|)+a_0+a_1x+a_2y\; $$ where ${\bf r_i}$ are the positions of the measurement points (the ''centres''). Each ''centre'' can be viewed as the source of an axisymmetric field  $\phi$ of the form $\phi(r)=r^2\log (r)$. The weights $S_i$ and the linar coefficients $a_0,a_1,a_2$ are the thin plate shell (tps) coefficients which determine the interpolated value at any point. The spatial derivatives are similarly obtained at any point by analytical differentiation of the source functions $\phi(r)$. These tps weights, with the corresponding centre coordinates, therefore contain all the information needed for interpolation at any point. We call that a ''tps field representation''.
     321$$\label{sol_gene} f({\bf r})=\sum S_i \phi({\bf|r-r_i}|)+a_0+a_1x+a_2y\; $$ where ${\bf r_i}$ are the positions of the measurement points (the ''centres''). Each ''centre'' can be viewed as the source of an axisymmetric field  $\phi$ of the form $\phi(r)=r^2\log (r)$. The weights $S_i$ and the linar coefficients $a_0,a_1,a_2$ are the thin plate shell (tps) coefficients which determine the interpolated value at any point. The spatial derivatives are similarly obtained at any point by analytical differentiation of the source functions $\phi(r)$. These tps weights, with the corresponding centre coordinates, therefore contain all the information needed for interpolation at any point. We call that a ''tps field representation''.^
    321322
    322323Because of memory limitation, the tps interpolation must be done in sub-domains for large data sets (with non-empty overlap to avoid steps). Then the tps coordinates and tps weights are represented with an addition index, labelling the subdomain.
     
    331332In summary, the ''field structure'' is specified by the following elements:
    332333
    333  * (optional) '''ListGlobalAttribute:''' list (cell array of character strings) of the names of global attributes  Att_1, Att_2...
    334  * (mandatory) '''ListVarName:''' list of the variable names Var_1, Var_2....(cell array of character strings).
    335  * (mandatory) '''VarDimName:''' list of the dimensions associated with each variable: this is a cell array whose number of element is equal to that of '''!ListVarName'''. Each element is the dimension name for a unidimensional variable, or a cell array specifying the list of dimension names for a multidimensional variable.
    336  * (optional) '''VarAttribute:''' cell array of structures of the form !VarAttribute{ivar}.key=value, defining an attribute tag name and value for the variable #ivar (variable number in the list !ListVarName]).
     334 * (optional) '''!ListGlobalAttribute:''' list (cell array of character strings) of the names of global attributes  Att_1, Att_2...
     335 * (mandatory) '''!ListVarName:''' list of the variable names Var_1, Var_2....(cell array of character strings).
     336 * (mandatory) '''!VarDimName:''' list of the dimensions associated with each variable: this is a cell array whose number of element is equal to that of '''!ListVarName'''. Each element is the dimension name for a unidimensional variable, or a cell array specifying the list of dimension names for a multidimensional variable.
     337 * (optional) '''!VarAttribute:''' cell array of structures of the form !VarAttribute{ivar}.key=value, defining an attribute tag name and value for the variable #ivar (variable number in the list !ListVarName]).
    337338 * .Att_1, Att_2... : values of the listed global attributes.
    338339 * .Var_1, .Var_2...: variables arrays whose names are listed in !ListVarName.
     
    340341In some cases, it is useful to define the field object independently from its data content. Then the variables .Var1... are replaced by the lists of dimension names and values.
    341342
    342  * '''ListDimName:''' list of dimension names (cell array of character strings)
    343  * '''DimValue:''' array of dimension values corresponding to !LisDimName.
     343 * '''!ListDimName:''' list of dimension names (cell array of character strings)
     344 * '''!DimValue:''' array of dimension values corresponding to !LisDimName.
    344345
    345346The following temporary information is added to manage projection and field substraction oerations, which must be done in general after projection:
     
    411412 * 'nb_tps': dimension of the index for the tps centres
    412413 * 'nb_subdomain' denotes the dimension for the subdomain index for tps coefficients
    413 
     414----------------------------
    414415== 6- Projection objects == #ProjObject
    415416=== 6.1 Definition and editing with the uvmat interface ===
    416 These are geometrical objects used to define cuts along lines or planes, to interpolate fields on a regular grid, to restrict the analysis or visualisation to field subregions. When a 2D or 3D field is opened by uvmat, a default projection plane object is created. New objects are created by the menu bar command  '''[Projection object]''' in '''uvmat.fig'''.  The creation of a new object ('''points''', '''line'''....) can be initiated by selecting the corresponding item in the menu. Alternatively, an existing xml object file can be opened by selecting the menu option '''[browse...]'''. 
     417These 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. When a 2D or 3D field is opened by uvmat, a default projection plane object is created. New objects are created by the menu bar command  '''[Projection object]''' in '''uvmat.fig'''.  The creation of a new object ('''points''', '''line'''....) can be initiated by selecting the corresponding item in the menu. Alternatively, an existing xml object file can be opened by selecting the menu option '''[browse...]'''.
    417418
    418419In 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. In the latter case, refresh the plots by pressing''' [PLOT] ''' in '''set_object.fig''' . Objects can be saved as xml files with the button ''' [SAVE]''' of '''set_object.fig'''.
     
    439440
    440441 * ''' 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.
    441    
    442  * ''' 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. 
    443     * 'points': the only relevant range is RangeX, with one value (a radius around the point).
    444     * 'lines': the only relevant range is RangeY, with one value, a radius transverse to the line.
    445     * 'polyline' and 'polygon' ranges are not relevant.
    446     * 'rectangle','ellipse': RangeX and RangeY (one value) define the half length and half width respectively. In 3D, RangeZ may set a range of projection transverse to the plane containing the object.
    447     * 'plane': RangeX and RangeY (two values each) may restrict a region in the coordinates of the plane. In 3D, RangeZ may set a range of projection transverse to the plane.
    448     * 'volume': RangeX, RangeY, rangeZ (two values each) define a selected volume in the data set.
     442
     443 * ''' 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.
     444   * 'points': the only relevant range is RangeX, with one value (a radius around the point).
     445   * 'lines': the only relevant range is RangeY, with one value, a radius transverse to the line.
     446   * 'polyline' and 'polygon' ranges are not relevant.
     447   * 'rectangle','ellipse': RangeX and RangeY (one value) define the half length and half width respectively. In 3D, RangeZ may set a range of projection transverse to the plane containing the object.
     448   * 'plane': RangeX and RangeY (two values each) may restrict a region in the coordinates of the plane. In 3D, RangeZ may set a range of projection transverse to the plane.
     449   * 'volume': RangeX, RangeY, rangeZ (two values each) define a selected volume in the data set.
    449450
    450451 * ''' DX: ''', ''' DY: ''', ''' DZ: ''':mesh  along each coordinate defining a grid for interpolation.
     
    458459
    459460=== 6.3 Projection modes ===
    460 Each field variable yields a corresponding variable with the same name in the projected field. in addition integral quantities (circulation, flux...) can be 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: 
     461Each field variable yields a corresponding variable with the same name in the projected field. in addition integral quantities (circulation, flux...) can be 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:
    461462
    462463 * ''' !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). Error flags ?
    463    * 'points': each field variable is averaged in a sphere of radius RangeX (a single value) around each projection point and attributed to this point position. An ancillary variable U_nbval(i) indicates the number of (non-false) data found around each point. Ancillary data and warning flags are not projected on points. 
    464    * 'line': for scattered coordinates, each initial data point within a range ''RangeY'' on each side of the line is normally projected on the line, keeping its field values. For grid lin interpolation and averaging.  Vector quantities are furthermore projected on the line as longitudinal (X) and normal (Y) components. The line length and mean value of each variable along the line is also calculated (giving access to circulation and flux). Ancillary data and warning flags are not projected on points. 
     464   * 'points': each field variable is averaged in a sphere of radius RangeX (a single value) around each projection point and attributed to this point position. An ancillary variable U_nbval(i) indicates the number of (non-false) data found around each point. Ancillary data and warning flags are not projected on points.
     465   * 'line': for scattered coordinates, each initial data point within a range ''RangeY'' on each side of the line is normally projected on the line, keeping its field values. For grid lin interpolation and averaging.  Vector quantities are furthermore projected on the line as longitudinal (X) and normal (Y) components. The line length and mean value of each variable along the line is also calculated (giving access to circulation and flux). Ancillary data and warning flags are not projected on points.
    465466   * 'plane': similar as line, RangeZ in 3D. RangeX and RangeY used to set bounds. All data are projected in this mode.
    466467   * 'volume': used to set bounds in 3D within a box [RangeX, RangeY, RangeZ].  All data are projected in this mode.
    467    *  no action on 'polyline', 'rectangle', 'polygon', 'ellipse'.
     468   * no action on 'polyline', 'rectangle', 'polygon', 'ellipse'.
    468469
    469470 * ''' !ProjMode 'interp_lin': '''  Linear interpolation of scalar and vector field variables, after exclusion of false data (marqued by error flag). Ancillary data and warning flags are not projected in this mode. Gridded data are interpolated by ..., while fields with scattered coordinates are projected with the Matlab function .... Note that this function provides interpolation only within the convex hull of the initial data set, attributing 'NaN' (undefined) field values out of this domain. To avoid problems with further data processing, uvmat transforms NaN values into zeros, but mark them with an error flag FF=1.
    470471   * 'points': linear interpolation on each point of the object.
    471472   * 'line','polyline', 'rectangle', 'polygon', 'ellipse': linear interpolation on points regularly spaced on the line, with mesh DX. The X coordinate is the distance following the line, with an origin at the starting point(the first point in 'line','polyline','polygon',the lower left corner for rectangle, the point along the main axis for an ellipse). The line length and mean value of each variable along the line is also calculated (giving access to circulation and flux).
    472    * 'plane': linear interpolation on a regular grid with meshes DX, DY and ortigin at (X,Y)=(0,0). This grid is bounded by the two values of RangeX and RangeY along X and Y respectively. 
    473  
    474  * ''' !ProjMode  'interp_tps':  '''  This behaves with different objects line 'interp_lin', but using the more precise thin spline shell method. This is particularly usefull to calculate spâtial field derivatives. Furthermore this method provides data exrtrapolation outside the initial convex hull (although it is not reliable at large distances). This mode does require a previous calculation of tps weights, see [#a5.1Gridingofdata section 5.1], so it does not act on the initial field cells with scattered coordinates. This is done by uvmat if tps projection is requested. Gridded data are linearly interpolated (to clarify...). 
     473   * 'plane': linear interpolation on a regular grid with meshes DX, DY and ortigin at (X,Y)=(0,0). This grid is bounded by the two values of RangeX and RangeY along X and Y respectively.
     474
     475 * ''' !ProjMode  'interp_tps':  '''  This behaves with different objects line 'interp_lin', but using the more precise thin spline shell method. This is particularly usefull to calculate spâtial field derivatives. Furthermore this method provides data exrtrapolation outside the initial convex hull (although it is not reliable at large distances). This mode does require a previous calculation of tps weights, see [#a5.1Gridingofdata section 5.1], so it does not act on the initial field cells with scattered coordinates. This is done by uvmat if tps projection is requested. Gridded data are linearly interpolated (to clarify...).
    475476
    476477 * ''' !ProjMode 'inside' and 'ouside '''': defined only for closed lines: rectangle, polygon, ellipse. For each field U, its probability distribution function Uhist  inside, or respectively outside,  the line is calculated, as well as the mean Umean. other statistics...
     
    478479 * ''' !ProjMode 'none', 'mask_inside', 'mask_outside': ''' no projection operation. The object is used solely for plotting purpose, to show a boundary or to prepare a mask, inside or outside a closed line, see [#a9-Masksandgrids section 9]).
    479480
    480 Operations, for instance 'vort', 'div' are performed after interpolation. Similarly for field difference, which requires interpolation to compare fields defined at different positions. Field variables to be substracted are initially marqued by an attribute 'CheckSub'. 
    481 
     481Operations, for instance 'vort', 'div' are performed after interpolation. Similarly for field difference, which requires interpolation to compare fields defined at different positions. Field variables to be substracted are initially marqued by an attribute 'CheckSub'.
    482482
    483483=== 6.4 Object representation ===
    484484Projections objects are drawn in magenta color when they are selected for creation or edition, and in blue otherwise.
    485485
    486  * 'points' are represented by dots surrounded by a dashed circle showing the range of projection. 
    487  * 'line' , 'polyline' are plotted as lines, surrounded by two dashed lines showing the range of projection, when applicable (i.e. not in the case !ProjMode='interp'). 
    488  * 'polygon', 'rectangle', 'ellipse' are drawn. In the case ProjMode ='inside' or 'outside' the corresponding area is painted in magenta (or blue when they are not selected). 
    489  * 'plane' are shown by their axis. These axis are limited to their range of selection  (RangeX and RangeY) when applicable. Otherwise they end at the edge of the figure with an arrow. ** 
     486 * 'points' are represented by dots surrounded by a dashed circle showing the range of projection.
     487 * 'line' , 'polyline' are plotted as lines, surrounded by two dashed lines showing the range of projection, when applicable (i.e. not in the case !ProjMode='interp').
     488 * 'polygon', 'rectangle', 'ellipse' are drawn. In the case ProjMode ='inside' or 'outside' the corresponding area is painted in magenta (or blue when they are not selected).
     489 * 'plane' are shown by their axis. These axis are limited to their range of selection  (RangeX and RangeY) when applicable. Otherwise they end at the edge of the figure with an arrow. **
    490490 * 'volume' are shown like 'plane', except that they are painted in magenta (or blue) **
    491491
     
    543543
    544544In the case of a 3D input field, the fig is set to uvmat. A middle plane of cut is automatically selected. This can be moved then with the slider on the interface set_object (see section 5). The default cuts are made at constant z coordiante, but any of the three initial coordiantes can be used as z coordinate, using the menu coord_z.
    545 
     545----------------------------
    546546== 8- Geometric calibration ==
    547547=== 8.1 Generalities ===
    548 Transforming image to physical coordinates is a key problem for measuring techniques based on imaging.
    549  
    550 The ''image coordinates'' represent the two cartesian axis X,Y of the image, with origin at the lower left corner. The coordinate of the first lower left pixel centre is therefore (1/2,1/2). Note that the Y axis is directed upward, while the corresponding image index j increases downward. Therefore, denoting npy the number of pixels along Y, the (X,Y) coordinates of a pixel indexed (i,j) are [[BR]] X=i-1/2, Y=npy-j+1/2.
     548Transforming image to physical coordinates is a key problem for measuring techniques based on imaging.   The ''image coordinates'' represent the two cartesian axis X,Y of the image, with origin at the lower left corner. The coordinate of the first lower left pixel centre is therefore (1/2,1/2). Note that the Y axis is directed upward, while the corresponding image index j increases downward. Therefore, denoting npy the number of pixels along Y, the (X,Y) coordinates of a pixel indexed (i,j) are [[BR]] X=i-1/2, Y=npy-j+1/2.
    551549
    552550The ''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:
     
    594592The coefficients are recorded in the xml element <code><ImaDoc/GeometryCalib></code> as follows:
    595593
    596  * <CalibrationType>: type of calibration ('rescale', 'linear', '3D...')
    597 
    598  * <fx_fy>: focal length along each coordinate of the image sensor, expressed in pixel interval.
    599 
    600  * <Cx_Cy>: position coordinates of the optical axis on the
    601 
    602  * <kc>: coefficient of quadratic deformation (=1 for the options calib_lin and calib_rescale)
    603 
    604  * <CoordUnit>: coordinate unit in physical space.
    605 
    606  * <Tx_Ty_Tz></code>: translation, (Tz=1 for the options calib_lin and calib_rescale)
    607 
    608  * <R>: rotation matrix (in 3 lines). For the option <[https://servforge.legi.grenoble-inp.fr/projects/soft-uvmat/search?q=wiki%3ACalibrationType CalibrationType]>= 'rescale', [[BR]] R (i=1)= [pxcmx 0 0] R (i=2)= [0 pxcmy 0] R (i=3)= [0 0 1], [[BR]]where pxcmx and pxcmy are the scaling factors along x and y.
    609 
    610  * <omc> 3 components of the rotation vector (this is for diagnostic use, it is redondant with the matrix R used for actual coordinate transforms).  The physical coordinate axis are transformed to the image coordinate axis by a composition of the translation T and the rotation)
    611 
    612  * <ErrorRms>: rms difference (in X and Y direction) between the image coordinates measured for the calibration points and the coordinates transformed from their physical coordinates (using the function ''px_XYZ.m in uvmat'')
    613 
    614  * <ErrorMax> : maximum difference (in X and Y direction) between the image coordinates measured for the calibration points and the coordinates transformed from their physical coordinates. (using the function ''px_XYZ.m'' in uvmat)
    615 
    616  * <SourceCalib> set of the point coordinates used for calibration 
    617 
    618   * <PointCoord> [x y z X Y] , where x,y,z are the physical coordinates of each point, X Y its image coordinates
    619 
    620  * <NbSlice_i> nbre of slices for the first field  index i (multilevel case), =1 by default.
    621 
    622  * <NbSlice_j> nbre of slices for the second index j (volume scan), =1 by default.
    623 
    624  * <SliceCoord> [x y z] positions (nb lines) of the nb planes, where nb=NbSlice_i (multilevel case) or nb=NbSlice_j of j indices (volume scan), for parallel volume scan, x=y=0, z= slice height, for angular scan, [x,y,z]=[origin].
    625 
    626  * <SliceDZ>   step distance between planes, or
    627 
    628  * <SliceDPhi> step angle for angular scan.
     594 * <CalibrationType>: type of calibration ('rescale', 'linear', '3D...')
     595
     596 * <fx_fy>: focal length along each coordinate of the image sensor, expressed in pixel interval.
     597
     598 * <Cx_Cy>: position coordinates of the optical axis on the
     599
     600 * <kc>: coefficient of quadratic deformation (=1 for the options calib_lin and calib_rescale)
     601
     602 * <CoordUnit>: coordinate unit in physical space.
     603
     604 * <Tx_Ty_Tz></code>: translation, (Tz=1 for the options calib_lin and calib_rescale)
     605
     606 * <R>: rotation matrix (in 3 lines). For the option <[https://servforge.legi.grenoble-inp.fr/projects/soft-uvmat/search?q=wiki%3ACalibrationType CalibrationType]>= 'rescale', [[BR]] R (i=1)= [pxcmx 0 0] R (i=2)= [0 pxcmy 0] R (i=3)= [0 0 1], [[BR]]where pxcmx and pxcmy are the scaling factors along x and y.
     607
     608 * <omc> 3 components of the rotation vector (this is for diagnostic use, it is redondant with the matrix R used for actual coordinate transforms).  The physical coordinate axis are transformed to the image coordinate axis by a composition of the translation T and the rotation)
     609
     610 * <ErrorRms>: rms difference (in X and Y direction) between the image coordinates measured for the calibration points and the coordinates transformed from their physical coordinates (using the function ''px_XYZ.m in uvmat'')
     611
     612 * <ErrorMax> : maximum difference (in X and Y direction) between the image coordinates measured for the calibration points and the coordinates transformed from their physical coordinates. (using the function ''px_XYZ.m'' in uvmat)
     613
     614 * <SourceCalib> set of the point coordinates used for calibration
     615
     616 * <PointCoord> [x y z X Y] , where x,y,z are the physical coordinates of each point, X Y its image coordinates
     617
     618 * <NbSlice_i> nbre of slices for the first field  index i (multilevel case), =1 by default.
     619
     620 * <NbSlice_j> nbre of slices for the second index j (volume scan), =1 by default.
     621
     622 * <SliceCoord> [x y z] positions (nb lines) of the nb planes, where nb=NbSlice_i (multilevel case) or nb=NbSlice_j of j indices (volume scan), for parallel volume scan, x=y=0, z= slice height, for angular scan, [x,y,z]=[origin].
     623
     624 * <SliceDZ>   step distance between planes, or
     625
     626 * <SliceDPhi> step angle for angular scan.
    629627
    630628== 9- Masks and grids ==
    631629=== 9.1 Masks ===
    632 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 [section 3.6->#sec3.6_mask].
    633 Mas 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.
     630Mask 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 [section 3.6->#sec3.6_mask].  Mas 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.
    634631
    635632First open an input image file name with the browser, or the edit box and carriadge 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.
     
    645642
    646643The grid will be limited to an  image , or to the common region of two images, depending whether one or two image names are indicated in the edit boxes image_1 and image_2. Press save to save the corresponding grid file (s). A dialog box appears to edit the name of the output grid file, and a second one in case of two images.
    647 
     644----------------------------
    648645== 10 - Processing field series ==
    649646=== 10.1 The GUI series.fig ===
     
    704701
    705702By selecting the press button 'peaklocking' on the 'plotgraph' interface, you smooth the current velocity histograms while preserving its integral over each unity (in pixels). This appears in red. Then an estimate of the peaklocking error is obtained by comparing the initial histogram to the smooth one.
    706 
     703----------------------------
    707704== 11 - PIV: Particle Imaging Velocimetry ==
    708705=== 11.1 Overview ===
     
    837834|   |  '''        civ2'''          | '''interp2'''  |        '''filter2 '''          | | dim.  |        nb_vectors2  |        nb_vec2_patch  |        nb_vec2_patch  | |x          |vec2_X          |vec2_patch_X  |        vec2_patch_X | |y          |         vec2_Y  |        vec2_patch_Y |         vec2_patch_Y | |z          |        vec2_Z |         vec2_patch_Z  |        vec2_patch_Z | |u                  |vec2_U |         vec2_patch0_U  |        vec2_patch_U | |v                   |vec2_V          |vec2_patch0_V  |        vec2_patch_V | |w           |        vec2_W          |vec2_patch0_W|          vec2_patch_W | |correlation  |        vec2_C  |          |          | |warning flag  |        vec2_F |          |          | |false flag  |        vec2_FixFlag |          |          | |du/dx  |         |vec2_patch0_DUDX          |vec2_patch_DUDX          | |du/dy  |         |vec2_patch0_DUDY          |vec2_patch_DUDY          | |dv/dx  |         |vec2_patch0_DVDX          |vec2_patch_DVDX          | |dv/dy  |         |vec2_patch0_DVDY          |vec2_patch_DVDY          |
    838835
    839 ----
     836---------------
    840837== 12 Tridimensional features:(to update **) ==
    841838=== 12-1 Multilevel image scanning ===
     
    843840
    844841=== 12-2 Volume image scanning ===
    845 === 12-3 3D3C PIV ** === 
     842=== 12-3 3D3C PIV ** ===
    846843This is performed by the GUI '''civ_3D.fig'''. The program requires input volume images .vol. These are images in the  png format, where  npz slices are concatenated along the y direction, forming a composite image of dimension (npy x npz, npx) from the images (npy x npx). These volume images can be created by the function {ima2vol.m} in {/series}.
    847 
     844----------------------------
    848845== 13 Editing xml files with the GUI editxml ==
    849846  This GUI '''editxml.fig''' visualises and edits xml files. It is automatically called by the browser of '''uvmat.fig''' when a file with extension .xml is opened.
     
    854851
    855852  Manual editing of element value is possible. Select the element and use the lower edit box. This edit box transforms in a menu when a preselected list of allowed input values has been set by the schema.
    856 
    857 == Appendix: overview of the package functions ==
     853----------------------------
     854== 14-Appendix: overview of the package functions ==
    858855=== Master GUI ===
    859856 * 'uvmat';...% master function for file scanning and visualisation of 2D fields