Changes between Version 50 and Version 51 of UvmatHelp


Ignore:
Timestamp:
Jun 7, 2013, 8:02:31 AM (7 years ago)
Author:
sommeria
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UvmatHelp

    v50 v51  
    5555The menu bar at the top of the GUI contains the following buttons:
    5656
    57  * '''[Open]''': gives access to the browser for the main input field. 
    58    * '''[browse...]''': open a general file browser ''browser_uvmat''. In the displayed list, a file can be selected for opening  (by a single mouse click),or directories are marqued by '+/'.  Select the first line '+/..' to move up in the directory tree, and the arrow <-- to move backward. The dates of file creation can be displayed by pressing the button '''[dates]'''. file ordering by name or date can be chosen by the popumenu above. A path can be directly entered by copy-paste in the upper edit window of the browser. 
     57 * '''[Open]''': gives access to the browser for the main input field.
     58   * '''[browse...]''': open a general file browser ''browser_uvmat''. In the displayed list, a file can be selected for opening  (by a single mouse click),or directories are marqued by '+/'.  Select the first line '+/..' to move up in the directory tree, and the arrow <-- to move backward. The dates of file creation can be displayed by pressing the button '''[dates]'''. file ordering by name or date can be chosen by the popumenu above. A path can be directly entered by copy-paste in the upper edit window of the browser.
    5959   * '''[browse campaign...]''':  scan the data organised as a project/campaign, see [#a3.7Dataorganisationinaproject section 3.7].
    60    *  Previously opened fields are memorised in the menu and can be  directly selected again.
     60   * Previously opened fields are memorised in the menu and can be  directly selected again.
    6161
    6262 * '''[Open_1] ''': used like '''[Open]''' to select a second field, for comparisons with the main one.
     
    6666 * '''[Projection object] ''': used to create projection objects (points, lines, patches, gridded planes) for data analysis and interpolation
    6767
    68  * '''[Tools]''': 
    69    * '''[Geometric calibration]''' for geometric calibration of images 
    70    * '''[LIF calibration]''':  calibration of images for Laser Induced Fluorescence 
    71    * '''[Make mask]''': for creating mask images (for PIV) 
    72    * '''[Make grid]:''': for making measurement grids for PIV 
     68 * '''[Tools]''':
     69   * '''[Geometric calibration]''' for geometric calibration of images
     70   * '''[LIF calibration]''':  calibration of images for Laser Induced Fluorescence
     71   * '''[Make mask]''': for creating mask images (for PIV)
     72   * '''[Make grid]:''': for making measurement grids for PIV
    7373   * '''[ruler]''': displays a ruler to measure lengths and angles of any line.
    7474
    75  * '''[Run] ''': 
    76    * '''[Field series]''': gives access to the GUI '''series.fig''' for analysis of field series 
     75 * '''[Run] ''':
     76   * '''[Field series]''': gives access to the GUI '''series.fig''' for analysis of field series
    7777   * '''[PIV(CIV)]''':  gives access to the GUI '''civ.fig''' for Particle Imaging Velocimetry
    7878
     
    9999 * '''Coordinate aspect ratio:''' when '''[!CheckFixAspectRatio]''' is selected (the default option for images), the scale ratio for the  x and y coordinates is fixed to 1 by default (it can be manually adjusted by the edit box '''[num_AspectRatio]'''. When '''[!CheckFixAspectRatio]''' is not selected the graph scales along x and y automatically adjust to the figure size.
    100100
    101  * '''Extracting graphs:'''   The graph displayed in the central window can be copied to a separate figure by pressing the menu bar command '''[Export/extract figure]'''. This allows plot editing, exporting in image format and printing, using standard Matlab graphic tools. Plots can be also exported on an existing figure for data comparison, using the option '''[Export/export on axis]'''. A movie can be produced using the command '''[Export/make movie avi]'''. 
     101 * '''Extracting graphs:'''   The graph displayed in the central window can be copied to a separate figure by pressing the menu bar command '''[Export/extract figure]'''. This allows plot editing, exporting in image format and printing, using standard Matlab graphic tools. Plots can be also exported on an existing figure for data comparison, using the option '''[Export/export on axis]'''. A movie can be produced using the command '''[Export/make movie avi]'''.
    102102
    103103 * '''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.
    104 
    105104
    106105== 3 Input files and navigation with uvmat ==
     
    114113For 3D PIV**, 'volume' images, with file extension .vol are used. These are images in the  png format, where the npz slices are concatenated along the y direction, forming a composite image of dimension (npy x npz, npx) from the images (npy x npx).
    115114
    116 === 3.2 Selecting fields from CIV  ===
     115=== 3.2 Selecting fields from CIV ===
    117116The 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].
    118117
     
    130129-'''Simple series:''' files in a series can be labeled by a single integer index i, with name obtained by concatenation of the full root ''!RootPath/RootFile''), an index string suffix, and the file extension ''!FileExt'' (example ''Exp01/aa_45.png'').  A frame series can be alternatively read from a  single movie file. Then the index ''i'' stands for the frame index within the file.
    131130
    132 -'''Double index series: ''' they are labeled by two integer indices i and j, with names obtained by concatenating the full root, the suffix '_i_j' and the file extension(e.g. {Exp/aa_45_2.png}). 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.
    133 
    134 -'''Pair file 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, the two indices are merged in a single label i, or a single index j if j1=j2.
    135 
    136 -'''Nomenclature types:''' These different indexing systems are implemented by a  functions {fullfile_uvmat.m}. The inputs are the root name, four indices i1,i2,j1,j2 and a character string representing 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}. Once the nomenclature type has been detected by the browser of '''uvmat.fig''', it is displayed in the edit box '''[!NomType]''' of '''uvmat.fig'''. This nomenclature type is defined as the index string for the first file in the series, for instance '_1' for a single indexing and '1_1-2' for a double indexing. For a field series in a single file, like a movie, the nomenclature type is '*'. 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.
     131-'''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.
     132
     133-'''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.
     134
     135-'''Nomenclature types:''' The ''nomenclature type'' is defined as the character string representing the index 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 [wiki:NomType 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 file names when the series is scanned.
    137136
    138137=== 3.4 Navigation among file indices ===
     
    160159The xml file <!ImaDoc> can contain the following sections:
    161160
    162  * <Heading>: contains elements <Campaign>, <Experiment>, <!DataSeries>, which recall the position of the file in the tree structure of data files. This allows the user  to check that the document file has not been displaced. 
    163  * <Camera> contains information on the camera settings, as well as the timing of all the images in a subsection <!BurstTiming>. <!TranslationMotor> and <Oscillator> contains information on the mechanical devices used to produce the laser sheet and scan volumes. 
    164  * <!GeometryCalib> contains the parameters of the geometric calibration relating the pixel position to the real space coordinates (see [#a8-Geometriccalibration section 8]]). In the case of volume scanning, it also describes the set of laser plane positions and angles. 
    165  * <Illumination> describes the illumination system used, including the position of the laser source. 
    166  * <Tracor> describes the properties of the flow tracor (particle, dye...) 
     161 * <Heading>: contains elements <Campaign>, <Experiment>, <!DataSeries>, which recall the position of the file in the tree structure of data files. This allows the user  to check that the document file has not been displaced.
     162 * <Camera> contains information on the camera settings, as well as the timing of all the images in a subsection <!BurstTiming>. <!TranslationMotor> and <Oscillator> contains information on the mechanical devices used to produce the laser sheet and scan volumes.
     163 * <!GeometryCalib> contains the parameters of the geometric calibration relating the pixel position to the real space coordinates (see [#a8-Geometriccalibration section 8]]). In the case of volume scanning, it also describes the set of laser plane positions and angles.
     164 * <Illumination> describes the illumination system used, including the position of the laser source.
     165 * <Tracor> describes the properties of the flow tracor (particle, dye...)
    167166
    168167The detailed commented structure is provided  in the schema file ''ImaDoc.xsd''. The xml documentation file is read by the function ''imadoc2struct.m''. If this file does not exist, a file with the same root name but extension .civ is sought (obsolete format).
    169168
    170169=== 3.6 Ancillary input files ===
    171  * ''' Mask:''' Masks are used to avoid PIV computations in specified areas. The file is a B&W 8 bit png image, with the same size as the image it has to mask. The grayscale code used is :
    172    * Intensity < 20: ('black mask') the vector in this place will be set to zero
    173    * 20 < Intensity < 200:('gray mask') the vector in this place will be absent 
    174    * Intensity>200  the vector will be computed
    175  The mask corresponding to an image or velocity field can be displayed in '''uvmat.fig''' by selecting the check box '''[view_mask]([CheckMask])''' on the upper left. Images with appropriate name can be automatically recognised by '''uvmat.fig''' and civ functions, see [#a9-Masksandgrids section 9.1]. Otherwise file selection by a browser is proposed when '''[view_mask]''' is selected.
    176 
    177  * ''' 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
     170 * ''' Mask:''' Masks are used to avoid PIV computations in specified areas. The file is a B&W 8 bit png image, with the same size as the image it has to mask. The grayscale code used is :
     171   * Intensity < 20: ('black mask') the vector in this place will be set to zero
     172   * 20 < Intensity < 200:('gray mask') the vector in this place will be absent
     173   * Intensity>200  the vector will be computed  The mask corresponding to an image or velocity field can be displayed in '''uvmat.fig''' by selecting the check box '''[view_mask]([CheckMask])''' on the upper left. Images with appropriate name can be automatically recognised by '''uvmat.fig''' and civ functions, see [#a9-Masksandgrids section 9.1]. Otherwise file selection by a browser is proposed when '''[view_mask]''' is selected.
     174
     175 * ''' 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
    178176{{{
    179177n X1 Y1 X2 Y2  ......  Xn Yn
    180178}}}
     179
    181180The coordinates correspond to the center of the correlation box on the first image of the pair (the actual vector position will be shifted by half the displacement found between the two images). A tool to create grids is described in [#a9-Masksandgrids section 9.2].
    182181
    183182 * '''.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'''.
    184183
    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''). 
    186    * Example : %... gives comments (not included in the file). This 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 correspopnding .civ file is named aa.civ. 
     184 * ''''.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'').
     185   * Example : %... gives comments (not included in the file). This 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 correspopnding .civ file is named aa.civ.
    187186
    188187{{{
     
    20120019 450.000824 30 60 30 1           
    202201}}}
    203 
    204202 * '''.cmx''' ascii text files containing the parameters sent by the GUI '''civ.fig''' to the CIV fortran programmes. Each velocity field named *.nc results from a parameter file *.cmx. It can be opened by the browser of '''uvmat.fig'''. In a later version of civx**, the .cmx file is replaced by a .xml ’!CivDoc’ file.
    205203
     
    207205
    208206=== 3.7 Data organisation in a  project: ===
    209 The package is designed to foster a good data organisation. The raw data from a project should be organised as:[[BR]] 
    210 '''!Project/Campaign/Experiment/DataSeries/data files'''.
    211 
    212  * 'Project': contains all information from a project.
    213  * 'Campaign' corresponds to a series of experiments obtained by varying a given set of physical parameters. A set of  parameter names (with units) is expected to be associated to a campaign. A project may involve several campaigns corresponding to different configurations, hence different relevant parameters. For a single configuration, 'Campaign' can be at the top of the data tree, without an additional 'Project' level. The uvmat package does not manage levels above 'Campaign'. 
    214  * 'Experiment' is a directory containing all the data for a particular experiment, defined by a choice of values for the physical parameters.
    215  * '!DataSeries' contains an image series or movie from a camera, or more generally a data series from a device. Its name must correspond to the device and remain the same for all the experiments using this device. The results from data processing, as provided by 'civ' or 'series', are stored at the same level in a !DataSeries directory, named from the source one with a extension specific to the processing program, for instance .civ for civ. ''
     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'''.
     208
     209 * 'Project': contains all information from a project.
     210 * 'Campaign' corresponds to a series of experiments obtained by varying a given set of physical parameters. A set of  parameter names (with units) is expected to be associated to a campaign. A project may involve several campaigns corresponding to different configurations, hence different relevant parameters. For a single configuration, 'Campaign' can be at the top of the data tree, without an additional 'Project' level. The uvmat package does not manage levels above 'Campaign'.
     211 * 'Experiment' is a directory containing all the data for a particular experiment, defined by a choice of values for the physical parameters.
     212 * '!DataSeries' contains an image series or movie from a camera, or more generally a data series from a device. Its name must correspond to the device and remain the same for all the experiments using this device. The results from data processing, as provided by 'civ' or 'series', are stored at the same level in a !DataSeries directory, named from the source one with a extension specific to the processing program, for instance .civ for civ. ''''
    216213
    217214'''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'.
    218215
    219216== 4 Field display ==
    220 
    221217The uvmat interface primarily reads and visualises two-dimensional fields, which can be images or scalars, or vector fields.
    222218
     
    249245-'''Error flags''': they mark in magenta color vectors considered as false. These vectors are kept in the data set so that their elimination can be reversed, but they must not be taken into account for data processing. They can be removed for visualisation by selecting the check box '''[!CheckHideFalse]'''.
    250246
    251 -'''Associated scalar: '''  for PIV velocity fields, the color  represents by default the image correlation, ranging from 0 to 1.  The red values correspond to poor correlations, green to fair values, and blue to good ones. The value range covered by each of the three colors is set by the pair of sliders  '''[Slider1]''' and '''[Slider2]''', or equivalently by the edit boxes '''[num_ColCode1]''' and '''[num_ColCode2]'''. Other color representations can be specified. '''[!ColorScalar]''' sets the scalar used for color representation, for instance the vector norm 'norm_vec' or vorticity 'vort' (the list of available scalars is set by the function {calc_scal.m}).  '''[ColorCode] ''' sets the kind of color representation:
    252  * 'rgb':  color ranging from red, for the scalar value set by '''[num_MinVec]''', to blue, for the scalar value set by  '''[num_MaxVec]'''. The  color thresholds from red to green and green to blue are set by '''[ColCode1]''' and '''[ColCode2]''' respectively, or the sliders  '''[Slider1]''' and '''[Slider2]'''. By unselecting the check box [CheckFixVecColor], these thresholds can be set to match the min and max scalar values.
    253  * 'black' or 'white': set the color for all vectors
    254  * 'brg': same as rgb but in reverse order, with blue for the lowest scalar values. 
     247-'''Associated scalar: '''  for PIV velocity fields, the color  represents by default the image correlation, ranging from 0 to 1.  The red values correspond to poor correlations, green to fair values, and blue to good ones. The value range covered by each of the three colors is set by the pair of sliders  '''[Slider1]''' and '''[Slider2]''', or equivalently by the edit boxes '''[num_ColCode1]''' and '''[num_ColCode2]'''. Other color representations can be specified. '''[!ColorScalar]''' sets the scalar used for color representation, for instance the vector norm 'norm_vec' or vorticity 'vort' (the list of available scalars is set by the function {calc_scal.m}).  '''[ColorCode] ''' sets the kind of color representation:
     248
     249 * 'rgb':  color ranging from red, for the scalar value set by '''[num_MinVec]''', to blue, for the scalar value set by  '''[num_MaxVec]'''. The  color thresholds from red to green and green to blue are set by '''[ColCode1]''' and '''[ColCode2]''' respectively, or the sliders  '''[Slider1]''' and '''[Slider2]'''. By unselecting the check box [CheckFixVecColor], these thresholds can be set to match the min and max scalar values.
     250 * 'black' or 'white': set the color for all vectors
     251 * 'brg': same as rgb but in reverse order, with blue for the lowest scalar values.
    255252 * '64 colors': quasi-continuous color representation, ranging from blue (for the scalar value given by '''[num_MinVec]''', to red, for the scalar value given by '''[num_MaxVec]'''.
    256253
     
    281278
    282279=== 4.6 Succession of operations: ===
    283 The following succession of operations is performed by '''uvmat.fig''':
    284 -'''File Reading:''' the input field is first read from the input file by the Matlab functions {imread.m}, {mmreader.m}, or {aviread.m} for images,  or the uvmat functions {nc2struct.m} or {read_civxdata.m} for netcdf files.
    285 -'''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).  -'''Transform:''' by default the 'phys' option transforms each of the input fields from pixel to physical coordinates. This operation can also combine two input fields.
    286 -'''Histogram:''' This is obtained from the input field in transformed coordinates, or if applicable from the fields resulting from the two input fields.
    287 -'''Projection:''' on  the projection object selected in the menu '''[list_object_1]''', see [section 7->#get_field]. A second projection, on the object selected by '''[list_object_1]''', can be plotted in the anciillary figure '''view_field.fig'''. Function used: {proj_field.m}.
    288 -'''Field calculation:''' a scalar can be calculated from each of the input fields, as selected by the menu '''[Fields]'''. This is performed by the function {calc_field.m}.
    289 -'''Field comparison''': when two fields of the same nature are introduced, the difference is taken by the function {sub_field.m.}. This is skipped if the transform function has already led to a single field. 
    290 -'''Plotting:''' plot the results of projection. Function used: {plot_field.m}
     280The following succession of operations is performed by '''uvmat.fig''':  -'''File Reading:''' the input field is first read from the input file by the Matlab functions {imread.m}, {mmreader.m}, or {aviread.m} for images,  or the uvmat functions {nc2struct.m} or {read_civxdata.m} for netcdf files.  -'''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).  -'''Transform:''' by default the 'phys' option transforms each of the input fields from pixel to physical coordinates. This operation can also combine two input fields.  -'''Histogram:''' This is obtained from the input field in transformed coordinates, or if applicable from the fields resulting from the two input fields.  -'''Projection:''' on  the projection object selected in the menu '''[list_object_1]''', see [section 7->#get_field]. A second projection, on the object selected by '''[list_object_1]''', can be plotted in the anciillary figure '''view_field.fig'''. Function used: {proj_field.m}.  -'''Field calculation:''' a scalar can be calculated from each of the input fields, as selected by the menu '''[Fields]'''. This is performed by the function {calc_field.m}.  -'''Field comparison''': when two fields of the same nature are introduced, the difference is taken by the function {sub_field.m.}. This is skipped if the transform function has already led to a single field.   -'''Plotting:''' plot the results of projection. Function used: {plot_field.m}
    291281
    292282== 5- Field structures ==
    293 
    294283=== 5.1 Griding of data ===
    295284Physical 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  [#a6-Projectionobjects: next section]).  The three possibilities of griding are defined as follows:
     
    311300This 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 {site} ${\bf r}$ is expressed in the form, (see http://coriolis.legi.grenoble-inp.fr/spip.php?article73)
    312301
    313 $$\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 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 coefficients therefore contain all the information for interpolation at any point.
     302$$\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 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 coefficients therefore contain all the information for interpolation at any point. ^
    314303
    315304Because 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.
     
    322311This field has a specific organisation, mirroring the structure of netcdf files (see [#a7-Netcdffilesandget_field.fig: section 7]). The field is described by a set of (single or multidimensional) data arrays, called the ''variables''. The ''dimensions'' of these arrays have names, in order to identify correspondance between different arrays. For instance the arrays representing the velocity components U and V must have the same dimensions. A dimension has a specific value, which sets the common size of all arrays sharing this dimension. Field description furthermore involves optional ''attributes'' to document the field data, for instance to specify the role of variables or to provide units. These attributes can be global, or can be attached to a specific variable.
    323312
    324 In summary, the ''field structure'' is specified by the following elements: 
    325  * (optional) '''ListGlobalAttribute:''' list (cell array of character strings) of the names of global attributes  Att_1, Att_2...
    326  * (mandatory) '''ListVarName:''' list of the variable names Var_1, Var_2....(cell array of character strings).
    327  * (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.
    328  * (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]).
    329  * .Att_1, Att_2... : values of the listed global attributes.
     313In summary, the ''field structure'' is specified by the following elements:
     314
     315 * (optional) '''!ListGlobalAttribute:''' list (cell array of character strings) of the names of global attributes  Att_1, Att_2...
     316 * (mandatory) '''!ListVarName:''' list of the variable names Var_1, Var_2....(cell array of character strings).
     317 * (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.
     318 * (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]).
     319 * .Att_1, Att_2... : values of the listed global attributes.
    330320 * .Var_1, .Var_2...: variables arrays whose names are listed in !ListVarName.
    331321
    332 In 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.
    333  * '''ListDimName:''' list of dimension names (cell array of character strings) 
    334  * '''DimValue:''' array of dimension values corresponding to !LisDimName.
    335 
    336 The following temporary information is added to manage projection and field substraction oerations, which must be done in general after projection:
    337  * '''!FieldRequest'''= ''interp_lin'' or ''interp_tps'' indicates whether lin interpolation  or derivatives by tps is needed to calculate the requested field.
    338  * '''Operation''': name (char string) of the operation to be performed to finalise the field cell after projection.
     322In 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.
     323
     324 * '''!ListDimName:''' list of dimension names (cell array of character strings)
     325 * '''!DimValue:''' array of dimension values corresponding to !LisDimName.
     326
     327The following temporary information is added to manage projection and field substraction oerations, which must be done in general after projection:
     328
     329 * '''!FieldRequest'''= ''interp_lin'' or ''interp_tps'' indicates whether lin interpolation  or derivatives by tps is needed to calculate the requested field.
     330 * '''Operation''': name (char string) of the operation to be performed to finalise the field cell after projection.
    339331 * '''!SubCheck'''= 0 /1 indicate that the field must be substracted (second  entry in uvmat)
    340332
     
    342334
    343335=== 5.3 Conventions for attributes in field objects: ===
    344 -'''Global attributes active in uvmat''': those are used for plot settings or data processing.
    345  * 'Conventions':
     336-'''Global attributes active in uvmat''': those are used for plot settings or data processing.
     337
     338 * 'Conventions':
    346339   * ='uvmat': indicate that the conventions described here are followed
    347    * ='uvmat/civdata': indicate that the variables are named according to [#civdata]. 
    348  * '!CoordMesh': typical mesh for coordinates, used to define default projection grids and mouse selection action. Calculated automatically from the data if not specified. 
    349  * '!CoordUnit': character string representing the unit for space coordinates. It is used to distinguish image coordinates (!CoordUnit='pixel') and physical (for instance  !CoordUnit='cm'). If '!CoordUnit' is defined,  [projection ->#set_object] will be allowed only on objects with the same '!CoordUnit', and plots will be done by default with axis option 'equal' (same scale for both axis). 
    350  * 'Dt': time interval for CIV data. It is used for calibration, to transform displacement into velocity. 
    351  * 'Time': real number indicating the time of the field, used to obtain time series from data sets. 
     340   * ='uvmat/civdata': indicate that the variables are named according to [#civdata #civdata].
     341 * '!CoordMesh': typical mesh for coordinates, used to define default projection grids and mouse selection action. Calculated automatically from the data if not specified.
     342 * '!CoordUnit': character string representing the unit for space coordinates. It is used to distinguish image coordinates (!CoordUnit='pixel') and physical (for instance  !CoordUnit='cm'). If '!CoordUnit' is defined,  [projection ->#set_object] will be allowed only on objects with the same '!CoordUnit', and plots will be done by default with axis option 'equal' (same scale for both axis).
     343 * 'Dt': time interval for CIV data. It is used for calibration, to transform displacement into velocity.
     344 * 'Time': real number indicating the time of the field, used to obtain time series from data sets.
    352345 * '!TimeUnit': character string representing the unit of time (consistently for Time, Dt and velocity).
    353346
    354 -'''Global attributes , unactive''' those are merely used for information purpose
    355  * Project: recalls the project name
    356  * Campaign: recalls the campaign name
    357  * Experiment:  recalls the experiment name(s) of the raw data
    358  * DataSeries:  recalls the device name (s), if defined, of the raw data   
    359  * ObjectStyle: ='points', 'line', 'plane', denotes the style of geometric object on which the data have been 'projected'. For instance a profiler project a physical field along a line. 
    360  * ObjectCoord:  Coordinates defining a geometric object on which the data have been projected. 
    361  * ObjectRangeX, ObjectRangeY, ObjectRangeZ : range of action of a projection object along each coordinate, see section 6.   
     347-'''Global attributes , unactive''' those are merely used for information purpose
     348
     349 * Project: recalls the project name
     350 * Campaign: recalls the campaign name
     351 * Experiment:  recalls the experiment name(s) of the raw data
     352 * DataSeries:  recalls the device name (s), if defined, of the raw data
     353 * ObjectStyle: ='points', 'line', 'plane', denotes the style of geometric object on which the data have been 'projected'. For instance a profiler project a physical field along a line.
     354 * ObjectCoord:  Coordinates defining a geometric object on which the data have been projected.
     355 * ObjectRangeX, ObjectRangeY, ObjectRangeZ : range of action of a projection object along each coordinate, see section 6.
    362356 * '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.
    363357
    364 -'''Attributes of variables:'''
    365  * Mesh: suggested step value to discretize the values of the variable, used to define the bins for histograms.
    366  * Role: it specifies the role of the variable arrays for plotting or processing programs, see below. if Role is not defined variables are considered by default as 'scalar'.
     358-'''Attributes of variables:'''
     359
     360 * Mesh: suggested step value to discretize the values of the variable, used to define the bins for histograms.
     361 * Role: it specifies the role of the variable arrays for plotting or processing programs, see below. if Role is not defined variables are considered by default as 'scalar'.
    367362 * 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).
    368363
    369 -'''The attribute 'Role':''' the following options are used for the attribute 'Role':
    370  * 'ancillary': information of secondary use, indicating for instance an error estimate of field variables within a field cell (omitted in plotting)
    371  * 'coord_x', 'coord_y',  'coord_z': represents a  sets of unstructured coordinates x, y  and z for the field variables sharing the same dimension name.
    372  * 'coord_tps': coordinates of thin plate shell (tps) centres used for spline interpolation.
    373  * 'discrete': field with discrete values (no spatial interpolation), repesented with dots (no line) in 1D plots.
    374  * 'errorflag': provides an error flag marking the field variables  as false or true within a field cell , default=0, no error. Different non zero values can mark different criteria of elimination, see [section 10.3->#sec10.3] for PIV data. Such flagging is reversible, since the data themselves are not lost.
    375  * 'grad_x', 'grad_y', 'grad_z'  :represents the x, y or z  component of a contravariant vector** (like gradients).
    376  * 'image_rgb': represents a color image. The last dimension of the array corresponds to the three color components 'rgb'. -* 'scalar': (default) represents a scalar field
    377  * 'tensor': represents a tensor field whose components correspond to the two last   dimensions of the array.**
    378  * vector: matrix whose last dimension states for the vector components.**
    379  * 'vector_x', 'vector_y', 'vector_z'  : represents the x, y or z  component of a vector (covariant) 
     364-'''The attribute 'Role':''' the following options are used for the attribute 'Role':
     365
     366 * 'ancillary': information of secondary use, indicating for instance an error estimate of field variables within a field cell (omitted in plotting)
     367 * 'coord_x', 'coord_y',  'coord_z': represents a  sets of unstructured coordinates x, y  and z for the field variables sharing the same dimension name.
     368 * 'coord_tps': coordinates of thin plate shell (tps) centres used for spline interpolation.
     369 * 'discrete': field with discrete values (no spatial interpolation), repesented with dots (no line) in 1D plots.
     370 * 'errorflag': provides an error flag marking the field variables  as false or true within a field cell , default=0, no error. Different non zero values can mark different criteria of elimination, see [section 10.3->#sec10.3] for PIV data. Such flagging is reversible, since the data themselves are not lost.
     371 * 'grad_x', 'grad_y', 'grad_z'  :represents the x, y or z  component of a contravariant vector** (like gradients).
     372 * 'image_rgb': represents a color image. The last dimension of the array corresponds to the three color components 'rgb'. -* 'scalar': (default) represents a scalar field
     373 * 'tensor': represents a tensor field whose components correspond to the two last   dimensions of the array.**
     374 * vector: matrix whose last dimension states for the vector components.**
     375 * 'vector_x', 'vector_y', 'vector_z'  : represents the x, y or z  component of a vector (covariant)
    380376 * 'warnflag': provides a warning flag about the quality of data for the field variables within a field cell., default=0, no warning.
    381377
     
    383379The variables of field objects are split into {field cells} representing spatial fields. Differerent types of field cells are identified for processing and plotting. This identification is performed by the function ''find_field_cells.m'' which first groups the variables into cells of variables sharing common variable dimensions, determines their spatial dimension, and idendify the following types.
    384380
    385  * Dimension variables: these are unique unidimensional variable arrays corresponding to a given dimension, leading to a cell with a single variable, dimension 1. This is interpreted as the set of coordinate values associated with this dimension. An alternative possibility, suitable for a coordiante with a constant grid mesh, is a variable array with two values with the same name as a dimension: it then specifies the lower and upper bounds of the coordinate. 
    386  * Field cell with unstructured coordinates: this is a cell of variables sharing the same set of unstructured coordinates, indicated by the attribute Role=coord_x, coord_y, coord_z. 
    387  * Field cell with structured coordinates: this is a cell of several variable(s) sharing the same set of dimensions associated with variables. (addditional dimension may indicate for instance a vector component, not associated with a coordinate). 
     381 * Dimension variables: these are unique unidimensional variable arrays corresponding to a given dimension, leading to a cell with a single variable, dimension 1. This is interpreted as the set of coordinate values associated with this dimension. An alternative possibility, suitable for a coordiante with a constant grid mesh, is a variable array with two values with the same name as a dimension: it then specifies the lower and upper bounds of the coordinate.
     382 * Field cell with unstructured coordinates: this is a cell of variables sharing the same set of unstructured coordinates, indicated by the attribute Role=coord_x, coord_y, coord_z.
     383 * Field cell with structured coordinates: this is a cell of several variable(s) sharing the same set of dimensions associated with variables. (addditional dimension may indicate for instance a vector component, not associated with a coordinate).
    388384 * Thin plate shell (tps) field cell: represents a set of coordinates and tps weights in  a way suitable for tps interpolation/filter.
    389385
    390 The field structure is furthermore indicated by using appropriate names for dimensions, but this is only for documentation, without  use in processing functions (except for coordinate dimensions denoting coordinate range, see above). The following conventions are used:   
    391  * coord_1,_2,_3: dimension with the same name as a coordinate variable array (coordinate dimension)
    392  * 'nb_coord': denotes the space dimension for vector components 
    393  * 'nb_coord_j', 'nb_coord_i': denotes the space dimensions for the two tensor components 
    394  * 'rgb' : denotes the diemension of the color component in a true color  image.
    395  * 'nb_point' or 'nb_vec' (for vectors) denotes the set of positions with unstructured coordinates.
    396  * 'nb_tps': dimension of the index for the tps centres
     386The field structure is furthermore indicated by using appropriate names for dimensions, but this is only for documentation, without  use in processing functions (except for coordinate dimensions denoting coordinate range, see above). The following conventions are used:
     387
     388 * coord_1,_2,_3: dimension with the same name as a coordinate variable array (coordinate dimension)
     389 * 'nb_coord': denotes the space dimension for vector components
     390 * 'nb_coord_j', 'nb_coord_i': denotes the space dimensions for the two tensor components
     391 * 'rgb' : denotes the diemension of the color component in a true color  image.
     392 * 'nb_point' or 'nb_vec' (for vectors) denotes the set of positions with unstructured coordinates.
     393 * 'nb_tps': dimension of the index for the tps centres
    397394 * 'nb_subdomain' denotes the dimension for the subdomain index for tps coefficients
    398395
     
    408405  The objects are defined by the following set of properties:
    409406
    410  * ''' {Name:} ''' any name given to the object 
    411  * ''' {Type:} ''' classify the object with the following choice: 
    412    * 'points': set of n points 
    413    * 'line': simple straight segment, defined by its two end points 
    414    * 'polyline': open line made of n-1 consecutive segments (defined by n points) 
    415    * 'rectangle': defined by its center, half width and half height. 
    416    * 'polygon': closed line made of n consecutive segments (defined by n points) 
    417    * 'ellipse': defined by its center, half width and half height. 
    418    * 'plane': plane with associated cartesian coordinates 
     407 * ''' {Name:} ''' any name given to the object
     408 * ''' {Type:} ''' classify the object with the following choice:
     409   * 'points': set of n points
     410   * 'line': simple straight segment, defined by its two end points
     411   * 'polyline': open line made of n-1 consecutive segments (defined by n points)
     412   * 'rectangle': defined by its center, half width and half height.
     413   * 'polygon': closed line made of n consecutive segments (defined by n points)
     414   * 'ellipse': defined by its center, half width and half height.
     415   * 'plane': plane with associated cartesian coordinates
    419416   * 'volume': volume with associated cartesian coordinates
    420417
     
    427424 * ''' {DX:} ''', ''' {DY:} ''', ''' {DZ:} ''':meash  along each coordinate defining a grid for interpolation.
    428425
    429  * ''' {Coord:} ''': matrix with two (for 2D fields) or three columns defining the object position. 
    430    * for  'points', 'line', 'polyline', 'polygon': matrix with n lines [xi yi zi], corresponding to each of the n defining points. Note that in 3D case, polygons must be included in a plane, which imposes restrictions on these coordinates. 
    431    * for 'rectangle', 'ellipse': coordinates of the center. 
     426 * ''' {Coord:} ''': matrix with two (for 2D fields) or three columns defining the object position.
     427   * for  'points', 'line', 'polyline', 'polygon': matrix with n lines [xi yi zi], corresponding to each of the n defining points. Note that in 3D case, polygons must be included in a plane, which imposes restrictions on these coordinates.
     428   * for 'rectangle', 'ellipse': coordinates of the center.
    432429   * for 'plane' or 'volume': coordinates of the origin of the new coordinate frame attached to the object.
    433430
     
    437434
    438435=== 6.3 Projection modes ===
    439 Each variable of the input field yields a corresponding variable in the projected field.  Integral quantities  (circulation, flux...) can be calculated as well. The result depends on the nature of the field variable (set by the variable attribute 'Role',  on the object style and projection mode ProjMode: when any averaging or interpolation process is involved, the only projected variables are scalars and vector components, excluding 'warnflag', 'errorflag', 'ancillary'. Those are only projected with the mode 'projection' on line, planes or volumes.     
     436Each variable of the input field yields a corresponding variable in the projected field.  Integral quantities  (circulation, flux...) can be calculated as well. The result depends on the nature of the field variable (set by the variable attribute 'Role',  on the object style and projection mode ProjMode: when any averaging or interpolation process is involved, the only projected variables are scalars and vector components, excluding 'warnflag', 'errorflag', 'ancillary'. Those are only projected with the mode 'projection' on line, planes or volumes.
    440437
    441438 * ''' {!ProjMode 'projection': } '''  this is a direct 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 variable on a regular grid on the projection project  (for instance on a line or plane).
     
    452449The result of projection can be easily checked by creating the object in uvmat, and using the menubar option '''[Export/field in workspace]'''  in '''view_field.fig'''.
    453450
    454  * ''' {Projection on n points:}  '''   for each variable U, a set of n values U(i),i=1 to n is obtained, together with the unstructured coordinates (X(i), Y(i)) of the n points, and Z(i) in 3D. 
    455   * ProjMode= 'projection': the value U(i) is obtained as an average of the (non false) data values in a domain  of sizes max(2RangeX, 2RangeY, 2RangeZ) centered at each projection point. An ancillary data U_nbval(i) is also obtained, indicating the number of non-false data around each point. 
    456   * ProjMode= 'interp_lin':   U(i),i=1 is obtained as a linear interpolation on each point.
    457 
    458  * ''' {Projection on open lines:} '''   This includes the object styles 'line', 'polyline'. For vector fields, the projected  x component is along the line and the y component is perpendicular. 3D case still needs to be implemented**. 
    459   * ProjMode='projection': in the case of unstructured coordinates, each data point in the region of action (width max(RangeY) around the line) is projected onto the line. The direction of projection is normal except if 'Phi' is non equal to 0 (only possible for 'line'). For structured coordinates with meshes DX,DY (DZ),  data are interpolated on the line with a mesh =min(DX,DY,DZ). For each field component U, a corresponding projected field U is produced. If DX is defined on the line, a smoothed field U_smooth is also calculated, as well as the mean U_mean along the line. 
     451 * ''' {Projection on n points:}  '''   for each variable U, a set of n values U(i),i=1 to n is obtained, together with the unstructured coordinates (X(i), Y(i)) of the n points, and Z(i) in 3D.
     452   * ProjMode= 'projection': the value U(i) is obtained as an average of the (non false) data values in a domain  of sizes max(2RangeX, 2RangeY, 2RangeZ) centered at each projection point. An ancillary data U_nbval(i) is also obtained, indicating the number of non-false data around each point.
     453   * ProjMode= 'interp_lin':   U(i),i=1 is obtained as a linear interpolation on each point.
     454
     455 * ''' {Projection on open lines:} '''   This includes the object styles 'line', 'polyline'. For vector fields, the projected  x component is along the line and the y component is perpendicular. 3D case still needs to be implemented**.
     456   * ProjMode='projection': in the case of unstructured coordinates, each data point in the region of action (width max(RangeY) around the line) is projected onto the line. The direction of projection is normal except if 'Phi' is non equal to 0 (only possible for 'line'). For structured coordinates with meshes DX,DY (DZ),  data are interpolated on the line with a mesh =min(DX,DY,DZ). For each field component U, a corresponding projected field U is produced. If DX is defined on the line, a smoothed field U_smooth is also calculated, as well as the mean U_mean along the line.
    460457 * ProjMode='interp_lin': non-false data are linearly interpolated on the line, with mesh =DX along the line. Data which are 'discrete','warnflag' or 'errorflag' (as defined by the attribute 'Role') are not projected.
    461458
    462  * ProjMode='interp_tps': same as 'interp' but with a smoothing operation.   
     459 * ProjMode='interp_tps': same as 'interp' but with a smoothing operation.
    463460
    464461 * ''' {Projection on closed lines:} '''  , This includes 'rectangle','ellipse','polygon'. For ProjMode='projection', 'interp', 'filter', it behaves like open lines (not all options implemented yet**). For ProjMode='inside' or 'outside', the pdf of each field variable, restricted to the inside or the outside respectively,  is calculated.
    465462
    466  * ''' {Projection on planes:}  ''' Data in the range of action (RangeZ on each side of the plane) are projected normally to the plane, and its position expressed with respect to the coordinate system attached to the plane. This coordinate system is defined by an origin, the plane position XObject,YObject, ZObject, the ranges [RangeX(1) RangeX(2)]  and [RangeY(1) RangeY(2)] for X and Y, and the Euler angles Phi, Theta, Psi. 
    467    * ProjMode='projection': in the case of unstructured coordinates, all field variables are projected onto the plane.  For structured coordinates with meshes DX,DY (DZ),  data are interpolated on the line with a mesh =min(DX,DY,DZ). 
     463 * ''' {Projection on planes:}  ''' Data in the range of action (RangeZ on each side of the plane) are projected normally to the plane, and its position expressed with respect to the coordinate system attached to the plane. This coordinate system is defined by an origin, the plane position XObject,YObject, ZObject, the ranges [RangeX(1) RangeX(2)]  and [RangeY(1) RangeY(2)] for X and Y, and the Euler angles Phi, Theta, Psi.
     464   * ProjMode='projection': in the case of unstructured coordinates, all field variables are projected onto the plane.  For structured coordinates with meshes DX,DY (DZ),  data are interpolated on the line with a mesh =min(DX,DY,DZ).
    468465   * ProjMode='interp_lin': non-false data are linearly interpolated on the grid defined by the plane coordinate system and and meshes DX, DY. Data which are 'discrete','warnflag' or 'errorflag' (as defined by the attribute 'Role') are not projected.
    469466   * ProjMode='interp_tps': same as interp_lin but with thin plate shell interpolation.
     
    480477  Object can be interactively drawn with the mouse on the GUI '''uvmat.fig ''' . First activate the creation mode by selecting the appropriate item in the menu bar Tools.
    481478
    482  * 'points': mark points with mouse left button. Use right click to end the series. The list of coordinates appear on the set_object interface.  These can be then manually edited, use plot on the GUI '''set_object.fig''' to validate. The range of action  can be set on the GUI '''set_object.fig''' by the edit box '''[YMax] ''' (only needed in the ProjMode 'projection'). This range is visualised by dashed circles around each point. The set of points can be determined from successive images (to track a feature for instance): for that purpose use the keyboard keys 'p' and 'm' to increament or decrement fields  without the mouse. 
    483  * 'line': just draw a line, keeping the mouse left button pressed, release to end. The range of action, set by '''[YMax]''', is visualised by two dashed lines (only if ProjMode='projection'). 
    484  * 'polyline': draw a line with several segments, press and release the mouse left button to mark each summit, press the right button to end the line. 
    485  * 'rectangle': defined by its center, half width and half height. 
    486  * 'polygon': closed line made of n consecutive segments (defined by n points) 
    487  * 'ellipse': defined by its center, half width and half height. 
    488  * 'plane': plane with associated cartesian coordinates 
     479 * 'points': mark points with mouse left button. Use right click to end the series. The list of coordinates appear on the set_object interface.  These can be then manually edited, use plot on the GUI '''set_object.fig''' to validate. The range of action  can be set on the GUI '''set_object.fig''' by the edit box '''[YMax] ''' (only needed in the ProjMode 'projection'). This range is visualised by dashed circles around each point. The set of points can be determined from successive images (to track a feature for instance): for that purpose use the keyboard keys 'p' and 'm' to increament or decrement fields  without the mouse.
     480 * 'line': just draw a line, keeping the mouse left button pressed, release to end. The range of action, set by '''[YMax]''', is visualised by two dashed lines (only if ProjMode='projection').
     481 * 'polyline': draw a line with several segments, press and release the mouse left button to mark each summit, press the right button to end the line.
     482 * 'rectangle': defined by its center, half width and half height.
     483 * 'polygon': closed line made of n consecutive segments (defined by n points)
     484 * 'ellipse': defined by its center, half width and half height.
     485 * 'plane': plane with associated cartesian coordinates
    489486 * 'volume': volume with associated cartesian coordinates
    490487
     
    576573  The coefficients are recorded in the xml element <code><ImaDoc/GeometryCalib></code> as follows:
    577574
    578 -<code><CalibrationType></code>: type of calibration ('rescale', 'linear', '3D...') -<code><fx_fy></code>: focal length along each coordinate of the image sensor, expressed in pixel interval. -<code><Cx_Cy></code>: position coordinates of the optical axis on the  -<code><kc></code>: coefficient of quadratic deformation (=1 for the options calib_lin and calib_rescale) -<code><CoordUnit></code>: coordinate unit in physical space. -<code><Tx_Ty_Tz></code>: translation, (Tz=1 for the options calib_lin and calib_rescale) -<code><R>:</code> rotation matrix (in 3 lines)
    579 
    580   For the option calib_rescale
    581     R (i=1)= [pxcmx 0 0] R (i=2)= [0 pxcmy 0] R (i=3)= [0 0 1]
    582 
    583 where pxcmx and pxcmy are the scaling factors along x and y. -<code><omc></code> 3 components of the rotation vector (this is for diagnostic use, it is redondant with the matrix R used for actual coordiante transforms).  The physical coordinate axis are transformed to the image coordinate axis by a composition of the translation T and the rotation) -<code><ErrorRms>:</code> 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 UVMAT/px.m) -<code><ErrorMax> </code>: 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 UVMAT/px.m) -<code><SourceCalib> </code>set of the point coordinates used for calibration -<code><PointCoord> </code>[x y z X Y] , where x,y,z are the physical coordinates of each point, X Y its image coordinates. -<code><NbSlice_i> </code>nbre of slices for the first field  index i (multilevel case), =1 by default. -<code><NbSlice_j> </code>nbre of slices for the second index j (volume scan), =1 by default. -<code><SliceCoord> </code>[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]. -<code><SliceDZ> </code>,  step distance between planes, or <code><SliceDPhi> </code> step angle for angular scan.
    584 
    585 [<doc115|right>->#top]
     575 * <CalibrationType>: type of calibration ('rescale', 'linear', '3D...')
     576
     577 * <fx_fy>: focal length along each coordinate of the image sensor, expressed in pixel interval.
     578
     579 * <Cx_Cy>: position coordinates of the optical axis on the
     580
     581 * <kc>: coefficient of quadratic deformation (=1 for the options calib_lin and calib_rescale)
     582
     583 * <CoordUnit>: coordinate unit in physical space.
     584
     585 * <Tx_Ty_Tz></code>: translation, (Tz=1 for the options calib_lin and calib_rescale)
     586
     587 * <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], where pxcmx and pxcmy are the scaling factors along x and y.
     588
     589 * <omc> 3 components of the rotation vector (this is for diagnostic use, it is redondant with the matrix R used for actual coordiante transforms).  The physical coordinate axis are transformed to the image coordinate axis by a composition of the translation T and the rotation)
     590
     591 * <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'')
     592
     593 * <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 UVMAT/px.m)
     594
     595* <SourceCalib> set of the point coordinates used for calibration
     596
     597   * <PointCoord> [x y z X Y] , where x,y,z are the physical coordinates of each point, X Y its image coordinates
     598
     599   * <NbSlice_i> nbre of slices for the first field  index i (multilevel case), =1 by default.
     600
     601   * <NbSlice_j> </code>nbre of slices for the second index j (volume scan), =1 by default.
     602
     603   * <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].
     604
     605  * <SliceDZ>   step distance between planes, or
     606
     607  * <SliceDPhi> step angle for angular scan.
    586608
    587609== 9- Masks and grids ==
    588610=== 9.1 Masks ===
    589   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].
    590 
     611Mask 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].
    591612Mas 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.
    592613
     
    606627== 10 - Processing field series ==
    607628=== 10.1 The GUI series.fig ===
    608 Operations on field series are controled by the GUI '''series.fig''', which allows the user to set the root name(s) and file indices over which a processing function operates. The GUI can be opened from '''uvmat''' through its menu bar option '''[Run/series]'''. It then mirrors the settings of '''uvmat'''. It can be alternatively opened by typing the Matlab command ''>>series'', then selecting  the input file series by the menu bar command '''[Open]'''. 
     629Operations on field series are controled by the GUI '''series.fig''', which allows the user to set the root name(s) and file indices over which a processing function operates. The GUI can be opened from '''uvmat''' through its menu bar option '''[Run/series]'''. It then mirrors the settings of '''uvmat'''. It can be alternatively opened by typing the Matlab command ''>>series'', then selecting  the input file series by the menu bar command '''[Open]'''.
    609630
    610631The 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.
    611632
    612 Several input file series can be introduced simultaneously by the menu bar command''' [Open_append]''', filling the successive lines of '''!InputTable'''. By contrast, the table of input files is fully refreshed by the browser of the menu bar command '''[Open]'''. The cells in the table can be also edited manually. Then press the button '''[REFRESH]''' to validate the input. 
    613 
    614 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 [#a11PIV:ParticleImagingVelocimetry 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'''. 
    615 
    616 The action function is first activated when it is selected in the menu '''[ActionName]'''. This first activation checks input data and sets the visibility of input GUI uicontrols. 
     633Several input file series can be introduced simultaneously by the menu bar command''' [Open_append]''', filling the successive lines of '''!InputTable'''. By contrast, the table of input files is fully refreshed by the browser of the menu bar command '''[Open]'''. The cells in the table can be also edited manually. Then press the button '''[REFRESH]''' to validate the input.
     634
     635The 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 [#a11PIV:ParticleImagingVelocimetry 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'''.
     636
     637The 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.
    617638
    618639The actual start of the processing is triggered by pressing the button '''[RUN]'''. It can be run in local mode, i.e. on the current Matlab session, or as ''background'', by selecting this option in '''!RunMode'''. In mode ''background'', calculation is performed in a new Matlab session (without graphics) so that the current Matlab session is free for new operations. If a cluster system has been detected, a third option ''cluster'' appears in the menu, allowing to dispatch parallel computations on a computer cluster. For the latter 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'').
     
    653674This action calls any user defined function by its name, acting on the series of fields defiend for ACTION. Some examples of usr_defined functions are in the subdirectory {/series}.
    654675
    655 -List of available functions:
    656  * ''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).
     676-List of available functions:
     677
     678 * ''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).
    657679 * ''ima_levels.m''
    658680 * ''ima2vol.m'' produce volume images for 3D3C PIV.
     
    664686== 11 - PIV: Particle Imaging Velocimetry ==
    665687=== 11.1 Overview ===
    666 
    667688PIV can be performed by selecting the Matlab function ''civ_series'' as '''[ActionName]''' in the GUI '''series'''. The same operations can be also performed with the older function ''civ.m'' running with the specific GUI '''civ.fig''', accessible from uvmat by the menu bar command '''[RUN/civ]'''. This older option is still used to run the fortran programs [CIVx].
    668689
     
    707728
    708729=== 11.3 FIX ===
    709 
    710730The FIX operation is used after civ to remove false vectors, using different criteria: -''' {warning flags:} ''' these are flags (vec_F) indicating problems with the image correlation process: -*vec_F(i)=0 or 1 : default , the processing is fine -*vec_F(i)=-2: 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: the search domain is too small -*vec_F(i)=2: (only in civ1) we keep the less accurate Hart result (resulting from combining correlation functions  from neighborhing points) and  vec_C(i)=-1 is chosen by convention. Reference: Hart D. P. (2000) 'PIV error correction',{ Exp. Fluids} '''29''', 13-22. -*vec_F(i)=3: the optimisation of the correlation function is unstable  or  local Intensity rms of the image =0 -*vec_F(i)=4:only in civ2: the difference between the estimator and the result is more than 1 pixel. The two criteria, vec_F(i)=-2, and 3, should be selected (default options). The criterium vec_F=2 (Hart) should not be selected, while vec_F=4 (for civ2) could be selected only for excellent data (otherwise it may be too strict).   -''' {Threshold on the image correlation}  ''' (vec_C) can be introduced by the edit box [thresh_vecC] (value between 0 and 1). It removes vectors with poor correlation.  -''' {Threshold on the velocity modulus } ''' (expressed in pixels): it can remove either too small values  (menu '''[inf_sup1]''' set to '<'), or excessive values (menu '''[inf_sup1]''' set to '>'). Erratic zero velocity vectors, produced by a fixed image background, can be eliminated by this criterium. These criteria can be as well applied to the difference with a reference field, defined by a file series (edit box '''[ref_fix1]''') and a field inside the file (menu '''[field_ref1]'''). -''' {Mask fix:} '''  It has the same effect as the one used in civ1, but the removed vectors are kept in memory, labelled as false. -''' {Manual fix:} ''' Interactive fixing with the mouse is also possible, see [section 4.2->#4.2].
    711731
     
    713733
    714734=== 11.4 PATCH ===
    715 
    716735-'''PATCH1: ''' interpolates the velocity values on a regular grid with a smoothing parameter rho. This also provides the spatial derivatives (vorticity, divergence) needed for the refined processing civ2. The numbers of grid points in x and y are set by nx and ny. The vectors which are too far from the smoothed field (erratic vectors) can be eliminated, using a threshold expressed in pixel displacement. The thin plate spline method must be done by subdomains for computational saving, use the default value 300.
    717736
    718737=== 11.5 CIV2 ===
    719 
    720738-'''CIV2:''' provides a refined calculation of the velocity field, using the civ1 result as previous estimate. The search range is determined by the civ1 field so there is no parameter. Use the option decimal shift to reduce peaklocking effects (advised). The option deformation is useful in the presence of strong shear or vorticity. Then image deformation and rotation is introduced before calculating the correlations. The other parameters (rho, ibx,iby, grid, mask) are used like for civ1 (take the same by default). The image pair for civ2 can be different than the one used in civ1 to get the first estimate. It is generally advised to use a moderate time interval for civ1, to avoid 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.
    721739
     
    745763
    746764=== 11.7 Description of the velocity files: === #civdata
    747 
    748765The velocity fields obtained by PIV, as well as their spatial derivatives, are stored in the machine independent binary format ['netcdf'->#netcdf]. The file contains constants ('global attributes') and fields ('variables') whose values can be directly accessed by their name.
    749766
     
    804821
    805822=== 12-2 Volume image scanning ===
    806 
    807823=== 12-3 3D3C PIV ** === This 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}.
    808824