| 1 | | == 1 Generalities== |
| 2 | | |
| 3 | | === 1.1 Aim=== |
| 4 | | |
| 5 | | The package uvmat can be used with a wide variety of input data: all image and movie formats recognised by Matlab (see [section 3.1->#sec3.1]), NetCDF binary files (see [section 7->#get_field]). It is however particularly designed for laboratory data obtained from imaging systems: it includes a GUI to run the Particle Image Velocimetry software [CIVx ->3], as well as tools for geometric calibration, masks, grid generation and image pre-processing (e.g. background removal), and editing xml documentation files. Stereoscopic PIV, PIV-LIF and 3D PIV in a volume (still under development) are handled. |
| 6 | | |
| 7 | | This package can be used without knowledge of the Matlab language, but it is designed to be complemented by user defined Matlab functions, providing flexibility for further data analysis. It provides convenient tools to develop a set of processing functions with a standardised system for input-output. |
| 8 | | |
| 9 | | Installation is described in [Presentation and download ->4] with package available there in a static version. The latest version can be downloaded from a [svn server->http://servforge.legi.grenoble-inp.fr/projects/soft-uvmat]. |
| 10 | | |
| 11 | | === 1.2 The package=== |
| 12 | | |
| 13 | | The master piece is a Matlab GUI, made of a Matlab figure '''uvmat.fig''' and an associated set of sub-functions in the file {uvmat.m}. The menu bar at the top of the GUI, push buttons and editing box in '''uvmat.fig''' activate the Matlab sub-functions (callback functions) in {uvmat.m}. The package also contains the following set of GUI (see [overview of the package->#overview] for a complete list). |
| 14 | | |
| 15 | | -'''browse_data.fig''' scans the data directory of a project |
| 16 | | - '''civ.fig:''' runs the software for Particle Imaging Velocimetry |
| 17 | | - '''editxml.fig:''' displays and edits xml files according to an xml schema. xml reading and editing is performed by the toolbox [xmltree->http://www.artefact.tk/software/matlab/xml/] , copied in the subdirectory /@xmltree. |
| 18 | | - '''geometry_calib.fig''': determines geometric calibration parameters for relating image to physical coordinates. The toolbox [->http://www.vision.caltech.edu/bouguetj/calib_doc/] is used, copied in the subdirectory /toolbox_calib. |
| 19 | | - '''get_field.fig:''' selects coordinates and field in a general NetCDF file. The subdirectory /get_field contains functions called by the GUI get_field. |
| 20 | | - '''series.fig:''' apply various processing functions to series of fields. These functions are stored in the subdirectory /series. |
| 21 | | -'''set_object.fig:''' creates and edits geometric objects used to project data: points, lines, planes... |
| 22 | | -'''view_field.fig:''' is a GUI complementing uvmat for plotting projected data. |
| 23 | | Functions in the package are used to generate file names, read files and plot data, and perform various ancillary tasks. |
| 24 | | |
| 25 | | === 1.3 Documentation and help=== |
| 26 | | The present on-line file is the reference document for the version currently available on the svn server. A html version ({uvmat_doc.html}) of this document is provided with the package, and accessible by help buttons in the GUIs. |
| 27 | | A short comment about each GUI uicontrol (push buttons, edit boxes, menus..), as well as the tag name of this uicontrol, is provided as a tool tip window by moving the mouse over it. In the present help document, the tags of GUI uicontrols are quoted as '''[uicontrol tag]''', names of files in the package are quoted as {fct name.m}, and commands on the Matlab workspace as '>> command’ . Features not yet implemented or tested (in particular 3D features) are marked by **. |
| 28 | | |
| 29 | | Information is also provided as comments in each function. Type '>>help fct_name' to get it, or open it with an editor. |
| 30 | | |
| 31 | | Finally a on-line [tutorial->105] is also provided with test images and data files. |
| 32 | | |
| 33 | | === 1.4 Copyright and licence=== |
| | 1 | =Help for Uvmat= |
| | 2 | |
| | 3 | == 1 Generalities == |
| | 4 | |
| | 5 | === 1.1 Aim === |
| | 6 | |
| | 7 | The package uvmat can be used with a wide variety of input data: all image and movie formats recognised by Matlab (see [section 3.1->#sec3.1]), NetCDF binary files (see [section 7->#get_field]). It is however particularly designed for laboratory data obtained from imaging systems: it includes a GUI to run the Particle Image Velocimetry software [CIVx ->3], as well as tools for geometric calibration, masks, grid generation and image pre-processing (e.g. background removal), and editing xml documentation files. Stereoscopic PIV, PIV-LIF and 3D PIV in a volume (still under development) are handled. |
| | 8 | |
| | 9 | This package can be used without knowledge of the Matlab language, but it is designed to be complemented by user defined Matlab functions, providing flexibility for further data analysis. It provides convenient tools to develop a set of processing functions with a standardised system for input-output. |
| | 10 | |
| | 11 | Installation is described in [Presentation and download ->4] with package available there in a static version. The latest version can be downloaded from a [svn server->http://servforge.legi.grenoble-inp.fr/projects/soft-uvmat]. |
| | 12 | |
| | 13 | === 1.2 The package === |
| | 14 | |
| | 15 | The master piece is a Matlab GUI, made of a Matlab figure '''uvmat.fig''' and an associated set of sub-functions in the file {uvmat.m}. The menu bar at the top of the GUI, push buttons and editing box in '''uvmat.fig''' activate the Matlab sub-functions (callback functions) in {uvmat.m}. The package also contains the following set of GUI (see [overview of the package->#overview] for a complete list). |
| | 16 | |
| | 17 | -'''browse_data.fig''' scans the data directory of a project - '''civ.fig:''' runs the software for Particle Imaging Velocimetry - '''editxml.fig:''' displays and edits xml files according to an xml schema. xml reading and editing is performed by the toolbox [xmltree->http://www.artefact.tk/software/matlab/xml/] , copied in the subdirectory /@xmltree. - '''geometry_calib.fig''': determines geometric calibration parameters for relating image to physical coordinates. The toolbox [->http://www.vision.caltech.edu/bouguetj/calib_doc/] is used, copied in the subdirectory /toolbox_calib. - '''get_field.fig:''' selects coordinates and field in a general NetCDF file. The subdirectory /get_field contains functions called by the GUI get_field. - '''series.fig:''' apply various processing functions to series of fields. These functions are stored in the subdirectory /series. -'''set_object.fig:''' creates and edits geometric objects used to project data: points, lines, planes... -'''view_field.fig:''' is a GUI complementing uvmat for plotting projected data. |
| | 18 | |
| | 19 | Functions in the package are used to generate file names, read files and plot data, and perform various ancillary tasks. |
| | 20 | |
| | 21 | === 1.3 Documentation and help === |
| | 22 | The present on-line file is the reference document for the version currently available on the svn server. A html version ({uvmat_doc.html}) of this document is provided with the package, and accessible by help buttons in the GUIs. |
| | 23 | A short comment about each GUI uicontrol (push buttons, edit boxes, menus..), as well as the tag name of this uicontrol, is provided as a tool tip window by moving the mouse over it. In the present help document, the tags of GUI uicontrols are quoted as '''[uicontrol tag]''', names of files in the package are quoted as {fct name.m}, and commands on the Matlab workspace as '>> command’ . Features not yet implemented or tested (in particular 3D features) are marked by **. |
| | 24 | |
| | 25 | Information is also provided as comments in each function. Type '>>help fct_name' to get it, or open it with an editor. |
| | 26 | |
| | 27 | Finally a on-line [tutorial->105] is also provided with test images and data files. |
| | 28 | |
| | 29 | === 1.4 Copyright and licence === |
| 136 | | The choice of fields, velocity, vorticity, divergence... is done by the popup menu '''[Fields]'''. The option 'image' gives access to an image file corresponding to the velocity field. The option 'get_field...' allows the user to display all the variables of the netcdf file in the GUI '''get_field.fig'''. This is the only available option when the input file is not from CIV. |
| 137 | | |
| 138 | | === 3.3 File naming and indexing=== |
| 139 | | |
| 140 | | Different kinds of file or image frame indexing are defined: |
| 141 | | |
| 142 | | -'''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 singlemovie file. Then the index i stands for the frame index within the file. |
| 143 | | |
| 144 | | -'''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. |
| 145 | | |
| 146 | | -'''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. |
| 147 | | 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. |
| | 118 | The choice of fields, velocity, vorticity, divergence... is done by the popup menu '''[Fields]'''. The option 'image' gives access to an image file corresponding to the velocity field. The option 'get_field...' allows the user to display all the variables of the netcdf file in the GUI '''get_field.fig'''. This is the only available option when the input file is not from CIV. |
| | 119 | |
| | 120 | === 3.3 File naming and indexing === |
| | 121 | Different kinds of file or image frame indexing are defined: |
| | 122 | |
| | 123 | -'''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 singlemovie file. Then the index i stands for the frame index within the file. |
| | 124 | |
| | 125 | -'''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. |
| | 126 | |
| | 127 | -'''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. |
| 286 | | -'''Warning flags''': they indicate a vector resulting from a dubious image correlation process, but not removed from the data set. Their display in black can be desactivated by selecting the check box '''[CheckHideWarning]'''. |
| 287 | | |
| 288 | | -'''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]'''. |
| 289 | | |
| 290 | | -'''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: |
| 291 | | -*'rgb': color ranging from red, for the scalar value set by '''[num_MinVec]''', to blue, for the scalar value set by '''[num_MaxVec]'''. The |
| 292 | | 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 [AutoVecColor], these thresholds can be set to match the min and max scalar values. |
| 293 | | -*'black' or 'white': set the color for all vectors |
| 294 | | -*'brg': same as rgb but in reverse order, with blue for the lowest scalar values. |
| 295 | | -*'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]'''. |
| 296 | | |
| 297 | | -'''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 |
| 298 | | -* fist line: the position coordinates x, y, (z for 3D cases). |
| 299 | | -* second line: the vector components |
| 300 | | -* 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 [section 10.3->#sec10.3]. |
| | 218 | -'''Warning flags''': they indicate a vector resulting from a dubious image correlation process, but not removed from the data set. Their display in black can be desactivated by selecting the check box '''[CheckHideWarning]'''. |
| | 219 | |
| | 220 | -'''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]'''. |
| | 221 | |
| | 222 | -'''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 [AutoVecColor], 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]'''. |
| | 223 | |
| | 224 | -'''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). -* second line: the vector components -* 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 [section 10.3->#sec10.3]. |
| 308 | | For color images, the histogram of each color component, r, g, b, is given with a curve of the corresponding color. In case of saturation, the proportion of pixels beyond the max limit is written on the graph. |
| 309 | | |
| 310 | | === 4.4 Comparing two fields=== |
| 311 | | |
| 312 | | A second field series can be opened and compared to the first one, using the menu bar command '''[Open_1]'''. Then a new file name and indices appear on the second line, as well as the check box '''[SubField]''' on the very right. The second field can be alternatively obtained by selecting a field in the popup menu '''[Fields_1] ''' (under '''[Fields]'''). |
| 313 | | |
| 314 | | If the two files are both images or scalar, their difference is introduced as the input field. If one field is an image (or scalar), while the other one is a vector field, the image will appear as a background in the vector field. This is convenient for instance to relate the CIV result to the quality of the images, or to relate vorticity to the vector field. |
| 315 | | |
| 316 | | If two vector fields are compared, their difference is taken as the input field, and is then displayed and analysed. If the two fields are not at the same points, the velocity of the second field is linearly interpolated at the positions of the first one (using the Matlab function {griddata.m}). The color and flags are then taken from the first field. |
| 317 | | |
| 318 | | The two file series will be scanned simultaneously by '''[runplus]''' ( '->') and '''[runmin]''' ('<-') , according to their own nomenclature. It is also possible to manually edit the second file indices '''[FieldIndex_1] ''' to compare two fields with different indices. |
| 319 | | If available, the time of the second field is indicated in the edit box '''[abs_time_1] ''' at the very right, below the time of the main field. |
| | 231 | For color images, the histogram of each color component, r, g, b, is given with a curve of the corresponding color. In case of saturation, the proportion of pixels beyond the max limit is written on the graph. |
| | 232 | |
| | 233 | === 4.4 Comparing two fields === |
| | 234 | A second field series can be opened and compared to the first one, using the menu bar command '''[Open_1]'''. Then a new file name and indices appear on the second line, as well as the check box '''[SubField]''' on the very right. The second field can be alternatively obtained by selecting a field in the popup menu '''[Fields_1] ''' (under '''[Fields]'''). |
| | 235 | |
| | 236 | If the two files are both images or scalar, their difference is introduced as the input field. If one field is an image (or scalar), while the other one is a vector field, the image will appear as a background in the vector field. This is convenient for instance to relate the CIV result to the quality of the images, or to relate vorticity to the vector field. |
| | 237 | |
| | 238 | If two vector fields are compared, their difference is taken as the input field, and is then displayed and analysed. If the two fields are not at the same points, the velocity of the second field is linearly interpolated at the positions of the first one (using the Matlab function {griddata.m}). The color and flags are then taken from the first field. |
| | 239 | |
| | 240 | The two file series will be scanned simultaneously by '''[runplus]''' ( '->') and '''[runmin]''' ('<-') , according to their own nomenclature. It is also possible to manually edit the second file indices '''[FieldIndex_1] ''' to compare two fields with different indices. If available, the time of the second field is indicated in the edit box '''[abs_time_1] ''' at the very right, below the time of the main field. |
| 324 | | === 4.5 Field transforms:=== |
| 325 | | A transform can be systematically applied after reading the input field, for instance the transform 'phys' which takes into account geometric calibration. This transform can possibly combine two input fields, for instance to substract a background from an image. The processing function is chosen by the popup menu '''[transform_fct]''' on the left, and its path is displayed in the box '''[path_transform]'''. Select the option 'more...' to browse new functions. The same functions can be called in data processsing using the GUI '''series.fig'''. A few functions are provided in the folder /transform_fct, see list in [annex->#overview]. |
| 326 | | |
| 327 | | These functions can transform fields into polar coordinates, do image filtering, Fourier transform, signal analysis for a 1D input field... Other functions can be easily written using those as templates. The general form of such functions is |
| 328 | | DataOut=transform_fct(DataIn,XmlData,DataIn_1,XmlData_1) |
| 329 | | where Data is an input field object, as described in [section 5.4->#sec5.4], and XmlData the content of the xml file Imadoc, as stored in the uvmat GUI. XmlData contains in particular the element .GeometryCalib containing the calibration parameters, see [section 7->#geometry_calib]. |
| 330 | | |
| 331 | | === 4.6 Succession of operations:=== |
| 332 | | |
| 333 | | The following succession of operations is performed by '''uvmat.fig''': |
| 334 | | -'''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. |
| 335 | | -'''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). |
| 336 | | -'''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. |
| 337 | | -'''Histogram:''' This is obtained from the input field in transformed coordinates, or if applicable from the fields resulting from the two input fields. |
| 338 | | -'''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}. |
| 339 | | -'''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}. |
| 340 | | -'''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. |
| 341 | | -'''Plotting:''' plot the results of projection. Function used: {plot_field.m} |
| 342 | | |
| 343 | | [<doc115|right>->#top] |
| 344 | | |
| 345 | | ---------------- |
| 346 | | [field_structures<-] |
| 347 | | '''{5- Field objects:=== |
| | 245 | |
| | 246 | === 4.5 Field transforms: === |
| | 247 | A transform can be systematically applied after reading the input field, for instance the transform 'phys' which takes into account geometric calibration. This transform can possibly combine two input fields, for instance to substract a background from an image. The processing function is chosen by the popup menu '''[transform_fct]''' on the left, and its path is displayed in the box '''[path_transform]'''. Select the option 'more...' to browse new functions. The same functions can be called in data processsing using the GUI '''series.fig'''. A few functions are provided in the folder /transform_fct, see list in [annex->#overview]. |
| | 248 | |
| | 249 | These functions can transform fields into polar coordinates, do image filtering, Fourier transform, signal analysis for a 1D input field... Other functions can be easily written using those as templates. The general form of such functions is DataOut=transform_fct(DataIn,XmlData,DataIn_1,XmlData_1) where Data is an input field object, as described in [section 5.4->#sec5.4], and XmlData the content of the xml file Imadoc, as stored in the uvmat GUI. XmlData contains in particular the element .[wiki:GeometryCalib] containing the calibration parameters, see [section 7->#geometry_calib]. |
| | 250 | |
| | 251 | === 4.6 Succession of operations: === |
| | 252 | 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} |
| | 253 | |
| | 254 | [<doc115|right>->#top] |
| | 255 | |
| | 256 | ---- |
| | 257 | [field_structures<-] '''{5- Field objects:===''' |
| 381 | | In summary, the {field object} is specified by a structure with the following elements: |
| 382 | | -*(optional) .ListGlobalAttribute: list (cell array of character strings) of the names of global attributes Att_1, Att_2... |
| 383 | | -* (mandatory) .ListVarName: list of the variable names Var_1, Var_2....(cell array of character strings). |
| 384 | | -* (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. |
| 385 | | -* (optional) .VarAttribute: cell array of structures of the form .VarAttribute<HTML>{ivar}</HTML>.key=value, defining an attribute tag name and value for the variable #ivar (variable number in the list .ListVarName). |
| 386 | | -* .Att_1, Att_2... : values of the listed global attributes. |
| 387 | | -* .Var_1, .Var_2....: variables arrays whose names are listed in .ListVarName |
| 388 | | |
| 389 | | 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. |
| 390 | | -* .ListDimName: list of dimension names (cell array of character strings) |
| 391 | | -* .DimValue: array of dimension values corresponding to LisDimName. |
| 392 | | |
| 393 | | The following temporary information is added to manage projection and field substraction oerations, which must be done in general after projection: |
| 394 | | -* 'FieldRequest': 'interp_lin', 'interp_tps' indicate whether lin interpolation or derivatives by tps is needed to calculate the requested field. |
| 395 | | -* 'Operation': name (char string) of the operation to be performed to finalise the field cell after projection. |
| 396 | | -* 'SubCheck' 0 /1 indicate that the field must be substracted (second entry in uvmat) |
| 397 | | |
| 398 | | Any other element can be added, but will not be taken into account if they are not listed in .ListGlobalAttribute or .ListVarName. |
| | 293 | In summary, the {field object} is specified by a structure with the following elements: -*(optional) .[wiki:ListGlobalAttribute]: list (cell array of character strings) of the names of global attributes Att_1, Att_2... -* (mandatory) .[wiki:ListVarName]: list of the variable names Var_1, Var_2....(cell array of character strings). -* (mandatory) .[wiki:VarDimName]: list of the dimensions associated with each variable: this is a cell array whose number of element is equal to that of .[wiki: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) .[wiki:VarAttribute]: cell array of structures of the form .[wiki:VarAttribute]<HTML>{ivar}</HTML>.key=value, defining an attribute tag name and value for the variable #ivar (variable number in the list .[wiki:ListVarName]). -* .Att_1, Att_2... : values of the listed global attributes. -* .Var_1, .Var_2....: variables arrays whose names are listed in .[wiki:ListVarName] |
| | 294 | |
| | 295 | 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. -* .[wiki:ListDimName]: list of dimension names (cell array of character strings) -* .[wiki:DimValue]: array of dimension values corresponding to LisDimName. |
| | 296 | |
| | 297 | The following temporary information is added to manage projection and field substraction oerations, which must be done in general after projection: -* 'FieldRequest': 'interp_lin', 'interp_tps' indicate 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) |
| | 298 | |
| | 299 | Any other element can be added, but will not be taken into account if they are not listed in .[wiki:ListGlobalAttribute] or .[wiki:ListVarName]. |
| 401 | | === 5.3 Conventions for attributes in field objects:=== |
| 402 | | -'''Global attributes active in uvmat''' |
| 403 | | Those are used for plot settings or data processing. |
| 404 | | -*'Conventions': |
| 405 | | ='uvmat': indicate that the conventions described here are followed |
| 406 | | ='uvmat/civdata': indicate that the variables are named according to [CIV data description->#civdata]. |
| 407 | | -*'CoordMesh': typical mesh for coordinates, used to define default projection grids and mouse selection action. Calculated automatically from the data if not specified. |
| 408 | | -*'CoordUnit': character string representing the unit for space coordinates. It is used to distinguish image coordinates (CoordUnit='pixel') and physical (for instance |
| 409 | | 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). |
| 410 | | -*Dt: time interval for CIV data. It is used for calibration, to transform displacement into velocity. |
| 411 | | -*Time: real number indicating the time of the field, used to obtain time series from data sets. |
| 412 | | -*TimeUnit: character string representing the unit of time (consistently for Time, Dt and velocity). |
| 413 | | |
| 414 | | -'''Global attributes , unactive''' |
| 415 | | those are merely used for information purpose |
| 416 | | -*Project: recalls the project name |
| 417 | | -*Campaign: recalls the campaign name |
| 418 | | -*Experiment: recalls the experiment name(s) of the raw data -*DataSeries: recalls the device name (s), if defined, of the raw data |
| 419 | | -*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. |
| 420 | | -*ObjectCoord: Coordinates defining a geometric object on which the data have been projected. |
| 421 | | -*ObjectRangeX, ObjectRangeY, ObjectRangeZ : range of action of a projection object along each coordinate, see section 6. |
| 422 | | -* '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. |
| 423 | | |
| 424 | | -'''Attributes of variables:''' |
| 425 | | -* Mesh: suggested step value to discretize the values of the variable, used to define the bins for histograms. |
| 426 | | -* 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'. |
| 427 | | -* 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). |
| 428 | | |
| 429 | | -'''The attribute 'Role':''' |
| 430 | | The following options are used for the attribute 'role': |
| 431 | | -* 'ancillary': information of secondary use, indicating for instance an error estimate of field variables within a field cell (omitted in plotting) |
| 432 | | -* '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. |
| 433 | | -* 'coord_tps': coordinates of thin plate shell (tps) centres used for spline interpolation. |
| 434 | | -* 'discrete': field with discrete values (no spatial interpolation), repesented with dots (no line) in 1D plots. |
| 435 | | -* '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. |
| 436 | | -* 'grad_x', 'grad_y', 'grad_z' :represents the x, y or z component of a contravariant vector** (like gradients). |
| 437 | | -* 'image_rgb': represents a color image. The last dimension of the array corresponds to the three color components 'rgb'. |
| 438 | | -* 'scalar': (default) represents a scalar field |
| 439 | | -* 'tensor': represents a tensor field whose components correspond to the two last dimensions of the array.** |
| 440 | | -* vector: matrix whose last dimension states for the vector components.** |
| 441 | | -* 'vector_x', 'vector_y', 'vector_z' : represents the x, y or z component of a vector (covariant) |
| 442 | | -* 'warnflag': provides a warning flag about the quality of data for the field variables within a field cell., default=0, no warning. |
| 443 | | |
| 444 | | === 5.4 Field cells:=== |
| | 302 | |
| | 303 | === 5.3 Conventions for attributes in field objects: === |
| | 304 | -'''Global attributes active in uvmat''' Those are used for plot settings or data processing. -*'Conventions': |
| | 305 | |
| | 306 | ='uvmat': indicate that the conventions described here are followed |
| | 307 | |
| | 308 | ='uvmat/civdata': indicate that the variables are named according to [CIV data description->#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). |
| | 309 | |
| | 310 | -'''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. |
| | 311 | |
| | 312 | -'''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). |
| | 313 | |
| | 314 | -'''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. |
| | 315 | |
| | 316 | === 5.4 Field cells: === |
| 447 | | -*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. |
| 448 | | -* 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. |
| 449 | | -* 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). |
| 450 | | -* Thin plate shell (tps) field cell: represents a set of coordinates and tps weights in a way suitable for tps interpolation/filter. |
| 451 | | |
| 452 | | 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: |
| 453 | | -* coord_1,_2,_3: dimension with the same name as a coordinate variable array (coordinate dimension) |
| 454 | | -* 'nb_coord': denotes the space dimension for vector components |
| 455 | | -* 'nb_coord_j', 'nb_coord_i': denotes the space dimensions for the two tensor components |
| 456 | | -* 'rgb' : denotes the diemension of the color component in a true color image. |
| 457 | | -* 'nb_point' or 'nb_vec' (for vectors) denotes the set of positions with unstructured coordinates. |
| 458 | | -* 'nb_tps': diemension of the index for the tps centres |
| 459 | | -* 'nb_subdomain' denotes the dimension for the subdomain index for tps coefficients |
| 460 | | |
| 461 | | [<doc115|right>->#top] |
| 462 | | |
| 463 | | ------------------------ |
| 464 | | [set_object<-] |
| 465 | | '''{6- Projection objects:=== |
| 466 | | |
| 467 | | === 6.1 Definition and editing with the uvmat interface:=== |
| 468 | | |
| 469 | | These are geometrical objects used to define cuts along lines or planes, to interpolate fields on a regular grid, to restrict the analysis or visualisation of fields to subregions. Objects are created by the menu bar command '''[Projection object]''' in '''uvmat.fig'''. The creation of a new object ('points', 'line'....) can be initiated by selecting the corresponding item in the menu. Alternatively, an existing xml object file can be opened by the option 'browse...'. |
| 470 | | |
| 471 | | In each case an auxiliary GUI '''set_object.fig''' describing the object properties appears, see next [sub-section->#sec6.2] for their definitions. This GUI can be edited by mouse drawing in the plotted field or by direct input. In the latter case, refresh the plots by pressing''' [PLOT] ''' in '''set_object.fig''' . Objects can be saved as xml files with the button ''' [SAVE]''' of '''set_object.fig'''. |
| | 319 | -*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. |
| | 320 | |
| | 321 | The field structure is furthermore indicated by using appropriate names for dimensions, but this is only for documentation, without use in processing functions (except for coordinate dimensions denoting coordinate range, see above). The following conventions are used: -* coord_1,_2,_3: dimension with the same name as a coordinate variable array (coordinate dimension) -* 'nb_coord': denotes the space dimension for vector components -* 'nb_coord_j', 'nb_coord_i': denotes the space dimensions for the two tensor components -* 'rgb' : denotes the diemension of the color component in a true color image. -* 'nb_point' or 'nb_vec' (for vectors) denotes the set of positions with unstructured coordinates. -* 'nb_tps': diemension of the index for the tps centres -* 'nb_subdomain' denotes the dimension for the subdomain index for tps coefficients |
| | 322 | |
| | 323 | [<doc115|right>->#top] |
| | 324 | |
| | 325 | ---- |
| | 326 | [set_object<-] '''{6- Projection objects:===''' |
| | 327 | |
| | 328 | === 6.1 Definition and editing with the uvmat interface: === |
| | 329 | These are geometrical objects used to define cuts along lines or planes, to interpolate fields on a regular grid, to restrict the analysis or visualisation of fields to subregions. Objects are created by the menu bar command '''[Projection object]''' in '''uvmat.fig'''. The creation of a new object ('points', 'line'....) can be initiated by selecting the corresponding item in the menu. Alternatively, an existing xml object file can be opened by the option 'browse...'. |
| | 330 | |
| | 331 | In each case an auxiliary GUI '''set_object.fig''' describing the object properties appears, see next [sub-section->#sec6.2] for their definitions. This GUI can be edited by mouse drawing in the plotted field or by direct input. In the latter case, refresh the plots by pressing''' [PLOT] ''' in '''set_object.fig''' . Objects can be saved as xml files with the button ''' [SAVE]''' of '''set_object.fig'''. |
| 508 | | === 6.3 Projection modes:=== |
| 509 | | 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. |
| 510 | | |
| 511 | | -''' {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). |
| 512 | | |
| 513 | | -''' {ProjMode 'interp':} ''' |
| 514 | | Linear interpolation of the fields on a grid of regularly spaced points defined on the projection object, with meshes DX, DY, DZ. The grid array along x starts at RangeX(1) and ends at the closest value smaller than RangeX(2). Similar convention is used for y and z in case of planes and volumes. |
| 515 | | |
| 516 | | -''' {ProjMode 'filter':} ''' filtered interpolation (used only for lines). For each point an average of the neighborhing data is used, with a weighting function whose range is given by max(RangeY). This is useful to get reliable profiles in the presence of 'holes' in the data fields. |
| 517 | | |
| 518 | | -''' {ProjMode 'inside' and 'ouside} '''': defined only for closed lines: rectangle, polygon, ellipse. For each field U, its probability distribution function Uhist inside, or respectively outside, the line is calculated, as well as the mean Umean. |
| 519 | | |
| 520 | | -''' {ProjMode 'none', 'mask_inside', 'mask_outside':} ''' no projection operation. The object is used solely for plotting purpose, to show a boundary or to prepare a mask, inside or outside a closed line, see [section 8.1->#sec8.1]). |
| 521 | | |
| | 357 | |
| | 358 | === 6.3 Projection modes: === |
| | 359 | 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). |
| | 360 | |
| | 361 | -''' {ProjMode 'interp':} ''' Linear interpolation of the fields on a grid of regularly spaced points defined on the projection object, with meshes DX, DY, DZ. The grid array along x starts at RangeX(1) and ends at the closest value smaller than RangeX(2). Similar convention is used for y and z in case of planes and volumes. |
| | 362 | |
| | 363 | -''' {ProjMode 'filter':} ''' filtered interpolation (used only for lines). For each point an average of the neighborhing data is used, with a weighting function whose range is given by max(RangeY). This is useful to get reliable profiles in the presence of 'holes' in the data fields. |
| | 364 | |
| | 365 | -''' {ProjMode 'inside' and 'ouside} '''': defined only for closed lines: rectangle, polygon, ellipse. For each field U, its probability distribution function Uhist inside, or respectively outside, the line is calculated, as well as the mean Umean. |
| | 366 | |
| | 367 | -''' {ProjMode 'none', 'mask_inside', 'mask_outside':} ''' no projection operation. The object is used solely for plotting purpose, to show a boundary or to prepare a mask, inside or outside a closed line, see [section 8.1->#sec8.1]). |
| 528 | | -''' {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. |
| 529 | | -*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. |
| 530 | | -*ProjMode= 'interp': U(i),i=1 is obtained as a linear interpolation on each point. |
| 531 | | |
| 532 | | -''' {Projection on open lines:} ''' |
| 533 | | 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**. |
| 534 | | -*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. |
| 535 | | -* ProjMode='interp': |
| 536 | | 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. |
| 537 | | -* ProjMode='filter': |
| 538 | | same as 'interp' but with a smoothing operation. |
| 539 | | |
| 540 | | -''' {Projection on closed lines:} ''' , |
| 541 | | 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. |
| 542 | | |
| 543 | | -''' {Projection on planes:} ''' |
| 544 | | 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. |
| 545 | | -*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). |
| 546 | | -* ProjMode='interp': |
| 547 | | 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. |
| 548 | | |
| 549 | | -''' {Projection on volumes:**} ''' |
| 550 | | This is used to delimitate a volume for 3D representation |
| | 374 | -''' {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': U(i),i=1 is obtained as a linear interpolation on each point. |
| | 375 | |
| | 376 | -''' {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': |
| | 377 | |
| | 378 | 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. |
| | 379 | |
| | 380 | -* ProjMode='filter': 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. |
| | 381 | |
| | 382 | -''' {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': |
| | 383 | |
| | 384 | 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. |
| | 385 | |
| | 386 | -''' {Projection on volumes:**} ''' This is used to delimitate a volume for 3D representation |
| 557 | | -* 'points' are represented by dots surrounded by a dashed circle showing the range of projection. |
| 558 | | -* 'line' , 'polyline' are plotted as lines, surrounded by two dashed lines showing the range of projection, when applicable (i.e. not in the case ProjMode='interp'). |
| 559 | | -* 'polygon', 'rectangle', 'ellipse' are drawn. In the case ProjMode ='inside' or 'outside' the corresponding area is painted in magenta (or blue when they are not selected). |
| 560 | | -* 'plane' are shown by their axis. These axis are limited to their range of selection (RangeX and RangeY) when applicable. Otherwise they end at the edge of the figure with an arrow. ** |
| 561 | | -* 'volume' are shown like 'plane', except that they are painted in magenta (or blue) ** |
| 562 | | |
| 563 | | -''' {Creating and editing objects with the mouse:} ''' |
| 564 | | 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. |
| 565 | | -*'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. |
| 566 | | -*'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'). |
| 567 | | -*'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. |
| 568 | | -*'rectangle': defined by its center, half width and half height. |
| 569 | | -*'polygon': closed line made of n consecutive segments (defined by n points) |
| 570 | | -*ellipse: defined by its center, half width and half height. |
| 571 | | -*plane: plane with associated cartesian coordinates |
| 572 | | -*volume: volume with associated cartesian coordinates |
| 573 | | |
| 574 | | [<doc115|right>->#top] |
| 575 | | |
| 576 | | ---------------- |
| 577 | | [get_field<-] |
| 578 | | '''{7- Netcdf files and get_field.fig:=== |
| 579 | | [netcdf<-] |
| 580 | | === 7.1 The NetCDF format:=== |
| 581 | | |
| | 393 | -* 'points' are represented by dots surrounded by a dashed circle showing the range of projection. -* 'line' , 'polyline' are plotted as lines, surrounded by two dashed lines showing the range of projection, when applicable (i.e. not in the case ProjMode='interp'). -* 'polygon', 'rectangle', 'ellipse' are drawn. In the case ProjMode ='inside' or 'outside' the corresponding area is painted in magenta (or blue when they are not selected). -* 'plane' are shown by their axis. These axis are limited to their range of selection (RangeX and RangeY) when applicable. Otherwise they end at the edge of the figure with an arrow. ** -* 'volume' are shown like 'plane', except that they are painted in magenta (or blue) ** |
| | 394 | |
| | 395 | -''' {Creating and editing objects with the mouse:} ''' |
| | 396 | |
| | 397 | 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. |
| | 398 | |
| | 399 | -*'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 |
| | 400 | |
| | 401 | [<doc115|right>->#top] |
| | 402 | |
| | 403 | ---- |
| | 404 | [get_field<-] '''{7- Netcdf files and get_field.fig:=== [netcdf<-]''' |
| | 405 | |
| | 406 | === 7.1 The NetCDF format: === |
| 592 | | -'''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. |
| 593 | | |
| 594 | | -'''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. |
| 595 | | |
| 596 | | 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. |
| 597 | | |
| 598 | | Another difference between attributes and variables is that variables may be multidimensional. Attributes are all either scalars (single-valued) or vectors (a single, fixed dimension). |
| 599 | | |
| 600 | | Variables are created with a name, type, and shape before they are assigned data values, so a variable may exist with no values. The value of an attribute is specified when it is created, unless it is a zero-length attribute. |
| 601 | | |
| 602 | | A variable may have attributes, but an attribute cannot have attributes. Attributes assigned to variables may have the same units as the variable (for example, valid_range) or have no units (for example, scale_factor). If you want to store data that requires units different from those of the associated variable, it is better to use a variable than an attribute. More generally, if data require ancillary data to describe them, are multidimensional, require any of the defined NetCDF dimensions to index their values, or require a significant amount of storage, that data should be represented using variables rather than attributes. |
| 603 | | |
| 604 | | |
| 605 | | === 7.3 The GUI get_field:=== |
| 606 | | |
| 607 | | This GUI is designed to analyse a NetCDF file, showing all the variables, attributes and variable dimensions. Variables can be selected and plotted. The GUI is opened by the Matlab prompt command '>>get_field'. It is also opened by the GUI '''uvmat.fig''' when an input NetCDF file does contain recognised CIVx data: then it takes the name 'uvmat_field', and some dfeatures are inhibited, to show that it depends on uvmat. |
| | 417 | -'''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. |
| | 418 | |
| | 419 | -'''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. |
| | 420 | |
| | 421 | 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. |
| | 422 | |
| | 423 | Another difference between attributes and variables is that variables may be multidimensional. Attributes are all either scalars (single-valued) or vectors (a single, fixed dimension). |
| | 424 | |
| | 425 | Variables are created with a name, type, and shape before they are assigned data values, so a variable may exist with no values. The value of an attribute is specified when it is created, unless it is a zero-length attribute. |
| | 426 | |
| | 427 | A variable may have attributes, but an attribute cannot have attributes. Attributes assigned to variables may have the same units as the variable (for example, valid_range) or have no units (for example, scale_factor). If you want to store data that requires units different from those of the associated variable, it is better to use a variable than an attribute. More generally, if data require ancillary data to describe them, are multidimensional, require any of the defined NetCDF dimensions to index their values, or require a significant amount of storage, that data should be represented using variables rather than attributes. |
| | 428 | |
| | 429 | === 7.3 The GUI get_field: === |
| | 430 | This GUI is designed to analyse a NetCDF file, showing all the variables, attributes and variable dimensions. Variables can be selected and plotted. The GUI is opened by the Matlab prompt command '>>get_field'. It is also opened by the GUI '''uvmat.fig''' when an input NetCDF file does contain recognised CIVx data: then it takes the name 'uvmat_field', and some dfeatures are inhibited, to show that it depends on uvmat. |
| 611 | | When a NetCDF input file is entered, 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. The whole content of the NetCDF file can be made available on the Matlab prompt in the form of a Matlab structure 'Data_get_field': use the menu bar button '''[Export]''', or click the right button mouse on the interface. |
| 612 | | |
| 613 | | Plots can be made in a new figure (default), to the interface '''uvmat.fig''', or added to an existing one, as selected in '''[list_fig]'''. Different processing or plotting functions can be activated by a selection in '''[ACTION]'''. The default action is a plot of selected field, as follows. |
| 614 | | |
| 615 | | -'''Ordinary graphs:''' to plot a simple graph, select the check box '''[1D_plot]'''. Then select the variable to plot in the column '''[ordinate] ''' and the corresponding abscissa in the column '''[abscissa]''', then press '''[RUN]'''. 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 no variable is selected in '''[abscissa]''' ( blank selected at first line), the variable is plotted versus its (first) index. |
| 616 | | |
| 617 | | -'''Scalar maps:''' select this check box to plot scalar fields as images. The scalar field is selected in the first column [scalar], with coordinates respectively selected in '''[coord_x_scalar] ''' and '''[coord_y_scalar]'''. If no variable is selected in '''[coord_x_scalar] ''' or '''[coord_y_scalar] ''' ( blank selected at first line), the index is used as coordinate. |
| 618 | | |
| 619 | | -'''Vector plots:''' select this check box to plot vector fields. The x and y vector components iare selected in the first (...) and second columns, while the coordiantes 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. |
| 620 | | |
| 621 | | -'''Automatic opening''': |
| 622 | | When an input file is opened a default plotting option is proposed. |
| 623 | | |
| 624 | | In the case of a 3D input field, the fig is set to uvmat. A middle plane of cut is automatically selected. This can be moved then with the slider on the interface set_object (see section 5). The default cuts are made at constant z coordiante, but any of the three initial coordiantes can be used as z coordinate, using the menu coord_z. |
| 625 | | |
| 626 | | -------------------------------------- |
| 627 | | [geometry_calib<-] |
| 628 | | '''{8- Geometric calibration:=== |
| 629 | | |
| 630 | | === 8.1 Generalities:=== |
| 631 | | |
| 632 | | Transforming image to physical coordinates is a key problem for measuring techniques based on imaging. The image coordinates represent the two cartesian axis x,y of the image, with origin at the lower left corner: the y direction is directed upward, while the corresponding image index j increases downward. The physical coordinates are defined from the experimental set-up. The correspondance is obtained by locating on the image 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: |
| | 434 | When a NetCDF input file is entered, 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. The whole content of the NetCDF file can be made available on the Matlab prompt in the form of a Matlab structure 'Data_get_field': use the menu bar button '''[Export]''', or click the right button mouse on the interface. |
| | 435 | |
| | 436 | Plots can be made in a new figure (default), to the interface '''uvmat.fig''', or added to an existing one, as selected in '''[list_fig]'''. Different processing or plotting functions can be activated by a selection in '''[ACTION]'''. The default action is a plot of selected field, as follows. |
| | 437 | |
| | 438 | -'''Ordinary graphs:''' to plot a simple graph, select the check box '''[1D_plot]'''. Then select the variable to plot in the column '''[ordinate] ''' and the corresponding abscissa in the column '''[abscissa]''', then press '''[RUN]'''. 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 no variable is selected in '''[abscissa]''' ( blank selected at first line), the variable is plotted versus its (first) index. |
| | 439 | |
| | 440 | -'''Scalar maps:''' select this check box to plot scalar fields as images. The scalar field is selected in the first column [scalar], with coordinates respectively selected in '''[coord_x_scalar] ''' and '''[coord_y_scalar]'''. If no variable is selected in '''[coord_x_scalar] ''' or '''[coord_y_scalar] ''' ( blank selected at first line), the index is used as coordinate. |
| | 441 | |
| | 442 | -'''Vector plots:''' select this check box to plot vector fields. The x and y vector components iare selected in the first (...) and second columns, while the coordiantes 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. |
| | 443 | |
| | 444 | -'''Automatic opening''': When an input file is opened a default plotting option is proposed. |
| | 445 | |
| | 446 | In the case of a 3D input field, the fig is set to uvmat. A middle plane of cut is automatically selected. This can be moved then with the slider on the interface set_object (see section 5). The default cuts are made at constant z coordiante, but any of the three initial coordiantes can be used as z coordinate, using the menu coord_z. |
| | 447 | |
| | 448 | ---- |
| | 449 | [geometry_calib<-] '''{8- Geometric calibration:===''' |
| | 450 | |
| | 451 | === 8.1 Generalities: === |
| | 452 | Transforming image to physical coordinates is a key problem for measuring techniques based on imaging. The image coordinates represent the two cartesian axis x,y of the image, with origin at the lower left corner: the y direction is directed upward, while the corresponding image index j increases downward. The physical coordinates are defined from the experimental set-up. The correspondance is obtained by locating on the image 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: |
| 664 | | Once the list of calibration points has been completed, press '''[APPLY]''', after selecting the appropriate option in '''[calib_type]'''. (see the previous sub-section 7.1). Note that the more advanced Tsai options require a sufficient number of calibration points (typically > 10) spread over the image. Calibration coefficients are recorded in the xml file <code><ImaDoc> </code> associated with the image currently opened by uvmat. If previous calibration data already exist, the previous xml file is updated, but the original one is preserved with the extension .xml~. If no xml file already exists, it is created. The image transformation to phys coordinates can be directly seen on the '''uvmat.fig''' interface after completion of the command '''[APPLY]'''. |
| 665 | | |
| 666 | | To reproduce the same calibrationn for image series, open one of the image in the series, and apply again the calibration with the same points, or copy-paste the section GeometryCalib of the xml documentation file with a text editor. |
| 667 | | |
| 668 | | Alternatively the command '''[REPLICATE]''' can be used to calibrate a whole set of experiments, using an overview of the data set provided by the GUI '''dataview.fig'''. |
| 669 | | |
| 670 | | ===8.3 Structure of the xml file:=== |
| 671 | | The coefficients are recorded in the xml element <code><ImaDoc/GeometryCalib></code> as follows: |
| 672 | | -<code><CalibrationType></code>: type of calibration ('rescale', 'linear', '3D...') |
| 673 | | -<code><fx_fy></code>: focal length along each coordinate of the image sensor, expressed in pixel interval. |
| 674 | | -<code><Cx_Cy></code>: position coordinates of the optical axis on the |
| 675 | | -<code><kc></code>: coefficient of quadratic deformation (=1 for the options calib_lin and calib_rescale) |
| 676 | | -<code><CoordUnit></code>: coordinate unit in physical space. |
| 677 | | -<code><Tx_Ty_Tz></code>: translation, (Tz=1 for the options calib_lin and calib_rescale) |
| 678 | | -<code><R>:</code> rotation matrix (in 3 lines) |
| 679 | | For the option calib_rescale |
| 680 | | R (i=1)= [pxcmx 0 0] |
| 681 | | R (i=2)= [0 pxcmy 0] |
| 682 | | R (i=3)= [0 0 1] |
| 683 | | where pxcmx and pxcmy are the scaling factors along x and y. |
| 684 | | -<code><omc></code> 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) |
| 685 | | -<code><ErrorRms>:</code> 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) |
| 686 | | -<code><ErrorMax> </code>: 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) |
| 687 | | -<code><SourceCalib> </code>set of the point coordinates used for calibration |
| 688 | | -<code><PointCoord> </code>[x y z X Y] , where x,y,z are the physical coordinates of each point, X Y its image coordinates. |
| 689 | | -<code><NbSlice_i> </code>nbre of slices for the first field index i (multilevel case), =1 by default. |
| 690 | | -<code><NbSlice_j> </code>nbre of slices for the second index j (volume scan), =1 by default. |
| 691 | | -<code><SliceCoord> </code>[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]. |
| 692 | | -<code><SliceDZ> </code>, step distance between planes, or <code><SliceDPhi> </code> step angle for angular scan. |
| 693 | | |
| 694 | | [<doc115|right>->#top] |
| 695 | | |
| 696 | | -------------------------------------------- |
| 697 | | '''{9- Masks and grids:=== |
| 698 | | [sec9.1<-] |
| 699 | | ===9.1 Masks:=== |
| 700 | | |
| 701 | | 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]. |
| 702 | | |
| 703 | | 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. |
| | 484 | |
| | 485 | Once the list of calibration points has been completed, press '''[APPLY]''', after selecting the appropriate option in '''[calib_type]'''. (see the previous sub-section 7.1). Note that the more advanced Tsai options require a sufficient number of calibration points (typically > 10) spread over the image. Calibration coefficients are recorded in the xml file <code><ImaDoc> </code> associated with the image currently opened by uvmat. If previous calibration data already exist, the previous xml file is updated, but the original one is preserved with the extension .xml~. If no xml file already exists, it is created. The image transformation to phys coordinates can be directly seen on the '''uvmat.fig''' interface after completion of the command '''[APPLY]'''. |
| | 486 | |
| | 487 | To reproduce the same calibrationn for image series, open one of the image in the series, and apply again the calibration with the same points, or copy-paste the section GeometryCalib of the xml documentation file with a text editor. |
| | 488 | |
| | 489 | Alternatively the command '''[REPLICATE]''' can be used to calibrate a whole set of experiments, using an overview of the data set provided by the GUI '''dataview.fig'''. |
| | 490 | |
| | 491 | === 8.3 Structure of the xml file: === |
| | 492 | The coefficients are recorded in the xml element <code><ImaDoc/GeometryCalib></code> as follows: |
| | 493 | |
| | 494 | -<code><CalibrationType></code>: type of calibration ('rescale', 'linear', '3D...') -<code><fx_fy></code>: focal length along each coordinate of the image sensor, expressed in pixel interval. -<code><Cx_Cy></code>: position coordinates of the optical axis on the -<code><kc></code>: coefficient of quadratic deformation (=1 for the options calib_lin and calib_rescale) -<code><CoordUnit></code>: coordinate unit in physical space. -<code><Tx_Ty_Tz></code>: translation, (Tz=1 for the options calib_lin and calib_rescale) -<code><R>:</code> rotation matrix (in 3 lines) |
| | 495 | |
| | 496 | For the option calib_rescale |
| | 497 | R (i=1)= [pxcmx 0 0] R (i=2)= [0 pxcmy 0] R (i=3)= [0 0 1] |
| | 498 | |
| | 499 | where pxcmx and pxcmy are the scaling factors along x and y. -<code><omc></code> 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) -<code><ErrorRms>:</code> 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) -<code><ErrorMax> </code>: 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) -<code><SourceCalib> </code>set of the point coordinates used for calibration -<code><PointCoord> </code>[x y z X Y] , where x,y,z are the physical coordinates of each point, X Y its image coordinates. -<code><NbSlice_i> </code>nbre of slices for the first field index i (multilevel case), =1 by default. -<code><NbSlice_j> </code>nbre of slices for the second index j (volume scan), =1 by default. -<code><SliceCoord> </code>[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]. -<code><SliceDZ> </code>, step distance between planes, or <code><SliceDPhi> </code> step angle for angular scan. |
| | 500 | |
| | 501 | [<doc115|right>->#top] |
| | 502 | |
| | 503 | ---- |
| | 504 | '''{9- Masks and grids:=== [sec9.1<-]''' |
| | 505 | |
| | 506 | === 9.1 Masks: === |
| | 507 | 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]. |
| | 508 | |
| | 509 | 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. |
| 720 | | -------------------------------------- |
| 721 | | [series<-] |
| 722 | | '''{10- Processing field series:=== |
| 723 | | |
| 724 | | ===10.1 The GUI series.fig:=== |
| 725 | | |
| 726 | | 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 must operate. The root path, subdirectory, root file name and extension are introduced in the same way as with the uvmat interface, in the edit windows '''[RootPath], [SubDir], [RootFile],''' and '''[FileExt],''' respectively. The nomenclature for file indexing is represented in '''[NomType]''' ('Indices'). |
| 727 | | |
| 728 | | Several input file series can be introduced simultaneously by the menu bar command''' [Open_insert]'''. By contrast, the current input series are refreshed by the browser from the menu bar command''' [Open]'''. |
| 729 | | |
| 730 | | The velocity type and field is automatioally chosen by default, but it can be specified by VelType and Field. For that purpose use the menus VelTypeMenu and fieldsinput. In case of multiple input file series, these menus act only on the first line. |
| 731 | | |
| 732 | | The processing function is chosen in the menu '''[ACTION]'''. All actions operate on the same series of input files, whose list can be obtained with the option 'check_files'. 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 . Finally any additional function can be called and included in the menu by selecting the option 'more...' . |
| 733 | | |
| 734 | | The series of file indices is set in the frame '''[RANGE]'''. Any action is performed from field index '''[first_i] ''' to '''[last_i] ''' with increment '''[incr_i]''' . In case of double indexing, action is similarly performed from field index''' [first_j]''' to '''[last_j]''' with increment '''[incr_j]'''. Succesive file names are ordered as a matrix {j,i} with the index j varying the fastest. The parameter nb_slice can be introduced to scan the i index modulo nb_slice. |
| 735 | | |
| 736 | | For pair indexing, the selected pair must be chosen in the menu list_pair-civ in the frame PAIRS (browse again an input field if this menu does not appear). Then the first_i and last_i refer to the 'reference indices'. With the option '*-*' in '''[list_pair_civ]''', available pairs are automatically chosen (this is appropriate if several image pairs are used in a time series, to account for a changing mean velocity). |
| 737 | | |
| 738 | | A projection object can be introduced by selecting the check box '''[PROJECTION OBJECT]'''. If a projection object has been already created the opened interface '''set_object.fig''' will be used. Otherwise a browser apperas to open an object file (xml). |
| 739 | | |
| 740 | | ===10.2 check_files:=== |
| 741 | | |
| | 526 | ---- |
| | 527 | [series<-] '''{10- Processing field series:===''' |
| | 528 | |
| | 529 | === 10.1 The GUI series.fig: === |
| | 530 | 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 must operate. The root path, subdirectory, root file name and extension are introduced in the same way as with the uvmat interface, in the edit windows '''[RootPath], [SubDir], [RootFile],''' and '''[FileExt],''' respectively. The nomenclature for file indexing is represented in '''[NomType]''' ('Indices'). |
| | 531 | |
| | 532 | Several input file series can be introduced simultaneously by the menu bar command''' [Open_insert]'''. By contrast, the current input series are refreshed by the browser from the menu bar command''' [Open]'''. |
| | 533 | |
| | 534 | The velocity type and field is automatioally chosen by default, but it can be specified by VelType and Field. For that purpose use the menus VelTypeMenu and fieldsinput. In case of multiple input file series, these menus act only on the first line. |
| | 535 | |
| | 536 | The processing function is chosen in the menu '''[ACTION]'''. All actions operate on the same series of input files, whose list can be obtained with the option 'check_files'. 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 . Finally any additional function can be called and included in the menu by selecting the option 'more...' . |
| | 537 | |
| | 538 | The series of file indices is set in the frame '''[RANGE]'''. Any action is performed from field index '''[first_i] ''' to '''[last_i] ''' with increment '''[incr_i]''' . In case of double indexing, action is similarly performed from field index''' [first_j]''' to '''[last_j]''' with increment '''[incr_j]'''. Succesive file names are ordered as a matrix {j,i} with the index j varying the fastest. The parameter nb_slice can be introduced to scan the i index modulo nb_slice. |
| | 539 | |
| | 540 | For pair indexing, the selected pair must be chosen in the menu list_pair-civ in the frame PAIRS (browse again an input field if this menu does not appear). Then the first_i and last_i refer to the 'reference indices'. With the option '*-*' in '''[list_pair_civ]''', available pairs are automatically chosen (this is appropriate if several image pairs are used in a time series, to account for a changing mean velocity). |
| | 541 | |
| | 542 | A projection object can be introduced by selecting the check box '''[PROJECTION OBJECT]'''. If a projection object has been already created the opened interface '''set_object.fig''' will be used. Otherwise a browser apperas to open an object file (xml). |
| | 543 | |
| | 544 | === 10.2 check_files: === |
| 762 | | In the case of two input files series, the field difference will be perfomed like with the interface uvmat.fig. It is not possible to use more than two input series for this funtion. |
| 763 | | |
| 764 | | ===10.5 merge_proj: } === |
| 765 | | |
| 766 | | This option allows to merge several field series in a single one. This is useful to merge fields obtained with different cameras. Select the different series, activating the check box add. In this case, it is generally useful to first interpolate the fields on a single grid. For that purpose select the check box GetObject, creating a projection object of type 'plane' with projection mode 'interp'. |
| 767 | | |
| 768 | | Since the different views have their own calibration, it is important to use the option 'phys' (menu menu_coord), and to create the grid in phys coordinates. |
| 769 | | |
| 770 | | ===10.6 more...:=== |
| 771 | | |
| 772 | | This action calls any user defined function by its name, acting on the series of fields defiend for ACTION. |
| 773 | | Some examples of usr_defined functions are in the subdirectory {/series}. |
| 774 | | |
| 775 | | -List of available functions: |
| 776 | | -*{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). |
| 777 | | -*{ima2vol.m:} produce volume images for 3D3C PIV. |
| 778 | | |
| 779 | | To update (**): |
| 780 | | -uvprofile: calculate the mean velocity profile and Reynolds stress u'v' along a band, averaged over the series of fields. |
| 781 | | -view_ima3D: provides a perspective view of a 3D image defined by a series of slice 2D images. The isosurfaces of the scalar field are represented. |
| 782 | | -part_stat: count particles and provides their density and luminosity histogramm |
| 783 | | Peaklocking errors:(to update **) |
| | 561 | In the case of two input files series, the field difference will be perfomed like with the interface uvmat.fig. It is not possible to use more than two input series for this funtion. |
| | 562 | |
| | 563 | === 10.5 merge_proj: } === |
| | 564 | This option allows to merge several field series in a single one. This is useful to merge fields obtained with different cameras. Select the different series, activating the check box add. In this case, it is generally useful to first interpolate the fields on a single grid. For that purpose select the check box GetObject, creating a projection object of type 'plane' with projection mode 'interp'. |
| | 565 | |
| | 566 | Since the different views have their own calibration, it is important to use the option 'phys' (menu menu_coord), and to create the grid in phys coordinates. |
| | 567 | |
| | 568 | === 10.6 more...: === |
| | 569 | 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}. |
| | 570 | |
| | 571 | -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). -*{ima2vol.m:} produce volume images for 3D3C PIV. |
| | 572 | |
| | 573 | To update (**): -uvprofile: calculate the mean velocity profile and Reynolds stress u'v' along a band, averaged over the series of fields. -view_ima3D: provides a perspective view of a 3D image defined by a series of slice 2D images. The isosurfaces of the scalar field are represented. -part_stat: count particles and provides their density and luminosity histogramm Peaklocking errors:(to update **) |
| 802 | | -''' {Input file name and indexing:} ''' |
| 803 | | The root name of the input file is displayed in the edit box '''[RootName]''', and a set of indices can be defined by the edit boxes '''[first_i] ''' (first index), '''[incr_i]''' (increment), '''[last_i ]'''(last index). The GUI offers a wide variety for the choice of image pairs to correlate. In the case of two file indices i and j, a mode for the choice of image pairs can be selected in the popup menu '''[mode]'''. |
| 804 | | -*'pairj1-j2': a given pair of j indices (or subscript a, b c...) can be chosen in the CIV1 menu '''[list_pair_civ1]''', while the corresponding indices i are set by '''[first_i] ''', '''[incr_i]''' , '''[last_i ]'''. |
| 805 | | -*'series(Di)': a sliding set of i index pairs is chosen by a set of {reference} indices i_ref given by '''[first_i] ''', '''[incr_i]''' , '''[last_i ]''' and a pair interval defined in '''[list_pair_civ1]''': the first choice 0|1 corresponds to the sliding pair i_ref|i_ref+1. the second choice -1|1 to the sliding pair i_ref-1|i_ref+1,...This mode is generally used with a single image series or movie, but it can be also used in volume scan, with a second index j chosen by '''[first_j] ''', '''[incr_j]''' , '''[last_j ]'''. |
| 806 | | -*'series(Dj)': operates like 'series(Di)', but with sliding j index pairs. |
| 807 | | -*comparing two image series: this is made possible by selecting 'displacement' in the popup menu '''[compare]''', which gives access to a browser for selecting the second image series. This second series can be reduced to a single reference image, if it contains no index. The displacement field with respect to this reference image is then obtained for successive times. |
| 808 | | -*stereo PIV: this option in the menu '''[compare]''' provides the three velocity components by comparing the stereoscopic views from two cameras, see [section 10.6->#sec10.6]. |
| 809 | | |
| 810 | | -''' {Succession of operations:} ''' |
| 811 | | |
| 812 | | The CIV process involves a succession of iterative operations: |
| 813 | | -*civ1: the initial image correlation process. |
| 814 | | -*fix1: detection of 'false' velocity vectors according to different criteria. |
| 815 | | -*patch1: interpolation and filtering on a regular grid, providing access to spatial derivatives of the velocity (diverrgence, curl, strain). |
| 816 | | -* civ2: advanced image correlation algorithm using the result of civ1 as a first approximation. |
| 817 | | -* fix2 and patch2: similar as fix1 and patch1, but applied to the civ2 results. |
| 818 | | This series of operations is chosen by selecting the corresponding check boxes on the left, which give access to the corresponding parameter input panels. Note that the result of each of these operations is stored in the output netcdf file, so the process can be split in several runs. When an existing netcdf velocity file is opened, the GUI '''civ.fig''' is automaticaly configured to perform the next operation (fix1, patch1, civ2...) needed in the process. |
| 819 | | |
| 820 | | {===11.2 CIV1:===} |
| 821 | | The image pair is selected in the menu '''[list_pair_civ1]''', see sub-section 10.1. The time interval of the image pair must be chosen sufficiently small to provide a good correlation, and sufficiently large to provide good measurment precision: a displacement of 5-10 pixels is generally optimum. |
| 822 | | |
| 823 | | The time interval for each image pair is indicated in '''[list_pair_civ1]''' iif the information is made available, either from a movie file, or from a detected xml file (with the name RootName.xml). The source of the timing information is indicated in the edit box '''[ImaDoc]'''. Examples of xml files are provides in /XML_SCHEMAS/ImaDoc_templates. In the absence of information, the file index is taken for the time. |
| 824 | | The time interval for a given index pair may change with time, so the time interval display is taken for given reference indices, given by '''[i_ref]''' and ''' [j_ref].'''. |
| 825 | | |
| 826 | | ('''[ibx], [iby])''' set the size (in pixels) of the 'correlation box', the sliding window used to get image correlations. '''[isx],[ isy]''' set the size of the 'search box' in which image correlation is calculated, see figure. This search box can be shifted with respect to the correlation box by parameters ([shift x],[shift_y]). This is useful in the presence of a known mean flow. |
| 827 | | |
| 828 | | The default value ibx=iby=(25,25) is generally good, use a larger size for images with few particles, use an elongated box , e.g. (11,41) , to optimise the resolution in one direction (for instance in a boundary layer). |
| | 590 | -''' {Input file name and indexing:} ''' The root name of the input file is displayed in the edit box '''[RootName]''', and a set of indices can be defined by the edit boxes '''[first_i] ''' (first index), '''[incr_i]''' (increment), '''[last_i ]'''(last index). The GUI offers a wide variety for the choice of image pairs to correlate. In the case of two file indices i and j, a mode for the choice of image pairs can be selected in the popup menu '''[mode]'''. -*'pairj1-j2': a given pair of j indices (or subscript a, b c...) can be chosen in the CIV1 menu '''[list_pair_civ1]''', while the corresponding indices i are set by '''[first_i] ''', '''[incr_i]''' , '''[last_i ]'''. -*'series(Di)': a sliding set of i index pairs is chosen by a set of {reference} indices i_ref given by '''[first_i] ''', '''[incr_i]''' , '''[last_i ]''' and a pair interval defined in '''[list_pair_civ1]''': the first choice 0|1 corresponds to the sliding pair i_ref|i_ref+1. the second choice -1|1 to the sliding pair i_ref-1|i_ref+1,...This mode is generally used with a single image series or movie, but it can be also used in volume scan, with a second index j chosen by '''[first_j] ''', '''[incr_j]''' , '''[last_j ]'''. -*'series(Dj)': operates like 'series(Di)', but with sliding j index pairs. -*comparing two image series: this is made possible by selecting 'displacement' in the popup menu '''[compare]''', which gives access to a browser for selecting the second image series. This second series can be reduced to a single reference image, if it contains no index. The displacement field with respect to this reference image is then obtained for successive times. -*stereo PIV: this option in the menu '''[compare]''' provides the three velocity components by comparing the stereoscopic views from two cameras, see [section 10.6->#sec10.6]. |
| | 591 | |
| | 592 | -''' {Succession of operations:} ''' |
| | 593 | |
| | 594 | The CIV process involves a succession of iterative operations: -*civ1: the initial image correlation process. -*fix1: detection of 'false' velocity vectors according to different criteria. -*patch1: interpolation and filtering on a regular grid, providing access to spatial derivatives of the velocity (diverrgence, curl, strain). -* civ2: advanced image correlation algorithm using the result of civ1 as a first approximation. -* fix2 and patch2: similar as fix1 and patch1, but applied to the civ2 results. This series of operations is chosen by selecting the corresponding check boxes on the left, which give access to the corresponding parameter input panels. Note that the result of each of these operations is stored in the output netcdf file, so the process can be split in several runs. When an existing netcdf velocity file is opened, the GUI '''civ.fig''' is automaticaly configured to perform the next operation (fix1, patch1, civ2...) needed in the process. |
| | 595 | |
| | 596 | {===11.2 CIV1:===} The image pair is selected in the menu '''[list_pair_civ1]''', see sub-section 10.1. The time interval of the image pair must be chosen sufficiently small to provide a good correlation, and sufficiently large to provide good measurment precision: a displacement of 5-10 pixels is generally optimum. |
| | 597 | |
| | 598 | The time interval for each image pair is indicated in '''[list_pair_civ1]''' iif the information is made available, either from a movie file, or from a detected xml file (with the name RootName.xml). The source of the timing information is indicated in the edit box '''[ImaDoc]'''. Examples of xml files are provides in /XML_SCHEMAS/ImaDoc_templates. In the absence of information, the file index is taken for the time. The time interval for a given index pair may change with time, so the time interval display is taken for given reference indices, given by '''[i_ref]''' and ''' [j_ref].'''. |
| | 599 | |
| | 600 | ('''[ibx], [iby])''' set the size (in pixels) of the 'correlation box', the sliding window used to get image correlations. '''[isx],[ isy]''' set the size of the 'search box' in which image correlation is calculated, see figure. This search box can be shifted with respect to the correlation box by parameters ([shift x],[shift_y]). This is useful in the presence of a known mean flow. |
| | 601 | |
| | 602 | The default value ibx=iby=(25,25) is generally good, use a larger size for images with few particles, use an elongated box , e.g. (11,41) , to optimise the resolution in one direction (for instance in a boundary layer). |
| 845 | | The PIV calculation is started by the press button [RUN], or [BATCH] if this option has been installed. BATCH sends the same computations as background computing tasks in a network. |
| 846 | | |
| 847 | | In both cases, the status of the computations can be checked by opening {.cmx } and {.log} files, using the uvmat browser or any text editor. These files are writtent in the same subdirectory as the NetCDF result files. Each {.cmx} file contains the set of parameters used for a civ computation. It is written by the civ interface just before ordering the computations. By contrast , the {.log} file is produced after completion of the computations, and it contains some information on the process, including possible error messages. |
| 848 | | |
| 849 | | [sec11.3<-] |
| 850 | | {===11.3 FIX===} |
| 851 | | |
| 852 | | The FIX operation is used after civ to remove false vectors, using different criteria: |
| 853 | | -''' {warning flags:} ''' these are flags (vec_F) indicating problems with the image correlation process: |
| 854 | | -*vec_F(i)=0 or 1 : default , the processing is fine |
| 855 | | -*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 |
| 856 | | -*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. |
| 857 | | Reference: Hart D. P. (2000) 'PIV error correction',{ Exp. Fluids} '''29''', 13-22. |
| 858 | | -*vec_F(i)=3: the optimisation of the correlation function is unstable or local Intensity rms of the image =0 |
| 859 | | -*vec_F(i)=4:only in civ2: the difference between the estimator and the result is more than 1 pixel. |
| 860 | | 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). |
| 861 | | -''' {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. |
| 862 | | -''' {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]'''). |
| 863 | | -''' {Mask fix:} ''' It has the same effect as the one used in civ1, but the removed vectors are kept in memory, labelled as false. |
| 864 | | -''' {Manual fix:} ''' Interactive fixing with the mouse is also possible, see [section 4.2->#4.2]. |
| 865 | | |
| 866 | | -''' {Code for FixFlag:} ''' |
| 867 | | -*FixFlag(i)=0 :default, everything is fine |
| 868 | | -*FixFlag(i)=1. : value 1 for the second digit: vector removed by criteria on vec_F or/and low correlation value |
| 869 | | -*FixFlag(i)=1..: value 1 for the third digit: vector selected by a criterium of difference with another field, for instance filter, or a field with differnt time interval. |
| 870 | | -*FixFlag(i)=...1, 2, 3 different criteria for elimination set by the program Fix of CIVx (not yet documented). |
| | 619 | |
| | 620 | The PIV calculation is started by the press button [RUN], or [BATCH] if this option has been installed. BATCH sends the same computations as background computing tasks in a network. |
| | 621 | |
| | 622 | In both cases, the status of the computations can be checked by opening {.cmx } and {.log} files, using the uvmat browser or any text editor. These files are writtent in the same subdirectory as the NetCDF result files. Each {.cmx} file contains the set of parameters used for a civ computation. It is written by the civ interface just before ordering the computations. By contrast , the {.log} file is produced after completion of the computations, and it contains some information on the process, including possible error messages. |
| | 623 | |
| | 624 | [sec11.3<-] {===11.3 FIX===} |
| | 625 | |
| | 626 | 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]. |
| | 627 | |
| | 628 | -''' {Code for FixFlag:} ''' -*FixFlag(i)=0 :default, everything is fine -*FixFlag(i)=1. : value 1 for the second digit: vector removed by criteria on vec_F or/and low correlation value -*FixFlag(i)=1..: value 1 for the third digit: vector selected by a criterium of difference with another field, for instance filter, or a field with differnt time interval. -*FixFlag(i)=...1, 2, 3 different criteria for elimination set by the program Fix of CIVx (not yet documented). |
| 908 | | Several fields, corresponding to the successive operations 'civ1', 'fix1', 'patch1', 'civ2', 'fix2', 'patch2' are stored in the same .nc file. |
| 909 | | 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. |
| 910 | | |
| 911 | | -'''List of constants (global attributes):''', |
| 912 | | Conventions 'uvmat/civdata'. |
| 913 | | | '''tag''' | ''' content''' | |
| 914 | | | Conventions| sets the conventions| |
| 915 | | | Program|name of the processing program| |
| 916 | | | CivStage| stage in the sequence civ1,fix1...| |
| 917 | | | Civ1_TestCiv1| 0| |
| 918 | | | Civ1_CorrBoxSize|size x,y of the correlation box| |
| 919 | | | Civ1_SearchBoxSize| size x,y of the search box| |
| 920 | | |Civ1_SearchBoxShift| (optional) shift of the search box| |
| 921 | | | Civ1_CorrSmooth| smooth parameter for the image corr| |
| 922 | | | Civ1_Dx |grid mesh along x| |
| 923 | | | Civ1_Dy| grid mesh along y| |
| 924 | | | Civ1_CheckGrid| =1 if a grid file is used, default=0| |
| 925 | | | Civ1_CheckMask| =1 if a mask file is used, default=0| |
| 926 | | | Civ1_CheckThreshold| =0/1 image luminosity threshold used | |
| 927 | | | Civ1_FileTypeA| type of input file A, 'image', 'movie'...| |
| 928 | | | Civ1_ImageA| path and name of input image A| |
| 929 | | | Civ1_FileTypeB| type of input file A, 'image', 'movie'...| |
| 930 | | | Civ1_ImageB|path and name of input image B| |
| 931 | | | Civ1_Dt| time interval for image pair| |
| 932 | | | Civ1_Time| mean time for the image pair| |
| 933 | | | Civ1_ImageBitDepth| nbre of grey level bits| |
| 934 | | | Civ1_ImageWidth| nbre of pixels along x| |
| 935 | | | Civ1_ImageHeight| nbre of pixels along y| |
| 936 | | | Civ1_FrameIndexA| frame index of image A in the series| |
| 937 | | | Civ1_FrameIndexB| frame index of image B in the series| |
| 938 | | | Patch1_Rho| 10| |
| 939 | | | Patch1_Threshold| threshold for the elimination of aberrant vectors| |
| 940 | | | Patch1_SubDomain| estimated nbre of vectors in a subdomain| |
| 941 | | |
| | 666 | 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. |
| | 667 | |
| | 668 | -'''List of constants (global attributes):''', |
| | 669 | |
| | 670 | Conventions 'uvmat/civdata'. |
| | 671 | |
| | 672 | | '''tag''' | ''' content''' | | Conventions| sets the conventions| | Program|name of the processing program| | CivStage| stage in the sequence civ1,fix1...| | Civ1_TestCiv1| 0| | Civ1_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_CorrSmooth| smooth parameter for the image corr| | Civ1_Dx |grid mesh along x| | Civ1_Dy| grid mesh along y| | Civ1_CheckGrid| =1 if a grid file is used, default=0| | Civ1_CheckMask| =1 if a mask file is used, default=0| | Civ1_CheckThreshold| =0/1 image luminosity threshold used | | Civ1_FileTypeA| type of input file A, 'image', 'movie'...| | Civ1_ImageA| path and name of input image A| | Civ1_FileTypeB| type of input file A, 'image', 'movie'...| | Civ1_ImageB|path and name of input image B| | Civ1_Dt| time interval for image pair| | Civ1_Time| mean time for the image pair| | Civ1_ImageBitDepth| nbre of grey level bits| | Civ1_ImageWidth| nbre of pixels along x| | Civ1_ImageHeight| nbre of pixels along y| | Civ1_FrameIndexA| frame index of image A in the series| | Civ1_FrameIndexB| frame index of image B in the series| | Patch1_Rho| 10| | Patch1_Threshold| threshold for the elimination of aberrant vectors| | Patch1_SubDomain| estimated nbre of vectors in a subdomain| |
| 947 | | | '''tag''' | ''' content''' | |
| 948 | | | Civ1_X| x coordinates| |
| 949 | | | Civ1_Y| y coordinates| |
| 950 | | | Civ1_Z| z coordinates (for PIV in volume)| |
| 951 | | | Civ1_U| x velocity component| |
| 952 | | | Civ1_V| y velocity component| |
| 953 | | | Civ1_W| z velocity component (if relevant)| |
| 954 | | | Civ1_F| warning flag| |
| 955 | | | Civ1_C| image correlation| |
| 956 | | | Civ1_FF| error flag| |
| 957 | | | Civ1_U_smooth| smoothed x velocity component| |
| 958 | | | Civ1_V_smooth| smoothed y velocity component| |
| 959 | | | Civ1_W_smooth| smoothed z velocity component| |
| 960 | | | Civ1_SubRange| sub range bounds| |
| 961 | | | Civ1_NbSites| nbre of tps sites in each sub-range| |
| 962 | | | Civ1_Coord_tps| tps coordinates| |
| 963 | | | Civ1_U_tps| tps weights for x vel component| |
| 964 | | | Civ1_V_tps| tps weights for y vel component| |
| 965 | | | Civ1_W_tps| tps weights for z vel component| |
| 966 | | |
| 967 | | -'''List of constants, old CIVx conventions):''' |
| 968 | | -* nb_coord: =2 for PIV in a plane, =3 for PIV in a volume. |
| 969 | | -* nb_dim: =2 for the usual 2 component PIV, =3 for 3 component PIV (stereoscopic or volume). |
| 970 | | -* constant_pixcm: =1 for a simple linear calibration provided by the scaling factors pixcmx and pixcmy, =0 otherwise. |
| 971 | | -* pixcmx: scale pixel/space unit (cm by default) along the x direction (only if constant_pixcm=1). |
| 972 | | -* pixcmy: scale pixel/space unit (cm by default) along the y direction (only if constant_pixcm=1) |
| 973 | | -* absolut_time_T0: time elapsed since the time origin of the series (the mean time for the two images of the pair is taken). |
| 974 | | -* dt: time interval between the two images of the pair. |
| 975 | | -* absolut_time_T0_2: same as absolute_time_T0 for the fields obtained by the second iteration (civ2), using a possibly different image pair. |
| 976 | | -* dt2: same as dt for the fields obtained by the second iteration (civ2). |
| 977 | | -* hart: =1 if the Hart option has been used for processing (see ref.???), =0 otherwise. |
| 978 | | -* civ: =1 if a civ1 operation has been performed (=0 if the field is not obtained from an image pair) |
| 979 | | -* fix: =1 if a fix1 operation has been performed, |
| 980 | | -* patch: =1 if a patch1 operation has been performed. |
| 981 | | -* civ2: =1 if a civ2 operation has been performed. |
| 982 | | -* fix2:=1 if a fix2 operation has been performed. |
| 983 | | -* patch2: =1 if a Patch2 operation has been performed. |
| 984 | | -* patch_nx: number of grid points in the x direction for the patch field |
| 985 | | -* patch_ny: number of grid points in the y direction for the patch field |
| 986 | | -* ro_patch: smoothing coefficient rho used for patch |
| 987 | | -* patch2_nx: number of grid points in the x direction for the patch2 field |
| 988 | | -* patch2_ny: number of grid points in the y direction for the patch2 field |
| 989 | | -* ro2_patch: smoothing coefficient rho used for patch2 |
| 990 | | |
| 991 | | -'''List of field variables (old CIVx conventions):''' |
| 992 | | 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). |
| | 678 | | '''tag''' | ''' content''' | | Civ1_X| x coordinates| | Civ1_Y| y coordinates| | Civ1_Z| z coordinates (for PIV in volume)| | Civ1_U| x velocity component| | Civ1_V| y velocity component| | Civ1_W| z velocity component (if relevant)| | Civ1_F| warning flag| | Civ1_C| image correlation| | Civ1_FF| error flag| | Civ1_U_smooth| smoothed x velocity component| | Civ1_V_smooth| smoothed y velocity component| | Civ1_W_smooth| smoothed z velocity component| | Civ1_SubRange| sub range bounds| | Civ1_NbSites| nbre of tps sites in each sub-range| | Civ1_Coord_tps| tps coordinates| | Civ1_U_tps| tps weights for x vel component| | Civ1_V_tps| tps weights for y vel component| | Civ1_W_tps| tps weights for z vel component| |
| | 679 | |
| | 680 | -'''List of constants, old CIVx conventions):''' -* nb_coord: =2 for PIV in a plane, =3 for PIV in a volume. -* nb_dim: =2 for the usual 2 component PIV, =3 for 3 component PIV (stereoscopic or volume). -* constant_pixcm: =1 for a simple linear calibration provided by the scaling factors pixcmx and pixcmy, =0 otherwise. -* pixcmx: scale pixel/space unit (cm by default) along the x direction (only if constant_pixcm=1). -* pixcmy: scale pixel/space unit (cm by default) along the y direction (only if constant_pixcm=1) -* absolut_time_T0: time elapsed since the time origin of the series (the mean time for the two images of the pair is taken). -* dt: time interval between the two images of the pair. -* absolut_time_T0_2: same as absolute_time_T0 for the fields obtained by the second iteration (civ2), using a possibly different image pair. -* dt2: same as dt for the fields obtained by the second iteration (civ2). -* hart: =1 if the Hart option has been used for processing (see ref.???), =0 otherwise. -* civ: =1 if a civ1 operation has been performed (=0 if the field is not obtained from an image pair) -* fix: =1 if a fix1 operation has been performed, -* patch: =1 if a patch1 operation has been performed. -* civ2: =1 if a civ2 operation has been performed. -* fix2:=1 if a fix2 operation has been performed. -* patch2: =1 if a Patch2 operation has been performed. -* patch_nx: number of grid points in the x direction for the patch field -* patch_ny: number of grid points in the y direction for the patch field -* ro_patch: smoothing coefficient rho used for patch -* patch2_nx: number of grid points in the x direction for the patch2 field -* patch2_ny: number of grid points in the y direction for the patch2 field -* ro2_patch: smoothing coefficient rho used for patch2 |
| | 681 | |
| | 682 | -'''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). |
| 1068 | | ===Other GUIs:(function .m and associated figure .fig)=== |
| 1069 | | |
| 1070 | | -'civ';... %function associated with the interface 'civ.fig' for PIV and spline interpolation |
| 1071 | | -'create_grid';...% called by the GUI geometry_calib to create a physical grid |
| 1072 | | - 'dataview';...% function for scanning directories in a campaign |
| 1073 | | -'editxml';...%display and edit xml files using a xls schema |
| 1074 | | -'geometry_calib';...%performs geometric calibration from a set of reference points |
| 1075 | | -'get_field';...% choose and plot a field from a Netcdf file |
| 1076 | | -'msgbox_uvmat';... associated with GUI msgbox_uvmat.fig to display message boxes, for error, warning or input calls |
| 1077 | | -'rotate_points';...%'rotate_points': associated with GUI rotate_points.fig to introduce (2D) rotation parameters |
| 1078 | | -'series';...% master function for analysis field series, with interface 'series.fig' |
| 1079 | | -'set_grid';...% creates a grid for PIV |
| 1080 | | -'set_object';...% edit a projection object |
| 1081 | | -'translate_points';...% associated with GUI translate_points.fig to display translation parameters |
| 1082 | | -'view_field';...% function for visualisation of projected fields' |
| 1083 | | |
| 1084 | | ===functions activated by mouse and keybord in GUI :=== |
| 1085 | | -'keyboard_callback';... % function activated when a key is pressed on the keyboard |
| 1086 | | -'mouse_down';% function activated when the mouse button is pressed on a figure (callback for 'WindowButtonDownFcn') |
| 1087 | | -'mouse_motion';...% permanently called by mouse motion over a figure (callback for 'WindowButtonMotionFcn') |
| 1088 | | -'mouse_up';... % function to be activated when the mouse button is released (callback for 'WindowButtonUpFcn') |
| 1089 | | |
| 1090 | | === main functions used:=== |
| 1091 | | -'civ_matlab';...% civ programs, Matlab version (called by civ.m, option Civprogram/Matlab in the upper menu bar) |
| 1092 | | -'plot_field';...%displays a vector field and/or scalar or images |
| 1093 | | -'plot_object';...%draws a projection object (points, line, plane...) |
| 1094 | | -'proj_field';...%project a field on a projection object (plane, line,...) |
| 1095 | | -'RUN_STLIN';...% combine 2 displacement fields for stereo PIV |
| 1096 | | -'sub_field';...% combine the two input fields, |
| 1097 | | |
| 1098 | | ===convert and I/O functions:=== |
| 1099 | | -'cell2tab';... % transform a Matlab cell in a character array suitable for display in a table |
| 1100 | | -'fill_GUI';... % fill a GUI with handles 'handles' from input data Param |
| 1101 | | -'imadoc2struct';...% convert the image documentation file ImaDoc into a Matlab structure |
| 1102 | | -'nc2struct';...% transform a netcdf file in a corresponding matlab structure |
| 1103 | | -'num2stra';...% transform number to the corresponding character string depending on the nomenclature. |
| 1104 | | -'read_field':...% read the fields from files in different formats (netcdf files, images, video) |
| 1105 | | -'read_GUI'::...% read a GUI and provide the data as a Matlab structure |
| 1106 | | 'read_image';... read images or video objects |
| 1107 | | -'read_multimadoc';... %read a set of Imadoc files and compare their timing of different file series |
| 1108 | | 'read_xls';...%read excel files containing the list of the experiments |
| 1109 | | -'stra2num';...% transform letters (a, b, A, B,) or numerical strings ('1','2'..) to the corresponding numbers |
| 1110 | | -'struct2nc';...% write fields in netcdf files |
| 1111 | | -'struct2xml';... transform a matlab structure to a xml tree. |
| 1112 | | -'xml2struct'...% read an xml file as a Matlab structure, converts numeric character strings into numbers |
| 1113 | | |
| 1114 | | ===ancillary functions:=== |
| 1115 | | -'calc_field';...% defines fields (velocity, vort, div...) from civx data (old conventions) and calculate them. |
| 1116 | | -'calc_field_interp': defines fields (velocity, vort, div...) from civ data and calculate them for projection with linear interpolation |
| 1117 | | -'calc_field_tps': defines fields (velocity, vort, div...) from civ data and calculate them with tps interpolation |
| 1118 | | -calc_tps': calculate the thin plate spline (tps) coefficients for interpolation |
| 1119 | | -'check_files';...% check the path, modification date and svn version for all the function in the toolbox UVMAT. |
| 1120 | | -'close_fig';...% function activated when a figure is closed |
| 1121 | | -'copyfields';...% copy fields between two matlab structures |
| 1122 | | -'delete_object';...%delete a projection object, defined by its index in the Uvmat list or by its graphic handle |
| 1123 | | 'fileparts_uvmat': splits a file name in root and indices and recognize file naming convention |
| 1124 | | -'filter_tps';...% find the thin plate spline coefficients for interpolation-smoothing |
| 1125 | | -'find_field_cells';...% group the variables of a nc-formated Matlab structure into 'fields' with common dimensions |
| 1126 | | -find_field_cells': test field structure for input in proj_field and plot_field, group the variables into 'fields' with common dimensions |
| 1127 | | -'find_file_series';...%check the content of an input file and find the corresponding file series |
| 1128 | | -'fullfile_uvmat';...%creates a file name from a root name and indices. |
| 1129 | | -'get_file_type': determine info about a file (image, multimage, civdata,...) |
| 1130 | | -'griddata_uvmat';...%make 2D linear interpolation using griddata, with input appropriate for both Matlab 6.5 and 7 |
| 1131 | | -'hist_update';...% update of a current global histogram by inclusion of a new field |
| 1132 | | -'ListDir';... scan the structure of the directory tree (for dataview.m) |
| 1133 | | -'open_uvmat';...% open with uvmat the field selected in the list of 'civ/status' or 'series/check_data_files' |
| 1134 | | -'peaklock';...% |
| 1135 | | -'phys_XYZ';...% transform coordiantes from pixels to phys |
| 1136 | | -'px_XYZ';...% transform coordiantes from phys to pixels |
| 1137 | | -'read_civxdata';...reads civx data from netcdf files |
| 1138 | | -'read_civdata';... reads new civ data from netcdf files |
| 1139 | | -'read_get_field';... read the list of selected variables from the GUI get_field (TODO: use read_GUI) |
| 1140 | | -'read_imatext';...%read .civ files (obsolete, but can be adapted to other text documentation files) |
| 1141 | | -'read_xls';...%read excel files containing the list of the experiments |
| 1142 | | -'reinit';...% suppress the personal parameter file 'uvmat_perso.mat' |
| 1143 | | -'set_col_vec';...% sets the color code for vectors depending on a scalar and input parameters (used for plot_field) |
| 1144 | | -'tps_coeff';...% calculate the thin plate spline (tps) coefficients |
| 1145 | | -'tps_eval';... %calculate the thin plate spline (tps) interpolation at a set of points |
| 1146 | | -'tps_eval_dxy';...% calculate the derivatives of thin plate spline (tps) interpolation at a set of points (limited to the 2D case) |
| 1147 | | -'update_imadoc';... %update the ImaDoc xml file |
| 1148 | | -'update_obj';... update the object representation graph and its projection field, record it in the uvmat interface |
| 1149 | | -'update_waitbar';... update the waitbar display, used for ACTION functions in the GUI 'series' |
| 1150 | | -'write_plot_param'...%update plotting parameters after plot, TODO: change into a general function: fill_GUI |
| 1151 | | |
| 1152 | | ===series functions=== |
| 1153 | | -'aver_stat': calculate field average over a time series |
| 1154 | | -'avi2png': copy an avi movie to a series of B/W .png images (take the average of green and blue color components) |
| 1155 | | -'check_data_files': check the existence, type and status of the files selected by series.fig |
| 1156 | | -'merge_proj': concatene several fields from series, can project them on a regular grid in phys coordinates |
| 1157 | | -'sub_background': subtract a sliding background to an image series |
| 1158 | | -'time_series': extract a time series after projection on an object (points , line..) |
| 1159 | | |
| 1160 | | ===transform functions=== |
| 1161 | | - 'ima_filter': low-pass filter of an image (builtin filtering parameter) |
| 1162 | | - 'ima_remove_background': removes backgound from an image (using the local minimum) |
| 1163 | | - 'ima_remove_particles': removes particles from an image (keeping the local minimum) |
| 1164 | | - 'FFT2_detrend': calculate the 2D spectrum of the input scalar after removing the linear trend (requires the Matlab image processing toolbox). |
| 1165 | | -'phys': transforms image (Unit='pixel') to real world (phys) coordinates using geometric calibration parameters. It acts if the input field contains the tag 'CoordUnit' with value 'pixel' |
| 1166 | | -'phys_polar': this transforms the fields to polar coordinates, radius in abscissa (same unit as x, y) and azimuth in ordinate (unit =degree). |
| | 719 | === Other GUIs:(function .m and associated figure .fig) === |
| | 720 | -'civ';... %function associated with the interface 'civ.fig' for PIV and spline interpolation -'create_grid';...% called by the GUI geometry_calib to create a physical grid - 'dataview';...% function for scanning directories in a campaign -'editxml';...%display and edit xml files using a xls schema -'geometry_calib';...%performs geometric calibration from a set of reference points -'get_field';...% choose and plot a field from a Netcdf file -'msgbox_uvmat';... associated with GUI msgbox_uvmat.fig to display message boxes, for error, warning or input calls -'rotate_points';...%'rotate_points': associated with GUI rotate_points.fig to introduce (2D) rotation parameters -'series';...% master function for analysis field series, with interface 'series.fig' -'set_grid';...% creates a grid for PIV -'set_object';...% edit a projection object -'translate_points';...% associated with GUI translate_points.fig to display translation parameters -'view_field';...% function for visualisation of projected fields' |
| | 721 | |
| | 722 | === functions activated by mouse and keybord in GUI : === |
| | 723 | -'keyboard_callback';... % function activated when a key is pressed on the keyboard -'mouse_down';% function activated when the mouse button is pressed on a figure (callback for 'WindowButtonDownFcn') -'mouse_motion';...% permanently called by mouse motion over a figure (callback for 'WindowButtonMotionFcn') -'mouse_up';... % function to be activated when the mouse button is released (callback for 'WindowButtonUpFcn') |
| | 724 | |
| | 725 | === main functions used: === |
| | 726 | -'civ_matlab';...% civ programs, Matlab version (called by civ.m, option Civprogram/Matlab in the upper menu bar) -'plot_field';...%displays a vector field and/or scalar or images -'plot_object';...%draws a projection object (points, line, plane...) -'proj_field';...%project a field on a projection object (plane, line,...) -'RUN_STLIN';...% combine 2 displacement fields for stereo PIV -'sub_field';...% combine the two input fields, |
| | 727 | |
| | 728 | === convert and I/O functions: === |
| | 729 | -'cell2tab';... % transform a Matlab cell in a character array suitable for display in a table -'fill_GUI';... % fill a GUI with handles 'handles' from input data Param -'imadoc2struct';...% convert the image documentation file ImaDoc into a Matlab structure -'nc2struct';...% transform a netcdf file in a corresponding matlab structure -'num2stra';...% transform number to the corresponding character string depending on the nomenclature. -'read_field':...% read the fields from files in different formats (netcdf files, images, video) -'read_GUI'::...% read a GUI and provide the data as a Matlab structure 'read_image';... read images or video objects -'read_multimadoc';... %read a set of Imadoc files and compare their timing of different file series 'read_xls';...%read excel files containing the list of the experiments -'stra2num';...% transform letters (a, b, A, B,) or numerical strings ('1','2'..) to the corresponding numbers -'struct2nc';...% write fields in netcdf files -'struct2xml';... transform a matlab structure to a xml tree. -'xml2struct'...% read an xml file as a Matlab structure, converts numeric character strings into numbers |
| | 730 | |
| | 731 | === ancillary functions: === |
| | 732 | -'calc_field';...% defines fields (velocity, vort, div...) from civx data (old conventions) and calculate them. -'calc_field_interp': defines fields (velocity, vort, div...) from civ data and calculate them for projection with linear interpolation -'calc_field_tps': defines fields (velocity, vort, div...) from civ data and calculate them with tps interpolation -calc_tps': calculate the thin plate spline (tps) coefficients for interpolation -'check_files';...% check the path, modification date and svn version for all the function in the toolbox UVMAT. -'close_fig';...% function activated when a figure is closed -'copyfields';...% copy fields between two matlab structures -'delete_object';...%delete a projection object, defined by its index in the Uvmat list or by its graphic handle 'fileparts_uvmat': splits a file name in root and indices and recognize file naming convention -'filter_tps';...% find the thin plate spline coefficients for interpolation-smoothing -'find_field_cells';...% group the variables of a nc-formated Matlab structure into 'fields' with common dimensions -find_field_cells': test field structure for input in proj_field and plot_field, group the variables into 'fields' with common dimensions -'find_file_series';...%check the content of an input file and find the corresponding file series -'fullfile_uvmat';...%creates a file name from a root name and indices. -'get_file_type': determine info about a file (image, multimage, civdata,...) -'griddata_uvmat';...%make 2D linear interpolation using griddata, with input appropriate for both Matlab 6.5 and 7 |
| | 733 | |
| | 734 | -'hist_update';...% update of a current global histogram by inclusion of a new field |
| | 735 | |
| | 736 | -'ListDir';... scan the structure of the directory tree (for dataview.m) -'open_uvmat';...% open with uvmat the field selected in the list of 'civ/status' or 'series/check_data_files' -'peaklock';...% -'phys_XYZ';...% transform coordiantes from pixels to phys -'px_XYZ';...% transform coordiantes from phys to pixels -'read_civxdata';...reads civx data from netcdf files -'read_civdata';... reads new civ data from netcdf files -'read_get_field';... read the list of selected variables from the GUI get_field (TODO: use read_GUI) -'read_imatext';...%read .civ files (obsolete, but can be adapted to other text documentation files) -'read_xls';...%read excel files containing the list of the experiments -'reinit';...% suppress the personal parameter file 'uvmat_perso.mat' -'set_col_vec';...% sets the color code for vectors depending on a scalar and input parameters (used for plot_field) -'tps_coeff';...% calculate the thin plate spline (tps) coefficients -'tps_eval';... %calculate the thin plate spline (tps) interpolation at a set of points -'tps_eval_dxy';...% calculate the derivatives of thin plate spline (tps) interpolation at a set of points (limited to the 2D case) -'update_imadoc';... %update the ImaDoc xml file -'update_obj';... update the object representation graph and its projection field, record it in the uvmat interface -'update_waitbar';... update the waitbar display, used for ACTION functions in the GUI 'series' -'write_plot_param'...%update plotting parameters after plot, TODO: change into a general function: fill_GUI |
| | 737 | |
| | 738 | === series functions === |
| | 739 | -'aver_stat': calculate field average over a time series -'avi2png': copy an avi movie to a series of B/W .png images (take the average of green and blue color components) -'check_data_files': check the existence, type and status of the files selected by series.fig -'merge_proj': concatene several fields from series, can project them on a regular grid in phys coordinates -'sub_background': subtract a sliding background to an image series -'time_series': extract a time series after projection on an object (points , line..) |
| | 740 | |
| | 741 | === transform functions === |
| | 742 | - 'ima_filter': low-pass filter of an image (builtin filtering parameter) - 'ima_remove_background': removes backgound from an image (using the local minimum) - 'ima_remove_particles': removes particles from an image (keeping the local minimum) - 'FFT2_detrend': calculate the 2D spectrum of the input scalar after removing the linear trend (requires the Matlab image processing toolbox). -'phys': transforms image (Unit='pixel') to real world (phys) coordinates using geometric calibration parameters. It acts if the input field contains the tag 'CoordUnit' with value 'pixel' -'phys_polar': this transforms the fields to polar coordinates, radius in abscissa (same unit as x, y) and azimuth in ordinate (unit =degree). |
