Changes between Version 129 and Version 130 of UvmatHelp


Ignore:
Timestamp:
Jan 13, 2015, 7:32:07 PM (6 years ago)
Author:
sommeria
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UvmatHelp

    v129 v130  
    1313The 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.
    1414
    15  * '''browse_data.fig:''' scans the data directory of a project
     15 * '''browse_data.fig:''' scans the data directory of a project.
    1616 * '''editxml.fig:'''  displays and edits XML files according to an XML schema. XML reading and editing is performed by the toolbox [http://www.artefact.tk/software/matlab/xml/ xmltree], integrated in the package ''UVMAT'' as a subdirectory /@xmltree.
    1717 * '''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, integrated in the package ''UVMAT'' as a subdirectory /toolbox_calib.
     
    6767
    6868 * '''[Tools]''':
    69    * '''[Geometric calibration]''' for geometric calibration of images
    70    * '''[LIF calibration]''':  calibration of images for Laser Induced Fluorescence
    71    * '''[Make mask]''': for creating mask images (for PIV)
    72    * '''[Make grid]:''': for making measurement grids for PIV
     69   * '''[Geometric calibration]''' for geometric calibration of images.
     70   * '''[LIF calibration]''':  calibration of images for Laser Induced Fluorescence.
     71   * '''[Make mask]''': for creating mask images (for PIV).
     72   * '''[Make grid]:''': for making measurement grids for PIV.
    7373   * '''[ruler]''': displays a ruler to measure lengths and angles of any line.
    7474
     
    166166 * '''<!GeometryCalib>''' contains the parameters of the geometric calibration relating the pixel position to the real space coordinates (see [#a8-Geometriccalibration section 8]]). In the case of volume scanning, it also describes the set of laser plane positions and angles.
    167167 * '''<Illumination>''' describes the illumination system used, including the position of the laser source.
    168  * '''<Tracor>''' describes the properties of the flow tracor (particle, dye...)
     168 * '''<Tracor>''' describes the properties of the flow tracor (particle, dye...).
    169169
    170170=== 3.6 Ancillary input files ===
    171171 * ''' Mask:''' Masks are used to avoid PIV computations in specified areas. The file is a B&W 8 bit png image, with the same size as the image it has to mask. The grayscale code used is :
    172    * Intensity < 20: ('black mask') the vector in this place will be set to zero
    173    * 20 < Intensity < 200:('gray mask') the vector in this place will be absent
     172   * Intensity < 20: ('black mask') the vector in this place will be set to zero.
     173   * 20 < Intensity < 200:('gray mask') the vector in this place will be absent.
    174174   * Intensity>200  the vector will be computed  The mask corresponding to an image or velocity field can be displayed in '''uvmat.fig''' by selecting the check box '''[view_mask]([!CheckMask])''' on the upper left. Images with appropriate name can be automatically recognised by '''uvmat.fig''' and civ functions, see [#a9-Masksandgrids section 9.1]. Otherwise file selection by a browser is proposed when '''[view_mask]''' is selected.
    175175
     
    262262
    263263 * 'rgb':  color ranging from red, for the scalar value set by '''[num_MinVec]''', to blue, for the scalar value set by  '''[num_MaxVec]'''. The  color thresholds from red to green and green to blue are set by '''[ColCode1]''' and '''[ColCode2]''' respectively, or the sliders  '''[Slider1]''' and '''[Slider2]'''. By unselecting the check box [!CheckFixVecColor], these thresholds can be set to match the min and max scalar values.
    264  * 'black' or 'white': set the color for all vectors
     264 * 'black' or 'white': set the color for all vectors.
    265265 * 'brg': same as rgb but in reverse order, with blue for the lowest scalar values.
    266266 * '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]'''.
     
    269269
    270270 * fist line: the position coordinates ''x'', ''y'', ''z'' for 3D cases).
    271  * second line: the vector components
     271 * second line: the vector components.
    272272 * 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 [#a11.3FIX section 11.3].
    273273
     
    359359In 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.
    360360
    361  * '''!ListDimName''' list of dimension names (cell array of character strings)
     361 * '''!ListDimName''' list of dimension names (cell array of character strings).
    362362 * '''!DimValue''' array of dimension values corresponding to !LisDimName.
    363363
     
    366366 * '''!ProjModeRequest'''= ''interp_lin'' or ''interp_tps'' indicates whether lin interpolation  or derivatives by tps is needed to calculate the requested field.
    367367 * '''Operation''': name (char string) of the operation to be performed to finalise the field cell after projection.
    368  * '''!SubCheck'''= 0 /1 indicate that the field must be substracted (second entry in UVMAT)
     368 * '''!SubCheck'''= 0 /1 indicate that the field must be substracted (second entry in UVMAT).
    369369
    370370Any other element can be added, but will not be taken into account if they are not listed in  ''!ListGlobalAttribute'' or ''!ListVarName''.
     
    374374
    375375 * 'Conventions':
    376    * ='uvmat': indicate that the conventions described here are followed
     376   * ='uvmat': indicate that the conventions described here are followed.
    377377   * ='uvmat/civdata': indicate that the variables are named according to [#civdata #civdata].
    378378 * '!CoordMesh': typical mesh for coordinates, used to define default projection grids and mouse selection action. Calculated automatically from the data if not specified.
     
    384384-'''Global attributes , unactive''' those are merely used for information purpose
    385385
    386  * Project: recalls the project name
    387  * Campaign: recalls the campaign name
    388  * Experiment:  recalls the experiment name(s) of the raw data
    389  * !DataSeries:  recalls the device name (s), if defined, of the raw data
     386 * Project: recalls the project name.
     387 * Campaign: recalls the campaign name.
     388 * Experiment:  recalls the experiment name(s) of the raw data.
     389 * !DataSeries:  recalls the device name (s), if defined, of the raw data.
    390390 * !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.
    391391 * !ObjectCoord:  Coordinates defining a geometric object on which the data have been projected.
     
    401401-'''The attribute 'Role':''' the following options are used for the attribute 'Role':
    402402
    403  * 'ancillary': information of secondary use, indicating for instance an error estimate of field variables within a field cell (omitted in plotting)
     403 * 'ancillary': information of secondary use, indicating for instance an error estimate of field variables within a field cell (omitted in plotting).
    404404 * '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.
    405405 * 'coord_tps': coordinates of thin plate shell (tps) centres used for spline interpolation.
     
    407407 * '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.
    408408 * 'grad_x', 'grad_y', 'grad_z'  :represents the x, y or z  component of a contravariant vector** (like gradients).
    409  * 'image_rgb': represents a color image. The last dimension of the array corresponds to the three color components 'rgb'. -* 'scalar': (default) represents a scalar field
     409 * 'image_rgb': represents a color image. The last dimension of the array corresponds to the three color components 'rgb'. -* 'scalar': (default) represents a scalar field.
    410410 * 'tensor': represents a tensor field whose components correspond to the two last   dimensions of the array.**
    411411 * vector: matrix whose last dimension states for the vector components.**
    412  * 'vector_x', 'vector_y', 'vector_z'  : represents the x, y or z  component of a vector (covariant)
     412 * 'vector_x', 'vector_y', 'vector_z'  : represents the x, y or z  component of a vector (covariant).
    413413 * 'warnflag': provides a warning flag about the quality of data for the field variables within a field cell., default=0, no warning.
    414414
     
    423423The 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:
    424424
    425  * coord_1,_2,_3: dimension with the same name as a coordinate variable array (coordinate dimension)
    426  * 'nb_coord': denotes the space dimension for vector components
    427  * 'nb_coord_j', 'nb_coord_i': denotes the space dimensions for the two tensor components
     425 * coord_1,_2,_3: dimension with the same name as a coordinate variable array (coordinate dimension).
     426 * 'nb_coord': denotes the space dimension for vector components.
     427 * 'nb_coord_j', 'nb_coord_i': denotes the space dimensions for the two tensor components.
    428428 * 'rgb' : denotes the diemension of the color component in a true color  image.
    429429 * 'nb_point' or 'nb_vec' (for vectors) denotes the set of positions with unstructured coordinates.
    430  * 'nb_tps': dimension of the index for the tps centres
    431  * 'nb_subdomain' denotes the dimension for the subdomain index for tps coefficients
     430 * 'nb_tps': dimension of the index for the tps centres.
     431 * 'nb_subdomain' denotes the dimension for the subdomain index for tps coefficients.
    432432
    433433----
     
    445445  The objects are defined by the following set of properties:
    446446
    447  * ''' Name: ''' any name given to the object
     447 * ''' Name: ''' any name given to the object.
    448448 * ''' Type: ''' classify the object with the following choice:
    449    * 'points': set of n points
    450    * 'line': simple straight segment, defined by its two end points
    451    * 'polyline': open line made of n-1 consecutive segments (defined by n points)
    452    * 'rectangle': defined by its center, half width and half height, and possibly angle of axis..
    453    * 'polygon': closed line made of n consecutive segments (defined by n points)
     449   * 'points': set of n points.
     450   * 'line': simple straight segment, defined by its two end points.
     451   * 'polyline': open line made of n-1 consecutive segments (defined by n points).
     452   * 'rectangle': defined by its center, half width and half height, and possibly angle of axis.
     453   * 'polygon': closed line made of n consecutive segments (defined by n points).
    454454   * 'ellipse': defined by its center, half width, half height, and possibly angle of axis.
    455    * 'plane': plane with associated cartesian coordinates
    456    * 'volume': volume with associated cartesian coordinates
     455   * 'plane': plane with associated cartesian coordinates.
     456   * 'volume': volume with associated cartesian coordinates.
    457457
    458458 * ''' !ProjMode: ''': specifies the method of projection of coordinates and field, as described in [#a6.3Projectionmodes next sub-section].
     
    505505 * 'polygon', 'rectangle', 'ellipse' are drawn as lines. In the case !ProjMode ='inside' or 'outside' the corresponding area is painted in magenta (or blue when they are not selected).
    506506 * 'plane' are shown by their axis ending with arrows. When the projection is limited to a sub-domain, by [RangeX] or [RangeY], the bounds are indicated by dashed lines.
    507  * 'volume' are shown like 'plane', except that they are painted in magenta (or blue) **
     507 * 'volume' are shown like 'plane', except that they are painted in magenta (or blue) **.
    508508
    509509Object 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, and possibly adjust parameters on the GUI '''set_object.fig'''. Then mark the set of point coordinates by pressing (then release) the left mouse button. Those appear in the table '''[Coord]''' of '''set_object.fig'''. For 'polyline' or 'polygon', press the right hand mouse button to end the line. 'Plane' and 'volume' cannot be created or modified with the mouse.
     
    562562The ''physical coordinates'' are defined from the experimental set-up. The correspondance with images is obtained by identifying a set of calibration points whose positions are known in the physical coordinate system. A cartesian calibration grid covering the whole image is the best option, but any set of calibration points can be used. We handle three kinds of transforms:
    563563
    564 -'''rescale''': linear rescaling along ''x'' and ''y'' + translation (no rotation nor deformation)
    565 
    566 -'''linear''': general linear transform, including translation and rotation (but no projection effects)
     564-'''rescale''': linear rescaling along ''x'' and ''y'' + translation (no rotation nor deformation).
     565
     566-'''linear''': general linear transform, including translation and rotation (but no projection effects).
    567567
    568568-'''3D_linear:''' this transform handles projection effects, needed if the observed plane is not perpendicular to the line of sight. It involves a 3D calibration needed to account for the depth effects occuring in volume scan.
     
    579579
    580580=== 8.2 The GUI geometry_calib.fig ===
    581 [[Image(geometry_calib.jpg)]]
    582 -''' 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 <!ImaDoc>, the corresponding parameters and the list of reference points are displayed in the table '''[!ListCoord]'''. The three first columns indicate the physical coordinates and the two last ones the corresponding image coordinates (in pixels). The physical unit is imposed as centimeter by the menu '''[!CoordUnit]''' to avoid mistakes. Calibration points can be alternatively introduced by opening any XML file <!ImaDoc> with the menu bar command '''[Import]''' of '''geometry_calib.fig'''. It is possible to import the whole information, option 'All', the calibration point coordinates only, or the calibration parameters only.
     581[[Image(geometry_calib.jpg)]] -''' 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 <!ImaDoc>, the corresponding parameters and the list of reference points are displayed in the table '''[!ListCoord]'''. The three first columns indicate the physical coordinates and the two last ones the corresponding image coordinates (in pixels). The physical unit is imposed as centimeter by the menu '''[!CoordUnit]''' to avoid mistakes. Calibration points can be alternatively introduced by opening any XML file <!ImaDoc> with the menu bar command '''[Import]''' of '''geometry_calib.fig'''. It is possible to import the whole information, option 'All', the calibration point coordinates only, or the calibration parameters only.
    583582
    584583-''' Plotting calibration points: ''' press the button '''[PLOT PTS] ''' to visualise the current list of calibration points. The physical or image coordinates will be used in the list '''[!ListCoord]''', depending on the option blank or 'phys' in the menu '''[transform_fct]''' of ''' uvmat.fig''' .
     
    608607-'''Section planes:''' deducing the physical coordinates from image coordinates requires information on the section plane. The default assumption is that the objects in the image are in the plane used for calibration, but uvmat can handle volume scanning by a laser plane. A set of section planes can be defined by their origin positions and rotation angle vectors. Theses planes are labelled by a ''z index'', assumed to be the frame index j (case of volume scan), or the index i modulo the number of slices !NbSlice (case of 'multilevel' scan). These settings are stored in the xml file <!ImaDoc> as part of the section <!GeometryCalib> and can be edited from '''uvmat.fig''' with the menu bar command '''[Tools/set slice]'''. A dialog box '''set_slices''' appears for entering the first and last section plane positions ''z'', as well as the number of slices and the option 'volume_scan' ('multilevel' otherwise). In the absence of 3D scan put twice the same value for first and last z.  Finally a tilt angle of the laser sheet, around the ''x'' and ''y'' axis, can be introduced, with a possible angular scanning from first to last section planes. After introduction of the plane position information, the z-index is displayed in the frame '''[FileIndices]''' of '''uvmat.fig'''. The local ''z'' position of the mouse pointer, assumed to lay on the current section plane, is then displayed in '''[text_display]'''.
    609608
    610 -'''Refraction effect:''' refraction effect can be accounted for if calibration was done in air by selecting the check box refraction, and introducing the water height (assumed at ''z''=cte) and refraction index. The apparent distance reduction for objects below the water height will be then taken into account.
    611 
    612 [[Image(browse_data_small.jpg)]]
    613 [[Image(set_slices_small.jpg)]]
     609-'''Refraction effect:''' refraction effect can be accounted for if calibration was done in air by selecting the check box refraction, and introducing the water height (assumed at ''z''=cte) and refraction index. The apparent distance reduction for objects below the water height will be then taken into account.
     610
     611[[Image(browse_data_small.jpg)]] [[Image(set_slices_small.jpg)]]
    614612
    615613=== 8.3 Structure of the XML file ===
    616614The coefficients are recorded in the XML element <!ImaDoc/GeometryCalib> as follows:
    617615
    618  * <!CalibrationType>: type of calibration ('rescale', 'linear', '3D...')
     616 * <!CalibrationType>: type of calibration ('rescale', 'linear', '3D...').
    619617
    620618 * <fx_fy>: focal length along each coordinate of the image sensor, expressed in pixels/cm.
     
    622620 * <Cx_Cy>: position coordinates of the optical axis on the image sensor.
    623621
    624  * <kc>: coefficient of quadratic deformation (=0 for the options calib_lin and calib_rescale)
     622 * <kc>: coefficient of quadratic deformation (=0 for the options calib_lin and calib_rescale).
    625623
    626624 * <!CoordUnit>: coordinate unit in physical space.
    627625
    628  * `<Tx_Ty_Tz>`: translation, (Tz=1 for the options calib_lin and calib_rescale)
     626 * `<Tx_Ty_Tz>`: translation, (Tz=1 for the options calib_lin and calib_rescale).
    629627
    630628 * `<R>`: rotation matrix (in 3 lines). For the option <[https://servforge.legi.grenoble-inp.fr/projects/soft-uvmat/search?q=wiki%3ACalibrationType !CalibrationType]>= 'rescale', [[BR]] R (i=1)= [pxcmx 0 0] R (i=2)= [0 pxcmy 0] R (i=3)= [0 0 1], [[BR]]where pxcmx and pxcmy are the scaling factors along ''x'' and ''y''.
    631629
    632  * <omc> 3 components of the rotation vector (this is for diagnostic use, it is redondant with the matrix R used for actual coordinate transforms).  The physical coordinate axis are transformed to the image coordinate axis by a composition of the translation T and the rotation)
    633 
    634  * <!ErrorRms>: rms difference (in X and Y direction) between the image coordinates measured for the calibration points and the coordinates transformed from their physical coordinates (using the function ''px_XYZ.m in UVMAT'')
    635 
    636  * <!ErrorMax> : maximum difference (in X and Y direction) between the image coordinates measured for the calibration points and the coordinates transformed from their physical coordinates. (using the function ''px_XYZ.m'' in UVMAT)
    637 
    638  * <!SourceCalib> set of the point coordinates used for calibration
    639 
    640  * <!PointCoord> [x y z X Y] , where x,y,z are the physical coordinates of each point, X Y its image coordinates
     630 * <omc> 3 components of the rotation vector (this is for diagnostic use, it is redondant with the matrix R used for actual coordinate transforms).  The physical coordinate axis are transformed to the image coordinate axis by a composition of the translation T and the rotation).
     631
     632 * <!ErrorRms>: rms difference (in X and Y direction) between the image coordinates measured for the calibration points and the coordinates transformed from their physical coordinates (using the function ''px_XYZ.m in UVMAT'').
     633
     634 * <!ErrorMax> : maximum difference (in X and Y direction) between the image coordinates measured for the calibration points and the coordinates transformed from their physical coordinates. (using the function ''px_XYZ.m'' in UVMAT).
     635
     636 * <!SourceCalib> set of the point coordinates used for calibration.
     637
     638 * <!PointCoord> [x y z X Y] , where x,y,z are the physical coordinates of each point, X Y its image coordinates.
    641639
    642640 * <!NbSlice_i> nbre of slices for the first field  index i (multilevel case), =1 by default.
     
    646644 * <!SliceCoord> [x y z] positions (nb lines) of the nb planes, where nb=NbSlice_i (multilevel case) or nb=NbSlice_j of j indices (volume scan), for parallel volume scan, x=y=0, z= slice height, for angular scan, [x,y,z]=[origin].
    647645
    648  * <SliceDZ>   step distance between planes, or
     646 * <SliceDZ>   step distance between planes.
    649647
    650648 * <SliceDPhi> step angle for angular scan.
     
    740738 * ''ima_levels.m'': provides images with modified grey scale intensity to avoid blinking effects on particles.''''''''''
    741739 * ''ima2vol.m'' produce volume images for 3D3C PIV.
    742  * ''turb_stat.m'': produces turbulent statistics (Reynolds stress tensor)
     740 * ''turb_stat.m'': produces turbulent statistics (Reynolds stress tensor).
    743741
    744742These can be used as template to create other functions. The general input of these functions in Matlab structure 'Param' which contains all the input parameters as given by the GUI series (see comments in the function for details). For batch operations, as needed for the cluster, this input is replaced by the name of an XML file which contains these parameters (this is the file produced in the floder '''/0_XML''' under the result directrory Output Subdir ). The first part of the function must give some options for the requested input information and may interactively introduce specific parameters needed for the function. The second part of the function, where the processing itself takes place, is then free from any input (so the operation can be easily dispatched to a remote computer).
     
    770768PIV can be performed by selecting the Matlab function ''civ_series'' as '''[!ActionName]''' in the GUI '''series.fig''': then the '''GUI civ_input''' appears to enter the processing parameters. An image file series must have been entered as input of '''series.fig''', or alternatively a Netcdf file resulting form a previous PIV processing (with conventions '''civdata''').
    771769
    772 An alternative possibility is to use the older Fortran program ''CivX'' from the GUI '''civ.fig'''. This can be called directly on the Matlab prompt, by typing  ''>>civ'', or from UVMAT by the menu bar command '''[RUN/PIV (old civ)]'''.    '''-Modes of frame pair indexing''' A first menu '''[!ListCompareMode]''' selects one among four modes of operation:
     770An alternative possibility is to use the older Fortran program ''CivX'' from the GUI '''civ.fig'''. This can be called directly on the Matlab prompt, by typing  ''>>civ'', or from UVMAT by the menu bar command '''[RUN/PIV (old civ)]'''.    ''''''
     771
     772'''-Modes of frame pair indexing''' A first menu '''[!ListCompareMode]''' selects one among four modes of operation:
    773773
    774774 * '''PIV''': makes image comparisons on sliding index pairs, as usual for measuring velocities by particle displacements. A second menu '''[!ListPairMode]''' in the panel '''[!PairIndices]''' then selects one among three possibilities (not always available depending on the file indexing):
     
    924924 * constant_pixcm: =1 for a simple linear calibration provided by the scaling factors pixcmx and pixcmy, =0 otherwise.
    925925 * pixcmx: scale pixel/space unit (cm by default) along the x direction (only if constant_pixcm=1).
    926  * pixcmy: scale pixel/space unit (cm by default) along the y direction (only if constant_pixcm=1)
     926 * pixcmy: scale pixel/space unit (cm by default) along the y direction (only if constant_pixcm=1).
    927927 * absolut_time_T0: time elapsed since the time origin of the series (the mean time for the two images of the pair is taken).
    928928 * dt: time interval between the two images of the pair.
     
    930930 * dt2: same as dt for the fields obtained by the second iteration (civ2).
    931931 * hart: =1 if the Hart option has been used for processing (see ref.???), =0 otherwise.
    932  * civ: =1 if a civ1 operation has been performed (=0 if the field is not obtained from an image pair)
    933  * fix: =1 if a fix1 operation has been performed,
     932 * civ: =1 if a civ1 operation has been performed (=0 if the field is not obtained from an image pair).
     933 * fix: =1 if a fix1 operation has been performed.
    934934 * patch: =1 if a patch1 operation has been performed.
    935935 * civ2: =1 if a civ2 operation has been performed.
    936936 * fix2:=1 if a fix2 operation has been performed.
    937937 * patch2: =1 if a Patch2 operation has been performed.
    938  * patch_nx: number of grid points in the x direction for the patch field
    939  * patch_ny: number of grid points in the y direction for the patch field
    940  * ro_patch: smoothing coefficient rho used for patch
    941  * patch2_nx: number of grid points in the x direction for the patch2 field
    942  * patch2_ny: number of grid points in the y direction for the patch2 field
    943  * ro2_patch: smoothing coefficient rho used for patch2
     938 * patch_nx: number of grid points in the x direction for the patch field.
     939 * patch_ny: number of grid points in the y direction for the patch field.
     940 * ro_patch: smoothing coefficient rho used for patch.
     941 * patch2_nx: number of grid points in the x direction for the patch2 field.
     942 * patch2_ny: number of grid points in the y direction for the patch2 field.
     943 * ro2_patch: smoothing coefficient rho used for patch2.
    944944
    945945-'''List of field variables (old CIVx conventions):''' a set of velocity vectors is defined by a 1D array of position coordinates x, y, and z for 3D civ, and a corresponding array for each of the velocity components u, v, and w for 3C civ. The field is therefore defined on an arbitrary set of point, without restriction to a regular mesh. Additional arrays are used to keep track of the quality of the PIV process leading to each vector. The image correlation maximum is represented by vec_C (a real number between 0 and 1). A flag vec_F represents a warning on the vector quality (see the list of values below). Another flag FixFlag marks false vectors: !FixFlag=0 for good vectors, and FixFlag is set to a non-zero value when it has been detected as false (using a 'fix' operation).
     
    991991== 14 - Appendix: overview of the package functions == #overview
    992992=== Master GUI ===
    993  * 'uvmat';...% master function for file scanning and visualisation of 2D fields
     993 * 'uvmat';...% master function for file scanning and visualisation of 2D fields.
    994994
    995995=== Other GUIs(function .m and associated figure .fig) ===
    996996 * 'browse_data';...% function, associated with the GUI 'browse_data.fig' for scanning directories in a project/campaign
    997  * 'civ';...   %function associated with the interface 'civ.fig' for PIV and spline interpolation (to be replaced by civ_series in series fcts)
    998  * 'create_grid';...% called by the GUI geometry_calib to create a physical grid
    999  * 'dataview';...% function for scanning directories in a campaign
    1000  * 'editxml';...%display and edit XML files using a xls schema
    1001  * 'geometry_calib';...%performs geometric calibration from a set of reference points
    1002  * 'get_field';...% choose and plot a field from a NetCDF file
    1003  * 'msgbox_uvmat';... associated with GUI msgbox_uvmat.fig to display message boxes, for error, warning or input calls
    1004  * 'rotate_points';...%'rotate_points': associated with GUI rotate_points.fig to introduce (2D) rotation parameters
    1005  * 'series';...% master function for analysis field series, with interface 'series.fig'
    1006  * 'set_grid';...% creates a grid for PIV
    1007  * 'set_object';...%  edit a projection object
    1008  * 'translate_points';...% associated with GUI translate_points.fig to display translation parameters
    1009  * 'view_field';...% function for visualisation of projected fields'
    1010 
    1011 === Functions activated by mouse and keybord in GUI  ===
    1012  * 'keyboard_callback';... % function activated when a key is pressed on the keyboard
    1013  * 'mouse_down';% function activated when the mouse button is pressed on a figure (callback for '!WindowButtonDownFcn')
    1014  * 'mouse_motion';...% permanently called by mouse motion over a figure (callback for '!WindowButtonMotionFcn')
    1015  * 'mouse_up';... % function to be activated when the mouse button is released (callback for '!WindowButtonUpFcn')
     997 * 'civ';...   %function associated with the interface 'civ.fig' for PIV and spline interpolation (to be replaced by civ_series in series fcts).
     998 * 'create_grid';...% called by the GUI geometry_calib to create a physical grid.
     999 * 'dataview';...% function for scanning directories in a campaign.
     1000 * 'editxml';...%display and edit XML files using a xls schema.
     1001 * 'geometry_calib';...%performs geometric calibration from a set of reference points.
     1002 * 'get_field';...% choose and plot a field from a NetCDF file.
     1003 * 'msgbox_uvmat';... associated with GUI msgbox_uvmat.fig to display message boxes, for error, warning or input calls.
     1004 * 'rotate_points';...%'rotate_points': associated with GUI rotate_points.fig to introduce (2D) rotation parameters.
     1005 * 'series';...% master function for analysis field series, with interface 'series.fig'.
     1006 * 'set_grid';...% creates a grid for PIV.
     1007 * 'set_object';...%  edit a projection object.
     1008 * 'translate_points';...% associated with GUI translate_points.fig to display translation parameters.
     1009 * 'view_field';...% function for visualisation of projected fields'.
     1010
     1011=== Functions activated by mouse and keybord in GUI ===
     1012 * 'keyboard_callback';... % function activated when a key is pressed on the keyboard.
     1013 * 'mouse_down';% function activated when the mouse button is pressed on a figure (callback for '!WindowButtonDownFcn').
     1014 * 'mouse_motion';...% permanently called by mouse motion over a figure (callback for '!WindowButtonMotionFcn').
     1015 * 'mouse_up';... % function to be activated when the mouse button is released (callback for '!WindowButtonUpFcn').
    10161016
    10171017=== Main functions used ===
    1018  * 'civ_matlab';...% civ programs, Matlab version (called by civ.m, option Civprogram/Matlab in the upper menu bar)
    1019  * 'plot_field';...%displays a vector field and/or scalar or images
    1020  * 'plot_object';...%draws a projection object (points, line, plane...)
    1021  * 'proj_field';...%project a field on a projection object (plane, line,...)
     1018 * 'civ_matlab';...% civ programs, Matlab version (called by civ.m, option Civprogram/Matlab in the upper menu bar).
     1019 * 'plot_field';...%displays a vector field and/or scalar or images.
     1020 * 'plot_object';...%draws a projection object (points, line, plane...).
     1021 * 'proj_field';...%project a field on a projection object (plane, line,...).
    10221022 * 'RUN_STLIN';...% combine 2 displacement fields for stereo PIV * 'sub_field';...% combine the two input fields,
    10231023
    10241024=== convert and I/O functions ===
    1025  * 'cell2tab';... % transform a Matlab cell in a character array suitable for display in a table
    1026  * 'fill_GUI';... % fill a GUI with handles 'handles' from input data Param
    1027  * 'imadoc2struct';...% convert the image documentation file <!ImaDoc> into a Matlab structure
    1028  * 'nomtype2pair';... creates nomenclature for index pairs knowing the image nomenclature, used by series fct
    1029  * 'nc2struct';...% transform a NetCDF file in a corresponding Matlab structure
     1025 * 'cell2tab';... % transform a Matlab cell in a character array suitable for display in a table.
     1026 * 'fill_GUI';... % fill a GUI with handles 'handles' from input data Param.
     1027 * 'imadoc2struct';...% convert the image documentation file <!ImaDoc> into a Matlab structure.
     1028 * 'nomtype2pair';... creates nomenclature for index pairs knowing the image nomenclature, used by series fct.
     1029 * 'nc2struct';...% transform a NetCDF file in a corresponding Matlab structure.
    10301030 * 'num2stra';...% transform number to the corresponding character string depending on the nomenclature.
    1031  * 'read_field':...% read the fields from files in different formats (NetCDF files, images, video)
    1032  * 'read_GUI'::...% read a GUI and provide the data as a Matlab structure
    1033  * 'read_image';... read images or video objects
    1034  * 'read_multimadoc';... %read a set of Imadoc files and compare their timing of different file series 'read_xls';...%read excel files containing the list of the experiments
    1035  * 'stra2num';...% transform letters (a, b, A, B,) or numerical strings ('1','2'..) to the corresponding numbers
    1036  * 'struct2nc';...% write fields in NetCDF files
     1031 * 'read_field':...% read the fields from files in different formats (NetCDF files, images, video).
     1032 * 'read_GUI'::...% read a GUI and provide the data as a Matlab structure.
     1033 * 'read_image';... read images or video objects.
     1034 * 'read_multimadoc';... %read a set of Imadoc files and compare their timing of different file series 'read_xls';...%read excel files containing the list of the experiments.
     1035 * 'stra2num';...% transform letters (a, b, A, B,) or numerical strings ('1','2'..) to the corresponding numbers.
     1036 * 'struct2nc';...% write fields in NetCDF files.
    10371037 * 'struct2xml';... transform a Matlab structure to a XML tree.
    1038  * 'xml2struct'...% read an XML file as a Matlab structure, converts numeric character strings into numbers
     1038 * 'xml2struct'...% read an XML file as a Matlab structure, converts numeric character strings into numbers.
    10391039
    10401040=== ancillary functions ===
    1041  * 'activate';...% emulate the mouse selection of a GUI element, for demo
    1042  * 'calc_field_interp': defines fields (velocity, vort, div...) from civ data and calculate them for projection with linear interpolation
    1043  * 'calc_field_tps': defines fields (velocity, vort, div...) from civ data and calculate them with tps interpolation
    1044  * calc_tps': calculate the thin plate spline (tps) coefficients for interpolation
     1041 * 'activate';...% emulate the mouse selection of a GUI element, for demo.
     1042 * 'calc_field_interp': defines fields (velocity, vort, div...) from civ data and calculate them for projection with linear interpolation.
     1043 * 'calc_field_tps': defines fields (velocity, vort, div...) from civ data and calculate them with tps interpolation.
     1044 * calc_tps': calculate the thin plate spline (tps) coefficients for interpolation.
    10451045 * 'check_files';...% check the path, modification date and svn version for all the function in the toolbox UVMAT.
    1046  * 'close_fig';...% function  activated when a figure is closed
    1047  * 'compile';...% compile a Matlab function, create a binary in a subdirectory /bin
    1048  * 'copyfields';...% copy fields between two Matlab structures
    1049  * 'delete_object';...%delete a projection object, defined by its index in the Uvmat list or by its graphic handle
    1050  * 'displ_uvmat';...% display a message using  msgbox_uvmat or on the log file in batch mode
    1051  * 'fileparts_uvmat': splits a file name in root and indices and recognize file naming convention
    1052  * 'filter_tps';...% find the thin plate spline coefficients for interpolation-smoothing
    1053  * 'find_field_cells';...% group the variables of a nc-formated Matlab structure into 'fields' with common dimensions
    1054  * find_field_cells': test field structure for input in proj_field and plot_field, group the variables  into 'fields' with common dimensions
    1055  * 'find_file_series';...%check the content of an input file and find the corresponding file series
    1056  * 'find_imadoc';...% find the <!ImaDoc> XML file associated with a given input file
     1046 * 'close_fig';...% function  activated when a figure is closed.
     1047 * 'compile';...% compile a Matlab function, create a binary in a subdirectory /bin.
     1048 * 'copyfields';...% copy fields between two Matlab structures.
     1049 * 'delete_object';...%delete a projection object, defined by its index in the Uvmat list or by its graphic handle.
     1050 * 'displ_uvmat';...% display a message using  msgbox_uvmat or on the log file in batch mode.
     1051 * 'fileparts_uvmat': splits a file name in root and indices and recognize file naming convention.
     1052 * 'filter_tps';...% find the thin plate spline coefficients for interpolation-smoothing.
     1053 * 'find_field_cells';...% group the variables of a nc-formated Matlab structure into 'fields' with common dimensions.
     1054 * find_field_cells': test field structure for input in proj_field and plot_field, group the variables  into 'fields' with common dimensions.
     1055 * 'find_file_series';...%check the content of an input file and find the corresponding file series.
     1056 * 'find_imadoc';...% find the <!ImaDoc> XML file associated with a given input file.
    10571057 * 'fullfile_uvmat';...%creates a file name from a root name and indices.
    10581058 * 'get_file_series';...% determine the list of file names and file indices for functions called by 'series'.
    1059  * 'get_file_type': determine info about a file (image, multimage, civdata,...)
    1060  * 'griddata_uvmat';...%make 2D linear interpolation using griddata, with input appropriate for both Matlab 6.5 and 7
    1061  * 'hist_update';...%  update of a current global histogram by inclusion of a new field
    1062  * 'imadoc2struct';...%convert the image documentation file <!ImaDoc> into a Matlab structure
    1063  * 'interp2_uvmat';...% linearly interpolate an image or scalar defined on a regular grid
    1064  * '!ListDir';... scan the structure of the directory tree (for dataview.m)
    1065  * 'mask_proj';...% restrict input fields to a mask region, set to 0 outside
     1059 * 'get_file_type': determine info about a file (image, multimage, civdata,...).
     1060 * 'griddata_uvmat';...%make 2D linear interpolation using griddata, with input appropriate for both Matlab 6.5 and 7.
     1061 * 'hist_update';...%  update of a current global histogram by inclusion of a new field.
     1062 * 'imadoc2struct';...%convert the image documentation file <!ImaDoc> into a Matlab structure.
     1063 * 'interp2_uvmat';...% linearly interpolate an image or scalar defined on a regular grid.
     1064 * '!ListDir';... scan the structure of the directory tree (for dataview.m).
     1065 * 'mask_proj';...% restrict input fields to a mask region, set to 0 outside.
    10661066 * 'peaklock';...%
    1067  * 'phys_XYZ';...% transform coordinates from pixels to phys
    1068  * 'px_XYZ';...% transform coordiantes from phys to pixels
    1069  * 'read_civxdata';...reads CIVx data from NetCDF files
    1070  * 'read_civdata';... reads new civ data from NetCDF files
    1071  * 'read_geometry_calib';... read data on the GUI geometry_calib
    1072  * 'read_imatext';...%read .civ files (obsolete, but can be adapted to other text documentation files)
    1073  * 'read_xls';...%read excel files containing the list of the experiments
    1074  * 'reinit';...% suppress the personal parameter file 'uvmat_perso.mat'
    1075  * 'set_col_vec';...% sets the color code for vectors depending on a scalar and input parameters (used for plot_field)
    1076  * 'set_subdomains';...% sort a set of points defined by scattered coordinates in subdomains, as needed for tps interpolation
    1077  * 'tps_coeff';...% calculate the thin plate spline (tps) coefficients
    1078  * 'tps_coeff_field';...% calculate the thin plate spline (tps) coefficients with subdomains for a field structure
     1067 * 'phys_XYZ';...% transform coordinates from pixels to phys.
     1068 * 'px_XYZ';...% transform coordiantes from phys to pixels.
     1069 * 'read_civxdata';...reads CIVx data from NetCDF files.
     1070 * 'read_civdata';... reads new civ data from NetCDF files.
     1071 * 'read_geometry_calib';... read data on the GUI geometry_calib.
     1072 * 'read_imatext';...%read .civ files (obsolete, but can be adapted to other text documentation files).
     1073 * 'read_xls';...%read excel files containing the list of the experiments.
     1074 * 'reinit';...% suppress the personal parameter file 'uvmat_perso.mat'.
     1075 * 'set_col_vec';...% sets the color code for vectors depending on a scalar and input parameters (used for plot_field).
     1076 * 'set_subdomains';...% sort a set of points defined by scattered coordinates in subdomains, as needed for tps interpolation.
     1077 * 'tps_coeff';...% calculate the thin plate spline (tps) coefficients.
     1078 * 'tps_coeff_field';...% calculate the thin plate spline (tps) coefficients with subdomains for a field structure.
    10791079 * 'tps_eval';... %calculate the thin plate spline (tps) interpolation at a set of points
    1080  * 'tps_eval_dxy';...% calculate the derivatives of thin plate spline (tps) interpolation at a set of points (limited to the 2D case)
    1081  * 'uigetfile_uvmat';... browser, and display of directories, faster than the Matlab fct uigetfile
     1080 * 'tps_eval_dxy';...% calculate the derivatives of thin plate spline (tps) interpolation at a set of points. (limited to the 2D case).
     1081 * 'uigetfile_uvmat';... browser, and display of directories, faster than the Matlab fct uigetfile.
    10821082 * 'update_imadoc';...  %update the XML file <!ImaDoc>.
    1083  * 'update_waitbar';... update the waitbar display, used for ACTION functions in the GUI 'series'
     1083 * 'update_waitbar';... update the waitbar display, used for ACTION functions in the GUI 'series'.
    10841084
    10851085=== series functions ===
    1086  * 'aver_stat': calculate field average over a time series
     1086 * 'aver_stat': calculate field average over a time series.
    10871087 * 'avi2png': copy an avi movie to a series of B/W .png images (take the average of green and blue color components)
    1088  * 'check_data_files': check the existence, type and status of the files selected by series.fig
     1088 * 'check_data_files': check the existence, type and status of the files selected by series.fig.
    10891089 * 'ima_levels': rescale the image intensity to reduce strong luminosity peaks (their blinking
    1090  * 'civ_input': function associated with the GUI 'civ_input.fig' to set the input parameters for civ_series
    1091  * 'civ_series': PIV function activated by the general GUI series (replaces civ)
    1092  * 'merge_proj': concatene several fields from series, can project them on a regular grid in phys coordinates
    1093  * 'sub_background': subtract a sliding background to an image series
    1094  * 'time_series': extract a time series after projection on an object (points , line..)
     1090 * 'civ_input': function associated with the GUI 'civ_input.fig' to set the input parameters for civ_series.
     1091 * 'civ_series': PIV function activated by the general GUI series (replaces civ).
     1092 * 'merge_proj': concatene several fields from series, can project them on a regular grid in phys coordinates.
     1093 * 'sub_background': subtract a sliding background to an image series.
     1094 * 'time_series': extract a time series after projection on an object (points , line..).
    10951095
    10961096=== transform functions ===
    1097  * 'ima_filter': low-pass filter of an image (builtin filtering parameter)
    1098  * 'ima_remove_background': removes backgound from an image (using the local minimum)
    1099  * 'ima_remove_particles': removes particles from an image (keeping the local minimum)
     1097 * 'ima_filter': low-pass filter of an image (builtin filtering parameter).
     1098 * 'ima_remove_background': removes backgound from an image (using the local minimum).
     1099 * 'ima_remove_particles': removes particles from an image (keeping the local minimum).
    11001100 * 'FFT2_detrend': calculate the 2D spectrum of the input scalar after removing the linear trend (requires the Matlab image processing toolbox).
    1101  * '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'
     1101 * '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'.
    11021102 * 'phys_polar': this transforms the fields to polar coordinates, radius in abscissa (same unit as x, y) and azimuth in ordinate (unit =degree).