Changes between Initial Version and Version 1 of UvmatHelp


Ignore:
Timestamp:
Jun 1, 2013, 2:59:30 PM (8 years ago)
Author:
sommeria
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UvmatHelp

    v1 v1  
     1== 1 Generalities==
     2=== 1.1 Aim===
     3
     4 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.
     5
     6    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.
     7
     8        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]. 
     9
     10=== 1.2 The package===
     11
     12      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).
     13
     14-'''browse_data.fig''' scans the data directory of a project
     15- '''civ.fig:''' runs the software for Particle Imaging Velocimetry
     16- '''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.
     17- '''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.
     18- '''get_field.fig:''' selects coordinates and field in a general NetCDF file. The subdirectory /get_field contains functions called by the GUI get_field.
     19- '''series.fig:''' apply various processing functions to series of fields. These functions are stored in the subdirectory /series.
     20-'''set_object.fig:''' creates and edits geometric objects used to project data: points, lines, planes...
     21-'''view_field.fig:''' is a GUI complementing uvmat for plotting projected data.
     22    Functions in the package are used to generate file names, read files and plot data, and perform various ancillary tasks.
     23
     24=== 1.3 Documentation and help=== 
     25        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.
     26         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 **.
     27
     28        Information is also provided as comments in each function. Type '>>help fct_name'  to get it, or open it with an editor.
     29
     30        Finally a on-line [tutorial->105] is also provided with test images and data files.
     31
     32=== 1.4 Copyright and licence===
     33Copyright Joel Sommeria, 2008, LEGI / CNRS-UJF-INPG, joel.sommeria@legi.grenoble-inp.fr.
     34
     35        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.
     36
     37        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.
     38
     39[<doc115|right>->#top]
     40------------------
     41[2-The GUI uvmat.fig<-]
     42== 2 Overview of the GUI uvmat.fig===
     43
     44=== 2.1 Opening the GUI===
     45
     46    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).
     47
     48<img55|center>
     49
     50The GUI contains an upper menu bar, a central display window, a lower left window for histogram, edit boxes and command buttons.
     51
     52Each 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_'.
     53
     54The red pushbuttons command the main actions. Their color changes to yellow while they are active. 
     55
     56=== 2.2 The menu bar===
     57The menu bar at the top of the GUI contains the following buttons:
     58-'''[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.
     59-*'''[browse...]''': usual file browser
     60-*'''[browse campaign...]''':  scan the data organised as a project/campaign, see [section 3.7->#sec3.7].
     61
     62-'''[Open_1] ''': used like '''[Open]''' to select a second field, for comparisons with the main one.
     63
     64-'''[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). 
     65
     66-'''[Projection object] ''': used to create projection objects (points, lines, patches, gridded planes) for data analysis and interpolation
     67
     68-'''[Edit] ''': used to edit projection objects or individual vectors in data fields.
     69
     70-'''[Tools]''':
     71-*'''[Geometric calibration]''':  for geometric calibration of images
     72-*'''[LIF calibration]''':  calibration of images for Laser Induced Fluorescence
     73-*'''[Make mask]''': for creating mask images (for PIV)
     74-*'''[Make grid]:''': for making measurement grids for PIV
     75-*'''[ruler]''': displays a ruler to measure lengths and angles of any line.
     76
     77-'''[Run] ''':
     78-*'''[Field series]''': gives access to the GUI '''series.fig''' for analysis of field series
     79-*'''[PIV(CIV)]''':  gives access to the GUI '''civ.fig''' for Particle Imaging Velocimetry
     80
     81-'''[Help] ''': displays the html help file
     82
     83<doc58|center>
     84
     85=== 2.3 Displaying the input file name===
     86
     87 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.
     88
     89    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.
     90
     91When 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).
     92
     93-'''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.
     94 
     95=== 2.4 General tools===
     96
     97-'''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.
     98
     99-'''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.
     100
     101-'''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]'''.
     102
     103-'''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.
     104
     105-'''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].
     106
     107-'''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.
     108
     109[<doc115|right>->#top]
     110
     111------------------
     112[3-Input files and navigation with uvmat<-]
     113== 3 Input files and navigation with uvmat===
     114
     115[sec3.1<-]
     116=== 3.1  Input data formats===
     117uvmat 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.
     118
     119Velocity 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}.
     120
     121The PIV software CIVx requires B&W images in the format png (portable network graphics). It is a binary format for images with lossless (reversible) compression, recommended by w3c ([->http://www.w3.org/Graphics/PNG] ). It is an open source patent-free replacement of GIF and can also replace many common uses of TIFF. It can be read directly by all standard programs of image visualisation and processing.  Compressing a raw binary image to its c png form typically saves disk storage by a factor of 3.
     122
     123For 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).
     124
     125=== 3.2 Selecting fields from CIV :===
     126
     127 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].
     128
     129<doc71|center>
     130
     131When 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.
     132
     133The 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.
     134
     135The 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.
     136
     137=== 3.3 File naming and indexing===
     138
     139    Different kinds of file or image frame indexing are defined:
     140
     141-'''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.
     142
     143-'''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. 
     144
     145-'''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.
     146Other 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.
     147
     148-'''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.
     149
     150[sec3.4<-]
     151=== 3.4 Navigation among file indices:===
     152
     153    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]'''.
     154
     155<doc65|center>
     156
     157 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.
     158
     159    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).
     160
     161The maximum  value detected for each index is indicated by the boxes '''[last_i]''' and '''[last_j] ''' respectively.
     162
     163-'''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]'''.
     164
     165-'''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.
     166
     167-'''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.
     168
     169
     170[sec3.5<-]
     171=== 3.5  Image documentation files (.xml):===
     172
     173Information 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].
     174
     175When 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.
     176
     177 The xml file <code><ImaDoc> </code> can contain the following sections:
     178
     179-<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.
     180-<code><Camera></code> contains information on the camera settings, as well as the timing of all the images in a subsection <code><BurstTiming></code>.
     181-<code><TranslationMotor></code> and <code><Oscillator></code> contains information on the mechanical devices used to produce the laser sheet and scan volumes.
     182-<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.
     183-<code><Illumination></code> describes the illumination system used, including the position of the laser source.
     184-<code><Tracor></code> describes the properties of the flow tracor (particle, dye...)
     185-<code><ImageTransform></code> describes  the image processing which may have been performed.
     186
     187The 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]).
     188
     189=== 3.6 Ancillary input files:===
     190[sec3.6_mask<-]
     191-''' 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 :
     192-* Intensity < 20: ('black mask') the vector in this place will be set to zero
     193-*  20 < Intensity < 200:('gray mask') the vector in this place will be absent
     194-*  Intensity>200  the vector will be computed
     195_ .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.
     196
     197[sec3.6_grid<-]
     198-''' Grid:'''
     199List 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
     200<cadre>
     201n
     202X1 Y1
     203X2 Y2
     204......
     205Xn Yn
     206</cadre>
     207The 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].
     208
     209-'''.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'''.
     210
     211[sec3.6_civ<-]
     212-''''.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}).
     213-*Example :
     214%... gives comments (not included in the file).
     215This 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.
     216<cadre>
     21719                                      % number of bursts
     2181024 1024                       % image size npx npy
     2194                                      % number of images per burst
     2202                                      % not used
     2210.016667                          % time of exposure (in seconds)
     2225.860000 5.860000           % scaling pixel/cm x and y directions
     2235.860000 5.860000           % same
     2240                                      % not used
     2251 0.000000 30 60 30 1
     2262 25.001003 30 60 30 1
     227.........................
     22818 424.999847 30 60 30 1
     22919 450.000824 30 60 30 1
     230% for each line:
     231burst 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.
     232</cadre>
     233
     234-'''.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.
     235
     236-'''.log''' ascii text files, containing information about the CIV or PATCH processing. Each velocity field named *.nc is associated with a  file *.log. A file *_patch.log is similarly produced by the ’patch’ program.  These files can be opened by the browser of '''uvmat.fig'''.
     237
     238[sec3.7<-]
     239=== 3.7 Data organisation in a  project:===
     240The package is designed to foster a good data organisation. The raw data from a project should be organised as
     241Project/Campaign/Experiment/DataSeries/data files.
     242
     243-'Project': contains all information from a project.
     244-'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'.
     245-'Experiment' is a directory containing all the data for a particular experiment, defined by a choice of values for the physical parameters.
     246-'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.
     247
     248'''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'.
     249
     250[<doc115|right>->#top]
     251
     252------------------
     253
     254== 4 Field display: ===
     255
     256   The uvmat interface primarily reads and visualises two-dimensional fields, which can be images or scalars, or vector fields.
     257
     258=== 4.1  Images and scalars:===
     259
     260    Images are matrices of integers, visualised by the Matlab function  {imagesc.m}.
     261
     262    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.
     263
     264<doc64|center>
     265
     266    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]'''.
     267
     268    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.
     269
     270  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. 
     271
     272Scalar 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).
     273
     274Scalars (or image intensity) can be also represented with contour plots, by switching the popup menu '''[Contours] ''' from the setting 'mage' to the setting 'contours'. Contours for positive scalar values are in sold line while contours for negative values are dashed. The interval between contours can be set by the edit box '''[IncrA]'''.
     275
     276[sec4.2<-]
     277=== 4.2 Vectors:===
     278
     279    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]'''.
     280
     281Each 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.
     282
     283<doc63|center>
     284
     285-'''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]'''.
     286
     287-'''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]'''.
     288
     289-'''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:
     290-*'rgb':  color ranging from red, for the scalar value set by '''[num_MinVec]''', to blue, for the scalar value set by  '''[num_MaxVec]'''. The
     291color 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.
     292-*'black' or 'white': set the color for all vectors
     293-*'brg': same as rgb but in reverse order, with blue for the lowest scalar values.
     294-*'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]'''.
     295
     296-'''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
     297-* fist line: the position coordinates x, y, (z for 3D cases).
     298-* second line: the vector components
     299-* 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].
     300
     301-'''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]'''.
     302
     303=== 4.3 Histograms===
     304
     305Histograms of the input fields are represented on the bottom left. The choice of the variable is done by the menu '''[histo1_menu]'''.
     306
     307 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.
     308
     309=== 4.4 Comparing two fields===
     310
     311    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]''').
     312
     313    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.
     314
     315    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.
     316
     317The 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.
     318If 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.
     319
     320The second field can be removed by unselecting the check box '''[SubField] ''' on the very right.
     321
     322[sec4.5<-]
     323===  4.5 Field transforms:===
     324A 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].
     325
     326These 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
     327DataOut=transform_fct(DataIn,XmlData,DataIn_1,XmlData_1)
     328where 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].
     329
     330===  4.6 Succession of operations:===
     331
     332The following succession of operations is performed by '''uvmat.fig''':
     333-'''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.
     334-'''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).
     335-'''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.
     336-'''Histogram:''' This is obtained from the input field in transformed coordinates, or if applicable from the fields resulting from the two input fields.
     337-'''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}.
     338-'''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}.
     339-'''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.
     340-'''Plotting:''' plot the results of projection. Function used: {plot_field.m}
     341
     342[<doc115|right>->#top]
     343
     344----------------
     345[field_structures<-]
     346'''{5- Field objects:===
     347
     348[sec5.1<-]
     349=== 5.1 Griding of data:===
     350<math>
     351Physical 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:
     352
     353-'''Regular grid:'''
     354           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.
     355         
     356-'''Structured orthogonal grid''':
     357             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).
     358
     359-'''Unstructured coordinates:'''
     360           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. 
     361
     362-'''Thin plate shell (tps) interpolation:'''
     363          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].
     364$$\label{sol_gene}
     365f({\bf r})=\sum S_i \phi({\bf|r-r_i}|)+a_0+a_1x+a_2y\;
     366$$
     367where {\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.
     368
     369Because 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.
     370
     371[sec5.2<-]
     372=== 5.2 Field representation as Matlab structure:===
     373
     374The 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.
     375
     376Data 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.
     377
     378This 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.
     379
     380In summary, the {field object} is specified by a structure with the following elements:
     381-*(optional) .ListGlobalAttribute: list (cell array of character strings) of the names of global attributes  Att_1, Att_2...
     382-* (mandatory) .ListVarName: list of the variable names Var_1, Var_2....(cell array of character strings).
     383-* (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.
     384-* (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).
     385-* .Att_1, Att_2... : values of the listed global attributes.
     386-* .Var_1, .Var_2....: variables arrays whose  names are listed in .ListVarName
     387
     388In 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.
     389-* .ListDimName: list of dimension names (cell array of character strings)
     390-* .DimValue: array of dimension values corresponding to LisDimName.
     391
     392The following temporary information is added to manage projection and field substraction oerations, which must be done in general after projection:
     393-* 'FieldRequest': 'interp_lin', 'interp_tps' indicate whether lin interpolation  or derivatives by tps is needed to calculate the requested field.
     394-* 'Operation': name (char string) of the operation to be performed to finalise the field cell after projection.
     395-* 'SubCheck' 0 /1 indicate that the field must be substracted (second  entry in uvmat)
     396
     397Any other element can be added, but will not be taken into account if they are not listed in  .ListGlobalAttribute or .ListVarName.
     398
     399[sec5.3<-]
     400=== 5.3 Conventions for attributes in field objects:===
     401-'''Global attributes active in uvmat'''
     402Those are used for plot settings or data processing.
     403-*'Conventions':
     404   ='uvmat': indicate that the conventions described here are followed
     405  ='uvmat/civdata': indicate that the variables are named according to  [CIV data description->#civdata].
     406-*'CoordMesh': typical mesh for coordinates, used to define default projection grids and mouse selection action. Calculated automatically from the data if not specified.
     407-*'CoordUnit': character string representing the unit for space coordinates. It is used to distinguish image coordinates (CoordUnit='pixel') and physical (for instance
     408CoordUnit='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).
     409-*Dt: time interval for CIV data. It is used for calibration, to transform displacement into velocity.
     410-*Time: real number indicating the time of the field, used to obtain time series from data sets.
     411-*TimeUnit: character string representing the unit of time (consistently for Time, Dt and velocity).
     412
     413-'''Global attributes , unactive'''
     414those are merely used for information purpose
     415-*Project: recalls the project name
     416-*Campaign: recalls the campaign name
     417-*Experiment:  recalls the experiment name(s) of the raw data -*DataSeries:  recalls the device name (s), if defined, of the raw data 
     418-*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.
     419-*ObjectCoord:  Coordinates defining a geometric object on which the data have been projected.
     420-*ObjectRangeX, ObjectRangeY, ObjectRangeZ : range of action of a projection object along each coordinate, see section 6. 
     421-* '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.
     422
     423-'''Attributes of variables:'''
     424-* Mesh: suggested step value to discretize the values of the variable, used to define the bins for histograms.
     425-* 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'.
     426-* 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).
     427
     428-'''The attribute 'Role':'''
     429The following options are used for the attribute 'role':
     430-* 'ancillary': information of secondary use, indicating for instance an error estimate of field variables within a field cell (omitted in plotting)
     431-* '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.
     432-* 'coord_tps': coordinates of thin plate shell (tps) centres used for spline interpolation.
     433-* 'discrete': field with discrete values (no spatial interpolation), repesented with dots (no line) in 1D plots.
     434-* '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.
     435-* 'grad_x', 'grad_y', 'grad_z'  :represents the x, y or z  component of a contravariant vector** (like gradients).
     436-* 'image_rgb': represents a color image. The last dimension of the array corresponds to the three color components 'rgb'.
     437-* 'scalar': (default) represents a scalar field
     438-* 'tensor': represents a tensor field whose components correspond to the two last   dimensions of the array.**
     439-* vector: matrix whose last dimension states for the vector components.**
     440-* 'vector_x', 'vector_y', 'vector_z'  : represents the x, y or z  component of a vector (covariant)
     441-* 'warnflag': provides a warning flag about the quality of data for the field variables within a field cell., default=0, no warning.
     442
     443=== 5.4 Field cells:===
     444The 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.
     445
     446-*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.
     447-* 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.
     448-* 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).
     449-* Thin plate shell (tps) field cell: represents a set of coordinates and tps weights in  a way suitable for tps interpolation/filter.
     450
     451The 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: 
     452-* coord_1,_2,_3: dimension with the same name as a coordinate variable array (coordinate dimension)
     453-* 'nb_coord': denotes the space dimension for vector components
     454-* 'nb_coord_j', 'nb_coord_i': denotes the space dimensions for the two tensor components
     455-*  'rgb' : denotes the diemension of the color component in a true color  image.
     456-*  'nb_point' or 'nb_vec' (for vectors) denotes the set of positions with unstructured coordinates.
     457-* 'nb_tps': diemension of the index for the tps centres
     458-* 'nb_subdomain' denotes the dimension for the subdomain index for tps coefficients
     459
     460[<doc115|right>->#top]
     461
     462------------------------
     463[set_object<-]
     464'''{6- Projection objects:===
     465
     466=== 6.1 Definition and editing with the uvmat interface:===
     467
     468    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...'. 
     469
     470 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'''.
     471
     472The 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.
     473
     474<doc69|center>
     475
     476[sec6.2<-]
     477=== 6.2 Object properties:===
     478
     479    The objects are defined by the following set of properties:
     480-''' {Name:} ''' any name given to the object
     481-''' {Type:} ''' classify the object with the following choice:
     482-*'points': set of n points
     483-*'line': simple straight segment, defined by its two end points
     484-*'polyline': open line made of n-1 consecutive segments (defined by n points)
     485-*'rectangle': defined by its center, half width and half height.
     486-* 'polygon': closed line made of n consecutive segments (defined by n points)
     487-*'ellipse': defined by its center, half width and half height.
     488-*'plane': plane with associated cartesian coordinates
     489-*'volume': volume with associated cartesian coordinates
     490
     491-''' {ProjMode:} ''': specifies the method of projection of coordinates and field. 
     492
     493-''' {Angle:} ''': three component rotation vector used to define the orientation, for instance for planes.
     494
     495-''' {RangeX:} ''', ''' {RangeY:} ''', ''' {RangeZ:} ''':bounds defining the range of projection along each coordinate, one or two values depending on the object type.
     496
     497-''' {DX:} ''', ''' {DY:} ''', ''' {DZ:} ''':meash  along each coordinate defining a grid for interpolation.
     498
     499-''' {Coord:} ''': matrix with two (for 2D fields) or three columns defining the object position.
     500-*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.
     501-*for 'rectangle', 'ellipse': coordinates of the center.
     502-*for 'plane' or 'volume': coordinates of the origin of the new coordinate frame attached to the object.
     503
     504-''' {CoordUnit:} ''' units for the coordinates, must fit with the units of coordinates for the projected field.
     505
     506[sec6.3<-]
     507=== 6.3 Projection modes:===
     508Each 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. 
     509 
     510-''' {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).
     511
     512-''' {ProjMode 'interp':} ''' 
     513Linear 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.
     514
     515-''' {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. 
     516
     517-''' {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.
     518
     519-''' {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]).
     520
     521
     522[sec6.4<-]
     523=== 6.4 Projected fields:===
     524
     525The 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'''.
     526
     527-''' {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.
     528-*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.
     529-*ProjMode= 'interp':   U(i),i=1 is obtained as a linear interpolation on each point.
     530
     531-''' {Projection on open lines:} ''' 
     532This 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**.
     533-*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.
     534-* ProjMode='interp':
     535 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.
     536-* ProjMode='filter':
     537same as 'interp' but with a smoothing operation.
     538 
     539-''' {Projection on closed lines:} '''  ,
     540This 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.
     541
     542-''' {Projection on planes:}  '''
     543Data 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.
     544-*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).
     545-* ProjMode='interp':
     546 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.
     547
     548-''' {Projection on volumes:**}  '''
     549This is used to delimitate a volume for 3D representation
     550
     551[sec6.5<-]
     552=== 6.5 Object representation:===
     553
     554Projections objects are drawn in magenta color when they are selected for creation or edition, and in blue otherwise.
     555
     556-* 'points' are represented by dots surrounded by a dashed circle showing the range of projection.
     557-* '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').
     558-* '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).
     559-* '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. **
     560-* 'volume' are shown like 'plane', except that they are painted in magenta (or blue) **
     561
     562-''' {Creating and editing objects with the mouse:} '''
     563     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.
     564-*'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.
     565-*'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').
     566-*'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.
     567-*'rectangle': defined by its center, half width and half height.
     568-*'polygon': closed line made of n consecutive segments (defined by n points)
     569-*ellipse: defined by its center, half width and half height.
     570-*plane: plane with associated cartesian coordinates
     571-*volume: volume with associated cartesian coordinates
     572
     573[<doc115|right>->#top]
     574
     575----------------
     576[get_field<-]
     577'''{7- Netcdf files and get_field.fig:===
     578[netcdf<-]
     579=== 7.1 The NetCDF format:===
     580
     581NetCDF (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.
     582
     583    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.
     584
     585    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.
     586
     587The NetCDF data model consists of variables, dimensions, and attributes.
     588
     589-'''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.
     590
     591-'''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. 
     592
     593-'''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.
     594
     595    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.
     596
     597    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).
     598
     599    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.
     600
     601    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.
     602
     603
     604=== 7.3 The GUI get_field:===
     605
     606    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.   
     607
     608<doc62|center>
     609
     610      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.
     611
     612    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.
     613
     614 -'''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.
     615
     616-'''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.
     617
     618-'''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.
     619
     620-'''Automatic opening''':
     621When an input file is opened a default plotting option is proposed.
     622
     623 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.
     624
     625--------------------------------------
     626[geometry_calib<-]
     627'''{8- Geometric calibration:===
     628
     629=== 8.1 Generalities:===
     630
     631    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:
     632
     633-''' {'rescale'} ''': linear rescaling along x and y + translation (no rotation nor deformation)
     634
     635-''' {'linear'} ''': general linear transform, including translation and rotation (but no perspective effects)
     636
     637-''' {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.
     638
     639    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'''.
     640
     641<doc68|center>
     642
     643=== 8.2 The GUI geometry_calib.fig}:===
     644
     645-''' {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'''.
     646
     647-''' {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''' .
     648
     649-''' {Appending  calibration points with the mouse:} '''
     650Calibration 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).
     651
     652-''' {Editing the  coordinates:} '''
     653    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. 
     654
     655-''' {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]'''.
     656
     657-''' {Detecting a physical grid:} ''' This tool '''[Tools/Detect grid]''' provides the same result as '''[Tools/Create grid]''', but it automatically recognises the grid points on the image, provided the four corners of the grid have been previously selected by the mouse. The calibration points are detected either as image maxima (option 'white markers'), or as black crosses (option 'black markers'). Their position can be adjusted by selection with the mouse.
     658
     659-''' {Translation and rotation of calibration points:} '''
     660    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]'''.
     661
     662-''' {Recording calibration parameters:} '''
     663    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]'''.
     664
     665      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.
     666
     667        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'''.
     668
     669===8.3 Structure of the xml file:===
     670    The coefficients are recorded in the xml element <code><ImaDoc/GeometryCalib></code> as follows:
     671-<code><CalibrationType></code>: type of calibration ('rescale', 'linear', '3D...')
     672-<code><fx_fy></code>: focal length along each coordinate of the image sensor, expressed in pixel interval.
     673-<code><Cx_Cy></code>: position coordinates of the optical axis on the
     674-<code><kc></code>: coefficient of quadratic deformation (=1 for the options calib_lin and calib_rescale)
     675-<code><CoordUnit></code>: coordinate unit in physical space.
     676-<code><Tx_Ty_Tz></code>: translation, (Tz=1 for the options calib_lin and calib_rescale)
     677-<code><R>:</code> rotation matrix (in 3 lines)
     678      For the option calib_rescale
     679           R (i=1)= [pxcmx 0 0]
     680           R (i=2)= [0 pxcmy 0]
     681           R (i=3)= [0 0 1]
     682where pxcmx and pxcmy are the scaling factors along x and y.
     683-<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)
     684-<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)
     685-<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)
     686-<code><SourceCalib> </code>set of the point coordinates used for calibration
     687-<code><PointCoord> </code>[x y z X Y] , where x,y,z are the physical coordinates of each point, X Y its image coordinates.
     688-<code><NbSlice_i> </code>nbre of slices for the first field  index i (multilevel case), =1 by default.
     689-<code><NbSlice_j> </code>nbre of slices for the second index j (volume scan), =1 by default.
     690-<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].
     691-<code><SliceDZ> </code>,  step distance between planes, or <code><SliceDPhi> </code> step angle for angular scan.
     692
     693[<doc115|right>->#top]
     694
     695--------------------------------------------
     696'''{9- Masks and grids:===
     697[sec9.1<-]
     698===9.1 Masks:===
     699
     700    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].
     701
     702Mas 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.
     703
     704First 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.
     705
     706Holes can be made by the press button mask_hole which allows to draw a polygon on the image (the matlab image processing toolbox is needed). The inside of this polygone is masked.
     707
     708Press the red push button  save_mask which appeared on the lower right. The saved mask is then displayed. A new image can be then entered.
     709
     710[sec9.2<-]
     711===9.2 Grids:===
     712
     713Grid 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.
     714
     715The 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.
     716
     717[<doc115|right>->#top]
     718
     719--------------------------------------
     720[series<-]
     721'''{10- Processing field series:===
     722
     723===10.1 The GUI series.fig:===
     724
     725    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').
     726
     727    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]'''.
     728
     729    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. 
     730
     731    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...' .
     732
     733    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.
     734
     735    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).
     736
     737    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).
     738
     739===10.2 check_files:===
     740
     741Gives 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).
     742
     743For 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.
     744
     745
     746===10.3 aver_stat:===
     747
     748    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.
     749
     750    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'.
     751
     752    With a projection object with title PATCH, the global histogram of field variables on the selected region will be obtained.   
     753
     754In 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.
     755   
     756
     757===10.4 time_series:===
     758
     759  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.
     760
     761In 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.
     762
     763===10.5 merge_proj: } ===
     764
     765    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'.
     766
     767    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.
     768
     769===10.6 more...:===
     770
     771This action calls any user defined function by its name, acting on the series of fields defiend for ACTION.
     772Some examples of usr_defined functions are in the subdirectory {/series}.
     773
     774-List of available functions:
     775-*{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).
     776-*{ima2vol.m:} produce volume images for 3D3C PIV.
     777
     778To update (**):
     779-uvprofile: calculate the mean velocity profile and Reynolds stress u'v' along a band, averaged over the series of fields.
     780-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.
     781-part_stat: count particles and provides their density and luminosity histogramm
     782Peaklocking errors:(to update **)
     783
     784By 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.
     785
     786[<doc115|right>->#top]
     787
     788--------------------------------
     789[civ<-]
     790'''{11- PIV: Particle Imaging Velocimetry===
     791
     792{===11.1 Overview:===}
     793
     794The 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 }).
     795
     796-''' {Opening the GUI:} '''
     797The 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.
     798
     799<doc78|center>
     800
     801-''' {Input file name and indexing:} '''
     802The 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]'''.
     803-*'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 ]'''.
     804-*'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 ]'''.
     805-*'series(Dj)': operates like 'series(Di)', but with sliding j index pairs.
     806-*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.
     807-*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].
     808
     809-''' {Succession of operations:} '''
     810
     811The CIV process involves a succession of iterative operations:
     812-*civ1: the initial image correlation process.
     813-*fix1: detection of 'false' velocity vectors according to different criteria.
     814-*patch1: interpolation and filtering on a regular grid, providing access to spatial derivatives of the velocity (diverrgence, curl, strain).
     815-* civ2: advanced image correlation algorithm using the result of civ1 as a first approximation.
     816-* fix2 and patch2: similar as fix1 and patch1, but applied to the civ2 results.
     817This 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.
     818
     819{===11.2 CIV1:===}
     820The 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.
     821
     822The 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.
     823The 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].'''.
     824
     825('''[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. 
     826
     827The 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).
     828
     829A parameter '''[rho(images)] ''' controls the smoothing of the image corelation curves used in civ, the default value 1 is generally used.
     830
     831The 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).
     832
     833<doc72|center>
     834
     835 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.
     836
     837A 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.
     838
     839Finally 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.
     840
     841 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.
     842
     843-''' {RUN and BATCH:} '''
     844 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.
     845
     846    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.
     847
     848[sec11.3<-]
     849{===11.3 FIX===}
     850
     851The FIX operation is used after civ to remove false vectors, using different criteria:
     852-''' {warning flags:} ''' these are flags (vec_F) indicating problems with the image correlation process:
     853-*vec_F(i)=0 or 1 : default , the processing is fine
     854-*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
     855-*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.
     856Reference: Hart D. P. (2000) 'PIV error correction',{ Exp. Fluids} '''29''', 13-22.
     857-*vec_F(i)=3: the optimisation of the correlation function is unstable  or  local Intensity rms of the image =0
     858-*vec_F(i)=4:only in civ2: the difference between the estimator and the result is more than 1 pixel.
     859The 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). 
     860-''' {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.
     861-''' {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]''').
     862-''' {Mask fix:} '''  It has the same effect as the one used in civ1, but the removed vectors are kept in memory, labelled as false.
     863-''' {Manual fix:} ''' Interactive fixing with the mouse is also possible, see [section 4.2->#4.2].
     864
     865-''' {Code for FixFlag:} '''
     866-*FixFlag(i)=0 :default, everything is fine
     867-*FixFlag(i)=1. : value 1 for the second digit: vector removed by criteria on vec_F or/and low correlation value
     868-*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.
     869-*FixFlag(i)=...1, 2, 3  different criteria for elimination set by the program Fix of CIVx (not yet documented).
     870
     871{===11.4 PATCH===}
     872
     873-'''PATCH1: ''' interpolates the velocity values on a regular grid with a smoothing parameter rho. This also provides the spatial derivatives (vorticity, divergence) needed for the refined processing civ2. The numbers of grid points in x and y are set by nx and ny. The vectors which are too far from the smoothed field (erratic vectors) can be eliminated, using a threshold expressed in pixel displacement. The thin plate spline method must be done by subdomains for computational saving, use the default value 300.
     874
     875{===11.5 CIV2===}
     876
     877-'''CIV2:''' provides a refined calculation of the velocity field, using the civ1 result as previous estimate. The search range is determined by the civ1 field so there is no parameter. Use the option decimal shift to reduce peaklocking effects (advised). The option deformation is useful in the presence of strong shear or vorticity. Then image deformation and rotation is introduced before calculating the correlations. The other parameters (rho, ibx,iby, grid, mask) are used like for civ1 (take the same by default). The image pair for civ2 can be different than the one used in civ1 to get the first estimate. It is generally advised to use a moderate time interval for civ1, to avoid false vectors, and to take a larger intervel for civ2, in order to optimize precision. As civ2 already knows where to look and takes into account image strain and rotation (with the option deformation) it allows for higher time intervals.
     878
     879-'''FIX2:''' like FIX1, except for the different flags vec_F provided by civ2. Use the default options.
     880
     881-'''PATCH2:''' like PATCH1
     882
     883Further 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.
     884
     885[sec11.6<-]
     886{=== 10.6 Stereoscopic PIV:===}
     887
     888To obtain the three velocity components in a plane with stereoscopic PIV, use the following procedure:
     889
     890Install 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.
     891
     892Make 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).
     893    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.
     894
     895Perform usual PIV for each image series:
     896    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.
     897
     898    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).
     899
     900Combine 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)**.
     901
     902[civdata<-]
     903{===11.7 Description of the velocity files :===}
     904
     905The 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.
     906
     907Several fields, corresponding to the successive operations 'civ1', 'fix1', 'patch1', 'civ2', 'fix2', 'patch2' are stored in the same .nc file.
     908When a third or higher order civ iteration is performed, a new .nc file is created, containing the two last iterations as civ1 and civ2.
     909
     910-'''List of constants (global attributes):''',
     911 Conventions 'uvmat/civdata'.
     912|  '''tag''' |  '''     content'''  |
     913| Conventions| sets the conventions|
     914|                Program|name of the processing program|
     915|              CivStage| stage in the sequence civ1,fix1...|
     916|         Civ1_TestCiv1| 0|
     917|    Civ1_CorrBoxSize|size x,y of the correlation box|
     918|  Civ1_SearchBoxSize| size x,y of the search box|
     919|Civ1_SearchBoxShift| (optional) shift of the search box|
     920|        Civ1_CorrSmooth| smooth parameter for the image corr|
     921|                Civ1_Dx |grid mesh along x|
     922|                Civ1_Dy| grid mesh along y|
     923|         Civ1_CheckGrid| =1 if a grid file is used, default=0|
     924|        Civ1_CheckMask| =1 if a mask file is used, default=0|
     925|    Civ1_CheckThreshold| =0/1 image luminosity  threshold used |
     926|         Civ1_FileTypeA| type of input file A, 'image', 'movie'...|
     927|            Civ1_ImageA| path and name of input image A|
     928|        Civ1_FileTypeB| type of input file A, 'image', 'movie'...|
     929|            Civ1_ImageB|path and name of input  image B|
     930|                Civ1_Dt| time interval for image pair|
     931|              Civ1_Time| mean time for the image pair|
     932|     Civ1_ImageBitDepth| nbre of grey level bits|
     933|        Civ1_ImageWidth| nbre of pixels along x|
     934|       Civ1_ImageHeight|  nbre of pixels along y|
     935|       Civ1_FrameIndexA| frame index of image A in the series|
     936|       Civ1_FrameIndexB|  frame index of image B in the series|
     937|             Patch1_Rho| 10|
     938|       Patch1_Threshold| threshold for the elimination of aberrant vectors|
     939|       Patch1_SubDomain| estimated nbre of vectors in a subdomain|
     940
     941
     942-'''List of variables:'''
     943
     944Conventions 'uvmat/civdata'.
     945
     946|  '''tag''' |  '''     content'''  |
     947|                Civ1_X| x coordinates|
     948|                Civ1_Y| y coordinates|
     949|                Civ1_Z| z coordinates (for PIV in volume)|
     950|                Civ1_U| x velocity component|
     951|                Civ1_V| y velocity component|
     952|                Civ1_W| z velocity component (if relevant)|
     953|                Civ1_F| warning flag|
     954|                Civ1_C| image correlation|
     955|                Civ1_FF| error flag|
     956|                Civ1_U_smooth| smoothed x velocity component|
     957|                Civ1_V_smooth| smoothed y velocity component|
     958|                Civ1_W_smooth| smoothed z velocity component|
     959|                Civ1_SubRange| sub range bounds|
     960|                Civ1_NbSites| nbre of tps sites in each sub-range|
     961|                Civ1_Coord_tps| tps coordinates|
     962|                Civ1_U_tps| tps weights for x vel component|
     963|                Civ1_V_tps| tps weights for y vel component|
     964|                Civ1_W_tps| tps weights for z vel component|
     965
     966-'''List of constants, old CIVx conventions):'''
     967-* nb_coord: =2 for PIV in a plane, =3 for PIV in a volume.
     968-* nb_dim: =2 for the usual 2 component PIV, =3 for 3 component PIV (stereoscopic or volume).
     969-* constant_pixcm: =1 for a simple linear calibration provided by the scaling factors pixcmx and pixcmy, =0 otherwise.
     970-* pixcmx: scale pixel/space unit (cm by default) along the x direction (only if constant_pixcm=1).
     971-* pixcmy: scale pixel/space unit (cm by default) along the y direction (only if constant_pixcm=1)
     972-* absolut_time_T0: time elapsed since the time origin of the series (the mean time for the two images of the pair is taken).
     973-* dt: time interval between the two images of the pair.
     974-* absolut_time_T0_2: same as absolute_time_T0 for the fields obtained by the second iteration (civ2), using a possibly different image pair.
     975-* dt2: same as dt for the fields obtained by the second iteration (civ2).
     976-* hart: =1 if the Hart option has been used for processing (see ref.???), =0 otherwise.
     977-* civ: =1 if a civ1 operation has been performed (=0 if the field is not obtained from an image pair)
     978-* fix: =1 if a fix1 operation has been performed,
     979-* patch: =1 if a patch1 operation has been performed.
     980-* civ2: =1 if a civ2 operation has been performed.
     981-* fix2:=1 if a fix2 operation has been performed.
     982-* patch2: =1 if a Patch2 operation has been performed.
     983-* patch_nx: number of grid points in the x direction for the patch field
     984-* patch_ny: number of grid points in the y direction for the patch field
     985-* ro_patch: smoothing coefficient rho used for patch
     986-* patch2_nx: number of grid points in the x direction for the patch2 field
     987-* patch2_ny: number of grid points in the y direction for the patch2 field
     988-* ro2_patch: smoothing coefficient rho used for patch2
     989
     990-'''List of field variables (old CIVx conventions):'''
     991A 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).
     992
     993The 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.
     994
     995-*Names of field variables for civ1 and patch1
     996
     997|   |  '''      civ1'''         | '''interp1'''  |      '''filter1 '''          |
     998| dim.  |       nb_vectors  |   nb_vec_patch  | nb_vec_patch  |
     999|x      |vec_X          |vec_patch_X  | vec_patch_X |
     1000|y      |       vec_Y  |        vec_patch_Y |   vec_patch_Y |
     1001|z      |       vec_Z |         vec_patch_Z  |  vec_patch_Z |
     1002|u              |vec_U |        vec_patch0_U  | vec_patch_U |
     1003|v              |vec_V          |vec_patch0_V  |        vec_patch_V |
     1004|w       |      vec_W   |vec_patch0_W|          vec_patch_W |
     1005|correlation  | vec_C  |          |       |
     1006|warning flag  |        vec_F |   |       |
     1007|false flag  |  vec_FixFlag |     |       |
     1008|du/dx  |        |vec_patch0_DUDX         |vec_patch_DUDX         |
     1009|du/dy  |        |vec_patch0_DUDY         |vec_patch_DUDY         |
     1010|dv/dx  |        |vec_patch0_DVDX         |vec_patch_DVDX         |
     1011|dv/dy  |        |vec_patch0_DVDY         |vec_patch_DVDY         |
     1012
     1013
     1014-*Names of field variables for civ2 and patch2
     1015
     1016|   |  '''      civ2'''         | '''interp2'''  |      '''filter2 '''          |
     1017| dim.  |       nb_vectors2  |  nb_vec2_patch  |        nb_vec2_patch  |
     1018|x      |vec2_X         |vec2_patch_X  |        vec2_patch_X |
     1019|y      |       vec2_Y  |       vec2_patch_Y |  vec2_patch_Y |
     1020|z      |       vec2_Z |        vec2_patch_Z  | vec2_patch_Z |
     1021|u              |vec2_U |       vec2_patch0_U  |        vec2_patch_U |
     1022|v              |vec2_V         |vec2_patch0_V  |       vec2_patch_V |
     1023|w       |      vec2_W          |vec2_patch0_W|         vec2_patch_W |
     1024|correlation  | vec2_C  |         |       |
     1025|warning flag  |        vec2_F |          |       |
     1026|false flag  |  vec2_FixFlag |    |       |
     1027|du/dx  |        |vec2_patch0_DUDX        |vec2_patch_DUDX        |
     1028|du/dy  |        |vec2_patch0_DUDY        |vec2_patch_DUDY        |
     1029|dv/dx  |        |vec2_patch0_DVDX        |vec2_patch_DVDX        |
     1030|dv/dy  |        |vec2_patch0_DVDY        |vec2_patch_DVDY        |
     1031
     1032
     1033
     1034----------------------------
     1035==12 Tridimensional features:(to update **)==
     1036
     1037
     1038{=== 12-1 Multilevel image scanning===}
     1039or 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.
     1040
     1041{=== 12-2 Volume image scanning===}
     1042
     1043
     1044{=== 12-3 3D3C PIV :**===}
     1045This 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}.
     1046
     1047-------------------------
     1048[editxml<-]
     1049==13 Editing xml files with the GUI editxml.fig:==
     1050
     1051    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.
     1052
     1053    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.
     1054
     1055    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.
     1056
     1057     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.
     1058
     1059</math>
     1060[overview<-]
     1061==Appendix: overview of the package:===
     1062
     1063===Master GUI:===
     1064
     1065-'uvmat';...% master function for file scanning and visualisation of 2D fields
     1066
     1067===Other GUIs:(function .m and associated figure .fig)===
     1068
     1069-'civ';...   %function associated with the interface 'civ.fig' for PIV and spline interpolation
     1070-'create_grid';...% called by the GUI geometry_calib to create a physical grid 
     1071- 'dataview';...% function for scanning directories in a campaign
     1072-'editxml';...%display and edit xml files using a xls schema
     1073-'geometry_calib';...%performs geometric calibration from a set of reference points
     1074-'get_field';...% choose and plot a field from a Netcdf file
     1075-'msgbox_uvmat';... associated with GUI msgbox_uvmat.fig to display message boxes, for error, warning or input calls
     1076-'rotate_points';...%'rotate_points': associated with GUI rotate_points.fig to introduce (2D) rotation parameters
     1077-'series';...% master function for analysis field series, with interface 'series.fig'
     1078-'set_grid';...% creates a grid for PIV
     1079-'set_object';...%  edit a projection object
     1080-'translate_points';...% associated with GUI translate_points.fig to display translation parameters 
     1081-'view_field';...% function for visualisation of projected fields'
     1082
     1083===functions activated by mouse and keybord in GUI :===
     1084-'keyboard_callback';... % function activated when a key is pressed on the keyboard
     1085-'mouse_down';% function activated when the mouse button is pressed on a figure (callback for 'WindowButtonDownFcn')
     1086-'mouse_motion';...% permanently called by mouse motion over a figure (callback for 'WindowButtonMotionFcn')
     1087-'mouse_up';... % function to be activated when the mouse button is released (callback for 'WindowButtonUpFcn')
     1088   
     1089=== main functions used:===
     1090-'civ_matlab';...% civ programs, Matlab version (called by civ.m, option Civprogram/Matlab in the upper menu bar)
     1091-'plot_field';...%displays a vector field and/or scalar or images
     1092-'plot_object';...%draws a projection object (points, line, plane...)
     1093-'proj_field';...%project a field on a projection object (plane, line,...)
     1094-'RUN_STLIN';...% combine 2 displacement fields for stereo PIV
     1095-'sub_field';...% combine the two input fields,
     1096
     1097===convert and I/O functions:===
     1098-'cell2tab';... % transform a Matlab cell in a character array suitable for display in a table
     1099-'fill_GUI';... % fill a GUI with handles 'handles' from input data Param
     1100-'imadoc2struct';...% convert the image documentation file ImaDoc into a Matlab structure
     1101-'nc2struct';...% transform a netcdf file in a corresponding matlab structure
     1102-'num2stra';...% transform number to the corresponding character string depending on the nomenclature.
     1103-'read_field':...% read the fields from files in different formats (netcdf files, images, video)
     1104-'read_GUI'::...% read a GUI and provide the data as a Matlab structure
     1105'read_image';... read images or video objects
     1106-'read_multimadoc';... %read a set of Imadoc files and compare their timing of different file series
     1107'read_xls';...%read excel files containing the list of the experiments
     1108-'stra2num';...% transform letters (a, b, A, B,) or numerical strings ('1','2'..) to the corresponding numbers
     1109-'struct2nc';...% write fields in netcdf files
     1110-'struct2xml';... transform a matlab structure to a xml tree.
     1111-'xml2struct'...% read an xml file as a Matlab structure, converts numeric character strings into numbers
     1112   
     1113===ancillary functions:===
     1114-'calc_field';...% defines fields (velocity, vort, div...) from civx data (old conventions) and calculate them.
     1115-'calc_field_interp': defines fields (velocity, vort, div...) from civ data and calculate them for projection with linear interpolation
     1116-'calc_field_tps': defines fields (velocity, vort, div...) from civ data and calculate them with tps interpolation
     1117-calc_tps': calculate the thin plate spline (tps) coefficients for interpolation
     1118-'check_files';...% check the path, modification date and svn version for all the function in the toolbox UVMAT.
     1119-'close_fig';...% function  activated when a figure is closed
     1120-'copyfields';...% copy fields between two matlab structures
     1121-'delete_object';...%delete a projection object, defined by its index in the Uvmat list or by its graphic handle
     1122'fileparts_uvmat': splits a file name in root and indices and recognize file naming convention
     1123-'filter_tps';...% find the thin plate spline coefficients for interpolation-smoothing
     1124-'find_field_cells';...% group the variables of a nc-formated Matlab structure into 'fields' with common dimensions
     1125-find_field_cells': test field structure for input in proj_field and plot_field, group the variables  into 'fields' with common dimensions
     1126-'find_file_series';...%check the content of an input file and find the corresponding file series
     1127-'fullfile_uvmat';...%creates a file name from a root name and indices.
     1128-'get_file_type': determine info about a file (image, multimage, civdata,...)
     1129-'griddata_uvmat';...%make 2D linear interpolation using griddata, with input appropriate for both Matlab 6.5 and 7
     1130 -'hist_update';...%  update of a current global histogram by inclusion of a new field
     1131-'ListDir';... scan the structure of the directory tree (for dataview.m)
     1132-'open_uvmat';...% open with uvmat the  field selected in the list of 'civ/status' or 'series/check_data_files'
     1133-'peaklock';...%
     1134-'phys_XYZ';...% transform coordiantes from pixels to phys
     1135-'px_XYZ';...% transform coordiantes from phys to pixels 
     1136-'read_civxdata';...reads civx data from netcdf files
     1137-'read_civdata';... reads new civ data from netcdf files
     1138-'read_get_field';... read the list of selected variables from the GUI get_field (TODO: use read_GUI)
     1139-'read_imatext';...%read .civ files (obsolete, but can be adapted to other text documentation files)
     1140-'read_xls';...%read excel files containing the list of the experiments
     1141-'reinit';...% suppress the personal parameter file 'uvmat_perso.mat'
     1142-'set_col_vec';...% sets the color code for vectors depending on a scalar and input parameters (used for plot_field)
     1143-'tps_coeff';...% calculate the thin plate spline (tps) coefficients
     1144-'tps_eval';... %calculate the thin plate spline (tps) interpolation at a set of points
     1145-'tps_eval_dxy';...% calculate the derivatives of thin plate spline (tps) interpolation at a set of points (limited to the 2D case)
     1146-'update_imadoc';...  %update the ImaDoc xml file
     1147-'update_obj';... update the object representation graph and its projection field, record it in the uvmat interface
     1148-'update_waitbar';... update the waitbar display, used for ACTION functions in the GUI 'series'
     1149-'write_plot_param'...%update plotting parameters after plot, TODO: change into a general function: fill_GUI
     1150   
     1151===series functions===
     1152-'aver_stat': calculate field average over a time series
     1153-'avi2png': copy an avi movie to a series of B/W .png images (take the average of green and blue color components)
     1154-'check_data_files': check the existence, type and status of the files selected by series.fig
     1155-'merge_proj': concatene several fields from series, can project them on a regular grid in phys coordinates
     1156-'sub_background': subtract a sliding background to an image series
     1157-'time_series': extract a time series after projection on an object (points , line..)
     1158
     1159===transform functions===
     1160- 'ima_filter': low-pass filter of an image (builtin filtering parameter)
     1161- 'ima_remove_background': removes backgound from an image (using the local minimum)
     1162- 'ima_remove_particles': removes particles from an image (keeping the local minimum)
     1163- 'FFT2_detrend': calculate the 2D spectrum of the input scalar after removing the linear trend (requires the Matlab image processing toolbox).
     1164-'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'
     1165-'phys_polar': this transforms the fields to polar coordinates, radius in abscissa (same unit as x, y) and azimuth in ordinate (unit =degree).