# Changes between Version 56 and Version 57 of UvmatHelp

Ignore:
Timestamp:
Jun 10, 2013, 10:01:04 PM (7 years ago)
Comment:

--

### Legend:

Unmodified
 v56 -'''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 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 file indices === -'''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 === The field indices can be incremented or decremented by the push buttons  '''[runplus]''' ( '''+''') and  '''[runmin]''' ('''-''') 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]'''. If this box is blank (or does not contain a number) the next available file is opened. == 5- Field structures == === 5.1 Griding of data === Physical fields can be defined either on regular grids, either scattered on an unstructured set of positions. Some measurements techniques, like PIV or particle tracking, provided unstructured data, while most methods of analysis require data  on a regular grid. This can be done by interpolation, defining a projection on a plane (with ProjMode='interp', see  [#a6-Projectionobjects: next section]).  The three possibilities of griding are defined as follows: Physical fields can be defined either on regular grids, either scattered on an unstructured set of positions. Some measurements techniques, like PIV or particle tracking, provided unstructured data, while most methods of analysis require data  on a regular grid. This can be done by interpolation, defining a projection on a plane (with !ProjMode='interp...', see  [#ProjObject next section]).  The three possibilities of griding are defined as follows: -'''Regular grid:''' 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. Each field is then a multi-dimensional array 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. -'''Structured orthogonal grid''': 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 [#a7.1TheNetCDFformat: section 7.1]). 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 [#a7.1TheNetCDFformat section 7.1]). -'''Unstructured coordinates:''' 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. 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 U(nb_point),V(nb_point) for each vector component, or alternatively by V(nb_points, j, i), where i, j possibly stand for vector or tensor components. -'''Thin plate shell (tps) interpolation:''' 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} ${\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 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. ^ 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''. 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. === 5.2 Field representation as Matlab structure === The uvmat package represents data as ''Matlab structures'', a set of data elements characterized by a tag name (char string) and a value. The value can be any Matlab object: number, array, character string or cell, or a structure containing elements in a hierarchical way. Each element is denoted in the form ''Data.tag=value''. The uvmat package represents data as ''Matlab structures'', a set of data elements characterized by a tag name (char string) and a value. The value can be any Matlab object: number, array, character string or cell, or a structure itself, providing a data organisation as hierarchical tree. Each element is denoted in the form ''Data.tag=value''. Data are kept in memory in the GUI uvmat as a Matlab structure, stored as ''!UserData'' in the GUI 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''. This field has a specific organisation, mirroring the structure of netcdf files (see [#a7-Netcdffilesandget_field.fig: section 7]). The field is described by a set of (single or multidimensional) data arrays, called the ''variables''. The ''dimensions'' of these arrays have names, in order to identify correspondance between different arrays. For instance the arrays representing the velocity components U and V must have the same dimensions. A dimension has a specific value, which sets the common size of all arrays sharing this dimension. Field description furthermore involves optional ''attributes'' to document the field data, for instance to specify the role of variables or to provide units. These attributes can be global, or can be attached to a specific variable. This field has a specific organisation, mirroring the structure of netcdf files (see [#a7-Netcdffilesandget_field section 7]). The field is described by a set of (single or multidimensional) data arrays, called the ''variables''. The ''dimensions'' of these arrays have names, in order to identify correspondance between different arrays. For instance the arrays representing the velocity components U and V must have the same dimensions. A dimension has a specific value, which sets the common size of all arrays sharing this dimension. Field description furthermore involves optional ''attributes'' to document the field data, for instance to specify the role of variables or to provide units. These attributes can be global, or can be attached to a specific variable. 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: * '''!FieldRequest'''= ''interp_lin'' or ''interp_tps'' indicates whether lin interpolation  or derivatives by tps is needed to calculate the requested field. * '''!ProjModeRequest'''= ''interp_lin'' or ''interp_tps'' indicates whether lin interpolation  or derivatives by tps is needed to calculate the requested field. * '''Operation''': name (char string) of the operation to be performed to finalise the field cell after projection. * '''!SubCheck'''= 0 /1 indicate that the field must be substracted (second  entry in uvmat) * Campaign: recalls the campaign name * Experiment:  recalls the experiment name(s) of the raw data * DataSeries:  recalls the device name (s), if defined, of the raw data * ObjectStyle: ='points', 'line', 'plane', denotes the style of geometric object on which the data have been 'projected'. For instance a profiler project a physical field along a line. * ObjectCoord:  Coordinates defining a geometric object on which the data have been projected. * !DataSeries:  recalls the device name (s), if defined, of the raw data * !ObjectStyle: ='points', 'line', 'plane', denotes the style of geometric object on which the data have been 'projected'. For instance a profiler project a physical field along a line. * !ObjectCoord:  Coordinates defining a geometric object on which the data have been projected. * ObjectRangeX, ObjectRangeY, ObjectRangeZ : range of action of a projection object along each coordinate, see section 6. * 'long_name':(convention from [unidata->http://www.unidata.ucar.edu:]) a long descriptive name, could be used for labeling plots, for example. If a variable has no long_name attribute assigned, the variable name should be used as a default. * Mesh: suggested step value to discretize the values of the variable, used to define the bins for histograms. * Role: it specifies the role of the variable arrays for plotting or processing programs, see below. if Role is not defined variables are considered by default as 'scalar'. * Unit or 'units' (convention from [unidata->http://www.unidata.ucar.edu:]) : char string giving the unit of a variable, used  in plot axis labels (overset by global attributes 'CoordUnit' and 'TimeUnit' if defined). * 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). -'''The attribute 'Role':''' the following options are used for the attribute 'Role': === 5.4 Field cells: === The 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. * Dimension variables: these are unique unidimensional variable arrays corresponding to a given dimension, leading to a cell with a single variable, dimension 1. This is interpreted as the set of coordinate values associated with this dimension. An alternative possibility, suitable for a coordiante with a constant grid mesh, is a variable array with two values with the same name as a dimension: it then specifies the lower and upper bounds of the coordinate. * Field cell with unstructured coordinates: this is a cell of variables sharing the same set of unstructured coordinates, indicated by the attribute Role=coord_x, coord_y, coord_z. * Field cell with structured coordinates: this is a cell of several variable(s) sharing the same set of dimensions associated with variables. (addditional dimension may indicate for instance a vector component, not associated with a coordinate). * Thin plate shell (tps) field cell: represents a set of coordinates and tps weights in  a way suitable for tps interpolation/filter. The variables of field structures can be grouped into ''field cells'' representing data sharing the same coordinates. 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 sharing common array dimensions, determines their spatial dimension, and idendify the following types of field cells, corresponding to the different kinds of data griding described in [wiki:#a5.1Gridingofdata section 5.1] * '''Dimension variables:''' these are unique unidimensional variable arrays corresponding to a given dimension, leading to a cell with a single variable, dimension 1. This is interpreted as the set of coordinate values associated with this dimension. An alternative possibility, suitable for a coordiante with a constant grid mesh, is a variable array with two values with the same name as a dimension: it then specifies the lower and upper bounds of the coordinate. * '''Field cell with 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). * '''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. * '''Thin plate shell (tps) field cell:''' represents an (unstructured) set of coordinates and tps weights in  a way suitable for tps interpolation. The field structure is furthermore indicated by using appropriate names for dimensions, but this is only for documentation, without  use in processing functions (except for coordinate dimensions denoting coordinate range, see above). The following conventions are used: The projection of fields on objects is performed by the function ''proj_field.m'', which can be used also in data processing. The projected field from a projection object drawn in the main plotting window of uvmat will be plotted in the secondary plotting GUI '''view_field.fig'''. The list of currently opened projection objects is displayed in the menus '''[!ListObject]''' and '''[!ListObject_1]''' at the bottom right of '''uvmat.fig'''.  One object can be selected in each of these menus: the projection on the object selected in '''[!ListObject]''' is viewed in '''uvmat.fig''' while that of the object selected in '''[!ListObject_1]''' is viewed in '''view_field.fig'''. All the created objects are sketched in both views, except the one generating 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. Objects can be viewed, edited, deleted... Objects can be viewed, edited, deleted...Also extracted as a Matlab structure using the menu bar command '''[Export]'''. === 6.2 Object properties === * ''' !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. * ''' {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]). * ''' !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]). === 6.4 Projected fields === The 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'''. * ''' {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. * ''' Projection on n points:  '''   for each variable U, a set of n values U(i),i=1 to n is obtained, together with the unstructured coordinates (X(i), Y(i)) of the n points, and Z(i) in 3D. * !ProjMode= 'projection': the value U(i) is obtained as an average of the (non false) data values in a domain  of sizes max(2RangeX, 2RangeY, 2RangeZ) centered at each projection point. An ancillary data U_nbval(i) is also obtained, indicating the number of non-false data around each point. * !ProjMode= 'interp_lin':   U(i),i=1 is obtained as a linear interpolation on each point. * ''' Projection on open lines: '''   This includes the object styles 'line', 'polyline'. For vector fields, the projected  x component is along the line and the y component is perpendicular. 3D case still needs to be implemented**. * ProjMode='projection': in the case of unstructured coordinates, each data point in the region of action (width max(RangeY) around the line) is projected onto the line. The direction of projection is normal except if 'Phi' is non equal to 0 (only possible for 'line'). For structured coordinates with meshes DX,DY (DZ),  data are interpolated on the line with a mesh =min(DX,DY,DZ). For each field component U, a corresponding projected field U is produced. If DX is defined on the line, a smoothed field U_smooth is also calculated, as well as the mean U_mean along the line. * ProjMode='interp_lin': non-false data are linearly interpolated on the line, with mesh =DX along the line. Data which are 'discrete','warnflag' or 'errorflag' (as defined by the attribute 'Role') are not projected. * !ProjMode='projection': in the case of unstructured coordinates, each data point in the region of action (width max(RangeY) around the line) is projected onto the line. The direction of projection is normal except if 'Phi' is non equal to 0 (only possible for 'line'). For structured coordinates with meshes DX,DY (DZ),  data are interpolated on the line with a mesh =min(DX,DY,DZ). For each field component U, a corresponding projected field U is produced. If DX is defined on the line, a smoothed field U_smooth is also calculated, as well as the mean U_mean along the line. * !ProjMode='interp_lin': non-false data are linearly interpolated on the line, with mesh =DX along the line. Data which are 'discrete','warnflag' or 'errorflag' (as defined by the attribute 'Role') are not projected. * ProjMode='interp_tps': same as 'interp' but with a smoothing operation.