Changes between Version 40 and Version 41 of UvmatHelp


Ignore:
Timestamp:
Jun 5, 2013, 7:07:33 PM (7 years ago)
Author:
sommeria
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UvmatHelp

    v40 v41  
    311311This 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)
    312312
    313 $$\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. ^
     313$$\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.
    314314
    315315Because 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.
    316316
    317317=== 5.2 Field representation as Matlab structure: ===
    318 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.
     318The 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''.
    319319
    320320Data 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''.
     
    323323
    324324In summary, the ''field structure'' is specified by the following elements: 
    325  * (optional) '''!ListGlobalAttribute:''' list (cell array of character strings) of the names of global attributes  Att_1, Att_2...
    326  * (mandatory) '''!ListVarName:''' list of the variable names Var_1, Var_2....(cell array of character strings).
    327  * (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.
     325 * (optional) '''ListGlobalAttribute:''' list (cell array of character strings) of the names of global attributes  Att_1, Att_2...
     326 * (mandatory) '''ListVarName:''' list of the variable names Var_1, Var_2....(cell array of character strings).
     327 * (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.
    328328 * (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]).
    329329 * .Att_1, Att_2... : values of the listed global attributes.
     
    331331
    332332In 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.
    333  * '''!ListDimName''': list of dimension names (cell array of character strings) 
    334  * '''!DimValue''': array of dimension values corresponding to !LisDimName.
     333 * '''ListDimName:''' list of dimension names (cell array of character strings) 
     334 * '''DimValue:''' array of dimension values corresponding to !LisDimName.
    335335
    336336The following temporary information is added to manage projection and field substraction oerations, which must be done in general after projection:
    337  * '''FieldRequest'''= ''interp_lin'' or ''interp_tps'' indicates whether lin interpolation  or derivatives by tps is needed to calculate the requested field.
     337 * '''!FieldRequest'''= ''interp_lin'' or ''interp_tps'' indicates whether lin interpolation  or derivatives by tps is needed to calculate the requested field.
    338338 * '''Operation''': name (char string) of the operation to be performed to finalise the field cell after projection.
    339  * '''SubCheck''' 0 /1 indicate that the field must be substracted (second  entry in uvmat)
     339 * '''!SubCheck'''= 0 /1 indicate that the field must be substracted (second  entry in uvmat)
    340340
    341341Any other element can be added, but will not be taken into account if they are not listed in  ''!ListGlobalAttribute'' or ''!ListVarName''.
    342342
    343343=== 5.3 Conventions for attributes in field objects: ===
    344 -'''Global attributes active in uvmat''' Those are used for plot settings or data processing.
    345 -'Conventions':
    346  * ='uvmat': indicate that the conventions described here are followed
    347  * ='uvmat/civdata': indicate that the variables are named according to  [CIV data description->#civdata]. 
    348 -'CoordMesh': typical mesh for coordinates, used to define default projection grids and mouse selection action. Calculated automatically from the data if not specified.
    349 -'CoordUnit': character string representing the unit for space coordinates. It is used to distinguish image coordinates (CoordUnit='pixel') and physical (for instance  CoordUnit='cm'). If 'CoordUnit' is defined,  [projection ->#set_object] will be allowed only on objects with the same 'CoordUnit', and plots will be done by default with axis option 'equal' (same scale for both axis).
    350 -*Dt: time interval for CIV data. It is used for calibration, to transform displacement into velocity. 
    351 -*Time: real number indicating the time of the field, used to obtain time series from data sets. 
    352 -*TimeUnit: character string representing the unit of time (consistently for Time, Dt and velocity).
     344-'''Global attributes active in uvmat''': those are used for plot settings or data processing.
     345 * 'Conventions':
     346   * ='uvmat': indicate that the conventions described here are followed
     347   * ='uvmat/civdata': indicate that the variables are named according to [wiki:#civdata]. 
     348 * '!CoordMesh': typical mesh for coordinates, used to define default projection grids and mouse selection action. Calculated automatically from the data if not specified.
     349 * '!CoordUnit': character string representing the unit for space coordinates. It is used to distinguish image coordinates (!CoordUnit='pixel') and physical (for instance  !CoordUnit='cm'). If '!CoordUnit' is defined,  [projection ->#set_object] will be allowed only on objects with the same '!CoordUnit', and plots will be done by default with axis option 'equal' (same scale for both axis).
     350 * 'Dt': time interval for CIV data. It is used for calibration, to transform displacement into velocity. 
     351 * 'Time': real number indicating the time of the field, used to obtain time series from data sets. 
     352 * '!TimeUnit': character string representing the unit of time (consistently for Time, Dt and velocity).
    353353
    354354-'''Global attributes , unactive''' those are merely used for information purpose
    355 -*Project: recalls the project name
    356 -*Campaign: recalls the campaign name
    357 -*Experiment:  recalls the experiment name(s) of the raw data
    358 -*DataSeries:  recalls the device name (s), if defined, of the raw data   
    359 -*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. 
    360 -*ObjectCoord:  Coordinates defining a geometric object on which the data have been projected. 
    361 -*ObjectRangeX, ObjectRangeY, ObjectRangeZ : range of action of a projection object along each coordinate, see section 6.   
    362 -* '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.
     355 * Project: recalls the project name
     356 * Campaign: recalls the campaign name
     357 * Experiment:  recalls the experiment name(s) of the raw data
     358 * DataSeries:  recalls the device name (s), if defined, of the raw data   
     359 * 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. 
     360 * ObjectCoord:  Coordinates defining a geometric object on which the data have been projected. 
     361 * ObjectRangeX, ObjectRangeY, ObjectRangeZ : range of action of a projection object along each coordinate, see section 6.   
     362 * '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.
    363363
    364364-'''Attributes of variables:'''
    365 -* Mesh: suggested step value to discretize the values of the variable, used to define the bins for histograms.
    366 -* 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'.
    367 -* 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).
    368 
    369 -'''The attribute 'Role':''' The following options are used for the attribute 'role':
    370 -* 'ancillary': information of secondary use, indicating for instance an error estimate of field variables within a field cell (omitted in plotting)
    371 -* 'coord_x', 'coord_y',  'coord_z': represents a  sets of unstructured coordinates x, y  and z for the field variables sharing the same dimension name.
    372 -* 'coord_tps': coordinates of thin plate shell (tps) centres used for spline interpolation.
    373 -* 'discrete': field with discrete values (no spatial interpolation), repesented with dots (no line) in 1D plots.
    374 -* 'errorflag': provides an error flag marking the field variables  as false or true within a field cell , default=0, no error. Different non zero values can mark different criteria of elimination, see [section 10.3->#sec10.3] for PIV data. Such flagging is reversible, since the data themselves are not lost.
    375 -* 'grad_x', 'grad_y', 'grad_z'  :represents the x, y or z  component of a contravariant vector** (like gradients).
    376 -* 'image_rgb': represents a color image. The last dimension of the array corresponds to the three color components 'rgb'. -* 'scalar': (default) represents a scalar field
    377 -* 'tensor': represents a tensor field whose components correspond to the two last   dimensions of the array.**
    378 -* vector: matrix whose last dimension states for the vector components.**
    379 -* 'vector_x', 'vector_y', 'vector_z'  : represents the x, y or z  component of a vector (covariant) 
    380 -* 'warnflag': provides a warning flag about the quality of data for the field variables within a field cell., default=0, no warning.
     365 * Mesh: suggested step value to discretize the values of the variable, used to define the bins for histograms.
     366 * 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'.
     367 * 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).
     368
     369-'''The attribute 'Role':''' the following options are used for the attribute 'Role':
     370 * 'ancillary': information of secondary use, indicating for instance an error estimate of field variables within a field cell (omitted in plotting)
     371 * 'coord_x', 'coord_y',  'coord_z': represents a  sets of unstructured coordinates x, y  and z for the field variables sharing the same dimension name.
     372 * 'coord_tps': coordinates of thin plate shell (tps) centres used for spline interpolation.
     373 * 'discrete': field with discrete values (no spatial interpolation), repesented with dots (no line) in 1D plots.
     374 * 'errorflag': provides an error flag marking the field variables  as false or true within a field cell , default=0, no error. Different non zero values can mark different criteria of elimination, see [section 10.3->#sec10.3] for PIV data. Such flagging is reversible, since the data themselves are not lost.
     375 * 'grad_x', 'grad_y', 'grad_z'  :represents the x, y or z  component of a contravariant vector** (like gradients).
     376 * 'image_rgb': represents a color image. The last dimension of the array corresponds to the three color components 'rgb'. -* 'scalar': (default) represents a scalar field
     377 * 'tensor': represents a tensor field whose components correspond to the two last   dimensions of the array.**
     378 * vector: matrix whose last dimension states for the vector components.**
     379 * 'vector_x', 'vector_y', 'vector_z'  : represents the x, y or z  component of a vector (covariant) 
     380 * 'warnflag': provides a warning flag about the quality of data for the field variables within a field cell., default=0, no warning.
    381381
    382382=== 5.4 Field cells: ===
    383 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.
    384 
    385 -*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.
    386 
    387 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:   -* coord_1,_2,_3: dimension with the same name as a coordinate variable array (coordinate dimension) -* 'nb_coord': denotes the space dimension for vector components  -* 'nb_coord_j', 'nb_coord_i': denotes the space dimensions for the two tensor components  -*  'rgb' : denotes the diemension of the color component in a true color  image. -*  'nb_point' or 'nb_vec' (for vectors) denotes the set of positions with unstructured coordinates. -* 'nb_tps': diemension of the index for the tps centres -* 'nb_subdomain' denotes the dimension for the subdomain index for tps coefficients
    388 
    389 [<doc115|right>->#top]
     383The 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.
     384
     385 * 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.
     386 * 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. 
     387 * 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).
     388 * Thin plate shell (tps) field cell: represents a set of coordinates and tps weights in  a way suitable for tps interpolation/filter.
     389
     390The 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:   
     391 * coord_1,_2,_3: dimension with the same name as a coordinate variable array (coordinate dimension)
     392 * 'nb_coord': denotes the space dimension for vector components 
     393 * 'nb_coord_j', 'nb_coord_i': denotes the space dimensions for the two tensor components 
     394 * 'rgb' : denotes the diemension of the color component in a true color  image.
     395 * 'nb_point' or 'nb_vec' (for vectors) denotes the set of positions with unstructured coordinates.
     396 * 'nb_tps': dimension of the index for the tps centres
     397 * 'nb_subdomain' denotes the dimension for the subdomain index for tps coefficients
    390398
    391399== 6- Projection objects: ==
     
    479487-'''Attributes: ''' annotate variables or files (global attributes) with small notes or supplementary meta data. Attributes are always scalar values or 1D arrays, which can be associated with either a variable or the file as a whole. Although there is no enforced limit, the user is expected to keep attributes small. Attribute names with specific meaning are defined in http://www.unidata.ucar.edu/software/netcdf/docs_beta/netcdf.html#Attribute-Conventions. An attribute '.Conventions' can be used to refer to additional sets of conventions used in a particular community.
    480488
    481   In contrast to variables, which are intended for bulk data, attributes are intended for ancillary data, or information about the data. The total amount of ancillary data associated with a NetCDF object, and stored in its attributes, is typically small enough to be memory-resident. However variables are often too large to entirely fit in memory and must be split into sections for processing.
    482 
    483   Another difference between attributes and variables is that variables may be multidimensional. Attributes are all either scalars (single-valued) or vectors (a single, fixed dimension).
    484 
    485   Variables are created with a name, type, and shape before they are assigned data values, so a variable may exist with no values. The value of an attribute is specified when it is created, unless it is a zero-length attribute.
    486 
    487   A variable may have attributes, but an attribute cannot have attributes. Attributes assigned to variables may have the same units as the variable (for example, valid_range) or have no units (for example, scale_factor). If you want to store data that requires units different from those of the associated variable, it is better to use a variable than an attribute. More generally, if data require ancillary data to describe them, are multidimensional, require any of the defined NetCDF dimensions to index their values, or require a significant amount of storage, that data should be represented using variables rather than attributes.
     489In contrast to variables, which are intended for bulk data, attributes are intended for ancillary data, or information about the data. The total amount of ancillary data associated with a NetCDF object, and stored in its attributes, is typically small enough to be memory-resident. However variables are often too large to entirely fit in memory and must be split into sections for processing.
     490
     491Another difference between attributes and variables is that variables may be multidimensional. Attributes are all either scalars (single-valued) or vectors (a single, fixed dimension).
     492
     493Variables are created with a name, type, and shape before they are assigned data values, so a variable may exist with no values. The value of an attribute is specified when it is created, unless it is a zero-length attribute.
     494
     495A variable may have attributes, but an attribute cannot have attributes. Attributes assigned to variables may have the same units as the variable (for example, valid_range) or have no units (for example, scale_factor). If you want to store data that requires units different from those of the associated variable, it is better to use a variable than an attribute. More generally, if data require ancillary data to describe them, are multidimensional, require any of the defined NetCDF dimensions to index their values, or require a significant amount of storage, that data should be represented using variables rather than attributes.
    488496
    489497=== 7.3 The GUI get_field: ===
     
    713721Combine PIV fields:  this is done by selecting PATCH1 and  test_stereo1 (at level civ1), or PATCH2 and  test_stereo2 (at level civ2) in the stereo mode (check box compare selected). The resulting fields camA-camB are in physical coordinates. They are final results which cannot be processed for further Civ operations: one must go back to the two image series for that purpose. Note that this stereo combination is only  possible in the RUN mode for the moment (no BATCH)**.
    714722
    715 [civdata<-] {===11.7 Description of the velocity files :===}
     723=== 11.7 Description of the velocity files: === #civdata
    716724
    717725The velocity fields obtained by PIV, as well as their spatial derivatives, are stored in the machine independent binary format ['netcdf'->#netcdf]. The file contains constants ('global attributes') and fields ('variables') whose values can be directly accessed by their name.