Changes between Version 2 and Version 3 of UvmatHelp


Ignore:
Timestamp:
Jun 1, 2013, 3:04:15 PM (7 years ago)
Author:
sommeria
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UvmatHelp

    v2 v3  
    1 == 1 Generalities==
    2 
    3 === 1.1 Aim===
    4 
    5  The package uvmat can be used with a wide variety of input data: all image and movie formats recognised by Matlab (see [section 3.1->#sec3.1]),  NetCDF binary files (see [section 7->#get_field]). It is however particularly designed for laboratory data obtained  from imaging systems: it includes a GUI to run the Particle Image Velocimetry  software [CIVx ->3], as well as tools for geometric calibration, masks, grid generation and image pre-processing (e.g. background removal), and editing xml documentation files. Stereoscopic PIV, PIV-LIF and 3D PIV in a volume (still under development) are handled.
    6 
    7     This package can be used without knowledge of the Matlab language, but it is designed to be complemented by user defined Matlab functions, providing flexibility for further data analysis. It provides convenient tools to develop a set of processing functions with a standardised system for input-output.
    8 
    9         Installation is described in [Presentation and download ->4] with package available there in a static version. The latest version can be downloaded from a [svn server->http://servforge.legi.grenoble-inp.fr/projects/soft-uvmat]. 
    10 
    11 === 1.2 The package===
    12 
    13       The master piece is a Matlab GUI, made of a Matlab figure '''uvmat.fig''' and an associated set of sub-functions in the file {uvmat.m}. The menu bar at the top of the GUI, push buttons and editing box in  '''uvmat.fig''' activate the Matlab sub-functions (callback functions) in {uvmat.m}.  The package also contains the following set of GUI (see [overview of the package->#overview] for a complete list).
    14 
    15 -'''browse_data.fig''' scans the data directory of a project
    16 - '''civ.fig:''' runs the software for Particle Imaging Velocimetry
    17 - '''editxml.fig:'''  displays and edits xml files according to an xml schema. xml reading and editing is performed by the toolbox [xmltree->http://www.artefact.tk/software/matlab/xml/] , copied in the subdirectory /@xmltree.
    18 - '''geometry_calib.fig''': determines geometric calibration parameters for relating image to physical coordinates. The toolbox [->http://www.vision.caltech.edu/bouguetj/calib_doc/] is used, copied in the subdirectory /toolbox_calib.
    19 - '''get_field.fig:''' selects coordinates and field in a general NetCDF file. The subdirectory /get_field contains functions called by the GUI get_field.
    20 - '''series.fig:''' apply various processing functions to series of fields. These functions are stored in the subdirectory /series.
    21 -'''set_object.fig:''' creates and edits geometric objects used to project data: points, lines, planes...
    22 -'''view_field.fig:''' is a GUI complementing uvmat for plotting projected data.
    23     Functions in the package are used to generate file names, read files and plot data, and perform various ancillary tasks.
    24 
    25 === 1.3 Documentation and help=== 
    26         The present on-line file is the reference document for the version currently available on the svn server. A html version ({uvmat_doc.html}) of this document is provided with the package, and accessible by help buttons in the GUIs.
    27          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 tags of GUI uicontrols are quoted as '''[uicontrol tag]''', names of files in the package are quoted as {fct name.m}, and commands on the Matlab workspace as  '>> command’  . Features not yet implemented or tested (in particular 3D features) are marked by **.
    28 
    29         Information is also provided as comments in each function. Type '>>help fct_name'  to get it, or open it with an editor.
    30 
    31         Finally a on-line [tutorial->105] is also provided with test images and data files.
    32 
    33 === 1.4 Copyright and licence===
     1=Help for Uvmat=
     2
     3== 1 Generalities ==
     4
     5=== 1.1 Aim ===
     6
     7  The package uvmat can be used with a wide variety of input data: all image and movie formats recognised by Matlab (see [section 3.1->#sec3.1]),  NetCDF binary files (see [section 7->#get_field]). It is however particularly designed for laboratory data obtained  from imaging systems: it includes a GUI to run the Particle Image Velocimetry  software [CIVx ->3], as well as tools for geometric calibration, masks, grid generation and image pre-processing (e.g. background removal), and editing xml documentation files. Stereoscopic PIV, PIV-LIF and 3D PIV in a volume (still under development) are handled.
     8
     9  This package can be used without knowledge of the Matlab language, but it is designed to be complemented by user defined Matlab functions, providing flexibility for further data analysis. It provides convenient tools to develop a set of processing functions with a standardised system for input-output.
     10
     11  Installation is described in [Presentation and download ->4] with package available there in a static version. The latest version can be downloaded from a [svn server->http://servforge.legi.grenoble-inp.fr/projects/soft-uvmat].
     12
     13=== 1.2 The package ===
     14
     15  The master piece is a Matlab GUI, made of a Matlab figure '''uvmat.fig''' and an associated set of sub-functions in the file {uvmat.m}. The menu bar at the top of the GUI, push buttons and editing box in  '''uvmat.fig''' activate the Matlab sub-functions (callback functions) in {uvmat.m}.  The package also contains the following set of GUI (see [overview of the package->#overview] for a complete list).
     16
     17-'''browse_data.fig''' scans the data directory of a project - '''civ.fig:''' runs the software for Particle Imaging Velocimetry  - '''editxml.fig:'''  displays and edits xml files according to an xml schema. xml reading and editing is performed by the toolbox [xmltree->http://www.artefact.tk/software/matlab/xml/] , copied in the subdirectory /@xmltree. - '''geometry_calib.fig''': determines geometric calibration parameters for relating image to physical coordinates. The toolbox [->http://www.vision.caltech.edu/bouguetj/calib_doc/] is used, copied in the subdirectory /toolbox_calib.  - '''get_field.fig:''' selects coordinates and field in a general NetCDF file. The subdirectory /get_field contains functions called by the GUI get_field. - '''series.fig:''' apply various processing functions to series of fields. These functions are stored in the subdirectory /series. -'''set_object.fig:''' creates and edits geometric objects used to project data: points, lines, planes... -'''view_field.fig:''' is a GUI complementing uvmat for plotting projected data.
     18
     19  Functions in the package are used to generate file names, read files and plot data, and perform various ancillary tasks.
     20
     21=== 1.3 Documentation and help ===
     22  The present on-line file is the reference document for the version currently available on the svn server. A html version ({uvmat_doc.html}) of this document is provided with the package, and accessible by help buttons in the GUIs.
     23    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 tags of GUI uicontrols are quoted as '''[uicontrol tag]''', names of files in the package are quoted as {fct name.m}, and commands on the Matlab workspace as  '>> command’  . Features not yet implemented or tested (in particular 3D features) are marked by **.
     24
     25  Information is also provided as comments in each function. Type '>>help fct_name'  to get it, or open it with an editor.
     26
     27  Finally a on-line [tutorial->105] is also provided with test images and data files.
     28
     29=== 1.4 Copyright and licence ===
    3430Copyright Joel Sommeria, 2008, LEGI / CNRS-UJF-INPG, joel.sommeria@legi.grenoble-inp.fr.
    3531
    36         The package UVMAT is free software; it can be redistributed and/or modified it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
    37 
    38         UVMAT 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.
    39 
    40 [<doc115|right>->#top]
    41 ------------------
    42 [2-The GUI uvmat.fig<-]
    43 == 2 Overview of the GUI uvmat.fig===
    44 
    45 === 2.1 Opening the GUI===
    46 
    47     Type '>>uvmat' in the Matlab prompt to display the GUI. If the function is unknown by Matlab, add the appropriate path (see the Matlab command '>>help path'). When the GUI is opening, the date of last modfication  is displayed in the central window. During opening, the program checks the Matlab path to all the functions of the package (using the function {check_functions.m}). If a function is missing, or if it is overridden by a function with the same name at another path location, a message is  displayed in the central window at the opening of the  GUI '''uvmat.fig'''. Finally, if the svn server is availlable,  the latest version number of the uvmat package is indicated (if  line-command version of svn is available).
     32  The package UVMAT is free software; it can be redistributed and/or modified it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
     33
     34  UVMAT 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.
     35
     36[<doc115|right>->#top]
     37
     38----
     39[2-The GUI uvmat.fig<-]== 2 Overview of the GUI uvmat.fig===
     40
     41=== 2.1 Opening the GUI ===
     42  Type '>>uvmat' in the Matlab prompt to display the GUI. If the function is unknown by Matlab, add the appropriate path (see the Matlab command '>>help path'). When the GUI is opening, the date of last modfication  is displayed in the central window. During opening, the program checks the Matlab path to all the functions of the package (using the function {check_functions.m}). If a function is missing, or if it is overridden by a function with the same name at another path location, a message is  displayed in the central window at the opening of the  GUI '''uvmat.fig'''. Finally, if the svn server is availlable,  the latest version number of the uvmat package is indicated (if  line-command version of svn is available).
    4843
    4944<img55|center>
    5045
    51 The GUI contains an upper menu bar, a central display window, a lower left window for histogram, edit boxes and command buttons. 
     46The GUI contains an upper menu bar, a central display window, a lower left window for histogram, edit boxes and command buttons.
    5247
    5348Each of theses graphic elements is described by a tag name, which can be displayed by moving the mouse over it: a tool tip window appears with the tag name followed by a short help description. The element tag and content can be also displayed in a zoom window, and possibly edited there, by a right hand mouse selection on the element. As a rule, tag names for checkboxes begins by 'Check', while tags of elements with numerical content begins by 'num_'.
    5449
    55 The red pushbuttons command the main actions. Their color changes to yellow while they are active. 
    56 
    57 === 2.2 The menu bar===
    58 The menu bar at the top of the GUI contains the following buttons:
    59 -'''[Open]''': gives access to the browser for the main input field. Test for instance with any image, or data provided in  [UV_DEMO->105]. Previously opened fields are memorised  in the menu and can be  directly selected again.
    60 -*'''[browse...]''': usual file browser
    61 -*'''[browse campaign...]''':  scan the data organised as a project/campaign, see [section 3.7->#sec3.7].
     50The red pushbuttons command the main actions. Their color changes to yellow while they are active.
     51
     52=== 2.2 The menu bar ===
     53The menu bar at the top of the GUI contains the following buttons: -'''[Open]''': gives access to the browser for the main input field. Test for instance with any image, or data provided in  [UV_DEMO->105]. Previously opened fields are memorised  in the menu and can be  directly selected again. -*'''[browse...]''': usual file browser -*'''[browse campaign...]''':  scan the data organised as a project/campaign, see [section 3.7->#sec3.7].
    6254
    6355-'''[Open_1] ''': used like '''[Open]''' to select a second field, for comparisons with the main one.
    6456
    65 -'''[Export] ''': used to export the displayed data, either as arrays in the Matlab workspace, either as a figure or a movie (for a succession of views). 
     57-'''[Export] ''': used to export the displayed data, either as arrays in the Matlab workspace, either as a figure or a movie (for a succession of views).
    6658
    6759-'''[Projection object] ''': used to create projection objects (points, lines, patches, gridded planes) for data analysis and interpolation
     
    6961-'''[Edit] ''': used to edit projection objects or individual vectors in data fields.
    7062
    71 -'''[Tools]''':
    72 -*'''[Geometric calibration]''':  for geometric calibration of images
    73 -*'''[LIF calibration]''':  calibration of images for Laser Induced Fluorescence
    74 -*'''[Make mask]''': for creating mask images (for PIV)
    75 -*'''[Make grid]:''': for making measurement grids for PIV
    76 -*'''[ruler]''': displays a ruler to measure lengths and angles of any line.
    77 
    78 -'''[Run] ''':
    79 -*'''[Field series]''': gives access to the GUI '''series.fig''' for analysis of field series
    80 -*'''[PIV(CIV)]''':  gives access to the GUI '''civ.fig''' for Particle Imaging Velocimetry
     63-'''[Tools]''': -*'''[Geometric calibration]''':  for geometric calibration of images -*'''[LIF calibration]''':  calibration of images for Laser Induced Fluorescence -*'''[Make mask]''': for creating mask images (for PIV) -*'''[Make grid]:''': for making measurement grids for PIV -*'''[ruler]''': displays a ruler to measure lengths and angles of any line.
     64
     65-'''[Run] ''': -*'''[Field series]''': gives access to the GUI '''series.fig''' for analysis of field series -*'''[PIV(CIV)]''':  gives access to the GUI '''civ.fig''' for Particle Imaging Velocimetry
    8166
    8267-'''[Help] ''': displays the html help file
     
    8469<doc58|center>
    8570
    86 === 2.3 Displaying the input file name===
    87 
    88  After selection by the browser,  the path and file names are determined. The path is splitted into the two first edit boxes '''[RootPath]''' and '''[SubDir],''' while the file name is split into a root name '''[RootFile]''', file index string '''[FileIndex]''', and file extension '''[FileExt]'''. The input file name can be directly entered and modified by these edit boxes, without the browser.
    89 
    90     Once a root name has been introduced, navigation among  the file indices is provided by the red push buttons '''[runplus]''' ( '''[+>]''')  and   '''[runmin] ''' ('''<HTML>[ <-]</HTML>'''). The central push button '''[run0]''' ('''[0]''') refreshes the current plot. See [section 3.4->#sec3.4] for more details.
     71=== 2.3 Displaying the input file name ===
     72  After selection by the browser,  the path and file names are determined. The path is splitted into the two first edit boxes '''[RootPath]''' and '''[SubDir],''' while the file name is split into a root name '''[RootFile]''', file index string '''[FileIndex]''', and file extension '''[FileExt]'''. The input file name can be directly entered and modified by these edit boxes, without the browser.
     73
     74  Once a root name has been introduced, navigation among  the file indices is provided by the red push buttons '''[runplus]''' ( '''[+>]''')  and   '''[runmin] ''' ('''<HTML>[ <-]</HTML>'''). The central push button '''[run0]''' ('''[0]''') refreshes the current plot. See [section 3.4->#sec3.4] for more details.
    9175
    9276When available, the time of each frame or field is displayed in the edit box '''[abs_time]''', at the very right. In the case of image pairs, the time interval Dt is displayed between the edit boxes '''[i1], [j1]''' and '''[i2], [j2]'''. This timing information can be read directly in the input file, in the case of movies or Netcdf files, or can be defined in an image documentation file, see [section 3.5->#sec3.5] (in case of conflict, the latter prevails).
    9377
    9478-'''Note: ''' the five last input file names, as well as other pieces of personal information,  are stored for convenience in a file ({uvmat_perso.mat}) automatically created in the user preference directory of Matlab (indicated by the Matlab command '>>prefdir'. Browsers then  read default input in this file. A corruption of this file {uvmat_perso.mat} may lead to problems for  opening uvmat, type '>>reinit' on the Matlab prompt to delete it.
    95  
    96 === 2.4 General tools===
    97 
    98 -'''Mouse motion:''' the local coordinates and field values are obtained by moving the mouse over a plotting axes. They are displayed in the text box '''[text_display]''' on the upper right.
     79
     80=== 2.4 General tools ===
     81-'''Mouse motion:''' the local coordinates and field values are obtained by moving the mouse over a plotting axes. They are displayed in the text box '''[text_display]''' on the upper right.
    9982
    10083-'''Zoom:''' is activated by selecting the check box '''[CheckZoom]''' on the upper right. Zoom in by pressing the left mouse button on the graph. Zoom out by pressing the right mouse button. A zoomed region can be displayed as a new figure by drawing a rectangle with the mouse, while pressing the left mouse button (release the button to stop drawing). The zoomed region can be translated  through the initial field by pressing the directional arrows of the key board.
    10184
    102 -'''Graph limits:''' they automatically adjust to the field when the check box '''[CheckFixLimits]''' is not selected (default). Otherwise they remain fixed, and can be adjusted by the check boxes '''[num_MinX]''', '''[num_MaxX]''', '''[num_MinY]''', '''[num_MaxY]'''. 
     85-'''Graph limits:''' they automatically adjust to the field when the check box '''[CheckFixLimits]''' is not selected (default). Otherwise they remain fixed, and can be adjusted by the check boxes '''[num_MinX]''', '''[num_MaxX]''', '''[num_MinY]''', '''[num_MaxY]'''.
    10386
    10487-'''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.
    10588
    106 -'''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. A movie can be produced using the command [Export/make movie avi].
    107 
    108 -'''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.
    109 
    110 [<doc115|right>->#top]
    111 
    112 ------------------
    113 [3-Input files and navigation with uvmat<-]
    114 == 3 Input files and navigation with uvmat===
     89-'''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. A movie can be produced using the command [Export/make movie avi].
     90
     91-'''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.
     92
     93[<doc115|right>->#top]
     94
     95----
     96[3-Input files and navigation with uvmat<-]== 3 Input files and navigation with uvmat===
    11597
    11698[sec3.1<-]
    117 === 3.1  Input data formats===
    118 uvmat can read any image format recognised by the Matlab image reading function ({imread.m}. Images can be in true color or B&W, with 8 bit or 16 bit grey levels. Image files containing multiple frames are handled. Movie files can be also opened, using the Matlab function {VideoReader.m}, or {mmreader.m} for older versions of Matlab.
     99
     100=== 3.1  Input data formats ===
     101uvmat can read any image format recognised by the Matlab image reading function ({imread.m}. Images can be in true color or B&W, with 8 bit or 16 bit grey levels. Image files containing multiple frames are handled. Movie files can be also opened, using the Matlab function {VideoReader.m}, or {mmreader.m} for older versions of Matlab.
    119102
    120103Velocity fields and all results of data processing are stored in the Netcdf format, see [section 7->#get_field] for details. They are read by the function {nc2struct.m} . Then different quantities (vorticity, divergence...) can be calculated  by the function {calc_scal.m}.
     
    124107For 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).
    125108
    126 === 3.2 Selecting fields from CIV :===
    127 
    128  The uvmat package 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 [section 10->#civ].
     109=== 3.2 Selecting fields from CIV : ===
     110  The uvmat package 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 [section 10->#civ].
    129111
    130112<doc71|center>
    131113
    132 When a CIV field is recognised,  the popup menu '''[Fields]''' is set by default to 'velocity' while a menu '''[VelType]''' (with items 'civ1', 'filter1',..) appears at the upper right of the GUI. 
     114When a CIV field is recognised,  the popup menu '''[Fields]''' is set by default to 'velocity' while a menu '''[VelType]''' (with items 'civ1', 'filter1',..) appears at the upper right of the GUI.
    133115
    134116The choice can be imposed by selecting a check box, or can be left automatic. The second iteration (civ2, filter2), presumed to be of higher quality,  is prefered by default. The filter fields are interpolated on a regular grid, with or without smoothing respectively. It allows to fill holes and get spatial derivatives. If a scalar depending on spatial derivatives, like vort, is selected, the field option switches automatically from civ  to filter.
    135117
    136 The choice of fields, velocity, vorticity, divergence... is done by the popup menu '''[Fields]'''. The option 'image' gives access to an image file corresponding to the velocity field. The option 'get_field...' allows the user to display all the variables of the netcdf file in the GUI '''get_field.fig'''. This is the only available option when the input file is not from CIV.
    137 
    138 === 3.3 File naming and indexing===
    139 
    140     Different kinds of file or image frame indexing are defined:
    141 
    142 -'''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  singlemovie file. Then the index i stands for the frame index within the file.
    143 
    144 -'''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. 
    145 
    146 -'''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.
    147 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.
     118The choice of fields, velocity, vorticity, divergence... is done by the popup menu '''[Fields]'''. The option 'image' gives access to an image file corresponding to the velocity field. The option 'get_field...' allows the user to display all the variables of the netcdf file in the GUI '''get_field.fig'''. This is the only available option when the input file is not from CIV.
     119
     120=== 3.3 File naming and indexing ===
     121  Different kinds of file or image frame indexing are defined:
     122
     123-'''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  singlemovie file. Then the index i stands for the frame index within the file.
     124
     125-'''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.
     126
     127-'''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.
    148128
    149129-'''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 u'''vmat.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.
    150130
    151131[sec3.4<-]
    152 === 3.4 Navigation among file indices:===
    153 
    154     The field indices can be incremented or decremented by the push buttons  '''[runplus] ''' ( ''''<code>+></code>'''') and  '''[runmin]''' (''''<code> <-</code>'''') respectively.  This scanning is performed  over the first index (i) or the second one (j), depending on the selection of the check boxes '''[scan_i] ''' or '''[scan_j] ''' respectively. The step for increment is set by the edit box '''[increment_scan]'''.
     132
     133=== 3.4 Navigation among file indices: ===
     134  The field indices can be incremented or decremented by the push buttons  '''[runplus] ''' ( ''''<code>+></code>'''') and  '''[runmin]''' (''''<code> <-</code>'''') respectively.  This scanning is performed  over the first index (i) or the second one (j), depending on the selection of the check boxes '''[scan_i] ''' or '''[scan_j] ''' respectively. The step for increment is set by the edit box '''[increment_scan]'''.
    155135
    156136<doc65|center>
    157137
    158  The current indices are displayed in the four edit boxes '''[i1], [i2], [j1], [j2]'''. The two first indices i1 and j1 are used for image series, while the second line i2, j2 is used to label the image pairs used for PIV data. The file indices can be directly set in these edit boxes, or equivalently in the edit box '''[FileIndex]''' at the top of the GUI.
    159 
    160     For navigation with index pairs, the reference index, defined as the integer part of the mean value ((j1+j2)/2), is incremented. If the check box '''[fix_pair] ''' is selected,  the difference j1-j2 is then fixed while the reference index i or j is incremented. Else the pair with appropriate reference index is searched. In the case of multiple choices, the most largest index interval is chosen. This allows us to scan successive fields obtained with different image pairs (to deal with time evolving velocity fields).
     138  The current indices are displayed in the four edit boxes '''[i1], [i2], [j1], [j2]'''. The two first indices i1 and j1 are used for image series, while the second line i2, j2 is used to label the image pairs used for PIV data. The file indices can be directly set in these edit boxes, or equivalently in the edit box '''[FileIndex]''' at the top of the GUI.
     139
     140  For navigation with index pairs, the reference index, defined as the integer part of the mean value ((j1+j2)/2), is incremented. If the check box '''[fix_pair] ''' is selected,  the difference j1-j2 is then fixed while the reference index i or j is incremented. Else the pair with appropriate reference index is searched. In the case of multiple choices, the most largest index interval is chosen. This allows us to scan successive fields obtained with different image pairs (to deal with time evolving velocity fields).
    161141
    162142The maximum  value detected for each index is indicated by the boxes '''[last_i]''' and '''[last_j] ''' respectively.
    163143
    164 -'''slices:''' Images may be obtained with laser scanning in a multilayer mode, introducing a periodicity for the index i. This can be accounted by pressing the pushbutton '''[slices]''' and introducing the period in the edit box '''[num_NbSlice]''' which then appears. The index i modulo nb_slice then appears in the edit box '''[z_index]'''. 
     144-'''slices:''' Images may be obtained with laser scanning in a multilayer mode, introducing a periodicity for the index i. This can be accounted by pressing the pushbutton '''[slices]''' and introducing the period in the edit box '''[num_NbSlice]''' which then appears. The index i modulo nb_slice then appears in the edit box '''[z_index]'''.
    165145
    166146-'''Movie scan:''' Fields  can be continuously scanned as a movie by pressing  the pushbuttons '''[Movie]''' ( '''[++>]''') or '''[MovieBackward]''' . The movie speed can be adjusted by the slider '''[speed]'''. Press '''[STOP] ''' to stop the movie.
     
    168148-'''Keyboard short cuts:''' the activation of the push buttons  '''[runplus]''' and  '''[runmin]''' can be performed by typing the key board letters 'p' and 'm' respectively, after the uvmat figure has been selected by the mouse. Similarly the command of the push button '''[run0]''' can be performed by typing the 'return carriage' key.
    169149
    170 
    171150[sec3.5<-]
    172 === 3.5  Image documentation files (.xml):===
    173 
     151
     152=== 3.5  Image documentation files (.xml): ===
    174153Information on image series is provided by a documentation file in the format xml. This file can include sections about image timing, geometric calibration, camera type and illumination. An xml file is a text file in which each element of information, or group of elements, is labelled by a tag. The list of tags and their hierarchical organisation is specified by a schema file (.xsd). The schema used for image documentation is {ImaDoc.xsd}, available in the uvmat package at the path indicated in {PARAM.xml}). For a general introduction to the xml language, see [http://www.w3schools.com/xml->http://www.w3schools.com/xml].
    175154
    176155When a new file series is opened in uvmat, a documentation file is automatically sought, whose path and name are displayed by {RootPath} and  {RootFile} respectively, with extension {.xml} ({RootPath} and {RootFile} are the contents of the edit boxes '''[RootPath]''' and ''' [RootFile]''').  The detection of this file is indicated by the visibility of the pushbutton '''[view_xml]''' on the upper right of the GUI '''uvmat.fig'''. Press this button to see the content through an xml editor '''editxml.fig''' (described in [section 9 ->#series]). The xml file can be also opened directly by the uvmat browser, or by any text editor.
    177156
    178  The xml file <code><ImaDoc> </code> can contain the following sections:
    179 
    180 -<code><Heading></code>: contains elements <code><Campaign>, <Experiment>, <Device></code>, 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.
    181 -<code><Camera></code> contains information on the camera settings, as well as the timing of all the images in a subsection <code><BurstTiming></code>.
    182 -<code><TranslationMotor></code> and <code><Oscillator></code> contains information on the mechanical devices used to produce the laser sheet and scan volumes.
    183 -<code><GeometryCalib></code> contains the parameters of the geometric calibration relating the pixel position to the real space coordinates (see [section 7->#geometry_calib]). In the case of volume scanning, it also describes the set of laser plane positions and angles.
    184 -<code><Illumination></code> describes the illumination system used, including the position of the laser source.
    185 -<code><Tracor></code> describes the properties of the flow tracor (particle, dye...)
    186 -<code><ImageTransform></code> describes  the image processing which may have been performed.
     157  The xml file <code><ImaDoc> </code> can contain the following sections:
     158
     159-<code><Heading></code>: contains elements <code><Campaign>, <Experiment>, <Device></code>, 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. -<code><Camera></code> contains information on the camera settings, as well as the timing of all the images in a subsection <code><BurstTiming></code>. -<code><TranslationMotor></code> and <code><Oscillator></code> contains information on the mechanical devices used to produce the laser sheet and scan volumes. -<code><GeometryCalib></code> contains the parameters of the geometric calibration relating the pixel position to the real space coordinates (see [section 7->#geometry_calib]). In the case of volume scanning, it also describes the set of laser plane positions and angles. -<code><Illumination></code> describes the illumination system used, including the position of the laser source. -<code><Tracor></code> describes the properties of the flow tracor (particle, dye...) -<code><ImageTransform></code> describes  the image processing which may have been performed.
    187160
    188161The 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 (see [section 3.6->#sec3.6_civ]).
    189162
    190 === 3.6 Ancillary input files:===
    191 [sec3.6_mask<-]
    192 -''' 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 :
    193 -* Intensity < 20: ('black mask') the vector in this place will be set to zero
    194 -*  20 < Intensity < 200:('gray mask') the vector in this place will be absent
    195 -*  Intensity>200  the vector will be computed
    196 _ .png imageswith appropriate name in the image directory can be automatically recognised by '''uvmat.fig''' and '''civ.fig''', see [section 8.1->#sec8.1].  The mask corresponding to an image or velocity field can be displayed in '''uvmat.fig''' by selecting the check box '''[view_mask]''' on the upper right.
    197 
    198 [sec3.6_grid<-]
    199 -''' Grid:'''
    200 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
    201 <cadre>
    202 n
    203 X1 Y1
    204 X2 Y2
    205 ......
    206 Xn Yn
    207 </cadre>
    208 The 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 [section->#sec8.2].
     163=== 3.6 Ancillary input files: ===
     164[sec3.6_mask<-] -''' 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 : -* Intensity < 20: ('black mask') the vector in this place will be set to zero -*  20 < Intensity < 200:('gray mask') the vector in this place will be absent  -*  Intensity>200  the vector will be computed _ .png imageswith appropriate name in the image directory can be automatically recognised by '''uvmat.fig''' and '''civ.fig''', see [section 8.1->#sec8.1].  The mask corresponding to an image or velocity field can be displayed in '''uvmat.fig''' by selecting the check box '''[view_mask]''' on the upper right.
     165
     166[sec3.6_grid<-] -''' 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 <cadre> n X1 Y1 X2 Y2  ......  Xn Yn  </cadre> The 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 [section->#sec8.2].
    209167
    210168-'''.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 briowser of '''uvmat.fig'''.
    211169
    212 [sec3.6_civ<-]
    213 -''''.civ' '''  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}).
    214 -*Example :
    215 %... gives comments (not included in the file).
    216 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 ;cvi file is named aa.civ.
    217 <cadre>
    218 19                                      % number of bursts
    219 1024 1024                       % image size npx npy
    220 4                                      % number of images per burst
    221 2                                      % not used
    222 0.016667                          % time of exposure (in seconds)
    223 5.860000 5.860000           % scaling pixel/cm x and y directions
    224 5.860000 5.860000           % same
    225 0                                      % not used
    226 1 0.000000 30 60 30 1
    227 2 25.001003 30 60 30 1
    228 .........................
    229 18 424.999847 30 60 30 1
    230 19 450.000824 30 60 30 1
    231 % for each line:
    232 burst number; time elapsed in second from the beginning; number of frames between image a and image b; number of frames between image b and image c; number of frames between image c and image d; image acquisition duration in frames.
    233 </cadre>
     170[sec3.6_civ<-] -''''.civ' '''  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}). -*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 ;cvi file is named aa.civ.  <cadre> 19                                         % number of bursts 1024 1024                             % image size npx npy 4                                      % number of images per burst 2                                      % not used 0.016667                          % time of exposure (in seconds) 5.860000 5.860000           % scaling pixel/cm x and y directions 5.860000 5.860000           % same 0                                      % not used 1 0.000000 30 60 30 1 2 25.001003 30 60 30 1 ......................... 18 424.999847 30 60 30 1 19 450.000824 30 60 30 1 % for each line: burst number; time elapsed in second from the beginning; number of frames between image a and image b; number of frames between image b and image c; number of frames between image c and image d; image acquisition duration in frames. </cadre>
    234171
    235172-'''.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.
     
    238175
    239176[sec3.7<-]
    240 === 3.7 Data organisation in a  project:===
    241 The package is designed to foster a good data organisation. The raw data from a project should be organised as
    242 Project/Campaign/Experiment/DataSeries/data files.
    243 
    244 -'Project': contains all information from a project.
    245 -'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'.
    246 -'Experiment' is a directory containing all the data for a particular experiment, defined by a choice of values for the physical parameters.
    247 -'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.
    248 
    249 '''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 DataSeriies 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'.
    250 
    251 [<doc115|right>->#top]
    252 
    253 ------------------
    254 
     177
     178=== 3.7 Data organisation in a  project: ===
     179The package is designed to foster a good data organisation. The raw data from a project should be organised as  Project/Campaign/Experiment/DataSeries/data files.
     180
     181-'Project': contains all information from a project. -'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'.  -'Experiment' is a directory containing all the data for a particular experiment, defined by a choice of values for the physical parameters. -'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. ''
     182
     183'''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 DataSeriies 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'.
     184
     185[<doc115|right>->#top]
     186
     187----
    255188== 4 Field display: ===
    256189
    257    The uvmat interface primarily reads and visualises two-dimensional fields, which can be images or scalars, or vector fields.
    258 
    259 === 4.1  Images and scalars:===
    260 
    261     Images are matrices of integers, visualised by the Matlab function  {imagesc.m}.
    262 
    263     True color images are described by a matrix A(npy,npx,3) of integers between 0 and 255, the last index labeling the color component red, green or blue. They are displayed directly as color images.
     190  The uvmat interface primarily reads and visualises two-dimensional fields, which can be images or scalars, or vector fields.
     191
     192=== 4.1  Images and scalars: ===
     193  Images are matrices of integers, visualised by the Matlab function  {imagesc.m}.
     194
     195  True color images are described by a matrix A(npy,npx,3) of integers between 0 and 255, the last index labeling the color component red, green or blue. They are displayed directly as color images.
    264196
    265197<doc64|center>
    266198
    267     The black and white (B/W) images are described by a matrix A(npy,npx) of integers, whose range depends on the camera dynamics (0 to 255 for 8 bit images, 0 to 65535 for 16 bit images). They are represented with gray levels, according to the colorbar displayed on the right. The luminosity and contrast can be adjusted using the edit boxes '''[MinA]''' and '''[MaxA]''' on the right of the interface: the luminosity level set by '''[MinA]''' (and levels below) is represented as black, and the luminosity level set by '''[MaxA]''' (or levels above) as white. When the check box '''[AutoScal]''' is selected, '''AMin''' and '''AMax''' are set automatically to the image minimum and maximum respectively. Then the image may appear dark if a single point is very bright, in that case a lower value must be set for '''AMax'''. B/W images can be displayed with false colors, from blue to red, by unselecting the check box '''[BW]'''.
    268 
    269     Two images can be visually compared by switching back and forth between them as a short movie. This is quite useful to get a visual feeling of the image correlation for PIV. This effect is obtained by introducing two image indices in the edit boxes j1 and j2 (or i1 and i2), and selecting the button  '''[movie_pair] ''' (''''[<-->]'''') to switch between these two indices. The speed of the movie can be adjusted by the slider '''[speed]'''. Press '''[movie_pair] ''' again, or '''[STOP]''', to stop the motion.
    270 
    271   Scalar fields are  represented like B/W images, by default with a false color map ranging from blue (minimum values) to red (maximum), or as gray scale images by selecting the check box '''[BW]'''. Other color maps can be used by extracting the figure with the menu bar button '''[Export/extract figure]''', then using the standard  Matlab button '''[Edit/Colormap]''' in the figure menu bar. 
     199  The black and white (B/W) images are described by a matrix A(npy,npx) of integers, whose range depends on the camera dynamics (0 to 255 for 8 bit images, 0 to 65535 for 16 bit images). They are represented with gray levels, according to the colorbar displayed on the right. The luminosity and contrast can be adjusted using the edit boxes '''[MinA]''' and '''[MaxA]''' on the right of the interface: the luminosity level set by '''[MinA]''' (and levels below) is represented as black, and the luminosity level set by '''[MaxA]''' (or levels above) as white. When the check box '''[AutoScal]''' is selected, '''AMin''' and '''AMax''' are set automatically to the image minimum and maximum respectively. Then the image may appear dark if a single point is very bright, in that case a lower value must be set for '''AMax'''. B/W images can be displayed with false colors, from blue to red, by unselecting the check box '''[BW]'''.
     200
     201  Two images can be visually compared by switching back and forth between them as a short movie. This is quite useful to get a visual feeling of the image correlation for PIV. This effect is obtained by introducing two image indices in the edit boxes j1 and j2 (or i1 and i2), and selecting the button  '''[movie_pair] ''' (''''[<-->]'''') to switch between these two indices. The speed of the movie can be adjusted by the slider '''[speed]'''. Press '''[movie_pair] ''' again, or '''[STOP]''', to stop the motion.
     202
     203  Scalar fields are  represented like B/W images, by default with a false color map ranging from blue (minimum values) to red (maximum), or as gray scale images by selecting the check box '''[BW]'''. Other color maps can be used by extracting the figure with the menu bar button '''[Export/extract figure]''', then using the standard  Matlab button '''[Edit/Colormap]''' in the figure menu bar.
    272204
    273205Scalar are represented by matrices with real ('double') values, unlike images which are integers. They can be alternatively defined with unstructured grid (see [section 5.3->#sec5.3]): they are then linearly interpolated on a regular grid before visualisation (a fairly slow process).
     
    276208
    277209[sec4.2<-]
    278 === 4.2 Vectors:===
    279 
    280     The vector fields are represented by arrows. The length of the arrows is automatically set when the check box'''[CheckFixVectors]''' is not selected, or it can be adjusted by the edit box '''[num_VecScale]'''.  For clarity of visualisation, the number of displayed vectors can be divided by 2 in each direction by selecting the check box '''[CheckDecimate4]'''.
    281 
    282 Each vector has a color, ranging from blue to red, which can represent an associated  scalar value. In addition, black and magenta colors represent warning and error flags respectively. This color system is primarily designed for PIV data but can be used in other contexts as well. 
     210
     211=== 4.2 Vectors: ===
     212  The vector fields are represented by arrows. The length of the arrows is automatically set when the check box'''[CheckFixVectors]''' is not selected, or it can be adjusted by the edit box '''[num_VecScale]'''.  For clarity of visualisation, the number of displayed vectors can be divided by 2 in each direction by selecting the check box '''[CheckDecimate4]'''.
     213
     214Each vector has a color, ranging from blue to red, which can represent an associated  scalar value. In addition, black and magenta colors represent warning and error flags respectively. This color system is primarily designed for PIV data but can be used in other contexts as well.
    283215
    284216<doc63|center>
    285217
    286 -'''Warning flags''': they indicate a vector resulting from a dubious  image correlation process, but not removed from the data set. Their display in black can be desactivated by selecting the check box '''[CheckHideWarning]'''.
    287 
    288 -'''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]'''.
    289 
    290 -'''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:
    291 -*'rgb':  color ranging from red, for the scalar value set by '''[num_MinVec]''', to blue, for the scalar value set by  '''[num_MaxVec]'''. The
    292 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 [AutoVecColor], these thresholds can be set to match the min and max scalar values.
    293 -*'black' or 'white': set the color for all vectors
    294 -*'brg': same as rgb but in reverse order, with blue for the lowest scalar values.
    295 -*'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]'''.
    296 
    297 -'''Mouse display''': when the mouse is moved over a vector, it is marked by a circle, and its features appear in the display text boxes on the upper right. These are
    298 -* fist line: the position coordinates x, y, (z for 3D cases).
    299 -* second line: the vector components
    300 -* third line: the vector index in the file, the values of the scalar (C), the warning flag (F) and the error flag (FF). The meaning of the flag values is given in [section 10.3->#sec10.3].
     218-'''Warning flags''': they indicate a vector resulting from a dubious  image correlation process, but not removed from the data set. Their display in black can be desactivated by selecting the check box '''[CheckHideWarning]'''.
     219
     220-'''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]'''.
     221
     222-'''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: -*'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 [AutoVecColor], these thresholds can be set to match the min and max scalar values. -*'black' or 'white': set the color for all vectors -*'brg': same as rgb but in reverse order, with blue for the lowest scalar values.  -*'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]'''.
     223
     224-'''Mouse display''': when the mouse is moved over a vector, it is marked by a circle, and its features appear in the display text boxes on the upper right. These are  -* fist line: the position coordinates x, y, (z for 3D cases).  -* second line: the vector components -* third line: the vector index in the file, the values of the scalar (C), the warning flag (F) and the error flag (FF). The meaning of the flag values is given in [section 10.3->#sec10.3].
    301225
    302226-'''Manual editing of vectors''':  vectors can be manually set as 'false' by pressing '''[Edit/Vectors] ''' in the menu bar, then selecting the vector with the mouse. The selected vector becomes magenta. Inversely, if a magenta vector is selected, it is rehabilitated and retrieves its initial color.  The corrections are  recorded as false flags in the data file by pressing the pushbutton '''[record]'''.
    303227
    304 === 4.3 Histograms===
    305 
     228=== 4.3 Histograms ===
    306229Histograms of the input fields are represented on the bottom left. The choice of the variable is done by the menu '''[histo1_menu]'''.
    307230
    308  For color images, the histogram of each color component, r, g, b, is given with a curve of the corresponding color. In case of saturation, the proportion of pixels beyond the max limit is written on the graph.
    309 
    310 === 4.4 Comparing two fields===
    311 
    312     A second field series can be opened and compared to the first one, using the menu bar command '''[Open_1]'''.  Then a new file name and indices appear on the second line, as well as the check box '''[SubField]''' on the very right. The second field can be alternatively obtained by selecting a field in the popup menu '''[Fields_1] ''' (under '''[Fields]''').
    313 
    314     If the two files are both images or scalar, their difference is introduced as the input field. If one field  is an image (or scalar), while the other one is a vector field, the image will appear as a background in the vector field. This is convenient for instance to relate the CIV result to the quality of the images, or to relate vorticity to the vector field.
    315 
    316     If  two vector fields are compared, their difference is taken as the input field, and is then displayed and analysed. If the two fields are not at the same points, the velocity of the second field is linearly interpolated at the positions of the first one (using the Matlab function {griddata.m}). The color and flags are then taken from the first field.
    317 
    318 The two file series will be scanned simultaneously by '''[runplus]''' ( '->') and  '''[runmin]''' ('<-') , according to their own nomenclature. It is also possible to manually edit the second file indices '''[FieldIndex_1] ''' to compare two fields with different indices.
    319 If available, the time of the second field is indicated in the edit box '''[abs_time_1] ''' at the very right, below the time of the main field.
     231  For color images, the histogram of each color component, r, g, b, is given with a curve of the corresponding color. In case of saturation, the proportion of pixels beyond the max limit is written on the graph.
     232
     233=== 4.4 Comparing two fields ===
     234  A second field series can be opened and compared to the first one, using the menu bar command '''[Open_1]'''.  Then a new file name and indices appear on the second line, as well as the check box '''[SubField]''' on the very right. The second field can be alternatively obtained by selecting a field in the popup menu '''[Fields_1] ''' (under '''[Fields]''').
     235
     236  If the two files are both images or scalar, their difference is introduced as the input field. If one field  is an image (or scalar), while the other one is a vector field, the image will appear as a background in the vector field. This is convenient for instance to relate the CIV result to the quality of the images, or to relate vorticity to the vector field.
     237
     238  If  two vector fields are compared, their difference is taken as the input field, and is then displayed and analysed. If the two fields are not at the same points, the velocity of the second field is linearly interpolated at the positions of the first one (using the Matlab function {griddata.m}). The color and flags are then taken from the first field.
     239
     240The two file series will be scanned simultaneously by '''[runplus]''' ( '->') and  '''[runmin]''' ('<-') , according to their own nomenclature. It is also possible to manually edit the second file indices '''[FieldIndex_1] ''' to compare two fields with different indices.  If available, the time of the second field is indicated in the edit box '''[abs_time_1] ''' at the very right, below the time of the main field.
    320241
    321242The second field can be removed by unselecting the check box '''[SubField] ''' on the very right.
    322243
    323244[sec4.5<-]
    324 ===  4.5 Field transforms:===
    325 A transform can be systematically applied after reading the input field, for instance the transform 'phys' which takes into account geometric calibration. This transform can possibly combine two input fields, for instance to substract a background from an image. The processing function is chosen  by the popup menu '''[transform_fct]''' on the left, and its path is displayed in the box '''[path_transform]'''. Select the option 'more...' to browse new functions. The same functions can be called in data processsing using the GUI '''series.fig'''. A few functions are provided in the folder /transform_fct, see list in  [annex->#overview].
    326 
    327 These functions can transform fields into polar coordinates, do image filtering, Fourier transform, signal analysis for a 1D input field... Other functions can be easily written using those as templates.  The  general form of such functions is
    328 DataOut=transform_fct(DataIn,XmlData,DataIn_1,XmlData_1)
    329 where Data is an input field object, as described in [section 5.4->#sec5.4], and XmlData the content of the xml file Imadoc, as stored in the uvmat GUI. XmlData contains in particular the element .GeometryCalib containing the calibration parameters, see  [section 7->#geometry_calib].
    330 
    331 ===  4.6 Succession of operations:===
    332 
    333 The following succession of operations is performed by '''uvmat.fig''':
    334 -'''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.
    335 -'''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).
    336 -'''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.
    337 -'''Histogram:''' This is obtained from the input field in transformed coordinates, or if applicable from the fields resulting from the two input fields.
    338 -'''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}.
    339 -'''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}.
    340 -'''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.
    341 -'''Plotting:''' plot the results of projection. Function used: {plot_field.m}
    342 
    343 [<doc115|right>->#top]
    344 
    345 ----------------
    346 [field_structures<-]
    347 '''{5- Field objects:===
     245
     246=== 4.5 Field transforms: ===
     247A transform can be systematically applied after reading the input field, for instance the transform 'phys' which takes into account geometric calibration. This transform can possibly combine two input fields, for instance to substract a background from an image. The processing function is chosen  by the popup menu '''[transform_fct]''' on the left, and its path is displayed in the box '''[path_transform]'''. Select the option 'more...' to browse new functions. The same functions can be called in data processsing using the GUI '''series.fig'''. A few functions are provided in the folder /transform_fct, see list in  [annex->#overview].
     248
     249These functions can transform fields into polar coordinates, do image filtering, Fourier transform, signal analysis for a 1D input field... Other functions can be easily written using those as templates.  The  general form of such functions is  DataOut=transform_fct(DataIn,XmlData,DataIn_1,XmlData_1) where Data is an input field object, as described in [section 5.4->#sec5.4], and XmlData the content of the xml file Imadoc, as stored in the uvmat GUI. XmlData contains in particular the element .[wiki:GeometryCalib] containing the calibration parameters, see  [section 7->#geometry_calib].
     250
     251=== 4.6 Succession of operations: ===
     252The 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}
     253
     254[<doc115|right>->#top]
     255
     256----
     257[field_structures<-] '''{5- Field objects:==='''
    348258
    349259[sec5.1<-]
    350 === 5.1 Griding of data:===
    351 <math>
    352 Physical fields can be defined either on regular grids, either scattered on an unstructured set of positions. Some measurements techniques, like PIV or particle tracking, provided unstructured data, while most methods of analysis require data  on a regular grid. This can be done by interpolation, defining a projection on a plane (with ProjMode='interp' or 'filter', see  [next section-> #set_object]).  The three possibilities of griding are defined as follows:
     260
     261=== 5.1 Griding of data: ===
     262<math> Physical fields can be defined either on regular grids, either scattered on an unstructured set of positions. Some measurements techniques, like PIV or particle tracking, provided unstructured data, while most methods of analysis require data  on a regular grid. This can be done by interpolation, defining a projection on a plane (with ProjMode='interp' or 'filter', see  [next section-> #set_object]).  The three possibilities of griding are defined as follows:
    353263
    354264-'''Regular grid:'''
    355            Each field is then a multi-dimensional array V whose dimensions match the space dimensions.  Because of the grid regularity, the set of positions is fully defined by the coordinate value for the first and last index along each dimension of the array.
    356          
    357 -'''Structured orthogonal grid''':
    358              Each field is again a multi-dimensional array V whose dimensions match the space dimensions, but the coordinates may not be regularly spaced, so they are represented as a monotonic 1D array variable with the same length as the corresponding dimension of V.  This is called a 'coordinate variable' (see section 7.1).
     265
     266  Each field is then a multi-dimensional array V whose dimensions match the space dimensions.  Because of the grid regularity, the set of positions is fully defined by the coordinate value for the first and last index along each dimension of the array.
     267
     268 -'''Structured orthogonal grid''':
     269
     270  Each field is again a multi-dimensional array V whose dimensions match the space dimensions, but the coordinates may not be regularly spaced, so they are represented as a monotonic 1D array variable with the same length as the corresponding dimension of V.  This is called a 'coordinate variable' (see section 7.1).
    359271
    360272-'''Unstructured coordinates:'''
    361            Fields may be alternatively obtained on a unstructured (grid-less) set of positions. The coordinates are then described by coordinate arrays X(nb_points), Y(nb_points), Z(nb_points). The corresponding field values are then represented as variables V(nb_points, j, i), where i, j possibly stand for vector or tensor components. 
     273
     274  Fields may be alternatively obtained on a unstructured (grid-less) set of positions. The coordinates are then described by coordinate arrays X(nb_points), Y(nb_points), Z(nb_points). The corresponding field values are then represented as variables V(nb_points, j, i), where i, j possibly stand for vector or tensor components.
    362275
    363276-'''Thin plate shell (tps) interpolation:'''
    364           This 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} $'''r'''$ is expressed in the form, see [thin plate spline->73].
    365 $$\label{sol_gene}
    366 f({\bf r})=\sum S_i \phi({\bf|r-r_i}|)+a_0+a_1x+a_2y\;
    367 $$
    368 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.
     277
     278  This 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} $'''r'''$ is expressed in the form, see [thin plate spline->73].
     279
     280$$\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. ^
    369281
    370282Because 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.
    371283
    372284[sec5.2<-]
    373 === 5.2 Field representation as Matlab structure:===
    374 
    375 The uvmat package represents data as 'Matlab structures', a set of data elements characterized by a tag name (char string) and a value. The value can be any Matlab object: number, array, character string or cell, or a structure containing itself elements in a hierarchical way. Each element is denoted in the form Data.tag=value. 
     285
     286=== 5.2 Field representation as Matlab structure: ===
     287The uvmat package represents data as 'Matlab structures', a set of data elements characterized by a tag name (char string) and a value. The value can be any Matlab object: number, array, character string or cell, or a structure containing itself elements in a hierarchical way. Each element is denoted in the form Data.tag=value.
    376288
    377289Data are kept in memory in the GUI uvmat as a Matlab structure, stored as 'UserData' in the figure. This structure can be extracted by the menu bar command '''[Export/field in work space] ''', then typing the Matlab command '>>Data_uvmat'. It contains the current input field as a substructure Data_uvmat.Field.
     
    379291This field has a specific organisation, mirroring the structure of netcdf files (see [section 7->#get_field]). This organisation defines a {field object}, used to specify the outcome of projections and plots.  The field is described by a set of arrays or matrices, 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.
    380292
    381 In summary, the {field object} is specified by a structure with the following elements:
    382 -*(optional) .ListGlobalAttribute: list (cell array of character strings) of the names of global attributes  Att_1, Att_2...
    383 -* (mandatory) .ListVarName: list of the variable names Var_1, Var_2....(cell array of character strings).
    384 -* (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.
    385 -* (optional) .VarAttribute: cell array of structures of the form .VarAttribute<HTML>{ivar}</HTML>.key=value, defining an attribute tag name and value for the variable #ivar (variable number in the list .ListVarName).
    386 -* .Att_1, Att_2... : values of the listed global attributes.
    387 -* .Var_1, .Var_2....: variables arrays whose  names are listed in .ListVarName
    388 
    389 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.
    390 -* .ListDimName: list of dimension names (cell array of character strings)
    391 -* .DimValue: array of dimension values corresponding to LisDimName.
    392 
    393 The following temporary information is added to manage projection and field substraction oerations, which must be done in general after projection:
    394 -* 'FieldRequest': 'interp_lin', 'interp_tps' indicate whether lin interpolation  or derivatives by tps is needed to calculate the requested field.
    395 -* 'Operation': name (char string) of the operation to be performed to finalise the field cell after projection.
    396 -* 'SubCheck' 0 /1 indicate that the field must be substracted (second  entry in uvmat)
    397 
    398 Any other element can be added, but will not be taken into account if they are not listed in  .ListGlobalAttribute or .ListVarName.
     293In summary, the {field object} is specified by a structure with the following elements:  -*(optional) .[wiki:ListGlobalAttribute]: list (cell array of character strings) of the names of global attributes  Att_1, Att_2... -* (mandatory) .[wiki:ListVarName]: list of the variable names Var_1, Var_2....(cell array of character strings). -* (mandatory) .[wiki:VarDimName]: list of the dimensions associated with each variable: this is a cell array whose number of element is equal to that of .[wiki: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. -* (optional) .[wiki:VarAttribute]: cell array of structures of the form .[wiki:VarAttribute]<HTML>{ivar}</HTML>.key=value, defining an attribute tag name and value for the variable #ivar (variable number in the list .[wiki:ListVarName]). -* .Att_1, Att_2... : values of the listed global attributes. -* .Var_1, .Var_2....: variables arrays whose  names are listed in .[wiki:ListVarName]
     294
     295In 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. -* .[wiki:ListDimName]: list of dimension names (cell array of character strings)  -* .[wiki:DimValue]: array of dimension values corresponding to LisDimName.
     296
     297The following temporary information is added to manage projection and field substraction oerations, which must be done in general after projection: -* 'FieldRequest': 'interp_lin', 'interp_tps' indicate whether lin interpolation  or derivatives by tps is needed to calculate the requested field. -* 'Operation': name (char string) of the operation to be performed to finalise the field cell after projection. -* 'SubCheck' 0 /1 indicate that the field must be substracted (second  entry in uvmat)
     298
     299Any other element can be added, but will not be taken into account if they are not listed in  .[wiki:ListGlobalAttribute] or .[wiki:ListVarName].
    399300
    400301[sec5.3<-]
    401 === 5.3 Conventions for attributes in field objects:===
    402 -'''Global attributes active in uvmat'''
    403 Those are used for plot settings or data processing.
    404 -*'Conventions':
    405    ='uvmat': indicate that the conventions described here are followed
    406   ='uvmat/civdata': indicate that the variables are named according to  [CIV data description->#civdata].
    407 -*'CoordMesh': typical mesh for coordinates, used to define default projection grids and mouse selection action. Calculated automatically from the data if not specified.
    408 -*'CoordUnit': character string representing the unit for space coordinates. It is used to distinguish image coordinates (CoordUnit='pixel') and physical (for instance
    409 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).
    410 -*Dt: time interval for CIV data. It is used for calibration, to transform displacement into velocity.
    411 -*Time: real number indicating the time of the field, used to obtain time series from data sets.
    412 -*TimeUnit: character string representing the unit of time (consistently for Time, Dt and velocity).
    413 
    414 -'''Global attributes , unactive'''
    415 those are merely used for information purpose
    416 -*Project: recalls the project name
    417 -*Campaign: recalls the campaign name
    418 -*Experiment:  recalls the experiment name(s) of the raw data -*DataSeries:  recalls the device name (s), if defined, of the raw data 
    419 -*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.
    420 -*ObjectCoord:  Coordinates defining a geometric object on which the data have been projected.
    421 -*ObjectRangeX, ObjectRangeY, ObjectRangeZ : range of action of a projection object along each coordinate, see section 6. 
    422 -* '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.
    423 
    424 -'''Attributes of variables:'''
    425 -* Mesh: suggested step value to discretize the values of the variable, used to define the bins for histograms.
    426 -* 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'.
    427 -* 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).
    428 
    429 -'''The attribute 'Role':'''
    430 The following options are used for the attribute 'role':
    431 -* 'ancillary': information of secondary use, indicating for instance an error estimate of field variables within a field cell (omitted in plotting)
    432 -* '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.
    433 -* 'coord_tps': coordinates of thin plate shell (tps) centres used for spline interpolation.
    434 -* 'discrete': field with discrete values (no spatial interpolation), repesented with dots (no line) in 1D plots.
    435 -* '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.
    436 -* 'grad_x', 'grad_y', 'grad_z'  :represents the x, y or z  component of a contravariant vector** (like gradients).
    437 -* 'image_rgb': represents a color image. The last dimension of the array corresponds to the three color components 'rgb'.
    438 -* 'scalar': (default) represents a scalar field
    439 -* 'tensor': represents a tensor field whose components correspond to the two last   dimensions of the array.**
    440 -* vector: matrix whose last dimension states for the vector components.**
    441 -* 'vector_x', 'vector_y', 'vector_z'  : represents the x, y or z  component of a vector (covariant)
    442 -* 'warnflag': provides a warning flag about the quality of data for the field variables within a field cell., default=0, no warning.
    443 
    444 === 5.4 Field cells:===
     302
     303=== 5.3 Conventions for attributes in field objects: ===
     304-'''Global attributes active in uvmat''' Those are used for plot settings or data processing. -*'Conventions':
     305
     306  ='uvmat': indicate that the conventions described here are followed
     307
     308='uvmat/civdata': indicate that the variables are named according to  [CIV data description->#civdata].  -*'CoordMesh': typical mesh for coordinates, used to define default projection grids and mouse selection action. Calculated automatically from the data if not specified. -*'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). -*Dt: time interval for CIV data. It is used for calibration, to transform displacement into velocity.  -*Time: real number indicating the time of the field, used to obtain time series from data sets.  -*TimeUnit: character string representing the unit of time (consistently for Time, Dt and velocity).
     309
     310-'''Global attributes , unactive''' those are merely used for information purpose -*Project: recalls the project name -*Campaign: recalls the campaign name -*Experiment:  recalls the experiment name(s) of the raw data -*DataSeries:  recalls the device name (s), if defined, of the raw data   -*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.  -*ObjectCoord:  Coordinates defining a geometric object on which the data have been projected.  -*ObjectRangeX, ObjectRangeY, ObjectRangeZ : range of action of a projection object along each coordinate, see section 6.   -* '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.
     311
     312-'''Attributes of variables:''' -* Mesh: suggested step value to discretize the values of the variable, used to define the bins for histograms.  -* 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'. -* 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).
     313
     314-'''The attribute 'Role':''' The following options are used for the attribute 'role': -* 'ancillary': information of secondary use, indicating for instance an error estimate of field variables within a field cell (omitted in plotting) -* '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. -* 'coord_tps': coordinates of thin plate shell (tps) centres used for spline interpolation. -* 'discrete': field with discrete values (no spatial interpolation), repesented with dots (no line) in 1D plots. -* '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. -* 'grad_x', 'grad_y', 'grad_z'  :represents the x, y or z  component of a contravariant vector** (like gradients). -* '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 -* 'tensor': represents a tensor field whose components correspond to the two last   dimensions of the array.** -* vector: matrix whose last dimension states for the vector components.** -* 'vector_x', 'vector_y', 'vector_z'  : represents the x, y or z  component of a vector (covariant)  -* 'warnflag': provides a warning flag about the quality of data for the field variables within a field cell., default=0, no warning.
     315
     316=== 5.4 Field cells: ===
    445317The 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.
    446318
    447 -*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.
    448 -* 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.
    449 -* 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).
    450 -* Thin plate shell (tps) field cell: represents a set of coordinates and tps weights in  a way suitable for tps interpolation/filter.
    451 
    452 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: 
    453 -* coord_1,_2,_3: dimension with the same name as a coordinate variable array (coordinate dimension)
    454 -* 'nb_coord': denotes the space dimension for vector components
    455 -* 'nb_coord_j', 'nb_coord_i': denotes the space dimensions for the two tensor components
    456 -*  'rgb' : denotes the diemension of the color component in a true color  image.
    457 -*  'nb_point' or 'nb_vec' (for vectors) denotes the set of positions with unstructured coordinates.
    458 -* 'nb_tps': diemension of the index for the tps centres
    459 -* 'nb_subdomain' denotes the dimension for the subdomain index for tps coefficients
    460 
    461 [<doc115|right>->#top]
    462 
    463 ------------------------
    464 [set_object<-]
    465 '''{6- Projection objects:===
    466 
    467 === 6.1 Definition and editing with the uvmat interface:===
    468 
    469     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 of fields to subregions. 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 the option 'browse...'. 
    470 
    471  In each case an auxiliary GUI '''set_object.fig''' describing the object properties appears, see next [sub-section->#sec6.2] for their definitions. This GUI  can be  edited by mouse drawing in the plotted field or by direct input. 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'''.
     319-*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. -* 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.  -* 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). -* Thin plate shell (tps) field cell: represents a set of coordinates and tps weights in  a way suitable for tps interpolation/filter.
     320
     321The 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:   -* coord_1,_2,_3: dimension with the same name as a coordinate variable array (coordinate dimension) -* 'nb_coord': denotes the space dimension for vector components  -* 'nb_coord_j', 'nb_coord_i': denotes the space dimensions for the two tensor components  -*  'rgb' : denotes the diemension of the color component in a true color  image. -*  'nb_point' or 'nb_vec' (for vectors) denotes the set of positions with unstructured coordinates. -* 'nb_tps': diemension of the index for the tps centres -* 'nb_subdomain' denotes the dimension for the subdomain index for tps coefficients
     322
     323[<doc115|right>->#top]
     324
     325----
     326[set_object<-] '''{6- Projection objects:==='''
     327
     328=== 6.1 Definition and editing with the uvmat interface: ===
     329  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 of fields to subregions. 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 the option 'browse...'.
     330
     331  In each case an auxiliary GUI '''set_object.fig''' describing the object properties appears, see next [sub-section->#sec6.2] for their definitions. This GUI  can be  edited by mouse drawing in the plotted field or by direct input. 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'''.
    472332
    473333The projection of fields on objects is performed by the function {proj_field.m}, which can be used also in data processing. The projected field resulting form a projection object drawn in the main plotting window of uvmat will be plotted in the secondary plotting GUI '''[view_field]'''.    The list of currently opened projection objects is displayed in the menus '''[list_object_1]''' and '''[list_object_2]''' at the bottom right of '''uvmat.fig'''.  One object can be selected in each of these menus: the projection on the object selected in '''[list_object_1]''' is viewed in '''uvmat.fig''' while that of the object selected in '''[list_object_2]''' is viewed in '''view_field.fig'''. All the created objects are sketched in both views, except the one on which projection leads to the currently plotted field (see [subsection 6.4->#sec6.4] for object representation). The active objects are plotted in magenta, while the inactive ones are in blue.
     
    476336
    477337[sec6.2<-]
    478 === 6.2 Object properties:===
    479 
    480     The objects are defined by the following set of properties:
    481 -''' {Name:} ''' any name given to the object
    482 -''' {Type:} ''' classify the object with the following choice:
    483 -*'points': set of n points
    484 -*'line': simple straight segment, defined by its two end points
    485 -*'polyline': open line made of n-1 consecutive segments (defined by n points)
    486 -*'rectangle': defined by its center, half width and half height.
    487 -* 'polygon': closed line made of n consecutive segments (defined by n points)
    488 -*'ellipse': defined by its center, half width and half height.
    489 -*'plane': plane with associated cartesian coordinates
    490 -*'volume': volume with associated cartesian coordinates
    491 
    492 -''' {ProjMode:} ''': specifies the method of projection of coordinates and field. 
     338
     339=== 6.2 Object properties: ===
     340  The objects are defined by the following set of properties:
     341
     342-''' {Name:} ''' any name given to the object -''' {Type:} ''' classify the object with the following choice: -*'points': set of n points -*'line': simple straight segment, defined by its two end points -*'polyline': open line made of n-1 consecutive segments (defined by n points) -*'rectangle': defined by its center, half width and half height. -* 'polygon': closed line made of n consecutive segments (defined by n points) -*'ellipse': defined by its center, half width and half height. -*'plane': plane with associated cartesian coordinates -*'volume': volume with associated cartesian coordinates
     343
     344-''' {ProjMode:} ''': specifies the method of projection of coordinates and field.
    493345
    494346-''' {Angle:} ''': three component rotation vector used to define the orientation, for instance for planes.
    495347
    496 -''' {RangeX:} ''', ''' {RangeY:} ''', ''' {RangeZ:} ''':bounds defining the range of projection along each coordinate, one or two values depending on the object type. 
     348-''' {RangeX:} ''', ''' {RangeY:} ''', ''' {RangeZ:} ''':bounds defining the range of projection along each coordinate, one or two values depending on the object type.
    497349
    498350-''' {DX:} ''', ''' {DY:} ''', ''' {DZ:} ''':meash  along each coordinate defining a grid for interpolation.
    499351
    500 -''' {Coord:} ''': matrix with two (for 2D fields) or three columns defining the object position.
    501 -*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.
    502 -*for 'rectangle', 'ellipse': coordinates of the center.
    503 -*for 'plane' or 'volume': coordinates of the origin of the new coordinate frame attached to the object.
    504 
    505 -''' {CoordUnit:} ''' units for the coordinates, must fit with the units of coordinates for the projected field.
     352-''' {Coord:} ''': matrix with two (for 2D fields) or three columns defining the object position. -*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.  -*for 'rectangle', 'ellipse': coordinates of the center. -*for 'plane' or 'volume': coordinates of the origin of the new coordinate frame attached to the object.
     353
     354-''' {CoordUnit:} ''' units for the coordinates, must fit with the units of coordinates for the projected field.
    506355
    507356[sec6.3<-]
    508 === 6.3 Projection modes:===
    509 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. 
    510  
    511 -''' {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).
    512 
    513 -''' {ProjMode 'interp':} ''' 
    514 Linear interpolation of the fields on a grid of regularly spaced points defined on the projection object, with meshes DX, DY, DZ. The grid array along x starts at RangeX(1) and ends at the closest value smaller than RangeX(2). Similar convention is used for y and z in case of planes and volumes.
    515 
    516 -''' {ProjMode  'filter':}  '''  filtered interpolation (used only for lines). For each point an average of the neighborhing data is used, with a weighting function whose range is given by max(RangeY). This is useful to get reliable profiles in the presence of 'holes' in the  data fields. 
    517 
    518 -''' {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.
    519 
    520 -''' {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 [section 8.1->#sec8.1]).
    521 
     357
     358=== 6.3 Projection modes: ===
     359Each 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.     -''' {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).
     360
     361-''' {ProjMode 'interp':} '''   Linear interpolation of the fields on a grid of regularly spaced points defined on the projection object, with meshes DX, DY, DZ. The grid array along x starts at RangeX(1) and ends at the closest value smaller than RangeX(2). Similar convention is used for y and z in case of planes and volumes.
     362
     363-''' {ProjMode  'filter':}  '''  filtered interpolation (used only for lines). For each point an average of the neighborhing data is used, with a weighting function whose range is given by max(RangeY). This is useful to get reliable profiles in the presence of 'holes' in the  data fields.
     364
     365-''' {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.
     366
     367-''' {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 [section 8.1->#sec8.1]).
    522368
    523369[sec6.4<-]
    524 === 6.4 Projected fields:===
    525 
     370
     371=== 6.4 Projected fields: ===
    526372The 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'''.
    527373
    528 -''' {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.
    529 -*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.
    530 -*ProjMode= 'interp':   U(i),i=1 is obtained as a linear interpolation on each point.
    531 
    532 -''' {Projection on open lines:} ''' 
    533 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**.
    534 -*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.
    535 -* ProjMode='interp':
    536  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.
    537 -* ProjMode='filter':
    538 same as 'interp' but with a smoothing operation.
    539  
    540 -''' {Projection on closed lines:} '''  ,
    541 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.
    542 
    543 -''' {Projection on planes:}  '''
    544 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.
    545 -*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).
    546 -* ProjMode='interp':
    547  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.
    548 
    549 -''' {Projection on volumes:**}  '''
    550 This is used to delimitate a volume for 3D representation
     374-''' {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.  -*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.  -*ProjMode= 'interp':   U(i),i=1 is obtained as a linear interpolation on each point.
     375
     376-''' {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**. -*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.  -* ProjMode='interp':
     377
     378  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.
     379
     380-* ProjMode='filter': same as 'interp' but with a smoothing operation.   -''' {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.
     381
     382-''' {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. -*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).  -* ProjMode='interp':
     383
     384  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.
     385
     386-''' {Projection on volumes:**}  ''' This is used to delimitate a volume for 3D representation
    551387
    552388[sec6.5<-]
    553 === 6.5 Object representation:===
    554 
     389
     390=== 6.5 Object representation: ===
    555391Projections objects are drawn in magenta color when they are selected for creation or edition, and in blue otherwise.
    556392
    557 -* 'points' are represented by dots surrounded by a dashed circle showing the range of projection.
    558 -* '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').
    559 -* '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).
    560 -* '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. **
    561 -* 'volume' are shown like 'plane', except that they are painted in magenta (or blue) **
    562 
    563 -''' {Creating and editing objects with the mouse:} '''
    564      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.
    565 -*'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.
    566 -*'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').
    567 -*'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.
    568 -*'rectangle': defined by its center, half width and half height.
    569 -*'polygon': closed line made of n consecutive segments (defined by n points)
    570 -*ellipse: defined by its center, half width and half height.
    571 -*plane: plane with associated cartesian coordinates
    572 -*volume: volume with associated cartesian coordinates
    573 
    574 [<doc115|right>->#top]
    575 
    576 ----------------
    577 [get_field<-]
    578 '''{7- Netcdf files and get_field.fig:===
    579 [netcdf<-]
    580 === 7.1 The NetCDF format:===
    581 
     393-* 'points' are represented by dots surrounded by a dashed circle showing the range of projection. -* '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'). -* '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). -* '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. ** -* 'volume' are shown like 'plane', except that they are painted in magenta (or blue) **
     394
     395-''' {Creating and editing objects with the mouse:} '''
     396
     397  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.
     398
     399-*'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.  -*'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'). -*'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. -*'rectangle': defined by its center, half width and half height. -*'polygon': closed line made of n consecutive segments (defined by n points) -*ellipse: defined by its center, half width and half height. -*plane: plane with associated cartesian coordinates -*volume: volume with associated cartesian coordinates
     400
     401[<doc115|right>->#top]
     402
     403----
     404[get_field<-] '''{7- Netcdf files and get_field.fig:=== [netcdf<-]'''
     405
     406=== 7.1 The NetCDF format: ===
    582407NetCDF (network Common Data Form) is a machine-independent format for representing scientific data, suitable for large arrays ([->http://www.unidata.ucar.edu/software/netcdf/]). Each piece of data can be directly accessed by its name without reading the whole file. New records can be added to the file without perturbing the remaining information. The next release of NetCDF is intended to be compatible with the newly developed and more general hdf format.
    583408
    584     The NetCDF format has been initially developed for meteorological data, but has been progressively chosen by many scientific communities. This format has been for instance proposed by the European network PIVNet ( http://www.meol.cnrs.fr/LML/EuroPIV2/Proceedings/p251.pdf ) to inter compare data obtained by various techniques of Particle Imaging Velocimetry.
    585 
    586     Libraries for reading-writing and data visualisation with usual computer languages can be freely downloaded. Recent releases of Matlab contain built in functions for reading and writting netcdf files. For old versions, a free toolbox must be downloaded from from http://sourceforge.net/projects/mexcdf/. Uvmat deals with both cases.
     409  The NetCDF format has been initially developed for meteorological data, but has been progressively chosen by many scientific communities. This format has been for instance proposed by the European network PIVNet ( http://www.meol.cnrs.fr/LML/EuroPIV2/Proceedings/p251.pdf ) to inter compare data obtained by various techniques of Particle Imaging Velocimetry.
     410
     411  Libraries for reading-writing and data visualisation with usual computer languages can be freely downloaded. Recent releases of Matlab contain built in functions for reading and writting netcdf files. For old versions, a free toolbox must be downloaded from from http://sourceforge.net/projects/mexcdf/. Uvmat deals with both cases.
    587412
    588413The NetCDF data model consists of variables, dimensions, and attributes.
     
    590415-'''Variables:''' N-dimensional arrays of data. Variables in NetCDF files can be one of six types (char, byte, short, int, float, double). Variables are used to store the bulk of the data in a NetCDF dataset. A variable represents an array of values of the same type and unit. A variable has a name, a data type, and a shape described by its list of dimensions specified when the variable is created. A variable may also have associated attributes, which may be added, deleted or changed after the variable is created.
    591416
    592 -'''Dimensions:''' describe the axes of the data arrays. A dimension has a name and a length. The naming can be useful to identify groups of variables with one to one correspondence, sharing the same dimensions. It is legal for a variable to have the same name as a dimension, it is then called a coordinate variable. Such variables have no special meaning to the NetCDF library, but they can be used in processing software to link the arrays of coordinate values to their corresponding field variables. 
    593 
    594 -'''Attributes: ''' annotate variables or files (global attributes) with small notes or supplementary meta data. Attributes are always scalar values or 1D arrays, which can be associated with either a variable or the file as a whole. Although there is no enforced limit, the user is expected to keep attributes small. Attribute names with specific meaning are defined in http://www.unidata.ucar.edu/software/netcdf/docs_beta/netcdf.html#Attribute-Conventions. An attribute '.Conventions' can be used to refer to additional sets of conventions used in a particular community.
    595 
    596     In contrast to variables, which are intended for bulk data, attributes are intended for ancillary data, or information about the data. The total amount of ancillary data associated with a NetCDF object, and stored in its attributes, is typically small enough to be memory-resident. However variables are often too large to entirely fit in memory and must be split into sections for processing.
    597 
    598     Another difference between attributes and variables is that variables may be multidimensional. Attributes are all either scalars (single-valued) or vectors (a single, fixed dimension).
    599 
    600     Variables are created with a name, type, and shape before they are assigned data values, so a variable may exist with no values. The value of an attribute is specified when it is created, unless it is a zero-length attribute.
    601 
    602     A variable may have attributes, but an attribute cannot have attributes. Attributes assigned to variables may have the same units as the variable (for example, valid_range) or have no units (for example, scale_factor). If you want to store data that requires units different from those of the associated variable, it is better to use a variable than an attribute. More generally, if data require ancillary data to describe them, are multidimensional, require any of the defined NetCDF dimensions to index their values, or require a significant amount of storage, that data should be represented using variables rather than attributes.
    603 
    604 
    605 === 7.3 The GUI get_field:===
    606 
    607     This GUI is designed to analyse a NetCDF file, showing all the variables, attributes and variable dimensions. Variables can be selected and plotted. The GUI is opened by the Matlab prompt command '>>get_field'. It is also opened by the GUI '''uvmat.fig''' when an input NetCDF file does contain recognised CIVx data: then it takes the name 'uvmat_field', and some dfeatures are inhibited, to show that it depends on uvmat.   
     417-'''Dimensions:''' describe the axes of the data arrays. A dimension has a name and a length. The naming can be useful to identify groups of variables with one to one correspondence, sharing the same dimensions. It is legal for a variable to have the same name as a dimension, it is then called a coordinate variable. Such variables have no special meaning to the NetCDF library, but they can be used in processing software to link the arrays of coordinate values to their corresponding field variables.
     418
     419-'''Attributes: ''' annotate variables or files (global attributes) with small notes or supplementary meta data. Attributes are always scalar values or 1D arrays, which can be associated with either a variable or the file as a whole. Although there is no enforced limit, the user is expected to keep attributes small. Attribute names with specific meaning are defined in http://www.unidata.ucar.edu/software/netcdf/docs_beta/netcdf.html#Attribute-Conventions. An attribute '.Conventions' can be used to refer to additional sets of conventions used in a particular community.
     420
     421  In contrast to variables, which are intended for bulk data, attributes are intended for ancillary data, or information about the data. The total amount of ancillary data associated with a NetCDF object, and stored in its attributes, is typically small enough to be memory-resident. However variables are often too large to entirely fit in memory and must be split into sections for processing.
     422
     423  Another difference between attributes and variables is that variables may be multidimensional. Attributes are all either scalars (single-valued) or vectors (a single, fixed dimension).
     424
     425  Variables are created with a name, type, and shape before they are assigned data values, so a variable may exist with no values. The value of an attribute is specified when it is created, unless it is a zero-length attribute.
     426
     427  A variable may have attributes, but an attribute cannot have attributes. Attributes assigned to variables may have the same units as the variable (for example, valid_range) or have no units (for example, scale_factor). If you want to store data that requires units different from those of the associated variable, it is better to use a variable than an attribute. More generally, if data require ancillary data to describe them, are multidimensional, require any of the defined NetCDF dimensions to index their values, or require a significant amount of storage, that data should be represented using variables rather than attributes.
     428
     429=== 7.3 The GUI get_field: ===
     430  This GUI is designed to analyse a NetCDF file, showing all the variables, attributes and variable dimensions. Variables can be selected and plotted. The GUI is opened by the Matlab prompt command '>>get_field'. It is also opened by the GUI '''uvmat.fig''' when an input NetCDF file does contain recognised CIVx data: then it takes the name 'uvmat_field', and some dfeatures are inhibited, to show that it depends on uvmat.
    608431
    609432<doc62|center>
    610433
    611       When a NetCDF input file is entered, the names and value of the global attributes are listed in the left column '''[attributes]''', the list of variables in the central column '''[variables]''', and the list of dimension names and values in the right column '''[dimensions]'''. By selecting one of the variables in the central column, the corresponding variable attributes and dimensions are displayed in the left and right columns respectively. The whole content of the NetCDF file can be made available on the Matlab prompt in the form of a Matlab structure 'Data_get_field': use the menu bar button '''[Export]''', or click the right button mouse on the interface.
    612 
    613     Plots can be made in a new figure (default), to the interface '''uvmat.fig''', or added to an existing one, as selected in '''[list_fig]'''. Different processing or plotting functions can be activated by a selection in '''[ACTION]'''. The default action is a plot of selected field, as follows.
    614 
    615  -'''Ordinary graphs:''' to plot a simple graph, select the check box '''[1D_plot]'''. Then select the variable to plot  in the column '''[ordinate] ''' and  the corresponding abscissa in the column '''[abscissa]''', then press '''[RUN]'''.  If the variable is indexed with more than one dimension, each component is plotted versus the first index (like with the plot Matlab function {plot.m}). If no variable is selected in '''[abscissa]'''  ( blank selected at first line), the variable is plotted versus its (first) index.
    616 
    617 -'''Scalar maps:''' select this check box to plot scalar fields as images. The scalar field is selected in the first column [scalar], with coordinates respectively selected in '''[coord_x_scalar] ''' and '''[coord_y_scalar]'''. If no variable is selected in '''[coord_x_scalar] '''  or '''[coord_y_scalar] ''' ( blank selected at first line), the index is used as coordinate.
    618 
    619 -'''Vector plots:''' select this check box to plot vector fields. The x and y vector components iare selected in the first (...) and second columns, while the coordiantes are selected in '''[coord_x_vector] ''' and '''[coord_y_vector]'''. If no variable is selected in '''[coord_x_scalar] '''  or '''[coord_y_scalar] ''' ( blank selected at first line), the index is used as coordinate. A scalar, set in ..., can be represented as vector color.
    620 
    621 -'''Automatic opening''':
    622 When an input file is opened a default plotting option is proposed.
    623 
    624  In 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.
    625 
    626 --------------------------------------
    627 [geometry_calib<-]
    628 '''{8- Geometric calibration:===
    629 
    630 === 8.1 Generalities:===
    631 
    632     Transforming 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 y direction is directed upward, while the corresponding image index j increases downward.  The physical coordinates are defined from the experimental set-up. The correspondance is obtained by locating on the image 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:
     434  When a NetCDF input file is entered, the names and value of the global attributes are listed in the left column '''[attributes]''', the list of variables in the central column '''[variables]''', and the list of dimension names and values in the right column '''[dimensions]'''. By selecting one of the variables in the central column, the corresponding variable attributes and dimensions are displayed in the left and right columns respectively. The whole content of the NetCDF file can be made available on the Matlab prompt in the form of a Matlab structure 'Data_get_field': use the menu bar button '''[Export]''', or click the right button mouse on the interface.
     435
     436  Plots can be made in a new figure (default), to the interface '''uvmat.fig''', or added to an existing one, as selected in '''[list_fig]'''. Different processing or plotting functions can be activated by a selection in '''[ACTION]'''. The default action is a plot of selected field, as follows.
     437
     438  -'''Ordinary graphs:''' to plot a simple graph, select the check box '''[1D_plot]'''. Then select the variable to plot  in the column '''[ordinate] ''' and  the corresponding abscissa in the column '''[abscissa]''', then press '''[RUN]'''.  If the variable is indexed with more than one dimension, each component is plotted versus the first index (like with the plot Matlab function {plot.m}). If no variable is selected in '''[abscissa]'''  ( blank selected at first line), the variable is plotted versus its (first) index.
     439
     440-'''Scalar maps:''' select this check box to plot scalar fields as images. The scalar field is selected in the first column [scalar], with coordinates respectively selected in '''[coord_x_scalar] ''' and '''[coord_y_scalar]'''. If no variable is selected in '''[coord_x_scalar] '''  or '''[coord_y_scalar] ''' ( blank selected at first line), the index is used as coordinate.
     441
     442-'''Vector plots:''' select this check box to plot vector fields. The x and y vector components iare selected in the first (...) and second columns, while the coordiantes are selected in '''[coord_x_vector] ''' and '''[coord_y_vector]'''. If no variable is selected in '''[coord_x_scalar] '''  or '''[coord_y_scalar] ''' ( blank selected at first line), the index is used as coordinate. A scalar, set in ..., can be represented as vector color.
     443
     444-'''Automatic opening''':  When an input file is opened a default plotting option is proposed.
     445
     446  In 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.
     447
     448----
     449[geometry_calib<-] '''{8- Geometric calibration:==='''
     450
     451=== 8.1 Generalities: ===
     452  Transforming 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 y direction is directed upward, while the corresponding image index j increases downward.  The physical coordinates are defined from the experimental set-up. The correspondance is obtained by locating on the image 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:
    633453
    634454-''' {'rescale'} ''': linear rescaling along x and y + translation (no rotation nor deformation)
     
    636456-''' {'linear'} ''': general linear transform, including translation and rotation (but no perspective effects)
    637457
    638 -''' {3D projection:} ''' this transforms handles projection effects, as needed for stereoscopic view, as well as quadratic distortion, according to the pinhole camera  model ( R.Y. Tsai, 'An Efficient and Accurate Camera Calibration Technique for 3D Machine Vision'. Proceedings of IEEE Conference on Computer Vision and Pattern Recognition, Miami Beach, FL, pp. 364-374, 1986). We use a more recent version, with the toolbox [->http://www.vision.caltech.edu/bouguetj/calib_doc/] . To use this option, the number of calibration points should be large enough and well spread over the whole image. 
    639 
    640     The transform coefficients for each image series are stored in the corresponding xml documentation file <code><ImaDoc></code>, in the section <code><GeometryCalib></code>.  Calibration coefficients  can be obtained with the interface '''geometry_calib.fig'''.
     458-''' {3D projection:} ''' this transforms handles projection effects, as needed for stereoscopic view, as well as quadratic distortion, according to the pinhole camera  model ( R.Y. Tsai, 'An Efficient and Accurate Camera Calibration Technique for 3D Machine Vision'. Proceedings of IEEE Conference on Computer Vision and Pattern Recognition, Miami Beach, FL, pp. 364-374, 1986). We use a more recent version, with the toolbox [->http://www.vision.caltech.edu/bouguetj/calib_doc/] . To use this option, the number of calibration points should be large enough and well spread over the whole image.
     459
     460  The transform coefficients for each image series are stored in the corresponding xml documentation file <code><ImaDoc></code>, in the section <code><GeometryCalib></code>.  Calibration coefficients  can be obtained with the interface '''geometry_calib.fig'''.
    641461
    642462<doc68|center>
    643463
    644 === 8.2 The GUI geometry_calib.fig}:===
    645 
     464=== 8.2 The GUI geometry_calib.fig}: ===
    646465-''' {Opening the GUI:} ''' it is made visible  from the GUI '''uvmat.fig''' by  the menu bar command '''[Tools/Geometric calibration] '''.  If calibration data already exist in the current file <code>ImaDoc </code>, the corresponding list of reference points is displayed  in the central window '''[ListCoord] ''' of '''geometry_calib.fig'''. The three first columns indicate the physical coordinates and the two last ones the corresponding image coordinates. Calibration points can be alternatively introduced by opening any <code><ImaDoc></code> xml file with the menu bar command''' [Open] ''' of '''geometry_calib.fig'''.
    647466
    648 -''' {Plotting calibration points:} ''' press the menu bar command button '''[Plot] ''' to visualise the list of calibration points. The physical or image coordinates will be used in the list '''[ListCoord]''', depending on the option 'phys' or 'px' in the menu '''[transform_fct]''' of ''' uvmat.fig''' .
    649 
    650 -''' {Appending  calibration points with the mouse:} '''
    651 Calibration points can be manually picked out by the mouse (left button click) after a calibration image has been opened by '''uvmat.fig''' (with the option '' or 'px' in the popup menu '''[transform_fct]'''), and the option '''[mouse_active]''' (at the very bottom) has been selected. Zoom can be used to improve the precision, but must be desactivated for mouse selection (then move across the image by the key board directional arrows). The coordinates in pixel of the selected points get listed in the box '''[ListCoord]''' of '''geometry_calib.fig'''. A calibration point can be later adjusted by selecting it with the mouse and moving it while pressing the left mouse button. Points can be accumulated from several images (use the key board short cuts 'p' and 'm' to move in the image series without monopolising the mouse).
     467-''' {Plotting calibration points:} ''' press the menu bar command button '''[Plot] ''' to visualise the list of calibration points. The physical or image coordinates will be used in the list '''[ListCoord]''', depending on the option 'phys' or 'px' in the menu '''[transform_fct]''' of ''' uvmat.fig''' .
     468
     469-''' {Appending  calibration points with the mouse:} ''' Calibration points can be manually picked out by the mouse (left button click) after a calibration image has been opened by '''uvmat.fig''' (with the option '' or 'px' in the popup menu '''[transform_fct]'''), and the option '''[mouse_active]''' (at the very bottom) has been selected. Zoom can be used to improve the precision, but must be desactivated for mouse selection (then move across the image by the key board directional arrows). The coordinates in pixel of the selected points get listed in the box '''[ListCoord]''' of '''geometry_calib.fig'''. A calibration point can be later adjusted by selecting it with the mouse and moving it while pressing the left mouse button. Points can be accumulated from several images (use the key board short cuts 'p' and 'm' to move in the image series without monopolising the mouse).''
    652470
    653471-''' {Editing the  coordinates:} '''
    654     For editing the physical coordinates of a calibration point, select it in the list '''[ListCoord]''', and use the edit boxes '''[XObject]''', '''[YObject]''', '''[ZObject] ''' (for 3D calibration). The image coordinates can be also edited by '''[XImage]''', '''[YImage]''', although they are preferably set directly by the mouse. Type 'return carriage' to validate the edition. The reference point can be suppressed by typing the 'backward' arrow on the key-board, or by filling the five boxes with blank values. 
     472
     473  For editing the physical coordinates of a calibration point, select it in the list '''[ListCoord]''', and use the edit boxes '''[XObject]''', '''[YObject]''', '''[ZObject] ''' (for 3D calibration). The image coordinates can be also edited by '''[XImage]''', '''[YImage]''', although they are preferably set directly by the mouse. Type 'return carriage' to validate the edition. The reference point can be suppressed by typing the 'backward' arrow on the key-board, or by filling the five boxes with blank values.
    655474
    656475-''' {Creating a physical grid:} ''' This tool '''[Tools/Create grid]''' in the  menu bar command provides the whole set of physical coordinates of a cartesian grid, after all their image coordinates have been picked out by the mouse. In the  GUI '''Create_grid.fig''' which appears, set the first and last x and y values and the meshes for the physical grid corresponding to the points already selected by the mouse. The physical coordinates of all the grid points then appears on '''[ListCoord]'''.
     
    659478
    660479-''' {Translation and rotation of calibration points:} '''
    661     A translation or rotation (in physical space) can be introduced by the menu bar commands '''[Tools/Translate points]''' and '''[Tools/Rotate points]'''.  In the case of rotation, the origin of the rotation, as well as the angle (in degree) must be introduced. The resulting coordinates appear in the list '''[ListCoord]'''.
     480
     481  A translation or rotation (in physical space) can be introduced by the menu bar commands '''[Tools/Translate points]''' and '''[Tools/Rotate points]'''.  In the case of rotation, the origin of the rotation, as well as the angle (in degree) must be introduced. The resulting coordinates appear in the list '''[ListCoord]'''.
    662482
    663483-''' {Recording calibration parameters:} '''
    664     Once the list of calibration points has been completed, press '''[APPLY]''', after selecting the appropriate option in '''[calib_type]'''. (see the previous sub-section 7.1). Note that the more advanced Tsai options  require a sufficient number of calibration points (typically > 10) spread over the image. Calibration coefficients are recorded in the xml file <code><ImaDoc> </code> associated with the image currently opened by uvmat. If previous calibration data already exist, the previous xml file is updated, but  the original one is preserved with the extension .xml~.  If no xml file already exists, it is created. The image transformation to phys coordinates can be directly seen on the '''uvmat.fig''' interface after completion of the command '''[APPLY]'''.
    665 
    666       To reproduce the same calibrationn for image series, open one of the image in the series, and apply again the calibration with the same points, or copy-paste the section GeometryCalib of the xml documentation file with a text editor.
    667 
    668         Alternatively the command '''[REPLICATE]''' can be used to calibrate a whole set of experiments, using an overview of the data set provided by the GUI '''dataview.fig'''.
    669 
    670 ===8.3 Structure of the xml file:===
    671     The coefficients are recorded in the xml element <code><ImaDoc/GeometryCalib></code> as follows:
    672 -<code><CalibrationType></code>: type of calibration ('rescale', 'linear', '3D...')
    673 -<code><fx_fy></code>: focal length along each coordinate of the image sensor, expressed in pixel interval.
    674 -<code><Cx_Cy></code>: position coordinates of the optical axis on the
    675 -<code><kc></code>: coefficient of quadratic deformation (=1 for the options calib_lin and calib_rescale)
    676 -<code><CoordUnit></code>: coordinate unit in physical space.
    677 -<code><Tx_Ty_Tz></code>: translation, (Tz=1 for the options calib_lin and calib_rescale)
    678 -<code><R>:</code> rotation matrix (in 3 lines)
    679       For the option calib_rescale
    680            R (i=1)= [pxcmx 0 0]
    681            R (i=2)= [0 pxcmy 0]
    682            R (i=3)= [0 0 1]
    683 where pxcmx and pxcmy are the scaling factors along x and y.
    684 -<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)
    685 -<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)
    686 -<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)
    687 -<code><SourceCalib> </code>set of the point coordinates used for calibration
    688 -<code><PointCoord> </code>[x y z X Y] , where x,y,z are the physical coordinates of each point, X Y its image coordinates.
    689 -<code><NbSlice_i> </code>nbre of slices for the first field  index i (multilevel case), =1 by default.
    690 -<code><NbSlice_j> </code>nbre of slices for the second index j (volume scan), =1 by default.
    691 -<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].
    692 -<code><SliceDZ> </code>,  step distance between planes, or <code><SliceDPhi> </code> step angle for angular scan.
    693 
    694 [<doc115|right>->#top]
    695 
    696 --------------------------------------------
    697 '''{9- Masks and grids:===
    698 [sec9.1<-]
    699 ===9.1 Masks:===
    700 
    701     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].
    702 
    703 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.
     484
     485  Once the list of calibration points has been completed, press '''[APPLY]''', after selecting the appropriate option in '''[calib_type]'''. (see the previous sub-section 7.1). Note that the more advanced Tsai options  require a sufficient number of calibration points (typically > 10) spread over the image. Calibration coefficients are recorded in the xml file <code><ImaDoc> </code> associated with the image currently opened by uvmat. If previous calibration data already exist, the previous xml file is updated, but  the original one is preserved with the extension .xml~.  If no xml file already exists, it is created. The image transformation to phys coordinates can be directly seen on the '''uvmat.fig''' interface after completion of the command '''[APPLY]'''.
     486
     487  To reproduce the same calibrationn for image series, open one of the image in the series, and apply again the calibration with the same points, or copy-paste the section GeometryCalib of the xml documentation file with a text editor.
     488
     489  Alternatively the command '''[REPLICATE]''' can be used to calibrate a whole set of experiments, using an overview of the data set provided by the GUI '''dataview.fig'''.
     490
     491=== 8.3 Structure of the xml file: ===
     492  The coefficients are recorded in the xml element <code><ImaDoc/GeometryCalib></code> as follows:
     493
     494-<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)
     495
     496  For the option calib_rescale
     497    R (i=1)= [pxcmx 0 0] R (i=2)= [0 pxcmy 0] R (i=3)= [0 0 1]
     498
     499where 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.
     500
     501[<doc115|right>->#top]
     502
     503----
     504'''{9- Masks and grids:=== [sec9.1<-]'''
     505
     506=== 9.1 Masks: ===
     507  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].
     508
     509Mas 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.
    704510
    705511First 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.
     
    710516
    711517[sec9.2<-]
    712 ===9.2 Grids:===
    713 
    714 Grid files, see [section 3.6->#sec3.6_grid], are used to impose a set of positions for PIV vectors. To create a grid for PIV, activate the menu bar Tools/Make grid on the GUI uvmat. Introduce a minimum value, mesh, and maximum value for each coordinate x in the edit boxes XMin, DX, XMax respectively. Do the same for the y coordinate.  This must be expressed in physical coordinates. 
     518
     519=== 9.2 Grids: ===
     520Grid files, see [section 3.6->#sec3.6_grid], are used to impose a set of positions for PIV vectors. To create a grid for PIV, activate the menu bar Tools/Make grid on the GUI uvmat. Introduce a minimum value, mesh, and maximum value for each coordinate x in the edit boxes XMin, DX, XMax respectively. Do the same for the y coordinate.  This must be expressed in physical coordinates.
    715521
    716522The 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.
     
    718524[<doc115|right>->#top]
    719525
    720 --------------------------------------
    721 [series<-]
    722 '''{10- Processing field series:===
    723 
    724 ===10.1 The GUI series.fig:===
    725 
    726     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  must operate. The root path, subdirectory, root file name and extension are introduced in the same way as with the uvmat interface, in the edit windows '''[RootPath], [SubDir], [RootFile],''' and '''[FileExt],''' respectively. The nomenclature for file indexing is represented in '''[NomType]''' ('Indices').
    727 
    728     Several input file series can be introduced simultaneously by the menu bar command''' [Open_insert]'''. By contrast, the current input series are refreshed by the browser from the menu bar command''' [Open]'''.
    729 
    730     The velocity type and field is automatioally chosen by default, but it can be specified by VelType and Field. For that purpose use the menus VelTypeMenu and fieldsinput. In case of multiple input file series, these menus act only on the first line. 
    731 
    732     The processing function is chosen in the menu '''[ACTION]'''.  All actions operate on the same series of input files, whose list can be obtained with the option 'check_files'. 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 .  Finally any additional function can be called and included in the menu by selecting the option 'more...' .
    733 
    734     The series of file indices is set in the frame '''[RANGE]'''. Any action is performed from field index '''[first_i] ''' to '''[last_i] '''  with increment '''[incr_i]''' . In case of double indexing, action is similarly performed from field index''' [first_j]''' to '''[last_j]''' with increment '''[incr_j]'''. Succesive file names are ordered as a matrix {j,i} with the index j varying the fastest. The parameter nb_slice can be introduced to scan the i index modulo nb_slice.
    735 
    736     For pair indexing, the selected pair must be chosen in the menu list_pair-civ in the frame PAIRS (browse again an input field if this menu does not appear). Then the first_i and last_i refer to the 'reference indices'. With the option '*-*' in '''[list_pair_civ]''', available pairs are automatically chosen (this is appropriate if several image pairs are used in a time series, to account for a changing mean velocity).
    737 
    738     A projection object can be introduced by selecting the check box '''[PROJECTION OBJECT]'''. If a projection object has been already created the  opened interface '''set_object.fig''' will be used. Otherwise a browser apperas to open an object file (xml).
    739 
    740 ===10.2 check_files:===
    741 
     526----
     527[series<-] '''{10- Processing field series:==='''
     528
     529=== 10.1 The GUI series.fig: ===
     530  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  must operate. The root path, subdirectory, root file name and extension are introduced in the same way as with the uvmat interface, in the edit windows '''[RootPath], [SubDir], [RootFile],''' and '''[FileExt],''' respectively. The nomenclature for file indexing is represented in '''[NomType]''' ('Indices').
     531
     532  Several input file series can be introduced simultaneously by the menu bar command''' [Open_insert]'''. By contrast, the current input series are refreshed by the browser from the menu bar command''' [Open]'''.
     533
     534  The velocity type and field is automatioally chosen by default, but it can be specified by VelType and Field. For that purpose use the menus VelTypeMenu and fieldsinput. In case of multiple input file series, these menus act only on the first line.
     535
     536  The processing function is chosen in the menu '''[ACTION]'''.  All actions operate on the same series of input files, whose list can be obtained with the option 'check_files'. 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 .  Finally any additional function can be called and included in the menu by selecting the option 'more...' .
     537
     538  The series of file indices is set in the frame '''[RANGE]'''. Any action is performed from field index '''[first_i] ''' to '''[last_i] '''  with increment '''[incr_i]''' . In case of double indexing, action is similarly performed from field index''' [first_j]''' to '''[last_j]''' with increment '''[incr_j]'''. Succesive file names are ordered as a matrix {j,i} with the index j varying the fastest. The parameter nb_slice can be introduced to scan the i index modulo nb_slice.
     539
     540  For pair indexing, the selected pair must be chosen in the menu list_pair-civ in the frame PAIRS (browse again an input field if this menu does not appear). Then the first_i and last_i refer to the 'reference indices'. With the option '*-*' in '''[list_pair_civ]''', available pairs are automatically chosen (this is appropriate if several image pairs are used in a time series, to account for a changing mean velocity).
     541
     542  A projection object can be introduced by selecting the check box '''[PROJECTION OBJECT]'''. If a projection object has been already created the  opened interface '''set_object.fig''' will be used. Otherwise a browser apperas to open an object file (xml).
     543
     544=== 10.2 check_files: ===
    742545Gives the series of files selected for processing and checks their existence. The oldest modified file is indicated, which is useful to detect whether any file in a civ processing is missing (then the oldest file is not updated).
    743546
    744547For NetCDF files, the last operation made (civ1, fix1, patch1, civ2, fix2, patch2) is indicated. The details of each NetCDF file can be dispalyed by selecting it with the mouse in the list.
    745548
    746 
    747 ===10.3 aver_stat:===
    748 
    749     This option provides any average over the processed files. If nb_slice is not equal to 1, the average is performed slice by slice, providing nb_slice results.   If a projection object is selected (check box GetObject), the field is projected before averaging.
    750 
    751     For unstructured coordinates varying for successive fields, the data is linearly interpolated on the coordinates of the first field in the series. It is then advised to project the fields on a regular grid, creating a projection object of type 'plane' with projection mode 'interp'.
    752 
    753     With a projection object with title PATCH, the global histogram of field variables on the selected region will be obtained.   
     549=== 10.3 aver_stat: ===
     550  This option provides any average over the processed files. If nb_slice is not equal to 1, the average is performed slice by slice, providing nb_slice results.   If a projection object is selected (check box GetObject), the field is projected before averaging.
     551
     552  For unstructured coordinates varying for successive fields, the data is linearly interpolated on the coordinates of the first field in the series. It is then advised to project the fields on a regular grid, creating a projection object of type 'plane' with projection mode 'interp'.
     553
     554  With a projection object with title PATCH, the global histogram of field variables on the selected region will be obtained.
    754555
    755556In the case of two input files series, the field difference will be perfomed like with the interface uvmat.fig. It is not possible to use more than two input series for this funtion.
    756    
    757 
    758 ===10.4 time_series:===
    759 
     557
     558=== 10.4 time_series: ===
    760559  This action provides a time series of the input field. It is advised to use a POINTS projection object, so the series is limited to the selected points.
    761560
    762 In the case of two input files series, the field difference will be perfomed like with the interface uvmat.fig. It is not possible to use more than two input series for this funtion.
    763 
    764 ===10.5 merge_proj: } ===
    765 
    766     This option allows to merge several field series  in a single one. This is useful to merge fields obtained with different cameras. Select the different series, activating the check box add. In this case, it is generally useful to first interpolate the fields on a single grid. For that purpose select the check box GetObject, creating a projection object of type 'plane' with projection mode 'interp'.
    767 
    768     Since the different views have their own calibration, it is important to use the option 'phys' (menu menu_coord), and to create the grid in phys coordinates.
    769 
    770 ===10.6 more...:===
    771 
    772 This action calls any user defined function by its name, acting on the series of fields defiend for ACTION.
    773 Some examples of usr_defined functions are in the subdirectory {/series}.
    774 
    775 -List of available functions:
    776 -*{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).
    777 -*{ima2vol.m:} produce volume images for 3D3C PIV.
    778 
    779 To update (**):
    780 -uvprofile: calculate the mean velocity profile and Reynolds stress u'v' along a band, averaged over the series of fields.
    781 -view_ima3D: provides a perspective view of a 3D image defined by a series of slice 2D images. The isosurfaces of the scalar field are represented.
    782 -part_stat: count particles and provides their density and luminosity histogramm
    783 Peaklocking errors:(to update **)
     561In the case of two input files series, the field difference will be perfomed like with the interface uvmat.fig. It is not possible to use more than two input series for this funtion.
     562
     563=== 10.5 merge_proj: } ===
     564  This option allows to merge several field series  in a single one. This is useful to merge fields obtained with different cameras. Select the different series, activating the check box add. In this case, it is generally useful to first interpolate the fields on a single grid. For that purpose select the check box GetObject, creating a projection object of type 'plane' with projection mode 'interp'.
     565
     566  Since the different views have their own calibration, it is important to use the option 'phys' (menu menu_coord), and to create the grid in phys coordinates.
     567
     568=== 10.6 more...: ===
     569This 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}.
     570
     571-List of available functions: -*{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). -*{ima2vol.m:} produce volume images for 3D3C PIV.
     572
     573To update (**): -uvprofile: calculate the mean velocity profile and Reynolds stress u'v' along a band, averaged over the series of fields. -view_ima3D: provides a perspective view of a 3D image defined by a series of slice 2D images. The isosurfaces of the scalar field are represented. -part_stat: count particles and provides their density and luminosity histogramm Peaklocking errors:(to update **)
    784574
    785575By 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.
     
    787577[<doc115|right>->#top]
    788578
    789 --------------------------------
    790 [civ<-]
    791 '''{11- PIV: Particle Imaging Velocimetry===
     579----
     580[civ<-] '''{11- PIV: Particle Imaging Velocimetry==='''
    792581
    793582{===11.1 Overview:===}
     
    795584The GUI '''civ.fig''' is used to run the programs [CIVx->3]  (Correlation Imaging Velocimetry). It is a free advanced Imaging Velocimetry implementation that relies on direct cross-correlation of pattern boxes between image pairs. The binary executable files suitable for the computer operating system need to be properly installed (see {uvmat_doc/README_INSTALL.txt }).
    796585
    797 -''' {Opening the GUI:} '''
    798 The GUI '''civ.fig''' for PIV calculation can be directly opened by the command '>>civ' on the Matlab prompt. Then open an image or a documentation file (.xml ) with the file browser. ''' '''The''' ''' GUI '''civ.fig''' can be also directly opened from '''uvmat.fig''', by the menu bar command '''[RUN/civ]'''.  A third way is just to open the Matlab image ({civ.fig} file) stored after each processing in the directory of the velocity fields. Then just edit it and run a new calculation.
     586-''' {Opening the GUI:} ''' The GUI '''civ.fig''' for PIV calculation can be directly opened by the command '>>civ' on the Matlab prompt. Then open an image or a documentation file (.xml ) with the file browser. ''' '''The''' ''' GUI '''civ.fig''' can be also directly opened from '''uvmat.fig''', by the menu bar command '''[RUN/civ]'''.  A third way is just to open the Matlab image ({civ.fig} file) stored after each processing in the directory of the velocity fields. Then just edit it and run a new calculation.
    799587
    800588<doc78|center>
    801589
    802 -''' {Input file name and indexing:} '''
    803 The root name of the input file is displayed in the edit box '''[RootName]''', and a set of indices can be defined by the edit boxes '''[first_i] ''' (first index), '''[incr_i]''' (increment), '''[last_i ]'''(last index). The GUI offers a wide variety for the choice of image pairs to correlate. In the case of two file indices i and j, a mode for the choice of image pairs can be selected in the popup menu '''[mode]'''.
    804 -*'pairj1-j2': a given pair of j indices (or subscript a, b c...) can be chosen in the CIV1 menu '''[list_pair_civ1]''', while the corresponding indices i are set by '''[first_i] ''', '''[incr_i]''' , '''[last_i ]'''.
    805 -*'series(Di)': a sliding set of i index pairs is chosen by a set of {reference} indices i_ref given by '''[first_i] ''', '''[incr_i]''' , '''[last_i ]''' and a pair interval defined in '''[list_pair_civ1]''': the first choice 0|1 corresponds to the sliding pair i_ref|i_ref+1. the second choice -1|1 to the sliding pair i_ref-1|i_ref+1,...This mode is generally used with a single image series or movie, but it can be also used in volume scan, with a second index j chosen by '''[first_j] ''', '''[incr_j]''' , '''[last_j ]'''.
    806 -*'series(Dj)': operates like 'series(Di)', but with sliding j index pairs.
    807 -*comparing two image series: this is made possible by selecting 'displacement' in the popup menu '''[compare]''', which gives access to a browser for selecting the second image series. This second series can be reduced to a single reference image, if it contains no index. The displacement field with respect to this reference image is then obtained  for successive times.
    808 -*stereo PIV: this option in the menu '''[compare]''' provides the three velocity components  by comparing the stereoscopic views from two cameras, see [section 10.6->#sec10.6].
    809 
    810 -''' {Succession of operations:} '''
    811 
    812 The CIV process involves a succession of iterative operations:
    813 -*civ1: the initial image correlation process.
    814 -*fix1: detection of 'false' velocity vectors according to different criteria.
    815 -*patch1: interpolation and filtering on a regular grid, providing access to spatial derivatives of the velocity (diverrgence, curl, strain).
    816 -* civ2: advanced image correlation algorithm using the result of civ1 as a first approximation.
    817 -* fix2 and patch2: similar as fix1 and patch1, but applied to the civ2 results.
    818 This series of operations is chosen by selecting the corresponding  check boxes on the left, which give access to the corresponding parameter input panels. Note that the result of each of these operations is stored in the output netcdf file, so the process can be split in several runs. When an existing netcdf velocity file is opened, the GUI '''civ.fig''' is automaticaly configured to perform the next operation (fix1, patch1, civ2...) needed in the process.
    819 
    820 {===11.2 CIV1:===}
    821 The image pair is selected in the menu '''[list_pair_civ1]''', see sub-section 10.1. The time interval of the image pair must be chosen sufficiently small to provide a good correlation, and sufficiently large to provide good measurment precision: a displacement of 5-10 pixels is generally optimum.
    822 
    823 The time interval for each image pair is indicated in '''[list_pair_civ1]''' iif the information is made available, either from a movie file, or from a detected xml file (with the name RootName.xml). The source of the timing information is indicated in the edit box '''[ImaDoc]'''. Examples of xml files are provides in /XML_SCHEMAS/ImaDoc_templates. In the absence of information, the file index is taken for the time.
    824 The time interval for a given index pair may change with time, so the time interval display is taken for given reference indices, given by '''[i_ref]''' and ''' [j_ref].'''.
    825 
    826 ('''[ibx], [iby])''' set the size (in pixels) of the 'correlation box', the sliding window used to get image correlations. '''[isx],[ isy]''' set the size of the 'search box' in which image correlation is calculated, see figure.  This search box can be shifted with respect to the correlation box by parameters  ([shift x],[shift_y]). This is useful in the presence of a known mean flow. 
    827 
    828 The default value ibx=iby=(25,25) is generally good, use a larger size for images with few particles, use an elongated box , e.g. (11,41) , to optimise the resolution in one direction (for instance in a boundary layer).
     590-''' {Input file name and indexing:} ''' The root name of the input file is displayed in the edit box '''[RootName]''', and a set of indices can be defined by the edit boxes '''[first_i] ''' (first index), '''[incr_i]''' (increment), '''[last_i ]'''(last index). The GUI offers a wide variety for the choice of image pairs to correlate. In the case of two file indices i and j, a mode for the choice of image pairs can be selected in the popup menu '''[mode]'''. -*'pairj1-j2': a given pair of j indices (or subscript a, b c...) can be chosen in the CIV1 menu '''[list_pair_civ1]''', while the corresponding indices i are set by '''[first_i] ''', '''[incr_i]''' , '''[last_i ]'''. -*'series(Di)': a sliding set of i index pairs is chosen by a set of {reference} indices i_ref given by '''[first_i] ''', '''[incr_i]''' , '''[last_i ]''' and a pair interval defined in '''[list_pair_civ1]''': the first choice 0|1 corresponds to the sliding pair i_ref|i_ref+1. the second choice -1|1 to the sliding pair i_ref-1|i_ref+1,...This mode is generally used with a single image series or movie, but it can be also used in volume scan, with a second index j chosen by '''[first_j] ''', '''[incr_j]''' , '''[last_j ]'''. -*'series(Dj)': operates like 'series(Di)', but with sliding j index pairs. -*comparing two image series: this is made possible by selecting 'displacement' in the popup menu '''[compare]''', which gives access to a browser for selecting the second image series. This second series can be reduced to a single reference image, if it contains no index. The displacement field with respect to this reference image is then obtained  for successive times.  -*stereo PIV: this option in the menu '''[compare]''' provides the three velocity components  by comparing the stereoscopic views from two cameras, see [section 10.6->#sec10.6].
     591
     592-''' {Succession of operations:} '''
     593
     594The CIV process involves a succession of iterative operations:  -*civ1: the initial image correlation process. -*fix1: detection of 'false' velocity vectors according to different criteria. -*patch1: interpolation and filtering on a regular grid, providing access to spatial derivatives of the velocity (diverrgence, curl, strain). -* civ2: advanced image correlation algorithm using the result of civ1 as a first approximation. -* fix2 and patch2: similar as fix1 and patch1, but applied to the civ2 results. This series of operations is chosen by selecting the corresponding  check boxes on the left, which give access to the corresponding parameter input panels. Note that the result of each of these operations is stored in the output netcdf file, so the process can be split in several runs. When an existing netcdf velocity file is opened, the GUI '''civ.fig''' is automaticaly configured to perform the next operation (fix1, patch1, civ2...) needed in the process.
     595
     596{===11.2 CIV1:===} The image pair is selected in the menu '''[list_pair_civ1]''', see sub-section 10.1. The time interval of the image pair must be chosen sufficiently small to provide a good correlation, and sufficiently large to provide good measurment precision: a displacement of 5-10 pixels is generally optimum.
     597
     598The time interval for each image pair is indicated in '''[list_pair_civ1]''' iif the information is made available, either from a movie file, or from a detected xml file (with the name RootName.xml). The source of the timing information is indicated in the edit box '''[ImaDoc]'''. Examples of xml files are provides in /XML_SCHEMAS/ImaDoc_templates. In the absence of information, the file index is taken for the time.  The time interval for a given index pair may change with time, so the time interval display is taken for given reference indices, given by '''[i_ref]''' and ''' [j_ref].'''.
     599
     600('''[ibx], [iby])''' set the size (in pixels) of the 'correlation box', the sliding window used to get image correlations. '''[isx],[ isy]''' set the size of the 'search box' in which image correlation is calculated, see figure.  This search box can be shifted with respect to the correlation box by parameters  ([shift x],[shift_y]). This is useful in the presence of a known mean flow.
     601
     602The default value ibx=iby=(25,25) is generally good, use a larger size for images with few particles, use an elongated box , e.g. (11,41) , to optimise the resolution in one direction (for instance in a boundary layer).
    829603
    830604A parameter '''[rho(images)] ''' controls the smoothing of the image corelation curves used in civ, the default value 1 is generally used.
    831605
    832 The search parameters (isx, isy,shift x,y) can be estimated using the press button '''[search range]'''. First introduce the estimated minimum and maximum values of each velocity component u and v. The result depends on the time interval of the image pair. Change the selected image pair if the maximum displacement (ibsx-ibx)/2 is too small (lack of precision) or too large (bad image correlations and risks of false vectors). 
     606The search parameters (isx, isy,shift x,y) can be estimated using the press button '''[search range]'''. First introduce the estimated minimum and maximum values of each velocity component u and v. The result depends on the time interval of the image pair. Change the selected image pair if the maximum displacement (ibsx-ibx)/2 is too small (lack of precision) or too large (bad image correlations and risks of false vectors).
    833607
    834608<doc72|center>
    835609
    836  The grid determines the positions of measured velocity vectors: it sets the central positions of the correlation boxes (in pixels) for the first image. A default regular grid can be set by the meshes '''[dx] ''' and '''[dy]''' (in pixels). Alternatively a custom [grid->#sec3.6_grid] can be stored in a text file and selected by the check box '''[GET_GRID]'''. This is convenient to limitate the processing to a subregion or to fine tune the resolution.
    837 
    838 A subregion can be alternatively  selected by a mask image, selecting the edit box '''[MASK]'''. If a mask image with an appropriate name is found in the image directory, it wil be detected, and the indication 'xxmask' appears in the edit box. (xx is the number of slices, equal to 1 for a single mask). Otherwise a browser appears to select a (single) mask file. 
     610  The grid determines the positions of measured velocity vectors: it sets the central positions of the correlation boxes (in pixels) for the first image. A default regular grid can be set by the meshes '''[dx] ''' and '''[dy]''' (in pixels). Alternatively a custom [grid->#sec3.6_grid] can be stored in a text file and selected by the check box '''[GET_GRID]'''. This is convenient to limitate the processing to a subregion or to fine tune the resolution.
     611
     612A subregion can be alternatively  selected by a mask image, selecting the edit box '''[MASK]'''. If a mask image with an appropriate name is found in the image directory, it wil be detected, and the indication 'xxmask' appears in the edit box. (xx is the number of slices, equal to 1 for a single mask). Otherwise a browser appears to select a (single) mask file.
    839613
    840614Finally thresholds on image intensity can be introduced to suppress underexposed or overexposed parts of the image: select the check box '''[THRESH],''' and edit the boxes '''[MinIma] ''' and '''[MaxIma] ''' which then appear.
    841615
    842  The velocity results are stored in the subdirectory set by the edit box '''[subdir_civ1].''' Use the browser''' [list_subdir_civ1]''' to check the existing subdirectories.
     616  The velocity results are stored in the subdirectory set by the edit box '''[subdir_civ1].''' Use the browser''' [list_subdir_civ1]''' to check the existing subdirectories.
    843617
    844618-''' {RUN and BATCH:} '''
    845  The PIV calculation is started by the press button [RUN], or [BATCH] if this option has been installed. BATCH sends the same computations as background computing tasks in a network.
    846 
    847     In both cases, the status of the computations can be checked by opening {.cmx } and {.log} files, using the uvmat browser or any text editor. These files are writtent in the same subdirectory as the NetCDF result files. Each {.cmx} file contains the set of parameters used for a civ computation. It is written by the civ interface just before ordering the computations. By contrast , the {.log} file is produced after completion of the computations, and it contains some information on the process, including possible error messages.
    848 
    849 [sec11.3<-]
    850 {===11.3 FIX===}
    851 
    852 The FIX operation is used after civ to remove false vectors, using different criteria:
    853 -''' {warning flags:} ''' these are flags (vec_F) indicating problems with the image correlation process:
    854 -*vec_F(i)=0 or 1 : default , the processing is fine
    855 -*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
    856 -*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.
    857 Reference: Hart D. P. (2000) 'PIV error correction',{ Exp. Fluids} '''29''', 13-22.
    858 -*vec_F(i)=3: the optimisation of the correlation function is unstable  or  local Intensity rms of the image =0
    859 -*vec_F(i)=4:only in civ2: the difference between the estimator and the result is more than 1 pixel.
    860 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). 
    861 -''' {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.
    862 -''' {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]''').
    863 -''' {Mask fix:} '''  It has the same effect as the one used in civ1, but the removed vectors are kept in memory, labelled as false.
    864 -''' {Manual fix:} ''' Interactive fixing with the mouse is also possible, see [section 4.2->#4.2].
    865 
    866 -''' {Code for FixFlag:} '''
    867 -*FixFlag(i)=0 :default, everything is fine
    868 -*FixFlag(i)=1. : value 1 for the second digit: vector removed by criteria on vec_F or/and low correlation value
    869 -*FixFlag(i)=1..: value 1 for the third digit: vector selected by a criterium of difference with another field, for instance filter, or a field with differnt time interval.
    870 -*FixFlag(i)=...1, 2, 3  different criteria for elimination set by the program Fix of CIVx (not yet documented).
     619
     620  The PIV calculation is started by the press button [RUN], or [BATCH] if this option has been installed. BATCH sends the same computations as background computing tasks in a network.
     621
     622  In both cases, the status of the computations can be checked by opening {.cmx } and {.log} files, using the uvmat browser or any text editor. These files are writtent in the same subdirectory as the NetCDF result files. Each {.cmx} file contains the set of parameters used for a civ computation. It is written by the civ interface just before ordering the computations. By contrast , the {.log} file is produced after completion of the computations, and it contains some information on the process, including possible error messages.
     623
     624[sec11.3<-] {===11.3 FIX===}
     625
     626The 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].
     627
     628-''' {Code for FixFlag:} ''' -*FixFlag(i)=0 :default, everything is fine -*FixFlag(i)=1. : value 1 for the second digit: vector removed by criteria on vec_F or/and low correlation value -*FixFlag(i)=1..: value 1 for the third digit: vector selected by a criterium of difference with another field, for instance filter, or a field with differnt time interval. -*FixFlag(i)=...1, 2, 3  different criteria for elimination set by the program Fix of CIVx (not yet documented).
    871629
    872630{===11.4 PATCH===}
     
    884642Further iterations: improvements can be obtained by further iterations of the civ2-fix2-patch2 process. Open again the interface, and consider the previous civ2 result as the prior guess civ1. It will be recopied and relabelled as civ1 in the new NetCDF file produced.
    885643
    886 [sec11.6<-]
    887 {=== 10.6 Stereoscopic PIV:===}
     644[sec11.6<-] {=== 10.6 Stereoscopic PIV:===}
    888645
    889646To obtain the three velocity components in a plane with stereoscopic PIV, use the following procedure:
    890647
    891 Install two cameras viewing a common field with angle about 45 ° on each side. A system of titled objective lenses (Sheimpflug) allows to optimize the focus in the whole image. 
     648Install two cameras viewing a common field with angle about 45 ° on each side. A system of titled objective lenses (Sheimpflug) allows to optimize the focus in the whole image.
    892649
    893650Make a careful geometric calibration, by taking the images of a grid positioned in the plane of the laser sheet used for particle illumination. Introduce a Tsai calibration with the calibration tool associated with the  image acquisition software Acquix. Calibration can be adjusted with the uvmat interface (see calibration).
    894     This calibration model is valid in air or with an interface air-water perpendicular to the line of sight for each camera. Otherwise, the calibration problem is more complex.
     651
     652  This calibration model is valid in air or with an interface air-water perpendicular to the line of sight for each camera. Otherwise, the calibration problem is more complex.
    895653
    896654Perform usual PIV for each image series:
    897     The images from each camera (camA and camB) must be in the same directory and the PIV results in a single subdirectory. It is advised to do the successive operations including civ2 and fix2. This double series of PIV processing can be done in two steps (keeping the same CIV subdirectory) or simulatenously, using the compare ('-') option.  Then the check boxed test_stereo1 and test_stereo2 in the PATCH1 and PATCH2 frames must be unselected.
    898 
    899     For PIV near a staigth wall, it is advised to create a grid for each image series, corresponding to a common array of physical positions. This can be done by the pusch button grid in uvmat (bottom right).
     655
     656  The images from each camera (camA and camB) must be in the same directory and the PIV results in a single subdirectory. It is advised to do the successive operations including civ2 and fix2. This double series of PIV processing can be done in two steps (keeping the same CIV subdirectory) or simulatenously, using the compare ('-') option.  Then the check boxed test_stereo1 and test_stereo2 in the PATCH1 and PATCH2 frames must be unselected.
     657
     658  For PIV near a staigth wall, it is advised to create a grid for each image series, corresponding to a common array of physical positions. This can be done by the pusch button grid in uvmat (bottom right).
    900659
    901660Combine PIV fields:  this is done by selecting PATCH1 and  test_stereo1 (at level civ1), or PATCH2 and  test_stereo2 (at level civ2) in the stereo mode (check box compare selected). The resulting fields camA-camB are in physical coordinates. They are final results which cannot be processed for further Civ operations: one must go back to the two image series for that purpose. Note that this stereo combination is only  possible in the RUN mode for the moment (no BATCH)**.
    902661
    903 [civdata<-]
    904 {===11.7 Description of the velocity files :===}
     662[civdata<-] {===11.7 Description of the velocity files :===}
    905663
    906664The 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.
    907665
    908 Several fields, corresponding to the successive operations 'civ1', 'fix1', 'patch1', 'civ2', 'fix2', 'patch2' are stored in the same .nc file.
    909 When a third or higher order civ iteration is performed, a new .nc file is created, containing the two last iterations as civ1 and civ2.
    910 
    911 -'''List of constants (global attributes):''',
    912  Conventions 'uvmat/civdata'.
    913 |  '''tag''' |  '''     content'''  |
    914 | Conventions| sets the conventions|
    915 |                Program|name of the processing program|
    916 |              CivStage| stage in the sequence civ1,fix1...|
    917 |         Civ1_TestCiv1| 0|
    918 |    Civ1_CorrBoxSize|size x,y of the correlation box|
    919 |  Civ1_SearchBoxSize| size x,y of the search box|
    920 |Civ1_SearchBoxShift| (optional) shift of the search box|
    921 |        Civ1_CorrSmooth| smooth parameter for the image corr|
    922 |                Civ1_Dx |grid mesh along x|
    923 |                Civ1_Dy| grid mesh along y|
    924 |         Civ1_CheckGrid| =1 if a grid file is used, default=0|
    925 |        Civ1_CheckMask| =1 if a mask file is used, default=0|
    926 |    Civ1_CheckThreshold| =0/1 image luminosity  threshold used |
    927 |         Civ1_FileTypeA| type of input file A, 'image', 'movie'...|
    928 |            Civ1_ImageA| path and name of input image A|
    929 |        Civ1_FileTypeB| type of input file A, 'image', 'movie'...|
    930 |            Civ1_ImageB|path and name of input  image B|
    931 |                Civ1_Dt| time interval for image pair|
    932 |              Civ1_Time| mean time for the image pair|
    933 |     Civ1_ImageBitDepth| nbre of grey level bits|
    934 |        Civ1_ImageWidth| nbre of pixels along x|
    935 |       Civ1_ImageHeight|  nbre of pixels along y|
    936 |       Civ1_FrameIndexA| frame index of image A in the series|
    937 |       Civ1_FrameIndexB|  frame index of image B in the series|
    938 |             Patch1_Rho| 10|
    939 |       Patch1_Threshold| threshold for the elimination of aberrant vectors|
    940 |       Patch1_SubDomain| estimated nbre of vectors in a subdomain|
    941 
     666Several fields, corresponding to the successive operations 'civ1', 'fix1', 'patch1', 'civ2', 'fix2', 'patch2' are stored in the same .nc file. When a third or higher order civ iteration is performed, a new .nc file is created, containing the two last iterations as civ1 and civ2.
     667
     668-'''List of constants (global attributes):''',
     669
     670  Conventions 'uvmat/civdata'.
     671
     672|  '''tag''' |  '''        content'''  | | Conventions| sets the conventions| |                Program|name of the processing program| |              CivStage| stage in the sequence civ1,fix1...| |         Civ1_TestCiv1| 0| |    Civ1_CorrBoxSize|size x,y of the correlation box| |  Civ1_SearchBoxSize| size x,y of the search box| |Civ1_SearchBoxShift| (optional) shift of the search box| |        Civ1_CorrSmooth| smooth parameter for the image corr| |                Civ1_Dx |grid mesh along x| |                Civ1_Dy| grid mesh along y| |         Civ1_CheckGrid| =1 if a grid file is used, default=0| |        Civ1_CheckMask| =1 if a mask file is used, default=0| |    Civ1_CheckThreshold| =0/1 image luminosity  threshold used | |         Civ1_FileTypeA| type of input file A, 'image', 'movie'...| |            Civ1_ImageA| path and name of input image A| |        Civ1_FileTypeB| type of input file A, 'image', 'movie'...| |            Civ1_ImageB|path and name of input  image B| |                Civ1_Dt| time interval for image pair| |              Civ1_Time| mean time for the image pair| |     Civ1_ImageBitDepth| nbre of grey level bits| |        Civ1_ImageWidth| nbre of pixels along x| |       Civ1_ImageHeight|  nbre of pixels along y| |       Civ1_FrameIndexA| frame index of image A in the series| |       Civ1_FrameIndexB|  frame index of image B in the series| |             Patch1_Rho| 10| |       Patch1_Threshold| threshold for the elimination of aberrant vectors| |       Patch1_SubDomain| estimated nbre of vectors in a subdomain|
    942673
    943674-'''List of variables:'''
     
    945676Conventions 'uvmat/civdata'.
    946677
    947 |  '''tag''' |  '''     content'''  |
    948 |                Civ1_X| x coordinates|
    949 |                Civ1_Y| y coordinates|
    950 |                Civ1_Z| z coordinates (for PIV in volume)|
    951 |                Civ1_U| x velocity component|
    952 |                Civ1_V| y velocity component|
    953 |                Civ1_W| z velocity component (if relevant)|
    954 |                Civ1_F| warning flag|
    955 |                Civ1_C| image correlation|
    956 |                Civ1_FF| error flag|
    957 |                Civ1_U_smooth| smoothed x velocity component|
    958 |                Civ1_V_smooth| smoothed y velocity component|
    959 |                Civ1_W_smooth| smoothed z velocity component|
    960 |                Civ1_SubRange| sub range bounds|
    961 |                Civ1_NbSites| nbre of tps sites in each sub-range|
    962 |                Civ1_Coord_tps| tps coordinates|
    963 |                Civ1_U_tps| tps weights for x vel component|
    964 |                Civ1_V_tps| tps weights for y vel component|
    965 |                Civ1_W_tps| tps weights for z vel component|
    966 
    967 -'''List of constants, old CIVx conventions):'''
    968 -* nb_coord: =2 for PIV in a plane, =3 for PIV in a volume.
    969 -* nb_dim: =2 for the usual 2 component PIV, =3 for 3 component PIV (stereoscopic or volume).
    970 -* constant_pixcm: =1 for a simple linear calibration provided by the scaling factors pixcmx and pixcmy, =0 otherwise.
    971 -* pixcmx: scale pixel/space unit (cm by default) along the x direction (only if constant_pixcm=1).
    972 -* pixcmy: scale pixel/space unit (cm by default) along the y direction (only if constant_pixcm=1)
    973 -* absolut_time_T0: time elapsed since the time origin of the series (the mean time for the two images of the pair is taken).
    974 -* dt: time interval between the two images of the pair.
    975 -* absolut_time_T0_2: same as absolute_time_T0 for the fields obtained by the second iteration (civ2), using a possibly different image pair.
    976 -* dt2: same as dt for the fields obtained by the second iteration (civ2).
    977 -* hart: =1 if the Hart option has been used for processing (see ref.???), =0 otherwise.
    978 -* civ: =1 if a civ1 operation has been performed (=0 if the field is not obtained from an image pair)
    979 -* fix: =1 if a fix1 operation has been performed,
    980 -* patch: =1 if a patch1 operation has been performed.
    981 -* civ2: =1 if a civ2 operation has been performed.
    982 -* fix2:=1 if a fix2 operation has been performed.
    983 -* patch2: =1 if a Patch2 operation has been performed.
    984 -* patch_nx: number of grid points in the x direction for the patch field
    985 -* patch_ny: number of grid points in the y direction for the patch field
    986 -* ro_patch: smoothing coefficient rho used for patch
    987 -* patch2_nx: number of grid points in the x direction for the patch2 field
    988 -* patch2_ny: number of grid points in the y direction for the patch2 field
    989 -* ro2_patch: smoothing coefficient rho used for patch2
    990 
    991 -'''List of field variables (old CIVx conventions):'''
    992 A set of velocity vectors is defined by a 1D array of position coordinates x, y, and z for 3D civ, and a corresponding array for each of the velocity components u, v, and w for 3C civ. The field is therefore defined on an arbitrary set of point, without restriction to a regular mesh. Additional arrays are used to keep track of the quality of the PIV process leading to each vector. The image correlation maximum is represented by vec_C (a real number between 0 and 1). A flag vec_F represents a warning on the vector quality (see the list of values below). Another flag FixFlag marks false vectors: FixFlag=0 for good vectors, and FixFlag is set to a non-zero value when it has been detected as false (using a 'fix' operation).
     678|  '''tag''' |  '''        content'''  | |                Civ1_X| x coordinates| |                Civ1_Y| y coordinates| |                Civ1_Z| z coordinates (for PIV in volume)| |                Civ1_U| x velocity component| |                Civ1_V| y velocity component| |                Civ1_W| z velocity component (if relevant)| |                Civ1_F| warning flag| |                Civ1_C| image correlation| |                Civ1_FF| error flag| |                Civ1_U_smooth| smoothed x velocity component| |                Civ1_V_smooth| smoothed y velocity component| |                Civ1_W_smooth| smoothed z velocity component| |                Civ1_SubRange| sub range bounds| |                Civ1_NbSites| nbre of tps sites in each sub-range| |                Civ1_Coord_tps| tps coordinates| |                Civ1_U_tps| tps weights for x vel component| |                Civ1_V_tps| tps weights for y vel component| |                Civ1_W_tps| tps weights for z vel component|
     679
     680-'''List of constants, old CIVx conventions):''' -* nb_coord: =2 for PIV in a plane, =3 for PIV in a volume. -* nb_dim: =2 for the usual 2 component PIV, =3 for 3 component PIV (stereoscopic or volume). -* constant_pixcm: =1 for a simple linear calibration provided by the scaling factors pixcmx and pixcmy, =0 otherwise. -* pixcmx: scale pixel/space unit (cm by default) along the x direction (only if constant_pixcm=1). -* pixcmy: scale pixel/space unit (cm by default) along the y direction (only if constant_pixcm=1) -* absolut_time_T0: time elapsed since the time origin of the series (the mean time for the two images of the pair is taken). -* dt: time interval between the two images of the pair. -* absolut_time_T0_2: same as absolute_time_T0 for the fields obtained by the second iteration (civ2), using a possibly different image pair. -* dt2: same as dt for the fields obtained by the second iteration (civ2). -* hart: =1 if the Hart option has been used for processing (see ref.???), =0 otherwise. -* civ: =1 if a civ1 operation has been performed (=0 if the field is not obtained from an image pair) -* fix: =1 if a fix1 operation has been performed, -* patch: =1 if a patch1 operation has been performed. -* civ2: =1 if a civ2 operation has been performed. -* fix2:=1 if a fix2 operation has been performed. -* patch2: =1 if a Patch2 operation has been performed. -* patch_nx: number of grid points in the x direction for the patch field -* patch_ny: number of grid points in the y direction for the patch field -* ro_patch: smoothing coefficient rho used for patch -* patch2_nx: number of grid points in the x direction for the patch2 field -* patch2_ny: number of grid points in the y direction for the patch2 field -* ro2_patch: smoothing coefficient rho used for patch2
     681
     682-'''List of field variables (old CIVx conventions):''' A set of velocity vectors is defined by a 1D array of position coordinates x, y, and z for 3D civ, and a corresponding array for each of the velocity components u, v, and w for 3C civ. The field is therefore defined on an arbitrary set of point, without restriction to a regular mesh. Additional arrays are used to keep track of the quality of the PIV process leading to each vector. The image correlation maximum is represented by vec_C (a real number between 0 and 1). A flag vec_F represents a warning on the vector quality (see the list of values below). Another flag FixFlag marks false vectors: FixFlag=0 for good vectors, and FixFlag is set to a non-zero value when it has been detected as false (using a 'fix' operation).
    993683
    994684The names of the fields (variables) resulting from each operation are given in the following table. Each column corresponds to an operation. 'filter1' and 'interp1' both result from the patch1 interpolation on the same points, with and without smoothing respectively. The first line is the name of the constant representing the number of vectors (the dimension of the arrays). The next successive lines indicate the variable names for the position and velocity components, the image correlation 'c', the 'flag' about civ quality and 'fix' flag (only available for civ1 and civ2), and the spatial derivatives obtained from the patch operations.
     
    996686-*Names of field variables for civ1 and patch1
    997687
    998 |   |  '''      civ1'''         | '''interp1'''  |      '''filter1 '''          |
    999 | dim.  |       nb_vectors  |   nb_vec_patch  | nb_vec_patch  |
    1000 |x      |vec_X          |vec_patch_X  | vec_patch_X |
    1001 |y      |       vec_Y  |        vec_patch_Y |   vec_patch_Y |
    1002 |z      |       vec_Z |         vec_patch_Z  |  vec_patch_Z |
    1003 |u              |vec_U |        vec_patch0_U  | vec_patch_U |
    1004 |v              |vec_V          |vec_patch0_V  |        vec_patch_V |
    1005 |w       |      vec_W   |vec_patch0_W|          vec_patch_W |
    1006 |correlation  | vec_C  |          |       |
    1007 |warning flag  |        vec_F |   |       |
    1008 |false flag  |  vec_FixFlag |     |       |
    1009 |du/dx  |        |vec_patch0_DUDX         |vec_patch_DUDX         |
    1010 |du/dy  |        |vec_patch0_DUDY         |vec_patch_DUDY         |
    1011 |dv/dx  |        |vec_patch0_DVDX         |vec_patch_DVDX         |
    1012 |dv/dy  |        |vec_patch0_DVDY         |vec_patch_DVDY         |
    1013 
     688|   |  '''        civ1'''          | '''interp1'''  |        '''filter1 '''          | | dim.  |        nb_vectors  |        nb_vec_patch  |        nb_vec_patch  | |x          |vec_X          |vec_patch_X  |        vec_patch_X | |y          |         vec_Y  |        vec_patch_Y |         vec_patch_Y | |z          |        vec_Z |         vec_patch_Z  |        vec_patch_Z | |u                  |vec_U |         vec_patch0_U  |        vec_patch_U | |v                   |vec_V          |vec_patch0_V  |        vec_patch_V | |w           |        vec_W          |vec_patch0_W|          vec_patch_W | |correlation  |        vec_C  |          |          | |warning flag  |        vec_F |          |          | |false flag  |        vec_FixFlag |          |          | |du/dx  |         |vec_patch0_DUDX          |vec_patch_DUDX          | |du/dy  |         |vec_patch0_DUDY          |vec_patch_DUDY          | |dv/dx  |         |vec_patch0_DVDX          |vec_patch_DVDX          | |dv/dy  |         |vec_patch0_DVDY          |vec_patch_DVDY          |
    1014689
    1015690-*Names of field variables for civ2 and patch2
    1016691
    1017 |   |  '''      civ2'''         | '''interp2'''  |      '''filter2 '''          |
    1018 | dim.  |       nb_vectors2  |  nb_vec2_patch  |        nb_vec2_patch  |
    1019 |x      |vec2_X         |vec2_patch_X  |        vec2_patch_X |
    1020 |y      |       vec2_Y  |       vec2_patch_Y |  vec2_patch_Y |
    1021 |z      |       vec2_Z |        vec2_patch_Z  | vec2_patch_Z |
    1022 |u              |vec2_U |       vec2_patch0_U  |        vec2_patch_U |
    1023 |v              |vec2_V         |vec2_patch0_V  |       vec2_patch_V |
    1024 |w       |      vec2_W          |vec2_patch0_W|         vec2_patch_W |
    1025 |correlation  | vec2_C  |         |       |
    1026 |warning flag  |        vec2_F |          |       |
    1027 |false flag  |  vec2_FixFlag |    |       |
    1028 |du/dx  |        |vec2_patch0_DUDX        |vec2_patch_DUDX        |
    1029 |du/dy  |        |vec2_patch0_DUDY        |vec2_patch_DUDY        |
    1030 |dv/dx  |        |vec2_patch0_DVDX        |vec2_patch_DVDX        |
    1031 |dv/dy  |        |vec2_patch0_DVDY        |vec2_patch_DVDY        |
    1032 
    1033 
    1034 
    1035 ----------------------------
    1036 ==12 Tridimensional features:(to update **)==
    1037 
    1038 
    1039 {=== 12-1 Multilevel image scanning===}
    1040 or multiplane scanning it also describes the set of laser planes. Then the current plane index is indicated by the text box z_index and the total number of planes by the text box nb_slice.
     692|   |  '''        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          |
     693
     694----
     695== 12 Tridimensional features:(to update **) ==
     696{=== 12-1 Multilevel image scanning===} or multiplane scanning it also describes the set of laser planes. Then the current plane index is indicated by the text box z_index and the total number of planes by the text box nb_slice.
    1041697
    1042698{=== 12-2 Volume image scanning===}
    1043699
    1044 
    1045 {=== 12-3 3D3C PIV :**===}
    1046 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}.
    1047 
    1048 -------------------------
     700{=== 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}.
     701
     702----
    1049703[editxml<-]
    1050 ==13 Editing xml files with the GUI editxml.fig:==
    1051 
    1052     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.
    1053 
    1054     When an input file is opened, editxml detects the title key, e.g. <ImaDoc>, and looks for the corresponding xml schema (e.g. {ImaDoc.xsd} ). This schema is sought  in the directory defined by <SchemaPath> in the installation file {PARAM.xml} of uvmat. If the schema is found, the hierarchical structure and keys given by the schema are diplayed.  Otherwise the  keys of the xml file are displayed.
    1055 
    1056     Simple elements in the xml file  are listed in the forme 'key'='value', and the corresponding attributes are shown in green. Comments from the schema are dispalyed in blue. Complex elements are indicated by '+'. Selecting them on the list gives access to the lower hierarchical level.  Press the  arrow '''[<---]''' to move back upward in the hierarchy.
    1057 
    1058      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.
    1059 
    1060 </math>
    1061 [overview<-]
    1062 ==Appendix: overview of the package:===
    1063 
    1064 ===Master GUI:===
    1065 
     704
     705== 13 Editing xml files with the GUI editxml.fig: ==
     706  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.
     707
     708  When an input file is opened, editxml detects the title key, e.g. <ImaDoc>, and looks for the corresponding xml schema (e.g. {ImaDoc.xsd} ). This schema is sought  in the directory defined by <SchemaPath> in the installation file {PARAM.xml} of uvmat. If the schema is found, the hierarchical structure and keys given by the schema are diplayed.  Otherwise the  keys of the xml file are displayed.
     709
     710  Simple elements in the xml file  are listed in the forme 'key'='value', and the corresponding attributes are shown in green. Comments from the schema are dispalyed in blue. Complex elements are indicated by '+'. Selecting them on the list gives access to the lower hierarchical level.  Press the  arrow '''[<---]''' to move back upward in the hierarchy.
     711
     712  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.
     713
     714</math> [overview<-]==Appendix: overview of the package:===
     715
     716=== Master GUI: ===
    1066717-'uvmat';...% master function for file scanning and visualisation of 2D fields
    1067718
    1068 ===Other GUIs:(function .m and associated figure .fig)===
    1069 
    1070 -'civ';...   %function associated with the interface 'civ.fig' for PIV and spline interpolation
    1071 -'create_grid';...% called by the GUI geometry_calib to create a physical grid 
    1072 - 'dataview';...% function for scanning directories in a campaign
    1073 -'editxml';...%display and edit xml files using a xls schema
    1074 -'geometry_calib';...%performs geometric calibration from a set of reference points
    1075 -'get_field';...% choose and plot a field from a Netcdf file
    1076 -'msgbox_uvmat';... associated with GUI msgbox_uvmat.fig to display message boxes, for error, warning or input calls
    1077 -'rotate_points';...%'rotate_points': associated with GUI rotate_points.fig to introduce (2D) rotation parameters
    1078 -'series';...% master function for analysis field series, with interface 'series.fig'
    1079 -'set_grid';...% creates a grid for PIV
    1080 -'set_object';...%  edit a projection object
    1081 -'translate_points';...% associated with GUI translate_points.fig to display translation parameters 
    1082 -'view_field';...% function for visualisation of projected fields'
    1083 
    1084 ===functions activated by mouse and keybord in GUI :===
    1085 -'keyboard_callback';... % function activated when a key is pressed on the keyboard
    1086 -'mouse_down';% function activated when the mouse button is pressed on a figure (callback for 'WindowButtonDownFcn')
    1087 -'mouse_motion';...% permanently called by mouse motion over a figure (callback for 'WindowButtonMotionFcn')
    1088 -'mouse_up';... % function to be activated when the mouse button is released (callback for 'WindowButtonUpFcn')
    1089    
    1090 === main functions used:===
    1091 -'civ_matlab';...% civ programs, Matlab version (called by civ.m, option Civprogram/Matlab in the upper menu bar)
    1092 -'plot_field';...%displays a vector field and/or scalar or images
    1093 -'plot_object';...%draws a projection object (points, line, plane...)
    1094 -'proj_field';...%project a field on a projection object (plane, line,...)
    1095 -'RUN_STLIN';...% combine 2 displacement fields for stereo PIV
    1096 -'sub_field';...% combine the two input fields,
    1097 
    1098 ===convert and I/O functions:===
    1099 -'cell2tab';... % transform a Matlab cell in a character array suitable for display in a table
    1100 -'fill_GUI';... % fill a GUI with handles 'handles' from input data Param
    1101 -'imadoc2struct';...% convert the image documentation file ImaDoc into a Matlab structure
    1102 -'nc2struct';...% transform a netcdf file in a corresponding matlab structure
    1103 -'num2stra';...% transform number to the corresponding character string depending on the nomenclature.
    1104 -'read_field':...% read the fields from files in different formats (netcdf files, images, video)
    1105 -'read_GUI'::...% read a GUI and provide the data as a Matlab structure
    1106 'read_image';... read images or video objects
    1107 -'read_multimadoc';... %read a set of Imadoc files and compare their timing of different file series
    1108 'read_xls';...%read excel files containing the list of the experiments
    1109 -'stra2num';...% transform letters (a, b, A, B,) or numerical strings ('1','2'..) to the corresponding numbers
    1110 -'struct2nc';...% write fields in netcdf files
    1111 -'struct2xml';... transform a matlab structure to a xml tree.
    1112 -'xml2struct'...% read an xml file as a Matlab structure, converts numeric character strings into numbers
    1113    
    1114 ===ancillary functions:===
    1115 -'calc_field';...% defines fields (velocity, vort, div...) from civx data (old conventions) and calculate them.
    1116 -'calc_field_interp': defines fields (velocity, vort, div...) from civ data and calculate them for projection with linear interpolation
    1117 -'calc_field_tps': defines fields (velocity, vort, div...) from civ data and calculate them with tps interpolation
    1118 -calc_tps': calculate the thin plate spline (tps) coefficients for interpolation
    1119 -'check_files';...% check the path, modification date and svn version for all the function in the toolbox UVMAT.
    1120 -'close_fig';...% function  activated when a figure is closed
    1121 -'copyfields';...% copy fields between two matlab structures
    1122 -'delete_object';...%delete a projection object, defined by its index in the Uvmat list or by its graphic handle
    1123 'fileparts_uvmat': splits a file name in root and indices and recognize file naming convention
    1124 -'filter_tps';...% find the thin plate spline coefficients for interpolation-smoothing
    1125 -'find_field_cells';...% group the variables of a nc-formated Matlab structure into 'fields' with common dimensions
    1126 -find_field_cells': test field structure for input in proj_field and plot_field, group the variables  into 'fields' with common dimensions
    1127 -'find_file_series';...%check the content of an input file and find the corresponding file series
    1128 -'fullfile_uvmat';...%creates a file name from a root name and indices.
    1129 -'get_file_type': determine info about a file (image, multimage, civdata,...)
    1130 -'griddata_uvmat';...%make 2D linear interpolation using griddata, with input appropriate for both Matlab 6.5 and 7
    1131  -'hist_update';...%  update of a current global histogram by inclusion of a new field
    1132 -'ListDir';... scan the structure of the directory tree (for dataview.m)
    1133 -'open_uvmat';...% open with uvmat the  field selected in the list of 'civ/status' or 'series/check_data_files'
    1134 -'peaklock';...%
    1135 -'phys_XYZ';...% transform coordiantes from pixels to phys
    1136 -'px_XYZ';...% transform coordiantes from phys to pixels 
    1137 -'read_civxdata';...reads civx data from netcdf files
    1138 -'read_civdata';... reads new civ data from netcdf files
    1139 -'read_get_field';... read the list of selected variables from the GUI get_field (TODO: use read_GUI)
    1140 -'read_imatext';...%read .civ files (obsolete, but can be adapted to other text documentation files)
    1141 -'read_xls';...%read excel files containing the list of the experiments
    1142 -'reinit';...% suppress the personal parameter file 'uvmat_perso.mat'
    1143 -'set_col_vec';...% sets the color code for vectors depending on a scalar and input parameters (used for plot_field)
    1144 -'tps_coeff';...% calculate the thin plate spline (tps) coefficients
    1145 -'tps_eval';... %calculate the thin plate spline (tps) interpolation at a set of points
    1146 -'tps_eval_dxy';...% calculate the derivatives of thin plate spline (tps) interpolation at a set of points (limited to the 2D case)
    1147 -'update_imadoc';...  %update the ImaDoc xml file
    1148 -'update_obj';... update the object representation graph and its projection field, record it in the uvmat interface
    1149 -'update_waitbar';... update the waitbar display, used for ACTION functions in the GUI 'series'
    1150 -'write_plot_param'...%update plotting parameters after plot, TODO: change into a general function: fill_GUI
    1151    
    1152 ===series functions===
    1153 -'aver_stat': calculate field average over a time series
    1154 -'avi2png': copy an avi movie to a series of B/W .png images (take the average of green and blue color components)
    1155 -'check_data_files': check the existence, type and status of the files selected by series.fig
    1156 -'merge_proj': concatene several fields from series, can project them on a regular grid in phys coordinates
    1157 -'sub_background': subtract a sliding background to an image series
    1158 -'time_series': extract a time series after projection on an object (points , line..)
    1159 
    1160 ===transform functions===
    1161 - 'ima_filter': low-pass filter of an image (builtin filtering parameter)
    1162 - 'ima_remove_background': removes backgound from an image (using the local minimum)
    1163 - 'ima_remove_particles': removes particles from an image (keeping the local minimum)
    1164 - 'FFT2_detrend': calculate the 2D spectrum of the input scalar after removing the linear trend (requires the Matlab image processing toolbox).
    1165 -'phys': transforms image (Unit='pixel') to real world (phys) coordinates using geometric calibration parameters. It acts if the input field contains the tag 'CoordUnit' with value 'pixel'
    1166 -'phys_polar': this transforms the fields to polar coordinates, radius in abscissa (same unit as x, y) and azimuth in ordinate (unit =degree).
     719=== Other GUIs:(function .m and associated figure .fig) ===
     720-'civ';...   %function associated with the interface 'civ.fig' for PIV and spline interpolation -'create_grid';...% called by the GUI geometry_calib to create a physical grid   - 'dataview';...% function for scanning directories in a campaign -'editxml';...%display and edit xml files using a xls schema -'geometry_calib';...%performs geometric calibration from a set of reference points -'get_field';...% choose and plot a field from a Netcdf file -'msgbox_uvmat';... associated with GUI msgbox_uvmat.fig to display message boxes, for error, warning or input calls -'rotate_points';...%'rotate_points': associated with GUI rotate_points.fig to introduce (2D) rotation parameters -'series';...% master function for analysis field series, with interface 'series.fig' -'set_grid';...% creates a grid for PIV -'set_object';...%  edit a projection object -'translate_points';...% associated with GUI translate_points.fig to display translation parameters   -'view_field';...% function for visualisation of projected fields'
     721
     722=== functions activated by mouse and keybord in GUI : ===
     723-'keyboard_callback';... % function activated when a key is pressed on the keyboard -'mouse_down';% function activated when the mouse button is pressed on a figure (callback for 'WindowButtonDownFcn') -'mouse_motion';...% permanently called by mouse motion over a figure (callback for 'WindowButtonMotionFcn') -'mouse_up';... % function to be activated when the mouse button is released (callback for 'WindowButtonUpFcn')
     724
     725=== main functions used: ===
     726-'civ_matlab';...% civ programs, Matlab version (called by civ.m, option Civprogram/Matlab in the upper menu bar) -'plot_field';...%displays a vector field and/or scalar or images -'plot_object';...%draws a projection object (points, line, plane...) -'proj_field';...%project a field on a projection object (plane, line,...) -'RUN_STLIN';...% combine 2 displacement fields for stereo PIV -'sub_field';...% combine the two input fields,
     727
     728=== convert and I/O functions: ===
     729-'cell2tab';... % transform a Matlab cell in a character array suitable for display in a table -'fill_GUI';... % fill a GUI with handles 'handles' from input data Param  -'imadoc2struct';...% convert the image documentation file ImaDoc into a Matlab structure -'nc2struct';...% transform a netcdf file in a corresponding matlab structure -'num2stra';...% transform number to the corresponding character string depending on the nomenclature. -'read_field':...% read the fields from files in different formats (netcdf files, images, video) -'read_GUI'::...% read a GUI and provide the data as a Matlab structure 'read_image';... read images or video objects -'read_multimadoc';... %read a set of Imadoc files and compare their timing of different file series 'read_xls';...%read excel files containing the list of the experiments -'stra2num';...% transform letters (a, b, A, B,) or numerical strings ('1','2'..) to the corresponding numbers -'struct2nc';...% write fields in netcdf files -'struct2xml';... transform a matlab structure to a xml tree. -'xml2struct'...% read an xml file as a Matlab structure, converts numeric character strings into numbers
     730
     731=== ancillary functions: ===
     732-'calc_field';...% defines fields (velocity, vort, div...) from civx data (old conventions) and calculate them. -'calc_field_interp': defines fields (velocity, vort, div...) from civ data and calculate them for projection with linear interpolation -'calc_field_tps': defines fields (velocity, vort, div...) from civ data and calculate them with tps interpolation -calc_tps': calculate the thin plate spline (tps) coefficients for interpolation -'check_files';...% check the path, modification date and svn version for all the function in the toolbox UVMAT. -'close_fig';...% function  activated when a figure is closed -'copyfields';...% copy fields between two matlab structures -'delete_object';...%delete a projection object, defined by its index in the Uvmat list or by its graphic handle 'fileparts_uvmat': splits a file name in root and indices and recognize file naming convention -'filter_tps';...% find the thin plate spline coefficients for interpolation-smoothing -'find_field_cells';...% group the variables of a nc-formated Matlab structure into 'fields' with common dimensions -find_field_cells': test field structure for input in proj_field and plot_field, group the variables  into 'fields' with common dimensions -'find_file_series';...%check the content of an input file and find the corresponding file series -'fullfile_uvmat';...%creates a file name from a root name and indices. -'get_file_type': determine info about a file (image, multimage, civdata,...) -'griddata_uvmat';...%make 2D linear interpolation using griddata, with input appropriate for both Matlab 6.5 and 7
     733
     734  -'hist_update';...%  update of a current global histogram by inclusion of a new field
     735
     736-'ListDir';... scan the structure of the directory tree (for dataview.m) -'open_uvmat';...% open with uvmat the  field selected in the list of 'civ/status' or 'series/check_data_files' -'peaklock';...% -'phys_XYZ';...% transform coordiantes from pixels to phys -'px_XYZ';...% transform coordiantes from phys to pixels   -'read_civxdata';...reads civx data from netcdf files -'read_civdata';... reads new civ data from netcdf files -'read_get_field';... read the list of selected variables from the GUI get_field (TODO: use read_GUI) -'read_imatext';...%read .civ files (obsolete, but can be adapted to other text documentation files)  -'read_xls';...%read excel files containing the list of the experiments -'reinit';...% suppress the personal parameter file 'uvmat_perso.mat' -'set_col_vec';...% sets the color code for vectors depending on a scalar and input parameters (used for plot_field) -'tps_coeff';...% calculate the thin plate spline (tps) coefficients -'tps_eval';... %calculate the thin plate spline (tps) interpolation at a set of points -'tps_eval_dxy';...% calculate the derivatives of thin plate spline (tps) interpolation at a set of points (limited to the 2D case) -'update_imadoc';...  %update the ImaDoc xml file -'update_obj';... update the object representation graph and its projection field, record it in the uvmat interface -'update_waitbar';... update the waitbar display, used for ACTION functions in the GUI 'series' -'write_plot_param'...%update plotting parameters after plot, TODO: change into a general function: fill_GUI
     737
     738=== series functions ===
     739-'aver_stat': calculate field average over a time series -'avi2png': copy an avi movie to a series of B/W .png images (take the average of green and blue color components) -'check_data_files': check the existence, type and status of the files selected by series.fig -'merge_proj': concatene several fields from series, can project them on a regular grid in phys coordinates -'sub_background': subtract a sliding background to an image series -'time_series': extract a time series after projection on an object (points , line..)
     740
     741=== transform functions ===
     742- 'ima_filter': low-pass filter of an image (builtin filtering parameter) - 'ima_remove_background': removes backgound from an image (using the local minimum) - 'ima_remove_particles': removes particles from an image (keeping the local minimum) - 'FFT2_detrend': calculate the 2D spectrum of the input scalar after removing the linear trend (requires the Matlab image processing toolbox). -'phys': transforms image (Unit='pixel') to real world (phys) coordinates using geometric calibration parameters. It acts if the input field contains the tag 'CoordUnit' with value 'pixel' -'phys_polar': this transforms the fields to polar coordinates, radius in abscissa (same unit as x, y) and azimuth in ordinate (unit =degree).