Changes between Version 56 and Version 57 of UvmatHelp


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

--

Legend:

Unmodified
Added
Removed
Modified
  • UvmatHelp

    v56 v57  
    133133-'''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.
    134134
    135 -'''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.
    136 
    137 === 3.4 Navigation among file indices ===
     135-'''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.
     136
     137=== 3.4 Navigation among field indices ===
    138138The 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.
    139139
     
    300300== 5- Field structures ==
    301301=== 5.1 Griding of data ===
    302 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:
     302Physical 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:
    303303
    304304-'''Regular grid:'''
    305305
    306 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.
     306Each 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.
    307307
    308308-'''Structured orthogonal grid''':
    309309
    310 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]).
     310Each 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]).
    311311
    312312-'''Unstructured coordinates:'''
    313313
    314 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.
     314Fields 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.
    315315
    316316-'''Thin plate shell (tps) interpolation:'''
    317317
    318 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)
    319 
    320 $$\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. ^
     318This 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)
     319
     320$$\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''.
    321321
    322322Because 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.
    323323
    324324=== 5.2 Field representation as Matlab structure ===
    325 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''.
     325The 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''.
    326326
    327327Data 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''.
    328328
    329 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.
     329This 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.
    330330
    331331In summary, the ''field structure'' is specified by the following elements:
    332332
    333  * (optional) '''!ListGlobalAttribute:''' list (cell array of character strings) of the names of global attributes  Att_1, Att_2...
    334  * (mandatory) '''!ListVarName:''' list of the variable names Var_1, Var_2....(cell array of character strings).
    335  * (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.
    336  * (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]).
     333 * (optional) '''ListGlobalAttribute:''' list (cell array of character strings) of the names of global attributes  Att_1, Att_2...
     334 * (mandatory) '''ListVarName:''' list of the variable names Var_1, Var_2....(cell array of character strings).
     335 * (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.
     336 * (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]).
    337337 * .Att_1, Att_2... : values of the listed global attributes.
    338338 * .Var_1, .Var_2...: variables arrays whose names are listed in !ListVarName.
     
    340340In 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.
    341341
    342  * '''!ListDimName:''' list of dimension names (cell array of character strings)
    343  * '''!DimValue:''' array of dimension values corresponding to !LisDimName.
     342 * '''ListDimName:''' list of dimension names (cell array of character strings)
     343 * '''DimValue:''' array of dimension values corresponding to !LisDimName.
    344344
    345345The following temporary information is added to manage projection and field substraction oerations, which must be done in general after projection:
    346346
    347  * '''!FieldRequest'''= ''interp_lin'' or ''interp_tps'' indicates whether lin interpolation  or derivatives by tps is needed to calculate the requested field.
     347 * '''!ProjModeRequest'''= ''interp_lin'' or ''interp_tps'' indicates whether lin interpolation  or derivatives by tps is needed to calculate the requested field.
    348348 * '''Operation''': name (char string) of the operation to be performed to finalise the field cell after projection.
    349349 * '''!SubCheck'''= 0 /1 indicate that the field must be substracted (second  entry in uvmat)
     
    368368 * Campaign: recalls the campaign name
    369369 * Experiment:  recalls the experiment name(s) of the raw data
    370  * DataSeries:  recalls the device name (s), if defined, of the raw data
    371  * 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.
    372  * ObjectCoord:  Coordinates defining a geometric object on which the data have been projected.
     370 * !DataSeries:  recalls the device name (s), if defined, of the raw data
     371 * !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.
     372 * !ObjectCoord:  Coordinates defining a geometric object on which the data have been projected.
    373373 * ObjectRangeX, ObjectRangeY, ObjectRangeZ : range of action of a projection object along each coordinate, see section 6.
    374374 * '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.
     
    378378 * Mesh: suggested step value to discretize the values of the variable, used to define the bins for histograms.
    379379 * 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'.
    380  * 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).
     380 * 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).
    381381
    382382-'''The attribute 'Role':''' the following options are used for the attribute 'Role':
     
    395395
    396396=== 5.4 Field cells: ===
    397 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.
    398 
    399  * 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.
    400  * 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.
    401  * 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).
    402  * Thin plate shell (tps) field cell: represents a set of coordinates and tps weights in  a way suitable for tps interpolation/filter.
     397The 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]
     398
     399 * '''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.
     400 * '''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).
     401 * '''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.
     402 * '''Thin plate shell (tps) field cell:''' represents an (unstructured) set of coordinates and tps weights in  a way suitable for tps interpolation.
    403403
    404404The 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:
     
    420420The 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.
    421421
    422 Objects can be viewed, edited, deleted...
     422Objects can be viewed, edited, deleted...Also extracted as a Matlab structure using the menu bar command '''[Export]'''.
    423423
    424424=== 6.2 Object properties ===
     
    462462 * ''' !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.
    463463
    464  * ''' {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]).
     464 * ''' !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]).
    465465
    466466=== 6.4 Projected fields ===
    467467The 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'''.
    468468
    469  * ''' {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.
     469 * ''' 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.
    470470   * !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.
    471471   * !ProjMode= 'interp_lin':   U(i),i=1 is obtained as a linear interpolation on each point.
    472472
    473473 * ''' 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**.
    474    * 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.
    475  * 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.
     474   * !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.
     475   * !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.
    476476
    477477 * ProjMode='interp_tps': same as 'interp' but with a smoothing operation.