# Changes between Version 61 and Version 62 of UvmatHelp

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

--

### Legend:

Unmodified
 v61 === 1.3 Documentation and help === The present on-line document is the reference document for the version currently available on the svn server. Features not yet implemented or tested (in particular 3D features) are marked by **. The document is accessible within Matlab by help buttons in the GUIs. A short comment about  each GUI ''uicontrol'' (push buttons, edit boxes, menus..), as well as the tag name of this ''uicontrol'', is provided as a tool tip window by moving the mouse over it. In the present help document, the tag of a GUI uicontrol is quoted as '''[uicontrol tag]''', a file name in the package is quoted as ''fct name.m'', and commands on the Matlab workspace as  '>> command’. The present on-line document is the reference document for the version currently available on the svn server. Features not yet implemented or tested (in particular 3D features) are marked by **. The document is accessible within Matlab by help buttons in the GUIs. A short comment about  each GUI ''uicontrol'' (push buttons, edit boxes, menus..), as well as the tag name of this ''uicontrol'', is provided as a tool tip window by moving the mouse over it. In the present help document, the tag of a GUI uicontrol is quoted as '''[uicontrol tag]''', a file name in the package is quoted as ''fct name.m'', and commands on the Matlab workspace as  '>> command’. Information is also provided as comments in each function. Type '>>help fct_name'  to get it, or open it with an editor. 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. ---- == 2 Overview of the GUI uvmat.fig == === 2.1 Opening the GUI === * '''[Run] ''': * '''[Field series]''': gives access to the GUI [#a10-Processingfieldseries '''series.fig'''] for processing field series. * '''[CivX(Fortran)]''':  gives access to the GUI [#a11-PIV:ParticleImagingVelocimetry '''civ.fig'''] for Particle Imaging Velocimetry (CivX version in Fortran). * '''[Field series]''': gives access to the GUI [#a10-Processingfieldseries "''series.fig''"] for processing field series. * '''[CivX(Fortran)]''':  gives access to the GUI [#a11-PIV:ParticleImagingVelocimetry "''civ.fig''"] for Particle Imaging Velocimetry (CivX version in Fortran). * '''[Help] ''': displays this help file using the Matlab browser. * '''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. -------------------- == 3 Input files and navigation with uvmat == === 3.1  Input data formats === === 3.2 Selecting fields from CIV === To update... The package uvmat recognizes the NetCDF fields obtained from the CIVx software.  This includes the velocity fields and their spatial derivatives, as well as information about the CIV processing (image correlation values and flags). The vorticity, divergence, or strain are read in the same NetCDF files, but are available only after a PATCH operation has been run in the CIVx software,  see [#a11-PIV:ParticleImagingVelocimetrys section 11]. To update... The package uvmat recognizes the NetCDF fields obtained from the CIVx software.  This includes the velocity fields and their spatial derivatives, as well as information about the CIV processing (image correlation values and flags). The vorticity, divergence, or strain are read in the same NetCDF files, but are available only after a PATCH operation has been run in the CIVx software,  see [#a11-PIV:ParticleImagingVelocimetrys section 11]. -'''Double index series: ''' they are labeled by two integer indices i and j. This double index labeling is commonly used for bursts of images (index j or equivalently a letter appendix 'a', 'b') separated by longer time intervals (index i).  It can be also used for successive volume scanning by a laser sheet, with index j representing the position in the volume and i the time. For a set of indexed movies (or multimage  files), the index i labels the files while the index j labels the frames  within a file. -'''Pair  indexing:''' new file series can result from the processing of primary series. For a sequential processing limited to a single file, the output index naturally reproduces  the input index. Other processing functions involve pairs of input files, for instance Particle Imaging Velocity from image pairs. In a simple series, the result from the two primary fields *_i1 and *_i2 is then labeled as *_i1-i2 with the file extension indicating  the output format. More generally,  the result from any processing involving a range of primary indices from  i1 to i2  is  labeled as _i1-i2.  If i1=i2 or j1=j2, the two indices are merged in a single label i, or j respectively. -'''Nomenclature types:''' The ''nomenclature type'' is defined as the character string representing the index (or indices) for the first file  in the series, for instance '_1' for a ''single indexing'' and '_1-2' for a  ''pair indexing'', '_1_1' for a ''double index'' series. The second index j can be also represented as a letter suffix, for instance '01a'.  For a field series in a single file, like a movie, the  nomenclature type is defined as '*'. The functions ''fullfile_uvmat.m'' generates a file name from a root name, four numerical indices i1,i2,j1,j2 and  the ''nomenclature type''. The reverse operation, splitting a name into a root and indices while detecting the ''nomenclature type'', is performed by the function ''fileparts_uvmat.m''. The function ''find_file_series.m'' is also needed to scan the whole file series, leading to a possible adjustement of the nomenclature type (for instance distinguishing '_001' from '_1' when the file with index 1000 has been opened). Once the nomenclature type has been detected by the browser of '''uvmat.fig''', it is displayed in the edit box '''[!NomType]''' and used to generate all the file names when the series is scanned. -'''Pair  indexing:''' new file series can result from the processing of primary series. For a sequential processing limited to a single file, the output index naturally reproduces  the input index. Other processing functions involve pairs of input files, for instance Particle Imaging Velocity from image pairs. In a simple series, the result from the two primary fields *_i1 and *_i2 is then labeled as *_i1-i2 with the file extension indicating  the output format. More generally,  the result from any processing involving a range of primary indices from  i1 to i2  is  labeled as _i1-i2.  If i1=i2 or j1=j2, the two indices are merged in a single label i, or j respectively. -'''Nomenclature types:''' The ''nomenclature type'' is defined as the character string representing the index (or indices) for the first file  in the series, for instance '_1' for a ''single indexing'' and '_1-2' for a  ''pair indexing'', '_1_1' for a ''double index'' series. The second index j can be also represented as a letter suffix, for instance '01a'.  For a field series in a single file, like a movie, the  nomenclature type is defined as '*'. The functions ''fullfile_uvmat.m'' generates a file name from a root name, four numerical indices i1,i2,j1,j2 and  the ''nomenclature type''. The reverse operation, splitting a name into a root and indices while detecting the ''nomenclature type'', is performed by the function ''fileparts_uvmat.m''. The function ''find_file_series.m'' is also needed to scan the whole file series, leading to a possible adjustement of the nomenclature type (for instance distinguishing '_001' from '_1' when the file with index 1000 has been opened). Once the nomenclature type has been detected by the browser of '''uvmat.fig''', it is displayed in the edit box '''[!NomType]''' and used to generate all the file names when the series is scanned. === 3.4 Navigation among field indices === * '''.fig''' Matlab figures represent plots but also Graphic User Interfaces (GUI). In that case Matlab functions (callbacks) are attached to the graphic objects in the figure and can be activated by the mouse. Matlab figures can be directly opened by the browser of '''uvmat.fig'''. * ''''.civ' ''' (obsolete)  ascii text file containing the list of image times and the scaling in pixels/cm. This is an obsolete version of the xml image documentation file. It is stored in the same directory as the corresponding series of images, with name ''root .civ'' (instead of {root.xml}). It is automatically sought by '''uvmat.fig''' and '''civ.fig''', in the absence of an xml file !ImaDoc. (it is read by the function ''read_imatext.m''). The following example is from an experience with 19 bursts of 4 images, named aa001a,aa001b,aa001c,aa001d,aa002a,aa002b,...,aa019c,aa019d, with an extension .png. The corresponding .civ file is named aa.civ. Comments (not included in the file) are indicated with %... * ''''.civ' ''' (obsolete)  ascii text file containing the list of image times and the scaling in pixels/cm. This is an obsolete version of the xml image documentation file. It is stored in the same directory as the corresponding series of images, with name ''root .civ'' (instead of {root.xml}). It is automatically sought by '''uvmat.fig''' and '''civ.fig''', in the absence of an xml file !ImaDoc. (it is read by the function ''read_imatext.m''). The following example is from an experience with 19 bursts of 4 images, named aa001a,aa001b,aa001c,aa001d,aa002a,aa002b,...,aa019c,aa019d, with an extension .png. The corresponding .civ file is named aa.civ. Comments (not included in the file) are indicated with %... {{{ '''Mirror data trees''' can be created to process a source data set in read only mode, to preserve the safety of the data source, and to allow several users to work in parallel without interference. This is done by opening the source Campaign with the menu bar option Open/browse campaign from uvmat. Select the source campaign directory with the browser. Then the GUI 'browse_data' appears. Then press 'create_mirror' and select the directory which must contain the mirror Campaign. A set of directory is then created for each experiment, in which are created symbolic  links to the !DataSeries directories. Data processing then results in real !DataSeries directories created in the Experiment directory.  An xml mirror.xml is created inside the directory mirror to mark its role; This xml file contains  the path and name of the source directory under the label . The mirror directory can be regularly updated by pressing the button 'update_mirror'. ---------------------------- == 4 Scalar and vector display == The uvmat interface primarily reads and visualises two-dimensional fields, which can be images or scalars, or vector fields. === 4.6 Succession of operations: === The following succession of operations is performed by '''uvmat.fig''': The following succession of operations is performed by '''uvmat.fig''': -'''File identification:''' the nomenclature type and file type (for instance image, movie, or Netcdf file) are identified from the opened file (using the function ''find_file_series.m''). -'''File Reading:''' the input field is first read from the input file by the Matlab function ''read_field.m''. -'''Second file reading:'''  The second input field is similarly read if selected. Note that it is kept in memory, so it is not read again if the file is unchanged (this is useful in the case of substraction of a fixed background for instance). -'''Transform:''' by default the 'phys' option transforms each of the input fields from pixel to physical coordinates. This operation can also combine two input field structures into a single field structure. -'''Histogram:''' This is obtained from the input field in transformed coordinates, or if applicable from the fields resulting from the two input fields. -'''Second file reading:'''  The second input field is similarly read if selected. Note that it is kept in memory, so it is not read again if the file is unchanged (this is useful in the case of substraction of a fixed background for instance). -'''Transform:''' by default the 'phys' option transforms each of the input fields from pixel to physical coordinates. This operation can also combine two input field structures into a single field structure. -'''Histogram:''' This is obtained from the input field in transformed coordinates, or if applicable from the fields resulting from the two input fields. -'''Projection:''' on  the projection object selected in the menu '''[!ListObject_1]''', see [#ProjObject section 6]. A second projection, on the object selected by '''[!ListObject]''', can be plotted in the ancillary figure '''view_field.fig'''. Projection is performed by the function ''proj_field.m''. -'''Field calculation:''' a scalar can be calculated after projection, as selected by the menu '''[Fields]'''. -'''Field comparison''': when two fields of the same nature are introduced, the difference is taken. This is skipped if the transform function has already led to a single field. -'''Field calculation:''' a scalar can be calculated after projection, as selected by the menu '''[Fields]'''. -'''Field comparison''': when two fields of the same nature are introduced, the difference is taken. This is skipped if the transform function has already led to a single field. -'''Plotting:''' plot the results of projection, using the function ''plot_field.m''. ---------------------------- == 5- Field structures == === 5.1 Griding of data === 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 position vector ${\bf r}$ is expressed in the form, (see http://coriolis.legi.grenoble-inp.fr/spip.php?article73) $$\label{sol_gene} f({\bf r})=\sum S_i \phi({\bf|r-r_i}|)+a_0+a_1x+a_2y\;$$ where ${\bf r_i}$ are the positions of the measurement points (the ''centres''). Each ''centre'' can be viewed as the source of an axisymmetric field  $\phi$ of the form $\phi(r)=r^2\log (r)$. The weights $S_i$ and the linar coefficients $a_0,a_1,a_2$ are the thin plate shell (tps) coefficients which determine the interpolated value at any point. The spatial derivatives are similarly obtained at any point by analytical differentiation of the source functions $\phi(r)$. These tps weights, with the corresponding centre coordinates, therefore contain all the information needed for interpolation at any point. We call that a ''tps field representation''. $$\label{sol_gene} f({\bf r})=\sum S_i \phi({\bf|r-r_i}|)+a_0+a_1x+a_2y\;$$ where ${\bf r_i}$ are the positions of the measurement points (the ''centres''). Each ''centre'' can be viewed as the source of an axisymmetric field  $\phi$ of the form $\phi(r)=r^2\log (r)$. The weights $S_i$ and the linar coefficients $a_0,a_1,a_2$ are the thin plate shell (tps) coefficients which determine the interpolated value at any point. The spatial derivatives are similarly obtained at any point by analytical differentiation of the source functions $\phi(r)$. These tps weights, with the corresponding centre coordinates, therefore contain all the information needed for interpolation at any point. We call that a ''tps field representation''.^ Because 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. In summary, the ''field structure'' is specified by the following elements: * (optional) '''ListGlobalAttribute:''' list (cell array of character strings) of the names of global attributes  Att_1, Att_2... * (mandatory) '''ListVarName:''' list of the variable names Var_1, Var_2....(cell array of character strings). * (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. * (optional) '''VarAttribute:''' cell array of structures of the form !VarAttribute{ivar}.key=value, defining an attribute tag name and value for the variable #ivar (variable number in the list !ListVarName]). * (optional) '''!ListGlobalAttribute:''' list (cell array of character strings) of the names of global attributes  Att_1, Att_2... * (mandatory) '''!ListVarName:''' list of the variable names Var_1, Var_2....(cell array of character strings). * (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. * (optional) '''!VarAttribute:''' cell array of structures of the form !VarAttribute{ivar}.key=value, defining an attribute tag name and value for the variable #ivar (variable number in the list !ListVarName]). * .Att_1, Att_2... : values of the listed global attributes. * .Var_1, .Var_2...: variables arrays whose names are listed in !ListVarName. In some cases, it is useful to define the field object independently from its data content. Then the variables .Var1... are replaced by the lists of dimension names and values. * '''ListDimName:''' list of dimension names (cell array of character strings) * '''DimValue:''' array of dimension values corresponding to !LisDimName. * '''!ListDimName:''' list of dimension names (cell array of character strings) * '''!DimValue:''' array of dimension values corresponding to !LisDimName. The following temporary information is added to manage projection and field substraction oerations, which must be done in general after projection: * 'nb_tps': dimension of the index for the tps centres * 'nb_subdomain' denotes the dimension for the subdomain index for tps coefficients ---------------------------- == 6- Projection objects == #ProjObject === 6.1 Definition and editing with the uvmat interface === These are geometrical objects used to define cuts along lines or planes, to interpolate fields on a regular grid, to restrict the analysis or visualisation to field subregions. When a 2D or 3D field is opened by uvmat, a default projection plane object is created. New objects are created by the menu bar command  '''[Projection object]''' in '''uvmat.fig'''.  The creation of a new object ('''points''', '''line'''....) can be initiated by selecting the corresponding item in the menu. Alternatively, an existing xml object file can be opened by selecting the menu option '''[browse...]'''. These are geometrical objects used to define cuts along lines or planes, to interpolate fields on a regular grid, to restrict the analysis or visualisation to field subregions. When a 2D or 3D field is opened by uvmat, a default projection plane object is created. New objects are created by the menu bar command  '''[Projection object]''' in '''uvmat.fig'''.  The creation of a new object ('''points''', '''line'''....) can be initiated by selecting the corresponding item in the menu. Alternatively, an existing xml object file can be opened by selecting the menu option '''[browse...]'''. In each case an auxiliary GUI '''set_object.fig''' describing the object properties appears, see next [#a6.2Objectproperties sub-section] for their definitions. This GUI can be directly edited and object coordinates can be set by mouse drawing on the plot. In the latter case, refresh the plots by pressing''' [PLOT] ''' in '''set_object.fig''' . Objects can be saved as xml files with the button ''' [SAVE]''' of '''set_object.fig'''. * ''' Angle: ''': three component rotation vector which defines the orientation of the object coordinate axis, for 'plane' and 'volume'. In 2D, this rotation vector has only one component along z, defining a rotation angle in the plane (expressed in degrees). This applies also to the main axis of 'ellipse' and 'rectangle'. In 3D, line objects ('line', 'polyline','rectangle','polygon','ellipse') are assumed contained in a plane, and 'Angle' defines the orientation of this plane. * ''' RangeX: ''', ''' RangeY: ''', ''' RangeZ: ''':bounds defining a range of projection along each coordinate with respect to the object. These ranges have one or two values depending on the object type. * 'points': the only relevant range is RangeX, with one value (a radius around the point). * 'lines': the only relevant range is RangeY, with one value, a radius transverse to the line. * 'polyline' and 'polygon' ranges are not relevant. * 'rectangle','ellipse': RangeX and RangeY (one value) define the half length and half width respectively. In 3D, RangeZ may set a range of projection transverse to the plane containing the object. * 'plane': RangeX and RangeY (two values each) may restrict a region in the coordinates of the plane. In 3D, RangeZ may set a range of projection transverse to the plane. * 'volume': RangeX, RangeY, rangeZ (two values each) define a selected volume in the data set. * ''' RangeX: ''', ''' RangeY: ''', ''' RangeZ: ''':bounds defining a range of projection along each coordinate with respect to the object. These ranges have one or two values depending on the object type. * 'points': the only relevant range is RangeX, with one value (a radius around the point). * 'lines': the only relevant range is RangeY, with one value, a radius transverse to the line. * 'polyline' and 'polygon' ranges are not relevant. * 'rectangle','ellipse': RangeX and RangeY (one value) define the half length and half width respectively. In 3D, RangeZ may set a range of projection transverse to the plane containing the object. * 'plane': RangeX and RangeY (two values each) may restrict a region in the coordinates of the plane. In 3D, RangeZ may set a range of projection transverse to the plane. * 'volume': RangeX, RangeY, rangeZ (two values each) define a selected volume in the data set. * ''' DX: ''', ''' DY: ''', ''' DZ: ''':mesh  along each coordinate defining a grid for interpolation. === 6.3 Projection modes === Each field variable yields a corresponding variable with the same name in the projected field. in addition integral quantities (circulation, flux...) can be calculated. The result of projection depends on the object type, the nature of the coordinates, the ''Role'' of field variables and on the projection mode !ProjMode: Each field variable yields a corresponding variable with the same name in the projected field. in addition integral quantities (circulation, flux...) can be calculated. The result of projection depends on the object type, the nature of the coordinates, the ''Role'' of field variables and on the projection mode !ProjMode: * ''' !ProjMode = 'projection':  '''  this is a normal projection  of the field data in a range of action around the object, as defined by the parameters 'RangeX', 'RangeY', "RangeZ'. The projection of an input variable defined on unstructured coordinates therefore remains unstructured. By contrast, an input variable defined on a regular grid always yields a projected variable on a regular grid (for instance on a line or plane). Error flags ? * 'points': each field variable is averaged in a sphere of radius RangeX (a single value) around each projection point and attributed to this point position. An ancillary variable U_nbval(i) indicates the number of (non-false) data found around each point. Ancillary data and warning flags are not projected on points. * 'line': for scattered coordinates, each initial data point within a range ''RangeY'' on each side of the line is normally projected on the line, keeping its field values. For grid lin interpolation and averaging.  Vector quantities are furthermore projected on the line as longitudinal (X) and normal (Y) components. The line length and mean value of each variable along the line is also calculated (giving access to circulation and flux). Ancillary data and warning flags are not projected on points. * 'points': each field variable is averaged in a sphere of radius RangeX (a single value) around each projection point and attributed to this point position. An ancillary variable U_nbval(i) indicates the number of (non-false) data found around each point. Ancillary data and warning flags are not projected on points. * 'line': for scattered coordinates, each initial data point within a range ''RangeY'' on each side of the line is normally projected on the line, keeping its field values. For grid lin interpolation and averaging.  Vector quantities are furthermore projected on the line as longitudinal (X) and normal (Y) components. The line length and mean value of each variable along the line is also calculated (giving access to circulation and flux). Ancillary data and warning flags are not projected on points. * 'plane': similar as line, RangeZ in 3D. RangeX and RangeY used to set bounds. All data are projected in this mode. * 'volume': used to set bounds in 3D within a box [RangeX, RangeY, RangeZ].  All data are projected in this mode. *  no action on 'polyline', 'rectangle', 'polygon', 'ellipse'. * no action on 'polyline', 'rectangle', 'polygon', 'ellipse'. * ''' !ProjMode 'interp_lin': '''  Linear interpolation of scalar and vector field variables, after exclusion of false data (marqued by error flag). Ancillary data and warning flags are not projected in this mode. Gridded data are interpolated by ..., while fields with scattered coordinates are projected with the Matlab function .... Note that this function provides interpolation only within the convex hull of the initial data set, attributing 'NaN' (undefined) field values out of this domain. To avoid problems with further data processing, uvmat transforms NaN values into zeros, but mark them with an error flag FF=1. * 'points': linear interpolation on each point of the object. * 'line','polyline', 'rectangle', 'polygon', 'ellipse': linear interpolation on points regularly spaced on the line, with mesh DX. The X coordinate is the distance following the line, with an origin at the starting point(the first point in 'line','polyline','polygon',the lower left corner for rectangle, the point along the main axis for an ellipse). The line length and mean value of each variable along the line is also calculated (giving access to circulation and flux). * 'plane': linear interpolation on a regular grid with meshes DX, DY and ortigin at (X,Y)=(0,0). This grid is bounded by the two values of RangeX and RangeY along X and Y respectively. * ''' !ProjMode  'interp_tps':  '''  This behaves with different objects line 'interp_lin', but using the more precise thin spline shell method. This is particularly usefull to calculate spâtial field derivatives. Furthermore this method provides data exrtrapolation outside the initial convex hull (although it is not reliable at large distances). This mode does require a previous calculation of tps weights, see [#a5.1Gridingofdata section 5.1], so it does not act on the initial field cells with scattered coordinates. This is done by uvmat if tps projection is requested. Gridded data are linearly interpolated (to clarify...). * 'plane': linear interpolation on a regular grid with meshes DX, DY and ortigin at (X,Y)=(0,0). This grid is bounded by the two values of RangeX and RangeY along X and Y respectively. * ''' !ProjMode  'interp_tps':  '''  This behaves with different objects line 'interp_lin', but using the more precise thin spline shell method. This is particularly usefull to calculate spâtial field derivatives. Furthermore this method provides data exrtrapolation outside the initial convex hull (although it is not reliable at large distances). This mode does require a previous calculation of tps weights, see [#a5.1Gridingofdata section 5.1], so it does not act on the initial field cells with scattered coordinates. This is done by uvmat if tps projection is requested. Gridded data are linearly interpolated (to clarify...). * ''' !ProjMode 'inside' and 'ouside '''': defined only for closed lines: rectangle, polygon, ellipse. For each field U, its probability distribution function Uhist  inside, or respectively outside,  the line is calculated, as well as the mean Umean. other statistics... * ''' !ProjMode 'none', 'mask_inside', 'mask_outside': ''' no projection operation. The object is used solely for plotting purpose, to show a boundary or to prepare a mask, inside or outside a closed line, see [#a9-Masksandgrids section 9]). Operations, for instance 'vort', 'div' are performed after interpolation. Similarly for field difference, which requires interpolation to compare fields defined at different positions. Field variables to be substracted are initially marqued by an attribute 'CheckSub'. Operations, for instance 'vort', 'div' are performed after interpolation. Similarly for field difference, which requires interpolation to compare fields defined at different positions. Field variables to be substracted are initially marqued by an attribute 'CheckSub'. === 6.4 Object representation === Projections objects are drawn in magenta color when they are selected for creation or edition, and in blue otherwise. * 'points' are represented by dots surrounded by a dashed circle showing the range of projection. * 'line' , 'polyline' are plotted as lines, surrounded by two dashed lines showing the range of projection, when applicable (i.e. not in the case !ProjMode='interp'). * 'polygon', 'rectangle', 'ellipse' are drawn. In the case ProjMode ='inside' or 'outside' the corresponding area is painted in magenta (or blue when they are not selected). * 'plane' are shown by their axis. These axis are limited to their range of selection  (RangeX and RangeY) when applicable. Otherwise they end at the edge of the figure with an arrow. ** * 'points' are represented by dots surrounded by a dashed circle showing the range of projection. * 'line' , 'polyline' are plotted as lines, surrounded by two dashed lines showing the range of projection, when applicable (i.e. not in the case !ProjMode='interp'). * 'polygon', 'rectangle', 'ellipse' are drawn. In the case ProjMode ='inside' or 'outside' the corresponding area is painted in magenta (or blue when they are not selected). * 'plane' are shown by their axis. These axis are limited to their range of selection  (RangeX and RangeY) when applicable. Otherwise they end at the edge of the figure with an arrow. ** * 'volume' are shown like 'plane', except that they are painted in magenta (or blue) ** 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. ---------------------------- == 8- Geometric calibration == === 8.1 Generalities === 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 coordinate of the first lower left pixel centre is therefore (1/2,1/2). Note that the Y axis is directed upward, while the corresponding image index j increases downward. Therefore, denoting npy the number of pixels along Y, the (X,Y) coordinates of a pixel indexed (i,j) are [[BR]] X=i-1/2, Y=npy-j+1/2. 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 coordinate of the first lower left pixel centre is therefore (1/2,1/2). Note that the Y axis is directed upward, while the corresponding image index j increases downward. Therefore, denoting npy the number of pixels along Y, the (X,Y) coordinates of a pixel indexed (i,j) are [[BR]] X=i-1/2, Y=npy-j+1/2. The ''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: The coefficients are recorded in the xml element as follows: * : type of calibration ('rescale', 'linear', '3D...') * : focal length along each coordinate of the image sensor, expressed in pixel interval. * : position coordinates of the optical axis on the * : coefficient of quadratic deformation (=1 for the options calib_lin and calib_rescale) * : coordinate unit in physical space. * : translation, (Tz=1 for the options calib_lin and calib_rescale) * : 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. * 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) * : 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'') * : 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) * set of the point coordinates used for calibration * [x y z X Y] , where x,y,z are the physical coordinates of each point, X Y its image coordinates * nbre of slices for the first field  index i (multilevel case), =1 by default. * nbre of slices for the second index j (volume scan), =1 by default. * [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]. *    step distance between planes, or * step angle for angular scan. * : type of calibration ('rescale', 'linear', '3D...') * : focal length along each coordinate of the image sensor, expressed in pixel interval. * : position coordinates of the optical axis on the * : coefficient of quadratic deformation (=1 for the options calib_lin and calib_rescale) * : coordinate unit in physical space. * : translation, (Tz=1 for the options calib_lin and calib_rescale) * : 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. * 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) * : 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'') * : 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) * set of the point coordinates used for calibration * [x y z X Y] , where x,y,z are the physical coordinates of each point, X Y its image coordinates * nbre of slices for the first field  index i (multilevel case), =1 by default. * nbre of slices for the second index j (volume scan), =1 by default. * [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]. *    step distance between planes, or * step angle for angular scan. == 9- Masks and grids == === 9.1 Masks === 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]. Mas files are automatically recognised by '''uvmat.fig''' and '''civ.fig''' if they are named [filebase '_xxmask_' 'filenumber' '.png'], where xx is the number of masks (nbslices) used when the series of fields corresponds physically to a set of nbslices positions. The mask filenumber used is the image field number modulo nbslices. Use xx=1 in the default case of a fixed position and a single mask. Masks can be made by pressing the menu bar Tools/make mask on the GUI uvmat. The mask is created interactively with the mouse on the current image. 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].  Mas files are automatically recognised by '''uvmat.fig''' and '''civ.fig''' if they are named [filebase '_xxmask_' 'filenumber' '.png'], where xx is the number of masks (nbslices) used when the series of fields corresponds physically to a set of nbslices positions. The mask filenumber used is the image field number modulo nbslices. Use xx=1 in the default case of a fixed position and a single mask. Masks can be made by pressing the menu bar Tools/make mask on the GUI uvmat. The mask is created interactively with the mouse on the current image. First 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. The 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. ---------------------------- == 10 - Processing field series == === 10.1 The GUI series.fig === By 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. ---------------------------- == 11 - PIV: Particle Imaging Velocimetry == === 11.1 Overview === |   |  '''        civ2'''          | '''interp2'''  |        '''filter2 '''          | | dim.  |        nb_vectors2  |        nb_vec2_patch  |        nb_vec2_patch  | |x          |vec2_X          |vec2_patch_X  |        vec2_patch_X | |y          |         vec2_Y  |        vec2_patch_Y |         vec2_patch_Y | |z          |        vec2_Z |         vec2_patch_Z  |        vec2_patch_Z | |u                  |vec2_U |         vec2_patch0_U  |        vec2_patch_U | |v                   |vec2_V          |vec2_patch0_V  |        vec2_patch_V | |w           |        vec2_W          |vec2_patch0_W|          vec2_patch_W | |correlation  |        vec2_C  |          |          | |warning flag  |        vec2_F |          |          | |false flag  |        vec2_FixFlag |          |          | |du/dx  |         |vec2_patch0_DUDX          |vec2_patch_DUDX          | |du/dy  |         |vec2_patch0_DUDY          |vec2_patch_DUDY          | |dv/dx  |         |vec2_patch0_DVDX          |vec2_patch_DVDX          | |dv/dy  |         |vec2_patch0_DVDY          |vec2_patch_DVDY          | ---- --------------- == 12 Tridimensional features:(to update **) == === 12-1 Multilevel image scanning === === 12-2 Volume image scanning === === 12-3 3D3C PIV ** === === 12-3 3D3C PIV ** === This is performed by the GUI '''civ_3D.fig'''. The program requires input volume images .vol. These are images in the  png format, where  npz slices are concatenated along the y direction, forming a composite image of dimension (npy x npz, npx) from the images (npy x npx). These volume images can be created by the function {ima2vol.m} in {/series}. ---------------------------- == 13 Editing xml files with the GUI editxml == 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. 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. == Appendix: overview of the package functions == ---------------------------- == 14-Appendix: overview of the package functions == === Master GUI === * 'uvmat';...% master function for file scanning and visualisation of 2D fields