# Changes between Version 50 and Version 51 of UvmatHelp

Ignore:
Timestamp:
Jun 7, 2013, 8:02:31 AM (8 years ago)
Comment:

--

### Legend:

Unmodified
 v50 The menu bar at the top of the GUI contains the following buttons: * '''[Open]''': gives access to the browser for the main input field. * '''[browse...]''': open a general file browser ''browser_uvmat''. In the displayed list, a file can be selected for opening  (by a single mouse click),or directories are marqued by '+/'.  Select the first line '+/..' to move up in the directory tree, and the arrow <-- to move backward. The dates of file creation can be displayed by pressing the button '''[dates]'''. file ordering by name or date can be chosen by the popumenu above. A path can be directly entered by copy-paste in the upper edit window of the browser. * '''[Open]''': gives access to the browser for the main input field. * '''[browse...]''': open a general file browser ''browser_uvmat''. In the displayed list, a file can be selected for opening  (by a single mouse click),or directories are marqued by '+/'.  Select the first line '+/..' to move up in the directory tree, and the arrow <-- to move backward. The dates of file creation can be displayed by pressing the button '''[dates]'''. file ordering by name or date can be chosen by the popumenu above. A path can be directly entered by copy-paste in the upper edit window of the browser. * '''[browse campaign...]''':  scan the data organised as a project/campaign, see [#a3.7Dataorganisationinaproject section 3.7]. *  Previously opened fields are memorised in the menu and can be  directly selected again. * Previously opened fields are memorised in the menu and can be  directly selected again. * '''[Open_1] ''': used like '''[Open]''' to select a second field, for comparisons with the main one. * '''[Projection object] ''': used to create projection objects (points, lines, patches, gridded planes) for data analysis and interpolation * '''[Tools]''': * '''[Geometric calibration]''' for geometric calibration of images * '''[LIF calibration]''':  calibration of images for Laser Induced Fluorescence * '''[Make mask]''': for creating mask images (for PIV) * '''[Make grid]:''': for making measurement grids for PIV * '''[Tools]''': * '''[Geometric calibration]''' for geometric calibration of images * '''[LIF calibration]''':  calibration of images for Laser Induced Fluorescence * '''[Make mask]''': for creating mask images (for PIV) * '''[Make grid]:''': for making measurement grids for PIV * '''[ruler]''': displays a ruler to measure lengths and angles of any line. * '''[Run] ''': * '''[Field series]''': gives access to the GUI '''series.fig''' for analysis of field series * '''[Run] ''': * '''[Field series]''': gives access to the GUI '''series.fig''' for analysis of field series * '''[PIV(CIV)]''':  gives access to the GUI '''civ.fig''' for Particle Imaging Velocimetry * '''Coordinate aspect ratio:''' when '''[!CheckFixAspectRatio]''' is selected (the default option for images), the scale ratio for the  x and y coordinates is fixed to 1 by default (it can be manually adjusted by the edit box '''[num_AspectRatio]'''. When '''[!CheckFixAspectRatio]''' is not selected the graph scales along x and y automatically adjust to the figure size. * '''Extracting graphs:'''   The graph displayed in the central window can be copied to a separate figure by pressing the menu bar command '''[Export/extract figure]'''. This allows plot editing, exporting in image format and printing, using standard Matlab graphic tools. Plots can be also exported on an existing figure for data comparison, using the option '''[Export/export on axis]'''. A movie can be produced using the command '''[Export/make movie avi]'''. * '''Extracting graphs:'''   The graph displayed in the central window can be copied to a separate figure by pressing the menu bar command '''[Export/extract figure]'''. This allows plot editing, exporting in image format and printing, using standard Matlab graphic tools. Plots can be also exported on an existing figure for data comparison, using the option '''[Export/export on axis]'''. A movie can be produced using the command '''[Export/make movie avi]'''. * '''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 == For 3D PIV**, 'volume' images, with file extension .vol are used. These are images in the  png format, where the npz slices are concatenated along the y direction, forming a composite image of dimension (npy x npz, npx) from the images (npy x npx). === 3.2 Selecting fields from CIV  === === 3.2 Selecting fields from CIV === 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]. -'''Simple series:''' files in a series can be labeled by a single integer index i, with name obtained by concatenation of the full root ''!RootPath/RootFile''), an index string suffix, and the file extension ''!FileExt'' (example ''Exp01/aa_45.png'').  A frame series can be alternatively read from a  single movie file. Then the index ''i'' stands for the frame index within the file. -'''Double index series: ''' they are labeled by two integer indices i and j, with names obtained by concatenating the full root, the suffix '_i_j' and the file extension(e.g. {Exp/aa_45_2.png}). 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. -'''Pair file 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, the two indices are merged in a single label i, or a single index j if j1=j2. -'''Nomenclature types:''' These different indexing systems are implemented by a  functions {fullfile_uvmat.m}. The inputs are the root name, four indices i1,i2,j1,j2 and a character string representing 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}. Once the nomenclature type has been detected by the browser of '''uvmat.fig''', it is displayed in the edit box '''[!NomType]''' of '''uvmat.fig'''. This nomenclature type is defined as the index string for the first file in the series, for instance '_1' for a single indexing and '1_1-2' for a double indexing. For a field series in a single file, like a movie, the nomenclature type is '*'. 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. -'''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 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 [wiki:NomType 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 file names when the series is scanned. === 3.4 Navigation among file indices === The xml file can contain the following sections: * : contains elements , , , which recall the position of the file in the tree structure of data files. This allows the user  to check that the document file has not been displaced. * contains information on the camera settings, as well as the timing of all the images in a subsection . and contains information on the mechanical devices used to produce the laser sheet and scan volumes. * contains the parameters of the geometric calibration relating the pixel position to the real space coordinates (see [#a8-Geometriccalibration section 8]]). In the case of volume scanning, it also describes the set of laser plane positions and angles. * describes the illumination system used, including the position of the laser source. * describes the properties of the flow tracor (particle, dye...) * : contains elements , , , which recall the position of the file in the tree structure of data files. This allows the user  to check that the document file has not been displaced. * contains information on the camera settings, as well as the timing of all the images in a subsection . and contains information on the mechanical devices used to produce the laser sheet and scan volumes. * contains the parameters of the geometric calibration relating the pixel position to the real space coordinates (see [#a8-Geometriccalibration section 8]]). In the case of volume scanning, it also describes the set of laser plane positions and angles. * describes the illumination system used, including the position of the laser source. * describes the properties of the flow tracor (particle, dye...) The detailed commented structure is provided  in the schema file ''ImaDoc.xsd''. The xml documentation file is read by the function ''imadoc2struct.m''. If this file does not exist, a file with the same root name but extension .civ is sought (obsolete format). === 3.6 Ancillary input files === * ''' Mask:''' Masks are used to avoid PIV computations in specified areas. The file is a B&W 8 bit png image, with the same size as the image it has to mask. The grayscale code used is : * Intensity < 20: ('black mask') the vector in this place will be set to zero * 20 < Intensity < 200:('gray mask') the vector in this place will be absent * Intensity>200  the vector will be computed The mask corresponding to an image or velocity field can be displayed in '''uvmat.fig''' by selecting the check box '''[view_mask]([CheckMask])''' on the upper left. Images with appropriate name can be automatically recognised by '''uvmat.fig''' and civ functions, see [#a9-Masksandgrids section 9.1]. Otherwise file selection by a browser is proposed when '''[view_mask]''' is selected. * ''' Grid:''' List of numbers (in ascii text) specifying the set of points where the PIV processing is performed.  It specifies the number of points n and a corresponding list of x and y coordinates expressed in image pixels, as follows * ''' Mask:''' Masks are used to avoid PIV computations in specified areas. The file is a B&W 8 bit png image, with the same size as the image it has to mask. The grayscale code used is : * Intensity < 20: ('black mask') the vector in this place will be set to zero * 20 < Intensity < 200:('gray mask') the vector in this place will be absent * Intensity>200  the vector will be computed  The mask corresponding to an image or velocity field can be displayed in '''uvmat.fig''' by selecting the check box '''[view_mask]([CheckMask])''' on the upper left. Images with appropriate name can be automatically recognised by '''uvmat.fig''' and civ functions, see [#a9-Masksandgrids section 9.1]. Otherwise file selection by a browser is proposed when '''[view_mask]''' is selected. * ''' Grid:''' List of numbers (in ascii text) specifying the set of points where the PIV processing is performed.  It specifies the number of points n and a corresponding list of x and y coordinates expressed in image pixels, as follows {{{ n X1 Y1 X2 Y2  ......  Xn Yn }}} The coordinates correspond to the center of the correlation box on the first image of the pair (the actual vector position will be shifted by half the displacement found between the two images). A tool to create grids is described in [#a9-Masksandgrids section 9.2]. * '''.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''). * Example : %... gives comments (not included in the file). This 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 correspopnding .civ file is named aa.civ. * ''''.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''). * Example : %... gives comments (not included in the file). This 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 correspopnding .civ file is named aa.civ. {{{ 19 450.000824 30 60 30 1 }}} * '''.cmx''' ascii text files containing the parameters sent by the GUI '''civ.fig''' to the CIV fortran programmes. Each velocity field named *.nc results from a parameter file *.cmx. It can be opened by the browser of '''uvmat.fig'''. In a later version of civx**, the .cmx file is replaced by a .xml ’!CivDoc’ file. === 3.7 Data organisation in a  project: === The package is designed to foster a good data organisation. The raw data from a project should be organised as:[[BR]] '''!Project/Campaign/Experiment/DataSeries/data files'''. * 'Project': contains all information from a project. * 'Campaign' corresponds to a series of experiments obtained by varying a given set of physical parameters. A set of  parameter names (with units) is expected to be associated to a campaign. A project may involve several campaigns corresponding to different configurations, hence different relevant parameters. For a single configuration, 'Campaign' can be at the top of the data tree, without an additional 'Project' level. The uvmat package does not manage levels above 'Campaign'. * 'Experiment' is a directory containing all the data for a particular experiment, defined by a choice of values for the physical parameters. * '!DataSeries' contains an image series or movie from a camera, or more generally a data series from a device. Its name must correspond to the device and remain the same for all the experiments using this device. The results from data processing, as provided by 'civ' or 'series', are stored at the same level in a !DataSeries directory, named from the source one with a extension specific to the processing program, for instance .civ for civ. '' The package is designed to foster a good data organisation. The raw data from a project should be organised as:[[BR]]   '''!Project/Campaign/Experiment/DataSeries/data files'''. * 'Project': contains all information from a project. * 'Campaign' corresponds to a series of experiments obtained by varying a given set of physical parameters. A set of  parameter names (with units) is expected to be associated to a campaign. A project may involve several campaigns corresponding to different configurations, hence different relevant parameters. For a single configuration, 'Campaign' can be at the top of the data tree, without an additional 'Project' level. The uvmat package does not manage levels above 'Campaign'. * 'Experiment' is a directory containing all the data for a particular experiment, defined by a choice of values for the physical parameters. * '!DataSeries' contains an image series or movie from a camera, or more generally a data series from a device. Its name must correspond to the device and remain the same for all the experiments using this device. The results from data processing, as provided by 'civ' or 'series', are stored at the same level in a !DataSeries directory, named from the source one with a extension specific to the processing program, for instance .civ for civ. '''' '''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 Field display == The uvmat interface primarily reads and visualises two-dimensional fields, which can be images or scalars, or vector fields. -'''Error flags''': they mark in magenta color vectors considered as false. These vectors are kept in the data set so that their elimination can be reversed, but they must not be taken into account for data processing. They can be removed for visualisation by selecting the check box '''[!CheckHideFalse]'''. -'''Associated scalar: '''  for PIV velocity fields, the color  represents by default the image correlation, ranging from 0 to 1.  The red values correspond to poor correlations, green to fair values, and blue to good ones. The value range covered by each of the three colors is set by the pair of sliders  '''[Slider1]''' and '''[Slider2]''', or equivalently by the edit boxes '''[num_ColCode1]''' and '''[num_ColCode2]'''. Other color representations can be specified. '''[!ColorScalar]''' sets the scalar used for color representation, for instance the vector norm 'norm_vec' or vorticity 'vort' (the list of available scalars is set by the function {calc_scal.m}).  '''[ColorCode] ''' sets the kind of color representation: * 'rgb':  color ranging from red, for the scalar value set by '''[num_MinVec]''', to blue, for the scalar value set by  '''[num_MaxVec]'''. The  color thresholds from red to green and green to blue are set by '''[ColCode1]''' and '''[ColCode2]''' respectively, or the sliders  '''[Slider1]''' and '''[Slider2]'''. By unselecting the check box [CheckFixVecColor], these thresholds can be set to match the min and max scalar values. * 'black' or 'white': set the color for all vectors * 'brg': same as rgb but in reverse order, with blue for the lowest scalar values. -'''Associated scalar: '''  for PIV velocity fields, the color  represents by default the image correlation, ranging from 0 to 1.  The red values correspond to poor correlations, green to fair values, and blue to good ones. The value range covered by each of the three colors is set by the pair of sliders  '''[Slider1]''' and '''[Slider2]''', or equivalently by the edit boxes '''[num_ColCode1]''' and '''[num_ColCode2]'''. Other color representations can be specified. '''[!ColorScalar]''' sets the scalar used for color representation, for instance the vector norm 'norm_vec' or vorticity 'vort' (the list of available scalars is set by the function {calc_scal.m}).  '''[ColorCode] ''' sets the kind of color representation: * 'rgb':  color ranging from red, for the scalar value set by '''[num_MinVec]''', to blue, for the scalar value set by  '''[num_MaxVec]'''. The  color thresholds from red to green and green to blue are set by '''[ColCode1]''' and '''[ColCode2]''' respectively, or the sliders  '''[Slider1]''' and '''[Slider2]'''. By unselecting the check box [CheckFixVecColor], these thresholds can be set to match the min and max scalar values. * 'black' or 'white': set the color for all vectors * 'brg': same as rgb but in reverse order, with blue for the lowest scalar values. * '64 colors': quasi-continuous color representation, ranging from blue (for the scalar value given by '''[num_MinVec]''', to red, for the scalar value given by '''[num_MaxVec]'''. === 4.6 Succession of operations: === The following succession of operations is performed by '''uvmat.fig''': -'''File Reading:''' the input field is first read from the input file by the Matlab functions {imread.m}, {mmreader.m}, or {aviread.m} for images,  or the uvmat functions {nc2struct.m} or {read_civxdata.m} for netcdf files. -'''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 fields. -'''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 '''[list_object_1]''', see [section 7->#get_field]. A second projection, on the object selected by '''[list_object_1]''', can be plotted in the anciillary figure '''view_field.fig'''. Function used: {proj_field.m}. -'''Field calculation:''' a scalar can be calculated from each of the input fields, as selected by the menu '''[Fields]'''. This is performed by the function {calc_field.m}. -'''Field comparison''': when two fields of the same nature are introduced, the difference is taken by the function {sub_field.m.}. This is skipped if the transform function has already led to a single field. -'''Plotting:''' plot the results of projection. Function used: {plot_field.m} The following succession of operations is performed by '''uvmat.fig''':  -'''File Reading:''' the input field is first read from the input file by the Matlab functions {imread.m}, {mmreader.m}, or {aviread.m} for images,  or the uvmat functions {nc2struct.m} or {read_civxdata.m} for netcdf files.  -'''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 fields.  -'''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 '''[list_object_1]''', see [section 7->#get_field]. A second projection, on the object selected by '''[list_object_1]''', can be plotted in the anciillary figure '''view_field.fig'''. Function used: {proj_field.m}.  -'''Field calculation:''' a scalar can be calculated from each of the input fields, as selected by the menu '''[Fields]'''. This is performed by the function {calc_field.m}.  -'''Field comparison''': when two fields of the same nature are introduced, the difference is taken by the function {sub_field.m.}. This is skipped if the transform function has already led to a single field.   -'''Plotting:''' plot the results of projection. Function used: {plot_field.m} == 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: 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. $$\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. ^ 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. 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. 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]). * .Att_1, Att_2... : values of the listed global attributes. 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]). * .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. 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. * '''Operation''': name (char string) of the operation to be performed to finalise the field cell after projection. 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. 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. * '''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) === 5.3 Conventions for attributes in field objects: === -'''Global attributes active in uvmat''': those are used for plot settings or data processing. * 'Conventions': -'''Global attributes active in uvmat''': those are used for plot settings or data processing. * 'Conventions': * ='uvmat': indicate that the conventions described here are followed * ='uvmat/civdata': indicate that the variables are named according to [#civdata]. * '!CoordMesh': typical mesh for coordinates, used to define default projection grids and mouse selection action. Calculated automatically from the data if not specified. * '!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). * 'Dt': time interval for CIV data. It is used for calibration, to transform displacement into velocity. * 'Time': real number indicating the time of the field, used to obtain time series from data sets. * ='uvmat/civdata': indicate that the variables are named according to [#civdata #civdata]. * '!CoordMesh': typical mesh for coordinates, used to define default projection grids and mouse selection action. Calculated automatically from the data if not specified. * '!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). * 'Dt': time interval for CIV data. It is used for calibration, to transform displacement into velocity. * 'Time': real number indicating the time of the field, used to obtain time series from data sets. * '!TimeUnit': character string representing the unit of time (consistently for Time, Dt and velocity). -'''Global attributes , unactive''' those are merely used for information purpose * Project: recalls the project name * 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. * ObjectRangeX, ObjectRangeY, ObjectRangeZ : range of action of a projection object along each coordinate, see section 6. -'''Global attributes , unactive''' those are merely used for information purpose * Project: recalls the project name * 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. * 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. -'''Attributes of variables:''' * 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'. -'''Attributes of variables:''' * 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). -'''The attribute 'Role':''' the following options are used for the attribute 'Role': * 'ancillary': information of secondary use, indicating for instance an error estimate of field variables within a field cell (omitted in plotting) * '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. * 'coord_tps': coordinates of thin plate shell (tps) centres used for spline interpolation. * 'discrete': field with discrete values (no spatial interpolation), repesented with dots (no line) in 1D plots. * '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. * 'grad_x', 'grad_y', 'grad_z'  :represents the x, y or z  component of a contravariant vector** (like gradients). * '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 * 'tensor': represents a tensor field whose components correspond to the two last   dimensions of the array.** * vector: matrix whose last dimension states for the vector components.** * 'vector_x', 'vector_y', 'vector_z'  : represents the x, y or z  component of a vector (covariant) -'''The attribute 'Role':''' the following options are used for the attribute 'Role': * 'ancillary': information of secondary use, indicating for instance an error estimate of field variables within a field cell (omitted in plotting) * '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. * 'coord_tps': coordinates of thin plate shell (tps) centres used for spline interpolation. * 'discrete': field with discrete values (no spatial interpolation), repesented with dots (no line) in 1D plots. * '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. * 'grad_x', 'grad_y', 'grad_z'  :represents the x, y or z  component of a contravariant vector** (like gradients). * '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 * 'tensor': represents a tensor field whose components correspond to the two last   dimensions of the array.** * vector: matrix whose last dimension states for the vector components.** * 'vector_x', 'vector_y', 'vector_z'  : represents the x, y or z  component of a vector (covariant) * 'warnflag': provides a warning flag about the quality of data for the field variables within a field cell., default=0, no warning. 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). * 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 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': dimension of the index for the tps centres 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': dimension of the index for the tps centres * 'nb_subdomain' denotes the dimension for the subdomain index for tps coefficients The objects are defined by the following set of properties: * ''' {Name:} ''' any name given to the object * ''' {Type:} ''' classify the object with the following choice: * 'points': set of n points * 'line': simple straight segment, defined by its two end points * 'polyline': open line made of n-1 consecutive segments (defined by n points) * 'rectangle': defined by its center, half width and half height. * 'polygon': closed line made of n consecutive segments (defined by n points) * 'ellipse': defined by its center, half width and half height. * 'plane': plane with associated cartesian coordinates * ''' {Name:} ''' any name given to the object * ''' {Type:} ''' classify the object with the following choice: * 'points': set of n points * 'line': simple straight segment, defined by its two end points * 'polyline': open line made of n-1 consecutive segments (defined by n points) * 'rectangle': defined by its center, half width and half height. * 'polygon': closed line made of n consecutive segments (defined by n points) * 'ellipse': defined by its center, half width and half height. * 'plane': plane with associated cartesian coordinates * 'volume': volume with associated cartesian coordinates * ''' {DX:} ''', ''' {DY:} ''', ''' {DZ:} ''':meash  along each coordinate defining a grid for interpolation. * ''' {Coord:} ''': matrix with two (for 2D fields) or three columns defining the object position. * for  'points', 'line', 'polyline', 'polygon': matrix with n lines [xi yi zi], corresponding to each of the n defining points. Note that in 3D case, polygons must be included in a plane, which imposes restrictions on these coordinates. * for 'rectangle', 'ellipse': coordinates of the center. * ''' {Coord:} ''': matrix with two (for 2D fields) or three columns defining the object position. * for  'points', 'line', 'polyline', 'polygon': matrix with n lines [xi yi zi], corresponding to each of the n defining points. Note that in 3D case, polygons must be included in a plane, which imposes restrictions on these coordinates. * for 'rectangle', 'ellipse': coordinates of the center. * for 'plane' or 'volume': coordinates of the origin of the new coordinate frame attached to the object. === 6.3 Projection modes === Each variable of the input field yields a corresponding variable in the projected field.  Integral quantities  (circulation, flux...) can be calculated as well. The result depends on the nature of the field variable (set by the variable attribute 'Role',  on the object style and projection mode ProjMode: when any averaging or interpolation process is involved, the only projected variables are scalars and vector components, excluding 'warnflag', 'errorflag', 'ancillary'. Those are only projected with the mode 'projection' on line, planes or volumes. Each variable of the input field yields a corresponding variable in the projected field.  Integral quantities  (circulation, flux...) can be calculated as well. The result depends on the nature of the field variable (set by the variable attribute 'Role',  on the object style and projection mode ProjMode: when any averaging or interpolation process is involved, the only projected variables are scalars and vector components, excluding 'warnflag', 'errorflag', 'ancillary'. Those are only projected with the mode 'projection' on line, planes or volumes. * ''' {!ProjMode 'projection': } '''  this is a direct 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 variable on a regular grid on the projection project  (for instance on a line or plane). 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. * 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. * ''' {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='interp_tps': same as 'interp' but with a smoothing operation. * ProjMode='interp_tps': same as 'interp' but with a smoothing operation. * ''' {Projection on closed lines:} '''  , This includes 'rectangle','ellipse','polygon'. For ProjMode='projection', 'interp', 'filter', it behaves like open lines (not all options implemented yet**). For ProjMode='inside' or 'outside', the pdf of each field variable, restricted to the inside or the outside respectively,  is calculated. * ''' {Projection on planes:}  ''' Data in the range of action (RangeZ on each side of the plane) are projected normally to the plane, and its position expressed with respect to the coordinate system attached to the plane. This coordinate system is defined by an origin, the plane position XObject,YObject, ZObject, the ranges [RangeX(1) RangeX(2)]  and [RangeY(1) RangeY(2)] for X and Y, and the Euler angles Phi, Theta, Psi. * ProjMode='projection': in the case of unstructured coordinates, all field variables are projected onto the plane.  For structured coordinates with meshes DX,DY (DZ),  data are interpolated on the line with a mesh =min(DX,DY,DZ). * ''' {Projection on planes:}  ''' Data in the range of action (RangeZ on each side of the plane) are projected normally to the plane, and its position expressed with respect to the coordinate system attached to the plane. This coordinate system is defined by an origin, the plane position XObject,YObject, ZObject, the ranges [RangeX(1) RangeX(2)]  and [RangeY(1) RangeY(2)] for X and Y, and the Euler angles Phi, Theta, Psi. * ProjMode='projection': in the case of unstructured coordinates, all field variables are projected onto the plane.  For structured coordinates with meshes DX,DY (DZ),  data are interpolated on the line with a mesh =min(DX,DY,DZ). * ProjMode='interp_lin': non-false data are linearly interpolated on the grid defined by the plane coordinate system and and meshes DX, DY. Data which are 'discrete','warnflag' or 'errorflag' (as defined by the attribute 'Role') are not projected. * ProjMode='interp_tps': same as interp_lin but with thin plate shell interpolation. Object can be interactively drawn with the mouse on the GUI '''uvmat.fig ''' . First activate the creation mode by selecting the appropriate item in the menu bar Tools. * 'points': mark points with mouse left button. Use right click to end the series. The list of coordinates appear on the set_object interface.  These can be then manually edited, use plot on the GUI '''set_object.fig''' to validate. The range of action  can be set on the GUI '''set_object.fig''' by the edit box '''[YMax] ''' (only needed in the ProjMode 'projection'). This range is visualised by dashed circles around each point. The set of points can be determined from successive images (to track a feature for instance): for that purpose use the keyboard keys 'p' and 'm' to increament or decrement fields  without the mouse. * 'line': just draw a line, keeping the mouse left button pressed, release to end. The range of action, set by '''[YMax]''', is visualised by two dashed lines (only if ProjMode='projection'). * 'polyline': draw a line with several segments, press and release the mouse left button to mark each summit, press the right button to end the line. * 'rectangle': defined by its center, half width and half height. * 'polygon': closed line made of n consecutive segments (defined by n points) * 'ellipse': defined by its center, half width and half height. * 'plane': plane with associated cartesian coordinates * 'points': mark points with mouse left button. Use right click to end the series. The list of coordinates appear on the set_object interface.  These can be then manually edited, use plot on the GUI '''set_object.fig''' to validate. The range of action  can be set on the GUI '''set_object.fig''' by the edit box '''[YMax] ''' (only needed in the ProjMode 'projection'). This range is visualised by dashed circles around each point. The set of points can be determined from successive images (to track a feature for instance): for that purpose use the keyboard keys 'p' and 'm' to increament or decrement fields  without the mouse. * 'line': just draw a line, keeping the mouse left button pressed, release to end. The range of action, set by '''[YMax]''', is visualised by two dashed lines (only if ProjMode='projection'). * 'polyline': draw a line with several segments, press and release the mouse left button to mark each summit, press the right button to end the line. * 'rectangle': defined by its center, half width and half height. * 'polygon': closed line made of n consecutive segments (defined by n points) * 'ellipse': defined by its center, half width and half height. * 'plane': plane with associated cartesian coordinates * 'volume': volume with associated cartesian coordinates 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 calib_rescale R (i=1)= [pxcmx 0 0] R (i=2)= [0 pxcmy 0] R (i=3)= [0 0 1] 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 coordiante 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 UVMAT/px.m) - : 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 UVMAT/px.m) - 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. [->#top] * : 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], 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 coordiante 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 UVMAT/px.m) * 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]. 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. == 10 - Processing field series == === 10.1 The GUI series.fig === Operations on field series are controled by the GUI '''series.fig''', which allows the user to set the root name(s) and file indices over which a processing function operates. The GUI can be opened from '''uvmat''' through its menu bar option '''[Run/series]'''. It then mirrors the settings of '''uvmat'''. It can be alternatively opened by typing the Matlab command ''>>series'', then selecting  the input file series by the menu bar command '''[Open]'''. Operations on field series are controled by the GUI '''series.fig''', which allows the user to set the root name(s) and file indices over which a processing function operates. The GUI can be opened from '''uvmat''' through its menu bar option '''[Run/series]'''. It then mirrors the settings of '''uvmat'''. It can be alternatively opened by typing the Matlab command ''>>series'', then selecting  the input file series by the menu bar command '''[Open]'''. The root path, subdirectory, root file name and extension are introduced in the different columns of the table '''[!InputTable]'''. The nomenclature for file indexing is represented in the column '''[!NomType]''', the index extension for the first file in the series. Several input file series can be introduced simultaneously by the menu bar command''' [Open_append]''', filling the successive lines of '''!InputTable'''. By contrast, the table of input files is fully refreshed by the browser of the menu bar command '''[Open]'''. The cells in the table can be also edited manually. Then press the button '''[REFRESH]''' to validate the input. The processing function is chosen in the menu '''[!ActionName]'''. The first option ''check_data_files'' lists the selected input file series and checks their existence. This is a good first test before starting a processing operation since all actions operate on the same input file series. The option ''aver_stat'' calculates  a global average on the successive fields, while ''time_series'' provides a time series. The option ''merge_proj'' is used to project a whole series on a given grid, or to create a file series by concatenation of different fields. These processing functions are described with more details in next sub-sections. The option ''civ_series'' gives access to the PIV processsing, see section [#a11PIV:ParticleImagingVelocimetry section 11].  Finally any additional function can be called and included in the menu by selecting the option ''more...'' . The corresponding path is displayed in '''!ActionPath'''. The action function is first activated when it is selected in the menu '''[ActionName]'''. This first activation checks input data and sets the visibility of input GUI uicontrols. Several input file series can be introduced simultaneously by the menu bar command''' [Open_append]''', filling the successive lines of '''!InputTable'''. By contrast, the table of input files is fully refreshed by the browser of the menu bar command '''[Open]'''. The cells in the table can be also edited manually. Then press the button '''[REFRESH]''' to validate the input. The processing function is chosen in the menu '''[!ActionName]'''. The first option ''check_data_files'' lists the selected input file series and checks their existence. This is a good first test before starting a processing operation since all actions operate on the same input file series. The option ''aver_stat'' calculates  a global average on the successive fields, while ''time_series'' provides a time series. The option ''merge_proj'' is used to project a whole series on a given grid, or to create a file series by concatenation of different fields. These processing functions are described with more details in next sub-sections. The option ''civ_series'' gives access to the PIV processsing, see section [#a11PIV:ParticleImagingVelocimetry section 11].  Finally any additional function can be called and included in the menu by selecting the option ''more...'' . The corresponding path is displayed in '''!ActionPath'''. The action function is first activated when it is selected in the menu '''[ActionName]'''. This first activation checks input data and sets the visibility of input GUI uicontrols. The actual start of the processing is triggered by pressing the button '''[RUN]'''. It can be run in local mode, i.e. on the current Matlab session, or as ''background'', by selecting this option in '''!RunMode'''. In mode ''background'', calculation is performed in a new Matlab session (without graphics) so that the current Matlab session is free for new operations. If a cluster system has been detected, a third option ''cluster'' appears in the menu, allowing to dispatch parallel computations on a computer cluster. For the latter option, a compiled version of the action function is useful, to avoid installing Matlab on each node of the cluster. This is achieved by selecting the option ''.sh'' in the menu '''!ActionExt'''. If the compiled version is not yet available, or outdated, the GUI proposes a new compilation of the selected function (launching the function ''compile.m''). This action calls any user defined function by its name, acting on the series of fields defiend for ACTION. Some examples of usr_defined functions are in the subdirectory {/series}. -List of available functions: * ''sub_background.m'': used to removed a mean background to the images. This is useful before CIV processing when some fiked features are visible in the background (when the laser sheet is close to the bottom). -List of available functions: * ''sub_background.m'': used to removed a mean background to the images. This is useful before CIV processing when some fiked features are visible in the background (when the laser sheet is close to the bottom). * ''ima_levels.m'' * ''ima2vol.m'' produce volume images for 3D3C PIV. == 11 - PIV: Particle Imaging Velocimetry == === 11.1 Overview === PIV can be performed by selecting the Matlab function ''civ_series'' as '''[ActionName]''' in the GUI '''series'''. The same operations can be also performed with the older function ''civ.m'' running with the specific GUI '''civ.fig''', accessible from uvmat by the menu bar command '''[RUN/civ]'''. This older option is still used to run the fortran programs [CIVx]. === 11.3 FIX === The FIX operation is used after civ to remove false vectors, using different criteria: -''' {warning flags:} ''' these are flags (vec_F) indicating problems with the image correlation process: -*vec_F(i)=0 or 1 : default , the processing is fine -*vec_F(i)=-2: the maximum of the correlation function is close to the border of the search box (at a distance of two pixels or less), so that its maximum cannot be reliably obtained: the search domain is too small -*vec_F(i)=2: (only in civ1) we keep the less accurate Hart result (resulting from combining correlation functions  from neighborhing points) and  vec_C(i)=-1 is chosen by convention. Reference: Hart D. P. (2000) 'PIV error correction',{ Exp. Fluids} '''29''', 13-22. -*vec_F(i)=3: the optimisation of the correlation function is unstable  or  local Intensity rms of the image =0 -*vec_F(i)=4:only in civ2: the difference between the estimator and the result is more than 1 pixel. The two criteria, vec_F(i)=-2, and 3, should be selected (default options). The criterium vec_F=2 (Hart) should not be selected, while vec_F=4 (for civ2) could be selected only for excellent data (otherwise it may be too strict).   -''' {Threshold on the image correlation}  ''' (vec_C) can be introduced by the edit box [thresh_vecC] (value between 0 and 1). It removes vectors with poor correlation.  -''' {Threshold on the velocity modulus } ''' (expressed in pixels): it can remove either too small values  (menu '''[inf_sup1]''' set to '<'), or excessive values (menu '''[inf_sup1]''' set to '>'). Erratic zero velocity vectors, produced by a fixed image background, can be eliminated by this criterium. These criteria can be as well applied to the difference with a reference field, defined by a file series (edit box '''[ref_fix1]''') and a field inside the file (menu '''[field_ref1]'''). -''' {Mask fix:} '''  It has the same effect as the one used in civ1, but the removed vectors are kept in memory, labelled as false. -''' {Manual fix:} ''' Interactive fixing with the mouse is also possible, see [section 4.2->#4.2]. === 11.4 PATCH === -'''PATCH1: ''' interpolates the velocity values on a regular grid with a smoothing parameter rho. This also provides the spatial derivatives (vorticity, divergence) needed for the refined processing civ2. The numbers of grid points in x and y are set by nx and ny. The vectors which are too far from the smoothed field (erratic vectors) can be eliminated, using a threshold expressed in pixel displacement. The thin plate spline method must be done by subdomains for computational saving, use the default value 300. === 11.5 CIV2 === -'''CIV2:''' provides a refined calculation of the velocity field, using the civ1 result as previous estimate. The search range is determined by the civ1 field so there is no parameter. Use the option decimal shift to reduce peaklocking effects (advised). The option deformation is useful in the presence of strong shear or vorticity. Then image deformation and rotation is introduced before calculating the correlations. The other parameters (rho, ibx,iby, grid, mask) are used like for civ1 (take the same by default). The image pair for civ2 can be different than the one used in civ1 to get the first estimate. It is generally advised to use a moderate time interval for civ1, to avoid false vectors, and to take a larger intervel for civ2, in order to optimize precision. As civ2 already knows where to look and takes into account image strain and rotation (with the option deformation) it allows for higher time intervals. === 11.7 Description of the velocity files: === #civdata The 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. === 12-2 Volume image scanning === === 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}.