# Changes between Version 210 and Version 211 of UvmatHelp

Ignore:
Timestamp:
Jan 7, 2022, 5:21:51 PM (5 months ago)
Comment:

--

### Legend:

Unmodified
 v210 Images produced by the software are in the format png (portable network graphics).  It is a binary format for images with lossless (reversible) compression,  recommended by w3c (http://www.w3.org/Graphics/PNG).  It is an open source patent-free replacement of GIF. It can be read directly by all  standard programs of image visualisation and processing.  Compressing a  raw binary image to its png form typically saves disk storage by a  factor of 3. ''UVMAT'' can also read data in the binary format NetCDF, as described in [#a7Netcdffilesandget_field section 7]. Velocity fields obtained by PIV and results of data processing are stored in this format. For 3D PIV, 'volume' images are also stored in this format. The input file type is recognized in ''UVMAT'' by the function ''get_file_type.m''  and the file is opened by the function ''read_field.m'' according to this file type. It is possible to include new input file types by a modification of these two functions. ''UVMAT'' can also read data in the binary format NetCDF, as described in [#a7Netcdffilesandget_field section 7]. Velocity fields obtained by PIV and results of data processing are stored in this format. For 3D PIV, 'volume' images are also stored in this format. The input file type is recognized in ''UVMAT'' by the function ''get_file_type.m''  and the file is opened by the function ''read_field.m'' according to this file type. It is possible to include new input file types by a modification of these two functions. === 3.2 Selecting fields from CIV === Different kinds of file or image frame indexing are defined: - '''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. This double index labeling is commonly used for bursts of images (index j or equivalently a letter appendix 'a', 'b') separated by longer time intervals (index i).  It can be also used for successive volume scanning by a laser sheet, with index j representing the position in the volume and i the time. For a set of indexed movies (or multimage  files), the index i labels the files while the index j labels the frames  within a file. - '''Pair  indexing:''' new file series can result from the processing of primary series. For a sequential processing limited to a single file, the output index naturally reproduces  the input index. Other processing functions involve pairs of input files, for instance Particle Imaging Velocity from image pairs. In a simple series, the result from the two primary fields *_i1 and *_i2 is then labeled as *_i1-i2 with the file extension indicating  the output format. More generally,  the result from any processing involving a range of primary indices from  i1 to i2  is  labeled as _i1-i2.  If i1=i2 or j1=j2, the two indices are merged in a single label i, or j respectively. - '''Nomenclature types:''' The ''nomenclature type'' is defined as the character string representing the index (or indices) for the first file  in the series, for instance '_1' for a ''single indexing'' and '_1-2' for a  ''pair indexing'', '_1_1' for a ''double index'' series. The second index j can be also represented as a letter suffix, for instance '01a'.  For a field series in a single file, like a movie, the  nomenclature type is defined as '*'. The functions ''fullfile_uvmat.m'' generates a file name from a root name, four numerical indices i1,i2,j1,j2 and  the ''nomenclature type''. The reverse operation, splitting a name into a root and indices while detecting the ''nomenclature type'', is performed by the function ''fileparts_uvmat.m''. The function ''find_file_series.m'' is also needed to scan the whole file series, leading to a possible adjustement of the nomenclature type (for instance distinguishing '_001' from '_1' when the file with index 1000 has been opened). Once the nomenclature type has been detected by the browser of the GUI '''uvmat''', it is displayed in the edit box '''[!NomType]''' and used to generate all the file names when the series is scanned. * '''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. This double index labeling is commonly used for bursts of images (index j or equivalently a letter appendix 'a', 'b') separated by longer time intervals (index i).  It can be also used for successive volume scanning by a laser sheet, with index j representing the position in the volume and i the time. For a set of indexed movies (or multimage  files), the index i labels the files while the index j labels the frames  within a file. * '''Pair  indexing:''' new file series can result from the processing of primary series. For a sequential processing limited to a single file, the output index naturally reproduces  the input index. Other processing functions involve pairs of input files, for instance Particle Imaging Velocity from image pairs. In a simple series, the result from the two primary fields *_i1 and *_i2 is then labeled as *_i1-i2 with the file extension indicating  the output format. More generally,  the result from any processing involving a range of primary indices from  i1 to i2  is  labeled as _i1-i2.  If i1=i2 or j1=j2, the two indices are merged in a single label i, or j respectively. * '''Nomenclature types:''' The ''nomenclature type'' is defined as the character string representing the index (or indices) for the first file  in the series, for instance '_1' for a ''single indexing'' and '_1-2' for a  ''pair indexing'', '_1_1' for a ''double index'' series. The second index j can be also represented as a letter suffix, for instance '01a'.  For a field series in a single file, like a movie, the  nomenclature type is defined as '*'. The functions ''fullfile_uvmat.m'' generates a file name from a root name, four numerical indices i1,i2,j1,j2 and  the ''nomenclature type''. The reverse operation, splitting a name into a root and indices while detecting the ''nomenclature type'', is performed by the function ''fileparts_uvmat.m''. The function ''find_file_series.m'' is also needed to scan the whole file series, leading to a possible adjustement of the nomenclature type (for instance distinguishing '_001' from '_1' when the file with index 1000 has been opened). Once the nomenclature type has been detected by the browser of the GUI '''uvmat''', it is displayed in the edit box '''[!NomType]''' and used to generate all the file names when the series is scanned. === 3.4 Navigation among field indices === The maximum  value detected for each index is indicated by the boxes '''[last_i]''' and '''[last_j] ''' respectively. - '''Slices:''' Images may be obtained with laser scanning in a multilayer mode, introducing a periodicity for the index i. This can be accounted by pressing the pushbutton '''[slices]''' and introducing the period in the edit box '''[num_NbSlice]''' which then appears. The index i modulo nb_slice then appears in the edit box '''[z_index]'''. - '''Movie scan:''' Fields  can be continuously scanned as a movie by pressing  the pushbuttons '''[Movie]''' ( '''[++>]''') or '''[!MovieBackward]''' . The movie speed can be adjusted by the slider '''[speed]'''. Press '''[STOP] ''' to stop the movie. * '''Slices:''' Images may be obtained with laser scanning in a multilayer mode, introducing a periodicity for the index i. This can be accounted by pressing the pushbutton '''[slices]''' and introducing the period in the edit box '''[num_NbSlice]''' which then appears. The index i modulo nb_slice then appears in the edit box '''[z_index]'''. * '''Movie scan:''' Fields  can be continuously scanned as a movie by pressing  the pushbuttons '''[Movie]''' ( '''[++>]''') or '''[!MovieBackward]''' . The movie speed can be adjusted by the slider '''[speed]'''. Press '''[STOP] ''' to stop the movie. -'''Keyboard short cuts:''' the activation of the push buttons  '''[runplus]''' and  '''[runmin]''' can be performed by typing the key board letters 'p' and 'm' respectively, after the UVMAT figure has been selected by the mouse. Similarly the command of the push button '''[run0]''' can be performed by typing the 'return carriage' key. [[Image(help_vectors_titres.jpg)]] - '''Warning flags''': they indicate a vector resulting from a dubious image correlation process, but not removed from the data set. They are displayed in black by default. This feature can be desactivated by selecting the check box '''hide warn''' ('''[!CheckHideWarning]'''). - '''Error flags''': they mark 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. These false vectors are displayed in magenta. They can be also removed from the plot by selecting the check box '''hide false''' ([!CheckHideFalse]''').''' - '''Associated scalar: '''  for PIV velocity fields, the color  represents by default the image correlation '''C''', 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: * '''Warning flags''': they indicate a vector resulting from a dubious image correlation process, but not removed from the data set. They are displayed in black by default. This feature can be desactivated by selecting the check box '''hide warn''' ('''[!CheckHideWarning]'''). * '''Error flags''': they mark 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. These false vectors are displayed in magenta. They can be also removed from the plot by selecting the check box '''hide false''' ([!CheckHideFalse]''').''' * '''Associated scalar: '''  for PIV velocity fields, the color  represents by default the image correlation '''C''', 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 '''fix''' ('''[!CheckFixVecColor]'''), these thresholds can be set to match the min and max 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]'''. - '''Mouse display''': when the mouse is moved over a vector, it is marked by a circle, and its features appear in the display text boxes on the upper right. These are * '''Mouse display''': when the mouse is moved over a vector, it is marked by a circle, and its features appear in the display text boxes on the upper right. These are * fist line: the position coordinates ''x'', ''y'', ''z'' for 3D cases). * third line: the vector index in the file, the values of the scalar (C), the warning flag (F) and the error flag (FF). The meaning of the flag values is given in [#a11.3FIX section 11.3]. - '''Manual editing of vectors''': error flags are automatically produced by the PIV operation, see [#a11.3FIX section 11.3]. It is also possible to introduce them manually by checking '''edit vect''' and selecting a vector with the mouse. The flag can be removed by selecting it again. To record the changes in the input file, press the button '''[record]'''. * '''Manual editing of vectors''': error flags are automatically produced by the PIV operation, see [#a11.3FIX section 11.3]. It is also possible to introduce them manually by checking '''edit vect''' and selecting a vector with the mouse. The flag can be removed by selecting it again. To record the changes in the input file, press the button '''[record]'''. === 4.4 Histograms === The following succession of operations is performed by '''uvmat.fig''': - '''File identification:''' the nomenclature type and file type (for instance image, movie, or NetCDF file) are identified from the opened file (using the function ''find_file_series.m''). - '''File Reading:''' the input field is first read from the input file by the Matlab function ''read_field.m''. - '''Second file reading:'''  The second input field is similarly read if selected. Note that it is kept in memory, so it is not read again if the file is unchanged (this is useful in the case of substraction of a fixed background for instance). - '''Transform:''' by default the 'phys' option transforms each of the input fields from pixel to physical coordinates. This operation can also combine two input field structures into a single field structure. - '''Histogram:''' This is obtained from the input field in transformed coordinates, or if applicable from the fields resulting from the two input fields. - '''Projection:''' on  the projection object selected in the menu '''[!ListObject_1]''', see [#ProjObject section 6]. A second projection, on the object selected by '''[!ListObject]''', can be plotted in the ancillary figure '''view_field.fig'''. Projection is performed by the function ''proj_field.m''. - '''Field calculation:''' a scalar can be calculated after projection, as selected by the menu '''[Fields]'''. - '''Field comparison''': when two fields of the same nature are introduced, the difference is taken. This is skipped if the transform function has already led to a single field.   - '''Plotting:''' plot the results of projection, using the function ''plot_field.m''. * '''File identification:''' the nomenclature type and file type (for instance image, movie, or NetCDF file) are identified from the opened file (using the function ''find_file_series.m''). * '''File Reading:''' the input field is first read from the input file by the Matlab function ''read_field.m''. * '''Second file reading:'''  The second input field is similarly read if selected. Note that it is kept in memory, so it is not read again if the file is unchanged (this is useful in the case of substraction of a fixed background for instance). * '''Transform:''' by default the 'phys' option transforms each of the input fields from pixel to physical coordinates. This operation can also combine two input field structures into a single field structure. * '''Histogram:''' This is obtained from the input field in transformed coordinates, or if applicable from the fields resulting from the two input fields. * '''Projection:''' on  the projection object selected in the menu '''[!ListObject_1]''', see [#ProjObject section 6]. A second projection, on the object selected by '''[!ListObject]''', can be plotted in the ancillary figure '''view_field.fig'''. Projection is performed by the function ''proj_field.m''. * '''Field calculation:''' a scalar can be calculated after projection, as selected by the menu '''[Fields]'''. * '''Field comparison''': when two fields of the same nature are introduced, the difference is taken. This is skipped if the transform function has already led to a single field.   - '''Plotting:''' plot the results of projection, using the function ''plot_field.m''. ---- Physical fields can be defined either on regular grids, either scattered on an unstructured set of positions. Some measurements techniques, like PIV or particle tracking, provided unstructured data, while most methods of analysis require data  on a regular grid. This can be done by interpolation, defining a projection on a plane (with '''[!ProjMode]''' ='interp...', see [#ProjObject next section]).  The three possibilities of griding are defined as follows: - '''Regular grid:''' * '''Regular grid:''' Each field is then a multi-dimensional array whose dimensions match the space dimensions.  Because of the grid regularity, the set of positions is fully defined by the coordinate value for the first and last index along each dimension of the array. - '''Structured orthogonal grid''': * '''Structured orthogonal grid''': Each field is again a multi-dimensional array V whose dimensions match the space dimensions, but the coordinates may not be regularly spaced, so they are represented as a monotonic 1D array variable with the same length as the corresponding dimension of V.  This is called a ''coordinate variable'' (see [#a7.1TheNetCDFformat section 7.1]). - '''Unstructured coordinates:''' * '''Unstructured coordinates:''' Fields may be alternatively obtained on a unstructured (grid-less) set of positions. The coordinates are then described by coordinate arrays X(nb_points), Y(nb_points), Z(nb_points). The corresponding field values are then represented as variables U(nb_point),V(nb_point) for each vector component, or alternatively by V(nb_points, j, i), where i, j possibly stand for vector or tensor components. - '''Thin plate shell (tps) interpolation:''' * '''Thin plate shell (tps) interpolation:''' This is a multi-dimensional generalisation of the spline interpolation/smoothing, an optimum way to interpolate data with minimal  curvature of the interpolating function. The result at an interpolation position vector ${\bf r}$ is expressed in the form, (see ThinPlateShell). === 5.3 Conventions for attributes in field objects === - '''Global attributes active in UVMAT''': those are used for plot settings or data processing. * '''Global attributes active in UVMAT''': those are used for plot settings or data processing. * 'Conventions': * '!TimeUnit': character string representing the unit of time (consistently for Time, Dt and velocity). - '''Global attributes , unactive''' those are merely used for information purpose * '''Global attributes , unactive''' those are merely used for information purpose * Project: recalls the project name. * '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:''' * '''Attributes of variables:''' * Mesh: suggested step value to discretize the values of the variable, used to define the bins for histograms. * 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': * '''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). The NetCDF data model consists of variables, dimensions, and attributes. - '''Variables:''' N-dimensional arrays of data. Variables in NetCDF files can be one of six types (char, byte, short, int, float, double). Variables are used to store the bulk of the data in a NetCDF dataset. A variable represents an array of values of the same type and unit. A variable has a name, a data type, and a shape described by its list of dimensions specified when the variable is created. A variable may also have associated attributes, which may be added, deleted or changed after the variable is created. - '''Dimensions:''' describe the axes of the data arrays. A dimension has a name and a length. The naming can be useful to identify groups of variables with one to one correspondence, sharing the same dimensions. It is legal for a variable to have the same name as a dimension, it is then called a coordinate variable. Such variables have no special meaning to the NetCDF library, but they can be used in processing software to link the arrays of coordinate values to their corresponding field variables. - '''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. * '''Variables:''' N-dimensional arrays of data. Variables in NetCDF files can be one of six types (char, byte, short, int, float, double). Variables are used to store the bulk of the data in a NetCDF dataset. A variable represents an array of values of the same type and unit. A variable has a name, a data type, and a shape described by its list of dimensions specified when the variable is created. A variable may also have associated attributes, which may be added, deleted or changed after the variable is created. * '''Dimensions:''' describe the axes of the data arrays. A dimension has a name and a length. The naming can be useful to identify groups of variables with one to one correspondence, sharing the same dimensions. It is legal for a variable to have the same name as a dimension, it is then called a coordinate variable. Such variables have no special meaning to the NetCDF library, but they can be used in processing software to link the arrays of coordinate values to their corresponding field variables. * '''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. 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. When a NetCDF input file opened, its full name, including path, is displayed in the upper window '''[inputfile]'''. The names and value of the global attributes are listed in the left column '''[attributes]''', the list of variables in the central column '''[variables]''', and the list of dimension names and values in the right column '''[dimensions]'''. By selecting one of the variables in the central column, the corresponding variable attributes and dimensions are displayed in the left and right columns respectively. Note that the whole content of the NetCDF file can be obtained by the function ''nc2struct.m''. Input fields can be selected according to three options, chosen by the menu '''[!FieldOption]'''. - '''1D plot:''' to plot a simple graph, ordinate versus abscissa. Select by the menu '''[ordinate]''' the variable(s) to plot as ordinate (use the key '''Ctrl''' for multiple selection). Then select the corresponding abscissa in the column '''[abscissa]'''.  If the variable is indexed with more than one dimension, each component is plotted versus the first index (like with the plot Matlab function ''plot.m''). If the option '''[matrix index]''' ('''[!CheckDimensionX]''') is selected, the ordinate variable is plotted versus its index. - '''scalar:''' to plot scalar fields as images. The variable representing the scalar is selected in the first column '''[scalar]''', with coordinates respectively selected in '''[Coord_x] ''' and '''[Coord_y]'''. Alternatively, matrix index can be used as coordinate if the options '''[matrix index]'''('''[CheckDimensionX]''' and '''[CheckDimensionY]''') are selected. - '''vectors:''' to plot vector fields. The x and y vector components are selected in the first (...) and second columns, while the coordinates are selected in '''[coord_x_vector] ''' and '''[coord_y_vector]'''. If no variable is selected in '''[coord_x_scalar] '''  or '''[coord_y_scalar] ''' ( blank selected at first line), the index is used as coordinate. A scalar, set in ..., can be represented as vector color. * '''1D plot:''' to plot a simple graph, ordinate versus abscissa. Select by the menu '''[ordinate]''' the variable(s) to plot as ordinate (use the key '''Ctrl''' for multiple selection). Then select the corresponding abscissa in the column '''[abscissa]'''.  If the variable is indexed with more than one dimension, each component is plotted versus the first index (like with the plot Matlab function ''plot.m''). If the option '''[matrix index]''' ('''[!CheckDimensionX]''') is selected, the ordinate variable is plotted versus its index. * '''scalar:''' to plot scalar fields as images. The variable representing the scalar is selected in the first column '''[scalar]''', with coordinates respectively selected in '''[Coord_x] ''' and '''[Coord_y]'''. Alternatively, matrix index can be used as coordinate if the options '''[matrix index]'''('''[CheckDimensionX]''' and '''[CheckDimensionY]''') are selected. * '''vectors:''' to plot vector fields. The x and y vector components are selected in the first (...) and second columns, while the coordinates are selected in '''[coord_x_vector] ''' and '''[coord_y_vector]'''. If no variable is selected in '''[coord_x_scalar] '''  or '''[coord_y_scalar] ''' ( blank selected at first line), the index is used as coordinate. A scalar, set in ..., can be represented as vector color. The attribute or variable considered as 'time' can be also chosen in the Panel '''[Time]'''. From the menu '''[!SwitchVarIndexTime]''', the time can be considered as the ''file index'', a global ''attribute'', a dimension ''variable'', or a ''dimension index''. Selection of ''attribute'' gives way to a list of global attribute tags in the menu '''[!TimeName]'''. Selection of variable gives way to a list of variables, while selection of ''dimension'' gives a list of dimension names. The ''physical coordinates'' are defined from the experimental set-up. The correspondance with images is obtained by identifying a set of calibration points whose positions are known in the physical coordinate system. A cartesian calibration grid covering the whole image is the best option, but any set of calibration points can be used. We handle three kinds of transforms: - '''rescale''': linear rescaling along ''x'' and ''y'' + translation (no rotation nor deformation). - '''linear''': general linear transform, including translation and rotation (but no projection effects). - '''3D_linear:''' this transform handles projection effects, needed if the observed plane is not perpendicular to the line of sight. It involves a 3D calibration needed to account for the depth effects occuring in volume scan. - '''3D_quadr:''' this is like 3D_linear, but takes also into account a quadratic deformation by the optics which occurs for wide fields of view (small focal lengths). - '''3D_extrinsic:''' this is like 3D_quadr, but uses intrinsic parameters of the camera, as explained below. * '''rescale''': linear rescaling along ''x'' and ''y'' + translation (no rotation nor deformation). * '''linear''': general linear transform, including translation and rotation (but no projection effects). * '''3D_linear:''' this transform handles projection effects, needed if the observed plane is not perpendicular to the line of sight. It involves a 3D calibration needed to account for the depth effects occuring in volume scan. * '''3D_quadr:''' this is like 3D_linear, but takes also into account a quadratic deformation by the optics which occurs for wide fields of view (small focal lengths). * '''3D_extrinsic:''' this is like 3D_quadr, but uses intrinsic parameters of the camera, as explained below. The 3D options involve a full 3D calibration relying on the [attachment:3D_view.pdf pinhole camera  model]. The method was first proposed by R.Y. Tsai, 'An Efficient and Accurate Camera Calibration Technique for 3D Machine Vision'. Proceedings of IEEE Conference on Computer Vision and Pattern Recognition, Miami Beach, FL, pp. 364-374 (1986). We use a more recent version, with the toolbox [->http://www.vision.caltech.edu/bouguetj/calib_doc/] . 3D calibrations are done in two steps. The camera'' intrinsic parameters'', which are the focal length and the quadratic deformation coefficient, are first determined by different views of the same grid observed at different angles. Then the ''extrinsic parameters'', which represent the rotation angles and translation of the physical coordinates with respect to the camera, are obtained with a single image of the grid positioned in a known plane $z=cte$. The option 3D_extrinsic allows the user to do only the second step from known intrinsic parameters. Those depend only on the camera with its objective lens and focus adjustement. Note that these 3D options require a calibration grid, with a sufficient number of calibration points covering the whole image. -''' Intrinsic parameters''': the previous procedure first determines the extrinsic parameters which characterize the camera optics (focal lengths and nonlinear deformation parameter). Then the extrinsic parameters, translation and rotation of the camera with respect to the reference grid, are determined on the last grid image. If the same optics is used in a new experiment, it is possible to skip the multiplane detection, importing the intrinsic parameters from a previous file by the menu bar tool '''[Import.../Intrinsic parameters]''', then applying the calibration with the option '3D_extrinsic' with the reference grid image only. - ''' Import features''': by the menu bar tool '''[Import...]''', you can choose to import different data from a previous file. * ''' Import features''': by the menu bar tool '''[Import...]''', you can choose to import different data from a previous file. * '''Calibration points''': imports the calibration poins of a previous grid saved as a file, the points and their coordinates will then appear in '''uvmat''' and '''geometry_calib'''. === 8.3 Setting the reference plane(s) === Deducing the physical coordinates from image coordinates requires information on the section plane. The default assumption is that the objects in the image are in the plane used for calibration, but '''uvmat''' can handle volume scanning by a laser plane. A set of section planes can be defined by their origin positions and rotation angle vectors. Theses planes are labelled by a ''z index'', assumed to be the frame index j (case of volume scan), or the index i modulo the number of slices !NbSlice (case of 'multilevel' scan). These settings are stored in the xml file as part of the section and can be edited from '''uvmat.fig''' with the menu bar command '''[Tools/set slice]'''. A dialog box '''set_slices''' appears for entering the first and last section plane positions ''z'', as well as the number of slices and the option 'volume_scan' ('multilevel' otherwise). In the absence of 3D scan put twice the same value for first and last z.  Finally a tilt angle of the laser sheet, around the ''x'' and ''y'' axis, can be introduced, with a possible angular scanning from first to last section planes. After introduction of the plane position information, the z-index is displayed in the frame '''[!FileIndices]''' of '''uvmat.fig'''. The local ''z'' position of the mouse pointer, assumed to lay on the current section plane, is then displayed in '''[text_display]'''. Deducing the physical coordinates from image coordinates requires information on the illumination plane. The default assumption is that the objects in the image are in the plane used for calibration (assumed horizontal with x,y coordinates), but '''uvmat''' can handle volume scanning by a laser plane. A set of section planes can be defined by their origin positions and rotation angle vectors. Theses planes are labelled by a ''z index'', assumed to be the frame index j (case of volume scan), or the index i modulo the number of slices !NbSlice (case of 'multilevel' scan). These settings are stored in the xml file as part of the section and can be edited from '''uvmat.fig''' with the menu bar command '''[Tools/set slice]'''. A dialog box '''set_slices''' appears for entering the first and last section plane positions ''z'', as well as the number of slices and the option 'volume_scan' ('multilevel' otherwise). In the absence of 3D scan put twice the same value for first and last z.  Finally a tilt angle of the laser sheet, around the ''x'' and ''y'' axis, can be introduced, with a possible angular scanning from first to last section planes. After introduction of the plane position information, the z-index is displayed in the frame '''[!FileIndices]''' of '''uvmat.fig'''. The local ''z'' position of the mouse pointer, assumed to lay on the current section plane, is then displayed in '''[text_display]'''. -''' Refraction effect:''' refraction effect can be accounted for if calibration was done in air by selecting the check box refraction, and introducing the water height (assumed at ''z''=cte) and refraction index. The apparent distance reduction for objects below the water height will be then taken into account. The settings of the GUI ''' series''' are controlled by the following parameters (fields of the Matlab structure 'Param'): ||'''Name'''||'''Values'''||'''Default'''||'''Role'''|| ||.!WholeIndexRange||'off'/'on'||'off'||prescribes the file index ranges from min to max (the whole file series is needed)|| ||.!AllowInputSort||'off'/'on'||'off'||for multiple lines in the input file table, provides an automatic alphabetic sorting of the list of input files  !SubDir (so that the order of intput file series used does not depend on the order of introduction)|| ||.!NbSlice||positive integer||1||nbre of slices for processing on field indices modulo !NbSlice|| ||.!VelType||'off'/'one'/'two'||'off'||allows to select one input velocity type (for PIV data), or two types (two menus)|| ||.!FieldName||'off'/'one'/'two'||||allows to select one input field name, or two  (two menus)|| ||.!FieldTransform||'off'/'on'||'off'||allows the visibility of the menu 'transform function' (for instance phys transform)|| ||.!ProjObject||'off'/'on'||'off'||allows the introduction of a projection object|| ||.Mask||'off'/'on'||'off'||allows the introduction of mask images|| |||||||||| ||.!OutputDirExt||char string beginning with '.'||'.series'||set the output dir extension .ext which should characterize the processing function used|| ||!OutputSubDirMode||'auto'/'off'/'first'/'last'||'auto'||for multiple  lines in the input file table:[[BR]]'auto': output in a folder named with 'subdir1-subdir2...' from all the input folders [[BR]]'off': no output file (only for run in the current Matlab session)[[BR]]'first': output in a folder named after the first input folder[[BR]]'last': output in a folder named after the last input folder|| ||!OutputFileMode||'!NbSlice'/'!NbInput'/'!NbInput_i'||'!NbSlice'||indicate the number of output files (used to manage the dispatching on a cluster)[[BR]]'!NbSlice': one output file per slice (single output file in the default case !NbSlice=1)[[BR]]'!NbInput_i': one output file expected per value of  i index [[BR]]'!NbInput': one output file expected per input file|| ||!ActionInput||Matlab structure||||Matalb sub-structure containing input parameters specific to the current function|| || '''Name''' || '''Values''' || '''Default''' || '''Role''' || || .!WholeIndexRange || 'off'/'on' || 'off' || prescribes the file index ranges from min to max (the whole file series is needed) || || .!AllowInputSort || 'off'/'on' || 'off' || for multiple lines in the input file table, provides an automatic alphabetic sorting of the list of input files  !SubDir (so that the order of intput file series used does not depend on the order of introduction) || || .!NbSlice || positive integer || 1 || nbre of slices for processing on field indices modulo !NbSlice || || .!VelType || 'off'/'one'/'two' || 'off' || allows to select one input velocity type (for PIV data), or two types (two menus) || || .!FieldName || 'off'/'one'/'two' |||| allows to select one input field name, or two  (two menus) || || .!FieldTransform || 'off'/'on' || 'off' || allows the visibility of the menu 'transform function' (for instance phys transform) || || .!ProjObject || 'off'/'on' || 'off' || allows the introduction of a projection object || || .Mask || 'off'/'on' || 'off' || allows the introduction of mask images || || .!OutputDirExt || char string beginning with '.' || '.series' || set the output dir extension .ext which should characterize the processing function used || || !OutputSubDirMode || 'auto'/'off'/'first'/'last' || 'auto' || for multiple  lines in the input file table:[[BR]]'auto': output in a folder named with 'subdir1-subdir2...' from all the input folders [[BR]]'off': no output file (only for run in the current Matlab session)[[BR]]'first': output in a folder named after the first input folder[[BR]]'last': output in a folder named after the last input folder || || !OutputFileMode || '!NbSlice'/'!NbInput'/'!NbInput_i' || '!NbSlice' || indicate the number of output files (used to manage the dispatching on a cluster)[[BR]]'!NbSlice': one output file per slice (single output file in the default case !NbSlice=1)[[BR]]'!NbInput_i': one output file expected per value of  i index [[BR]]'!NbInput': one output file expected per input file || || !ActionInput || Matlab structure |||| Matalb sub-structure containing input parameters specific to the current function || To update (**): LIF_series: do LIF analysis, Stereo_PIV: combine two velicity series to yield the 3 components, part_stat: count particles and provides their density and luminosity histogramm, Peaklocking errors: estimate errors in PIV . By selecting the press button 'peaklocking' on the 'plotgraph' interface, you smooth the current velocity histograms while preserving its integral over each unity (in pixels). This appears in red. Then an estimate of the peaklocking error is obtained by comparing the initial histogram to the smooth one. The button '''[TEST]''' allows the user to witness the correlation as a live plot. It first opens the source image in a new figure '''view_field'''. By moving the mouse in the figure, the local correlation box and the corresponding search box are drawn in the image, and the 2D correlation result then appears in a new figure 'Figure1 Image Correlation' which automatically pops up. It is possible to freeze the current correlation plot, and get the values in the Matlab work space, by left mouse selection. The figure belows shows the correlation process and the '''[!SearchBox]''' and '''[!CorrBox]''' explained before. [[Image(civ1_test.jpg)]] [[Image(Correlation for PIV.png)]] [[Image(civ1_test.jpg)]]  [[Image(Correlation for PIV.png)]] The grid determines the positions of measured velocity vectors: it sets the central positions of the correlation boxes (in pixels) for the first image. A default regular grid can be set by the meshes '''[num_Dx] ''' and '''[num_Dy]''' (in pixels). Alternatively a custom [#a9.2Grids grid] can be stored in a text file and selected by the check box '''get grid'''. This is convenient to limitate the processing to a subregion or to fine tune the resolution. === 11.5 CIV2 === - '''CIV2:''' provides a refined calculation of the velocity field, using the civ1 result as previous estimate. The civ1 field provides an estimated shift for each measurement point, so there is no edit box to enter shift parameter. The other parameters, in particular '''[!CorrBoxSize]''' and '''[!SearchBoxSize]''', have the same meaning as for Civ1. The image pair for civ2 ( set by the menu '''[!ListPairCiv2]''', can be different than the one used in civ1. It is generally advised to use a moderate time interval for civ1, to provide a first estimate avoiding 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. * '''CIV2:''' provides a refined calculation of the velocity field, using the civ1 result as previous estimate. The civ1 field provides an estimated shift for each measurement point, so there is no edit box to enter shift parameter. The other parameters, in particular '''[!CorrBoxSize]''' and '''[!SearchBoxSize]''', have the same meaning as for Civ1. The image pair for civ2 ( set by the menu '''[!ListPairCiv2]''', can be different than the one used in civ1. It is generally advised to use a moderate time interval for civ1, to provide a first estimate avoiding 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. Image deformation and rotation can be introduced before calculating the correlations, by selecting '''[!CheckDeformation]'''. This option  is useful in the presence of strong shear or vorticity. The image correlation can be visualised by pressing the button '''TEST''' in the same way as for civ1. - '''FIX2:''' like '''[FIX1]''', except for a new possible flag value vec_F=4 which indicates that the difference between the estimator and the result is more than 1 pixel. This should be selected for excellent data (otherwise it may be too strict). - '''PATCH2:''' like '''[PATCH1]'''. Using the '''[TEST]''' option, we can similarly quantify the influence of the smoothing parameter. The recommended value of the rms difference between '''[Civ2]''' and '''[Patch2]''' (field 'filter2') is now set to 0.1, to safely avoid systematic distortion by smoothing in the final result. * '''FIX2:''' like '''[FIX1]''', except for a new possible flag value vec_F=4 which indicates that the difference between the estimator and the result is more than 1 pixel. This should be selected for excellent data (otherwise it may be too strict). * '''PATCH2:''' like '''[PATCH1]'''. Using the '''[TEST]''' option, we can similarly quantify the influence of the smoothing parameter. The recommended value of the rms difference between '''[Civ2]''' and '''[Patch2]''' (field 'filter2') is now set to 0.1, to safely avoid systematic distortion by smoothing in the final result. Further iterations: improvements can be obtained by further iterations of the civ2-fix2-patch2 process. Open again the interface, and consider the previous civ2 result as the prior guess civ1, and select the option civ3 in the checkbox which now appears in the panel civ2. The result will be put in a new NetCDF file, but still labelled as Civ2 field. Several fields, corresponding to the successive operations 'civ1', 'fix1', 'patch1', 'civ2', 'fix2', 'patch2' are stored in the same .nc file. When a third or higher order civ iteration is performed, a new .nc file is created, containing the two last iterations as civ1 and civ2. - '''List of constants (global attributes):''', * '''List of constants (global attributes):''', Conventions 'uvmat/civdata'. ||'''tag'''||'''        content'''|| ||Conventions||sets the conventions|| ||Program||name of the processing program|| ||!CivStage]||stage in the sequence civ1,fix1...|| ||Civ1(2)_ImageA||path and name of input image A|| ||Civ1(2)_ImageB||path and name of input  image B|| ||Civ1(2)_Time||mean time for the image pair|| ||Civ1(2)_Dt||time interval for image pair|| ||Civ1(2)_CorrBoxSize||size x,y of the correlation box|| ||Civ1_SearchBoxSize||size x,y of the search box|| ||Civ1_SearchBoxShift||(optional) shift of the search box|| ||Civ1(2)_CorrSmooth||smooth parameter for the image corr|| ||Civ1(2)_Dx,Civ1(2)_Dy||grid mesh along x, y|| ||Civ1(2)_CheckGrid||=1 if a grid file is used, default=0|| ||Civ1(2)_CheckMask||=1 if a mask file is used, default=0|| ||Civ1(2)_CheckThreshold||=0/1 image luminosity  threshold used|| ||Civ1_ImageBitDepth||nbre of grey level bits|| ||Civ1_ImageWidth||nbre of pixels along x|| ||Civ1_ImageHeight||nbre of pixels along y|| ||Civ1(2)_FrameIndexA||frame index of image A in the series|| ||Civ1(2)_FrameIndexB||frame index of image B in the series|| ||Patch1(2)_Rho||smoothing parameter for thin plate shell|| ||Patch1(2)_Threshold||threshold for the elimination of aberrant vectors|| ||Patch1(2)_SubDomain||estimated nbre of vectors in a subdomain|| ||Civ2_CheckDecimal||=1 if decimal shift option is used (reduced peaklocking)|| ||Civ2_CheckDeformation||=1 if image deformation option is used|| - '''List of variables:''' || '''tag''' || '''        content''' || || Conventions || sets the conventions || || Program || name of the processing program || || !CivStage] || stage in the sequence civ1,fix1... || || Civ1(2)_ImageA || path and name of input image A || || Civ1(2)_ImageB || path and name of input  image B || || Civ1(2)_Time || mean time for the image pair || || Civ1(2)_Dt || time interval for image pair || || Civ1(2)_CorrBoxSize || size x,y of the correlation box || || Civ1_SearchBoxSize || size x,y of the search box || || Civ1_SearchBoxShift || (optional) shift of the search box || || Civ1(2)_CorrSmooth || smooth parameter for the image corr || || Civ1(2)_Dx,Civ1(2)_Dy || grid mesh along x, y || || Civ1(2)_CheckGrid ||= 1 if a grid file is used, default=0 =|| || Civ1(2)_CheckMask ||= 1 if a mask file is used, default=0 =|| || Civ1(2)_CheckThreshold ||= 0/1 image luminosity  threshold used =|| || Civ1_ImageBitDepth || nbre of grey level bits || || Civ1_ImageWidth || nbre of pixels along x || || Civ1_ImageHeight || nbre of pixels along y || || Civ1(2)_FrameIndexA || frame index of image A in the series || || Civ1(2)_FrameIndexB || frame index of image B in the series || || Patch1(2)_Rho || smoothing parameter for thin plate shell || || Patch1(2)_Threshold || threshold for the elimination of aberrant vectors || || Patch1(2)_SubDomain || estimated nbre of vectors in a subdomain || || Civ2_CheckDecimal ||= 1 if decimal shift option is used (reduced peaklocking) =|| || Civ2_CheckDeformation ||= 1 if image deformation option is used =|| * '''List of variables:''' Conventions 'uvmat/civdata'. ||'''tag'''||'''dimensions'''||'''        content'''|| ||Civ1_X||nb_vec_1||x coordinates|| ||Civ1_Y||nb_vec_1||y coordinates|| ||Civ1_Z||nb_vec_1||z coordinates (for PIV in volume)|| ||Civ1_U||nb_vec_1||x velocity component|| ||Civ1_V||nb_vec_1||y velocity component|| ||Civ1_W||nb_vec_1||z velocity component (if relevant)|| ||Civ1_F||nb_vec_1||warning flag|| ||Civ1_C||nb_vec_1||image correlation|| ||Civ1_FF||nb_vec_1||error flag|| ||Civ1_U_smooth||nb_vec_1||smoothed x velocity component|| ||Civ1_V_smooth||nb_vec_1||smoothed y velocity component|| ||Civ1_W_smooth||nb_vec_1||smoothed z velocity component|| ||Civ1_SubRange||(nb_coord,nb_bounds,nb_subdomain_1)||subdomain bounds|| ||Civ1_NbCentres||nb_subdomain_1||nbre of tps centres (valid vectors) in each subdomain|| ||Civ1_Coord_tps||(nb_tps_1,nb_coord,nb_subdomain_1)||coordinates of tps centres for each subdomain|| ||Civ1_U_tps||(nb_tps_1,nb_subdomain_1)||tps weights for x vel component|| ||Civ1_V_tps||(nb_tps_1,nb_subdomain_1)||tps weights for y vel component|| ||Civ1_W_tps||(nb_tps_1,nb_subdomain_1)||tps weights for z vel component|| || '''tag''' || '''dimensions''' || '''        content''' || || Civ1_X || nb_vec_1 || x coordinates || || Civ1_Y || nb_vec_1 || y coordinates || || Civ1_Z || nb_vec_1 || z coordinates (for PIV in volume) || || Civ1_U || nb_vec_1 || x velocity component || || Civ1_V || nb_vec_1 || y velocity component || || Civ1_W || nb_vec_1 || z velocity component (if relevant) || || Civ1_F || nb_vec_1 || warning flag || || Civ1_C || nb_vec_1 || image correlation || || Civ1_FF || nb_vec_1 || error flag || || Civ1_U_smooth || nb_vec_1 || smoothed x velocity component || || Civ1_V_smooth || nb_vec_1 || smoothed y velocity component || || Civ1_W_smooth || nb_vec_1 || smoothed z velocity component || || Civ1_SubRange || (nb_coord,nb_bounds,nb_subdomain_1) || subdomain bounds || || Civ1_NbCentres || nb_subdomain_1 || nbre of tps centres (valid vectors) in each subdomain || || Civ1_Coord_tps || (nb_tps_1,nb_coord,nb_subdomain_1) || coordinates of tps centres for each subdomain || || Civ1_U_tps || (nb_tps_1,nb_subdomain_1) || tps weights for x vel component || || Civ1_V_tps || (nb_tps_1,nb_subdomain_1) || tps weights for y vel component || || Civ1_W_tps || (nb_tps_1,nb_subdomain_1) || tps weights for z vel component || '''dimensions:''' * For civ2, all indices _1 are replaced by _2 - '''List of constants, old CIVx conventions:''' * '''List of constants, old CIVx conventions:''' * nb_coord: =2 for PIV in a plane, =3 for PIV in a volume. * ro2_patch: smoothing coefficient rho used for patch2. - '''List of field variables (old CIVx conventions):''' a set of velocity vectors is defined by a 1D array of position coordinates x, y, and z for 3D civ, and a corresponding array for each of the velocity components u, v, and w for 3C civ. The field is therefore defined on an arbitrary set of point, without restriction to a regular mesh. Additional arrays are used to keep track of the quality of the PIV process leading to each vector. The image correlation maximum is represented by vec_C (a real number between 0 and 1). A flag vec_F represents a warning on the vector quality (see the list of values below). Another flag !FixFlag marks false vectors: !FixFlag=0 for good vectors, and !FixFlag is set to a non-zero value when it has been detected as false (using a 'fix' operation). * '''List of field variables (old CIVx conventions):''' a set of velocity vectors is defined by a 1D array of position coordinates x, y, and z for 3D civ, and a corresponding array for each of the velocity components u, v, and w for 3C civ. The field is therefore defined on an arbitrary set of point, without restriction to a regular mesh. Additional arrays are used to keep track of the quality of the PIV process leading to each vector. The image correlation maximum is represented by vec_C (a real number between 0 and 1). A flag vec_F represents a warning on the vector quality (see the list of values below). Another flag !FixFlag marks false vectors: !FixFlag=0 for good vectors, and !FixFlag is set to a non-zero value when it has been detected as false (using a 'fix' operation). The names of the fields (variables) resulting from each operation are given in the following table. Each column corresponds to an operation. 'filter1' and 'interp1' both result from the patch1 interpolation on the same points, with and without smoothing respectively. The first line is the name of the constant representing the number of vectors (the dimension of the arrays). The next successive lines indicate the variable names for the position and velocity components, the image correlation 'c', the 'flag' about civ quality and 'fix' flag (only available for civ1 and civ2), and the spatial derivatives obtained from the patch operations. - '''Names of field variables for civ1 and patch1''' ||'''   '''||civ1||'''interp1'''||'''filter1 '''|| ||dim.||nb_vectors||nb_vec_patch||nb_vec_patch|| ||x||vec_X||vec_patch_X||vec_patch_X|| ||y||vec_Y||vec_patch_Y||vec_patch_Y|| ||z||vec_Z||vec_patch_Z||vec_patch_Z|| ||u||vec_U||vec_patch0_U||vec_patch_U|| ||v||vec_V||vec_patch0_V||vec_patch_V|| ||w||vec_W||vec_patch0_W||vec_patch_W|| ||correlation||vec_C|||||| ||warning flag||vec_F|||||| ||false flag||vec_FixFlag|||||| ||du/dx||||vec_patch0_DUDX||vec_patch_DUDX|| ||du/dy||||vec_patch0_DUDY||vec_patch_DUDY|| ||dv/dx||||vec_patch0_DVDX||vec_patch_DVDX|| ||dv/dy||||vec_patch0_DVDY||vec_patch_DVDY|| - '''Names of field variables for civ2 and patch2''' * '''Names of field variables for civ1 and patch1''' || '''   ''' || civ1 || '''interp1''' || '''filter1 ''' || || dim. || nb_vectors || nb_vec_patch || nb_vec_patch || || x || vec_X || vec_patch_X || vec_patch_X || || y || vec_Y || vec_patch_Y || vec_patch_Y || || z || vec_Z || vec_patch_Z || vec_patch_Z || || u || vec_U || vec_patch0_U || vec_patch_U || || v || vec_V || vec_patch0_V || vec_patch_V || || w || vec_W || vec_patch0_W || vec_patch_W || || correlation || vec_C || || warning flag || vec_F || || false flag || vec_FixFlag || || du/dx |||| vec_patch0_DUDX || vec_patch_DUDX || || du/dy |||| vec_patch0_DUDY || vec_patch_DUDY || || dv/dx |||| vec_patch0_DVDX || vec_patch_DVDX || || dv/dy |||| vec_patch0_DVDY || vec_patch_DVDY || * '''Names of field variables for civ2 and patch2''' same as previous, replacing 'vec' by 'vec2'. ---- == 13 - Editing XML files with the GUI editxml == This GUI '''editxml.fig''' visualises and edits XML files. It is automatically called by the browser of '''uvmat.fig''' when a file with extension .xml is opened. This GUI ''' editxml.fig'''  visualises and edits XML files. It is automatically called by the browser of ''' uvmat.fig''' when a file with extension .xml is opened. When an input file is opened, editxml detects the title key, e.g. , and looks for the corresponding XML schema (e.g. {!ImaDoc.xsd} ). This schema is sought  in the directory defined by in the installation file {PARAM.xml} of UVMAT. If the schema is found, the hierarchical structure and keys given by the schema are diplayed.  Otherwise the  keys of the XML file are displayed.