Changes between Version 174 and Version 175 of UvmatHelp
- Timestamp:
- Jan 23, 2015, 10:53:36 AM (10 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
UvmatHelp
v174 v175 26 26 The present on-line document is the reference document for the version currently available on the svn server. Features not yet implemented or tested (in particular 3D features) are marked by **. The document is accessible within Matlab by help buttons in the GUIs. 27 27 28 A short comment about each GUI element, called ''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 tag of a GUI element is quoted as '''[tag]''', a file name in the package is enhanced as ''fct name.m'', and commands on the Matlab workspace as '>> command’. The tag name can be also obtained by pressing the right hand mouse button on the element.28 A short comment about each GUI element, called ''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, a GUI element is quoted as '''GUI''', its tags as '''[tag]''', a file name in the package is enhanced as ''fct name.m'', and commands on the Matlab workspace as '>> command’. The tag name can be also obtained by pressing the right hand mouse button on the element. 29 29 30 30 Information is also provided as comments in each function. Type '>>help fct_name' to get it, or open it with an editor. … … 172 172 * Intensity < 20: ('black mask') the vector in this place will be set to zero. 173 173 * 20 < Intensity < 200:('gray mask') the vector in this place will be absent. 174 * Intensity>200 the vector will be computed The mask corresponding to an image or velocity field can be displayed in the GUI '''uvmat''' by selecting the check box '''[view_mask] ([!CheckMask])'''on the upper left. Images with appropriate name can be automatically recognised by '''uvmat''' and civ functions, see [#a9-Masksandgrids section 9.1]. Otherwise file selection by a browser is proposed when '''[view_mask]''' is selected.174 * Intensity>200 the vector will be computed The mask corresponding to an image or velocity field can be displayed in the GUI '''uvmat''' by selecting the check box '''[view_mask]''' ('''[!CheckMask]''') on the upper left. Images with appropriate name can be automatically recognised by '''uvmat''' and civ functions, see [#a9-Masksandgrids section 9.1]. Otherwise file selection by a browser is proposed when '''[view_mask]''' is selected. 175 175 176 176 * ''' Grid:''' List of numbers (in ASCII text) specifying the set of points where the PIV processing is performed. It specifies the number of points n and a corresponding list of x and y coordinates expressed in image pixels, as follows … … 200 200 }}} 201 201 202 * '''.cmx''' ASCII text files containing the parameters sent by the GUI '''civ ''' to the CIV fortran programmes. Each velocity field named *.nc results from a parameter file *.cmx. It can be opened by the browser of the GUI '''uvmat'''. In a later version of CIVx**, the .cmx file is replaced by a .xml ’!CivDoc’ file.202 * '''.cmx''' ASCII text files containing the parameters sent by the GUI '''civ_input''' to the CIV fortran programmes. Each velocity field named *.nc results from a parameter file *.cmx. It can be opened by the browser of the GUI '''uvmat'''. In a later version of CIVx**, the .cmx file is replaced by a .xml ’!CivDoc’ file. 203 203 204 204 * '''.log''' ASCII text files, containing information about processing in batch mode. Each velocity field named *.nc is associated with a file *.log. A file *_patch.log is similarly produced by the ’patch’ program. These files can be opened by the browser of the GUI '''uvmat'''. 205 205 206 206 === 3.7 Data organisation in a project === 207 The package is designed to foster a good data organisation. The raw data from a project should be organised as:[[BR]] '''!Project/Campaign/Experiment/DataSeries/data files'''.207 The package is designed to foster a good data organisation. The raw data from a project should be organised as:[[BR]] '''[!Project/Campaign/Experiment/DataSeries/data files]'''. 208 208 209 209 * '''Project''' contains all information on a project. … … 294 294 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 the list in [#overview the function overview]. 295 295 296 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 [#a5.2FieldrepresentationasMatlabstructure section 5.2], 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 [#a8.2TheGUIgeometry_calib.fig section 8.2].296 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 [#a5.2FieldrepresentationasMatlabstructure section 5.2], 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 [#a8.2TheGUIgeometry_calib.fig section 8.2]. 297 297 298 298 === 4.7 Succession of operations: === … … 320 320 == 5 - Field structures == 321 321 === 5.1 Griding of data === 322 Physical fields can be defined either on regular grids, either scattered on an unstructured set of positions. Some measurements techniques, like PIV or particle tracking, provided unstructured data, while most methods of analysis require data on a regular grid. This can be done by interpolation, defining a projection on a plane (with !ProjMode='interp...', see [#ProjObject next section]). The three possibilities of griding are defined as follows:323 324 - '''Regular grid:'''322 Physical fields can be defined either on regular grids, either scattered on an unstructured set of positions. Some measurements techniques, like PIV or particle tracking, provided unstructured data, while most methods of analysis require data on a regular grid. This can be done by interpolation, defining a projection on a plane (with '''[!ProjMode='interp...']''', see [#ProjObject next section]). The three possibilities of griding are defined as follows: 323 324 - '''Regular grid:''' 325 325 326 326 Each field is then a multi-dimensional array whose dimensions match the space dimensions. Because of the grid regularity, the set of positions is fully defined by the coordinate value for the first and last index along each dimension of the array. 327 327 328 - '''Structured orthogonal grid''':328 - '''Structured orthogonal grid''': 329 329 330 330 Each field is again a multi-dimensional array V whose dimensions match the space dimensions, but the coordinates may not be regularly spaced, so they are represented as a monotonic 1D array variable with the same length as the corresponding dimension of V. This is called a ''coordinate variable'' (see [#a7.1TheNetCDFformat section 7.1]). 331 331 332 - '''Unstructured coordinates:'''332 - '''Unstructured coordinates:''' 333 333 334 334 Fields may be alternatively obtained on a unstructured (grid-less) set of positions. The coordinates are then described by coordinate arrays X(nb_points), Y(nb_points), Z(nb_points). The corresponding field values are then represented as variables U(nb_point),V(nb_point) for each vector component, or alternatively by V(nb_points, j, i), where i, j possibly stand for vector or tensor components. 335 335 336 - '''Thin plate shell (tps) interpolation:'''336 - '''Thin plate shell (tps) interpolation:''' 337 337 338 338 This is a multi-dimensional generalisation of the spline interpolation/smoothing, an optimum way to interpolate data with minimal curvature of the interpolating function. The result at an interpolation position vector ${\bf r}$ is expressed in the form, (see ThinPlateShell) … … 372 372 373 373 === 5.3 Conventions for attributes in field objects: === 374 - '''Global attributes active in UVMAT''': those are used for plot settings or data processing.374 - '''Global attributes active in UVMAT''': those are used for plot settings or data processing. 375 375 376 376 * 'Conventions': … … 383 383 * '!TimeUnit': character string representing the unit of time (consistently for Time, Dt and velocity). 384 384 385 - '''Global attributes , unactive''' those are merely used for information purpose385 - '''Global attributes , unactive''' those are merely used for information purpose 386 386 387 387 * Project: recalls the project name. … … 394 394 * '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. 395 395 396 - '''Attributes of variables:'''396 - '''Attributes of variables:''' 397 397 398 398 * Mesh: suggested step value to discretize the values of the variable, used to define the bins for histograms. … … 400 400 * 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). 401 401 402 - '''The attribute 'Role':''' the following options are used for the attribute 'Role':402 - '''The attribute 'Role':''' the following options are used for the attribute 'Role': 403 403 404 404 * 'ancillary': information of secondary use, indicating for instance an error estimate of field variables within a field cell (omitted in plotting). … … 437 437 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 to field subregions. The projection of fields on objects is performed by the function ''proj_field.m'', which can be used as well in data processing outside the GUI '''UVMAT''', using for instance [#a10-Processingfieldseries series.fig]. 438 438 439 When a 2D or 3D field is opened by '''uvmat ;fig''', a default projection object called 'plane' is created, so that all field plots (in 2D and 3D) are considered as the result of a projection. New objects are created by the menu bar command '''[Projection object]''' in the GUI '''uvmat'''. The creation of a new object ('''points''', '''line'''....) can be initiated by selecting the corresponding item in the menu. In each case an auxiliary GUI '''set_object.fig''' describing the object properties appears, see next [#a6.2Objectproperties sub-section] for their definitions. This GUI can be directly edited and object coordinates can be set by mouse drawing on the plot, see [#a6.4Objectrepresentation section 6.4]. To validate edition on the GUI '''set_object.fig''', refresh the plots by pressing '''[REFRESH]'''. Objects can be saved as xml files with the (upper right) button '''[SAVE]''' of '''set_object.fig'''. The object can be later opened by the menu option '''[browse...]''' in the menu bar command '''[Projection object]''' of the GUI '''uvmat'''.439 When a 2D or 3D field is opened by '''uvmat.fig''', a default projection object called 'plane' is created, so that all field plots (in 2D and 3D) are considered as the result of a projection. New objects are created by the menu bar command '''[Projection object]''' in the GUI '''uvmat'''. The creation of a new object ('''points''', '''line'''....) can be initiated by selecting the corresponding item in the menu. In each case an auxiliary GUI '''set_object.fig''' describing the object properties appears, see next [#a6.2Objectproperties sub-section] for their definitions. This GUI can be directly edited and object coordinates can be set by mouse drawing on the plot, see [#a6.4Objectrepresentation section 6.4]. To validate edition on the GUI '''set_object.fig''', refresh the plots by pressing '''[REFRESH]'''. Objects can be saved as xml files with the (upper right) button '''[SAVE]''' of '''set_object.fig'''. The object can be later opened by the menu option '''[browse...]''' in the menu bar command '''[Projection object]''' of the GUI '''uvmat'''. 440 440 441 441 The names of the created objects are listed in the menu '''[!ListObject]'''. The properties of the object selected in this menu can be viewed by activating the check box '''[!CheckViewObject]'''. Check '''[!CheckEditObject]''' to allow object editing with '''set_object.fig'''. The selected object is plotted in magenta, while the inactive ones are in blue. The field plot resulting from projection can be viewed in the GUI '''view_field''' by activating '''[!CheckViewField]'''. This option is automatically selected when a new object is created. Then the projection object used for the main plotting window in UVMAT can be selected by the menu '''[!ListObject_1]''' which reproduces the list of available objects. The active objects are plotted in magenta, while the inactive ones are in blue. The object can be deleted by pressing '''[!DeleteObject]'''. … … 461 461 * ''' Angle: '''three component rotation vector which defines the orientation of the object coordinate axis, for 'plane' and 'volume'. In 2D, this rotation vector has only one component along z, defining a rotation angle in the plane (expressed in degrees). This applies also to the main axis of 'ellipse' and 'rectangle'. In 3D, line objects ('line', 'polyline','rectangle','polygon','ellipse') are assumed contained in a plane, and 'Angle' defines the orientation of this plane. 462 462 463 * ''' RangeX ''', ''' RangeY ''', ''' RangeZ:''' bounds defining a range of projection along each coordinate with respect to the object. These ranges have one or two values depending on the object type.463 * ''' RangeX''', ''' RangeY''', '''RangeZ:''' bounds defining a range of projection along each coordinate with respect to the object. These ranges have one or two values depending on the object type. 464 464 * 'points': the only relevant range is RangeX, with one value (a radius around the point). 465 465 * 'lines': the only relevant range is RangeY, with one value, a radius transverse to the line. … … 469 469 * 'volume': RangeX, RangeY, RangeZ (two values each) define a selected volume in the data set. 470 470 471 * ''' DX ''', ''' DY''', ''' DZ: '''mesh along each coordinate defining a grid for interpolation.471 * ''' DX''', ''' DY''', ''' DZ: '''mesh along each coordinate defining a grid for interpolation. 472 472 473 473 * ''' Coord: ''' matrix with two (for 2D fields) or three columns defining the object position. … … 481 481 482 482 === 6.3 Projection modes === 483 Each field variable yields a corresponding variable with the same name in the projected field. Integral quantities (circulation, flux...) can be also calculated. The result of projection depends on the object type, the nature of the coordinates, the ''Role'' of field variables and on the projection mode ''' !ProjMode''':483 Each field variable yields a corresponding variable with the same name in the projected field. Integral quantities (circulation, flux...) can be also calculated. The result of projection depends on the object type, the nature of the coordinates, the ''Role'' of field variables and on the projection mode '''[!ProjMode]''': 484 484 485 485 * ''' !ProjMode = 'projection': ''' this is a normal 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 projected variable on a regular grid (for instance on a line or plane). Data marked as false are projected, with their error flag, only for 'plane' or 'volume'. … … 540 540 541 541 === 7.2 The GUI get_field === 542 This GUI '''get_field.fig''' is aimed at browsing a NetCDF file, showing all its variables, attributes and variable dimensions. Variables can be selected for input in '''uvmat''' or '''series'''. The GUI is opened by selecting the option ''' get_field...''' in the menu '''[!FieldName]''' of '''uvmat''' or '''series'''. This option is automatically selected when the input NetCDF file is not recognised as CIV data.542 This GUI '''get_field.fig''' is aimed at browsing a NetCDF file, showing all its variables, attributes and variable dimensions. Variables can be selected for input in '''uvmat''' or '''series'''. The GUI is opened by selecting the option '''[get_field...]''' in the menu '''[!FieldName]''' of '''uvmat''' or '''series'''. This option is automatically selected when the input NetCDF file is not recognised as CIV data. 543 543 544 544 [[Image(7-2 The GUI get_field.png)]] … … 546 546 When a NetCDF input file opened, its full name, including path, is displayed in the upper window '''[inputfile]'''. The names and value of the global attributes are listed in the left column '''[attributes]''', the list of variables in the central column '''[variables]''', and the list of dimension names and values in the right column '''[dimensions]'''. By selecting one of the variables in the central column, the corresponding variable attributes and dimensions are displayed in the left and right columns respectively. Note that the whole content of the NetCDF file can be obtained by the function ''nc2struct.m''. Input fields can be selected according to three options, chosen by the menu '''[!FieldOption]'''. 547 547 548 -'''1D plot:''' to plot a simple graph, ordinate versus abscissa. Select by the menu '''[ordinate]''' the variable(s) to plot as ordinate (use the key '''Ctrl''' for multiple selection). Then select the corresponding abscissa in the column '''[abscissa]'''. If the variable is indexed with more than one dimension, each component is plotted versus the first index (like with the plot Matlab function ''plot.m''). If the option '''[matrix index]''' ('''[!CheckDimensionX]''') is selected, the ordinate variable is plotted versus its index.548 -'''1D plot:''' to plot a simple graph, ordinate versus abscissa. Select by the menu '''[ordinate]''' the variable(s) to plot as ordinate (use the key '''Ctrl''' for multiple selection). Then select the corresponding abscissa in the column '''[abscissa]'''. If the variable is indexed with more than one dimension, each component is plotted versus the first index (like with the plot Matlab function ''plot.m''). If the option '''[matrix index]''' ('''[!CheckDimensionX]''') is selected, the ordinate variable is plotted versus its index. 549 549 550 550 -'''scalar:''' to plot scalar fields as images. The variable representing the scalar is selected in the first column '''[scalar]''', with coordinates respectively selected in '''[Coord_x] ''' and '''[Coord_y]'''. Alternatively, matrix index can be used as coordinate if the options '''[matrix index]'''('''[CheckDimensionX]''' and '''[CheckDimensionY]''') are selected. … … 565 565 The ''physical coordinates'' are defined from the experimental set-up. The correspondance with images is obtained by identifying a set of calibration points whose positions are known in the physical coordinate system. A cartesian calibration grid covering the whole image is the best option, but any set of calibration points can be used. We handle three kinds of transforms: 566 566 567 - '''rescale''': linear rescaling along ''x'' and ''y'' + translation (no rotation nor deformation).568 569 - '''linear''': general linear transform, including translation and rotation (but no projection effects).570 571 - '''3D_linear:''' this transform handles projection effects, needed if the observed plane is not perpendicular to the line of sight. It involves a 3D calibration needed to account for the depth effects occuring in volume scan.572 573 - '''3D_quadr:''' this is like 3D_linear, but takes also into account a quadratic deformation by the optics which occurs for wide fields of view (small focal lengths).574 575 - '''3D_extrinsic:''' this is like 3D_quadr, but uses intrinsic parameters of the camera, as explained below.567 - '''rescale''': linear rescaling along ''x'' and ''y'' + translation (no rotation nor deformation). 568 569 - '''linear''': general linear transform, including translation and rotation (but no projection effects). 570 571 - '''3D_linear:''' this transform handles projection effects, needed if the observed plane is not perpendicular to the line of sight. It involves a 3D calibration needed to account for the depth effects occuring in volume scan. 572 573 - '''3D_quadr:''' this is like 3D_linear, but takes also into account a quadratic deformation by the optics which occurs for wide fields of view (small focal lengths). 574 575 - '''3D_extrinsic:''' this is like 3D_quadr, but uses intrinsic parameters of the camera, as explained below. 576 576 577 577 The 3D options involve a full 3D calibration relying on the [attachment:3D_view.pdf pinhole camera model]. The method was first proposed by R.Y. Tsai, 'An Efficient and Accurate Camera Calibration Technique for 3D Machine Vision'. Proceedings of IEEE Conference on Computer Vision and Pattern Recognition, Miami Beach, FL, pp. 364-374 (1986). We use a more recent version, with the toolbox [->http://www.vision.caltech.edu/bouguetj/calib_doc/] . 3D calibrations are done in two steps. The camera'' intrinsic parameters'', which are the focal length and the quadratic deformation coefficient, are first determined by different views of the same grid observed at different angles. Then the ''extrinsic parameters'', which represent the rotation angles and translation of the physical coordinates with respect to the camera, are obtained with a single image of the grid positioned in a known plane $z=cte$. The option 3D_extrinsic allows the user to do only the second step from known intrinsic parameters. Those depend only on the camera with its objective lens and focus adjustement. Note that these 3D options require a calibration grid, with a sufficient number of calibration points covering the whole image. … … 604 604 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, keeping the GUI geometry_calib opened. 605 605 606 To calibrate at once a set of experiments, a better alternative is the command '''[REPLICATE]'''. Open a folder '''Campaign''', parent of the folders '''Experiment''' to treat. The GUI '''data_browser.fig''', also described in [#a3.7Dataorganisationinaproject section 3.7], then pops up. A two-column display appears, with the list of '''Experiments''' on the left and the list of corresponding '''[!DataSeries]''' on the right. Select the list of experiments to calibrate, and a single camera name in '''[!DataSeries]''', then validate by pressing ''' OK'''.607 608 -''' 3D calibration''': 3D projection is handled by the options in '''[calib_type]''' '3D_lin' or '3D_quad' (if non-linear distortion is significant). By default, the set of calibration points is assumed to be contained in a single plane ''z''=0. For a correct determination of the 3D features, the normal to this plane must be tilted with respect to the line of view. Otherwise this problem of indetermination can be resolved by using a set of (typically 5-10) calibrations images using a plane grid with different tilting angles (for precision the grid must cover a large area of the view field). On each image, get calibration points with the tool '''[!Tools/Detect grid]''', introducing the appropriate grid mesh. Do not fill info on ''z'' coordinates. Store the points each time (without applying calibration at this stage), which fills the list [!ListCoordFiles] of file names. Then introduce a last grid image which will be considered as defining the orientation of the ''z'' axis, perpendicular to the grid. Detect points on this last image, but instead of storing them, apply the calibration with the option 3D_linear or 3D_quadr. A non-zero ''z'' position of this grid can be introduced by a z translation performed with '''!Tools/Translate points'''.609 610 -''' Intrinsic parameters''': the previous procedure first determines the extrinsic parameters which characterize the camera optics (focal lengths and nonlinear deformation parameter). Then the extrinsic parameters, translation and rotation of the camera with respect to the reference grid, are determined on the last grid image. If the same optics is used in a new experiment, it is possible to skip the multiplane detection, importing the intrinsic parameters from a previous <!ImaDoc> file by the menu bar tool '''[!Import/Intrinsic]''' parameters, then applying the calibration with the option '3D_extrinsic' with the reference grid image only.611 612 -''' Section planes:''' deducing the physical coordinates from image coordinates requires information on the section plane. The default assumption is that the objects in the image are in the plane used for calibration, but uvmat can handle volume scanning by a laser plane. A set of section planes can be defined by their origin positions and rotation angle vectors. Theses planes are labelled by a ''z index'', assumed to be the frame index j (case of volume scan), or the index i modulo the number of slices !NbSlice (case of 'multilevel' scan). These settings are stored in the xml file <!ImaDoc> as part of the section <!GeometryCalib> and can be edited from '''uvmat.fig''' with the menu bar command '''[Tools/set slice]'''. A dialog box '''set_slices''' appears for entering the first and last section plane positions ''z'', as well as the number of slices and the option 'volume_scan' ('multilevel' otherwise). In the absence of 3D scan put twice the same value for first and last z. Finally a tilt angle of the laser sheet, around the ''x'' and ''y'' axis, can be introduced, with a possible angular scanning from first to last section planes. After introduction of the plane position information, the z-index is displayed in the frame '''[!FileIndices]''' of '''uvmat.fig'''. The local ''z'' position of the mouse pointer, assumed to lay on the current section plane, is then displayed in '''[text_display]'''.613 614 -''' Refraction effect:''' refraction effect can be accounted for if calibration was done in air by selecting the check box refraction, and introducing the water height (assumed at ''z''=cte) and refraction index. The apparent distance reduction for objects below the water height will be then taken into account.606 To calibrate at once a set of experiments, a better alternative is the command '''[REPLICATE]'''. Open a folder '''Campaign''', parent of the folders '''Experiment''' to treat. The GUI '''data_browser.fig''', also described in [#a3.7Dataorganisationinaproject section 3.7], then pops up. A two-column display appears, with the list of '''Experiments''' on the left and the list of corresponding '''[!DataSeries]''' on the right. Select the list of experiments to calibrate, and a single camera name in '''[!DataSeries]''', then validate by pressing '''[OK]'''. 607 608 -''' 3D calibration''': 3D projection is handled by the options in '''[calib_type]''' '3D_lin' or '3D_quad' (if non-linear distortion is significant). By default, the set of calibration points is assumed to be contained in a single plane ''z''=0. For a correct determination of the 3D features, the normal to this plane must be tilted with respect to the line of view. Otherwise this problem of indetermination can be resolved by using a set of (typically 5-10) calibrations images using a plane grid with different tilting angles (for precision the grid must cover a large area of the view field). On each image, get calibration points with the tool '''[!Tools/Detect grid]''', introducing the appropriate grid mesh. Do not fill info on ''z'' coordinates. Store the points each time (without applying calibration at this stage), which fills the list [!ListCoordFiles] of file names. Then introduce a last grid image which will be considered as defining the orientation of the ''z'' axis, perpendicular to the grid. Detect points on this last image, but instead of storing them, apply the calibration with the option 3D_linear or 3D_quadr. A non-zero ''z'' position of this grid can be introduced by a z translation performed with '''[!Tools/Translate points]'''. 609 610 -''' Intrinsic parameters''': the previous procedure first determines the extrinsic parameters which characterize the camera optics (focal lengths and nonlinear deformation parameter). Then the extrinsic parameters, translation and rotation of the camera with respect to the reference grid, are determined on the last grid image. If the same optics is used in a new experiment, it is possible to skip the multiplane detection, importing the intrinsic parameters from a previous <!ImaDoc> file by the menu bar tool '''[!Import/Intrinsic]''' parameters, then applying the calibration with the option '3D_extrinsic' with the reference grid image only. 611 612 -''' Section planes:''' deducing the physical coordinates from image coordinates requires information on the section plane. The default assumption is that the objects in the image are in the plane used for calibration, but uvmat can handle volume scanning by a laser plane. A set of section planes can be defined by their origin positions and rotation angle vectors. Theses planes are labelled by a ''z index'', assumed to be the frame index j (case of volume scan), or the index i modulo the number of slices !NbSlice (case of 'multilevel' scan). These settings are stored in the xml file <!ImaDoc> as part of the section <!GeometryCalib> and can be edited from '''uvmat.fig''' with the menu bar command '''[Tools/set slice]'''. A dialog box '''set_slices''' appears for entering the first and last section plane positions ''z'', as well as the number of slices and the option 'volume_scan' ('multilevel' otherwise). In the absence of 3D scan put twice the same value for first and last z. Finally a tilt angle of the laser sheet, around the ''x'' and ''y'' axis, can be introduced, with a possible angular scanning from first to last section planes. After introduction of the plane position information, the z-index is displayed in the frame '''[!FileIndices]''' of '''uvmat.fig'''. The local ''z'' position of the mouse pointer, assumed to lay on the current section plane, is then displayed in '''[text_display]'''. 613 614 -''' Refraction effect:''' refraction effect can be accounted for if calibration was done in air by selecting the check box refraction, and introducing the water height (assumed at ''z''=cte) and refraction index. The apparent distance reduction for objects below the water height will be then taken into account. 615 615 616 616 [[Image(browse_data_small.jpg)]] [[Image(set_slices_small.jpg)]] … … 655 655 == 9 - Masks and grids == 656 656 === 9.1 Masks === 657 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 [#MaskGrids section 3.6]. Mask 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.657 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 [#MaskGrids section 3.6]. Mask 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. 658 658 659 659 First open an input image file name with the browser, or the edit box and carriage return. From the image name, a corresponding mask name is proposed in the lower edit box. It should be edited if a series of masks is made, in case of mutipositions (number nbslices) of the laser sheet in a series. The names must be [filebase '_xxmask' 'filenumber' '.png'], where xx is the number of masks (nbslices). The mask filenumber used is the image field number modulo nbslices. The filenumber can be incremented by the NEXT press button. … … 675 675 The root path, subdirectory, root file name and extension are introduced in the different columns of the table '''[!InputTable]'''. The nomenclature for file indexing is represented in the column '''[!NomType]''', the index extension for the first file in the series. 676 676 677 Several input file series can be introduced simultaneously with the upper menu bar, or filling manually the successive lines of ''' !InputTable'''. To get a new line, press the 'down' keyboard arrow after selecting the last existing line (this copies by default the last line content to the new line). A line can be suppressed by selecting it and pressing the key 'Suppress'. Press the button '''[REFRESH]''' to validate the input (checking the existence of the file series) after any editing.677 Several input file series can be introduced simultaneously with the upper menu bar, or filling manually the successive lines of '''[!InputTable]'''. To get a new line, press the 'down' keyboard arrow after selecting the last existing line (this copies by default the last line content to the new line). A line can be suppressed by selecting it and pressing the key 'Suppress'. Press the button '''[REFRESH]''' to validate the input (checking the existence of the file series) after any editing. 678 678 679 679 The panel '''[!IndexRange]''' specifies the range of input file or field indices to process while the panel Action specifies the processing function. New processing functions can be added by the user. The files resulting from the processing are put in a folder with the same path !RootPath as the folder !SubDir containing the input files. The name of this output folder is defined in '''[!OuputSubdir]''': the default name is the input folder ''!SubDir'', followed by an extension depending on the processing function. … … 688 688 The menu bar at the top of the GUI contains the following buttons: 689 689 690 * '''[Open]''': Open or browse input files. It operates like for the GUI UVMAT, except that there are now two possibilities: ''' browse...''' or '''browse_append...''' The latter appends a new input line to the table '''[!InputTable]''' while the former refreshes the table.690 * '''[Open]''': Open or browse input files. It operates like for the GUI UVMAT, except that there are now two possibilities: '''[browse...]''' or '''[browse_append...]''' The latter appends a new input line to the table '''[!InputTable]''' while the former refreshes the table. 691 691 692 692 * '''[Open campaign]''': does the same as '''[Open]''' but scans the data organised as a project/campaign, see [https://servforge.legi.grenoble-inp.fr/#a3.7Dataorganisationinaproject section 3.7]. … … 711 711 712 712 === 10.5 Field transform, projection object and mask === 713 A transform function can be introduced by the menu '''[!TransformName]''' in the frame '''[!FieldTransform]'''. New transform functions can be introduced by the option 'more....'. Its path is then recorded and displayed in '''[!TransformPath]. Transform '''functions act field by field to modify the input (for instance transforming image to physical coordinates), like in the GUI UVMAT, while the ''' Action''' functions act on the whole series.713 A transform function can be introduced by the menu '''[!TransformName]''' in the frame '''[!FieldTransform]'''. New transform functions can be introduced by the option 'more....'. Its path is then recorded and displayed in '''[!TransformPath]. Transform '''functions act field by field to modify the input (for instance transforming image to physical coordinates), like in the GUI UVMAT, while the '''[Action]''' functions act on the whole series. 714 714 715 715 A projection object can be introduced by selecting the check box '''[!CheckObject]'''. If a projection object has been already created the opened interface '''set_object.fig''' will be used. Otherwise a browser appears to open an object file (XML). It is possible to view the current projection object by pressing '''[view]''', edit it by selecting '''[edit]''', or delete it by pressing '''[delete]'''. 716 716 717 Similarly the check box '''[!CheckMask]''' can be used to select a mask option. These different menus only appear if they are needed as input of the currently selected ''' Action''' function.717 Similarly the check box '''[!CheckMask]''' can be used to select a mask option. These different menus only appear if they are needed as input of the currently selected '''[Action]''' function. 718 718 719 719 === 10.6 The frame [Action] === 720 The processing function is chosen in the menu '''[!ActionName]'''. The first option ''check_data_files'' lists the selected input file series and checks their existence. This is a good first test before starting a processing operation since all actions operate on the same input file series. The option ''aver_stat'' calculates a global average on the successive fields, while ''time_series'' provides a time series. The option ''merge_proj'' is used to project a whole series on a given grid, or to create a file series by concatenation of different fields. These processing functions are described with more details in next sub-sections. The option ''civ_series'' gives access to the PIV processsing, see section [#Civ: section 11]. Finally any additional function can be called and included in the menu by selecting the option ''more...'' . The corresponding path is displayed in '''!ActionPath'''.720 The processing function is chosen in the menu '''[!ActionName]'''. The first option ''check_data_files'' lists the selected input file series and checks their existence. This is a good first test before starting a processing operation since all actions operate on the same input file series. The option ''aver_stat'' calculates a global average on the successive fields, while ''time_series'' provides a time series. The option ''merge_proj'' is used to project a whole series on a given grid, or to create a file series by concatenation of different fields. These processing functions are described with more details in next sub-sections. The option ''civ_series'' gives access to the PIV processsing, see section [#Civ: section 11]. Finally any additional function can be called and included in the menu by selecting the option ''more...'' The corresponding path is displayed in '''[!ActionPath]'''. 721 721 722 722 The action function is first activated when it is selected in the menu '''[!ActionName]'''. This first activation checks input data and sets the visibility of input GUI uicontrols. 723 723 724 The actual start of the processing is triggered by pressing the button '''[RUN]'''. It can be run in local mode, i.e. on the current Matlab session, or as ''background'', by selecting this option in ''' !RunMode'''. In mode ''background'', calculation is performed in a new Matlab session (without graphics) so that the current Matlab session is free for new operations. If a cluster system has been detected, a third option ''cluster'' appears in the menu, allowing to dispatch parallel computations on a computer cluster.725 726 For the cluster option, a compiled version of the action function is useful, to avoid installing Matlab on each node of the cluster. This is achieved by selecting the option ''.sh'' in the menu ''' !ActionExt'''. If the compiled version is not yet available, or outdated, the GUI proposes a new compilation of the selected function (launching the function ''compile.m'' requiring the Matlab compilator toolbox). The use of compiled function on the cluster requires a file '!RunTime' whose address needs to be specified in the parameter file PARAM.xml of the package UVMAT. The commands in '''series''' are set for the system 'oar', but adding the equivalent commands for another cluster system is straightforward (this must be done in the sub-function ''RUN_Callback''of ''series.m'').724 The actual start of the processing is triggered by pressing the button '''[RUN]'''. It can be run in local mode, i.e. on the current Matlab session, or as ''background'', by selecting this option in '''[!RunMode]'''. In mode ''background'', calculation is performed in a new Matlab session (without graphics) so that the current Matlab session is free for new operations. If a cluster system has been detected, a third option ''cluster'' appears in the menu, allowing to dispatch parallel computations on a computer cluster. 725 726 For the cluster option, a compiled version of the action function is useful, to avoid installing Matlab on each node of the cluster. This is achieved by selecting the option ''.sh'' in the menu '''[!ActionExt]'''. If the compiled version is not yet available, or outdated, the GUI proposes a new compilation of the selected function (launching the function ''compile.m'' requiring the Matlab compilator toolbox). The use of compiled function on the cluster requires a file '!RunTime' whose address needs to be specified in the parameter file PARAM.xml of the package UVMAT. The commands in '''series''' are set for the system 'oar', but adding the equivalent commands for another cluster system is straightforward (this must be done in the sub-function ''RUN_Callback'' of ''series.m''). 727 727 728 728 === 10.7 Action functions of general use === … … 730 730 731 731 * ''check_data_files:'' gives the series of files selected for processing and checks their existence. The oldest modified file is indicated, which is useful to detect whether any file in a civ processing is missing (then the oldest file is not updated). For NetCDF files, the last operation made (civ1, fix1, patch1, civ2, fix2, patch2) is indicated. The details of each NetCDF file can be dispalyed by selecting it with the mouse in the list. 732 * ''aver_stat'': this option provides any average over the processed files. If '''[!NbSlice]''' is not equal to 1, the average is performed slice by slice, providing !NbSlice results. If a projection object is selected (check box '''[!CheckObject]'''), the field is projected before averaging. For unstructured coordinates varying for successive fields, the data is linearly interpolated on the coordinates of the first field in the series. It is then advised to project the fields on a regular grid, creating a projection object of type '''plane''' with projection mode ''' interp_lin''' or '''interp_tps'''. With a projection mode 'inside' or 'outside', the global histogram of field variables on the selected region will be obtained. In the case of two input files series, the field difference will be performed like with the interface uvmat.fig. It is not possible to use more than two input series for this function.732 * ''aver_stat'': this option provides any average over the processed files. If '''[!NbSlice]''' is not equal to 1, the average is performed slice by slice, providing !NbSlice results. If a projection object is selected (check box '''[!CheckObject]'''), the field is projected before averaging. For unstructured coordinates varying for successive fields, the data is linearly interpolated on the coordinates of the first field in the series. It is then advised to project the fields on a regular grid, creating a projection object of type '''plane''' with projection mode '''[interp_lin]''' or '''[interp_tps]'''. With a projection mode 'inside' or 'outside', the global histogram of field variables on the selected region will be obtained. In the case of two input files series, the field difference will be performed like with the interface uvmat.fig. It is not possible to use more than two input series for this function. 733 733 * ''time_series:'' this action provides a time series of the input field, possibly projected . Thus projection on 'points' lead to time series of the projected variable(s) for each point, projection by interpolation on a line will (x,time) field, while projection on a plane gives a 3D matrix, whose first index corresponds to time. Note that for a vector field, projection on a tilted line or plane yields the vector components longitudinal and normal to the object. To preserve the original ''x'' and ''y'' components, introduce them as ''scalar'', not ''vectors''. 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. 734 734 * ''merge_proj'': 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, using the input option ''append''. In this case, it is generally useful to interpolate the fields on a single grid. For that purpose select a projection object of type 'plane' with projection mode 'interp_lin', or 'interp_tps' to get spatial derivative. 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. 735 735 * ''civ_series'': does PIV processing, see section [#Civ: section 11]. 736 736 737 === 10.8 Other functions Action ...===738 With the option '' more...'' in !ActionName, a browsers pops up to choose an Action function. Some examples of functions are in the subdirectory ''{/series}'' of the folder containing '''''umat'''''. A few more examples (less reliable) are in the subfolder ''{/series/usr_fct}'', a good place to put your own functions.737 === 10.8 Other functions Action === 738 With the option '''[more...]''' in [!ActionName], a browsers pops up to choose an Action function. Some examples of functions are in the subdirectory ''{/series}'' of the folder containing '''''umat'''''. A few more examples (less reliable) are in the subfolder ''{/series/usr_fct}'', a good place to put your own functions. 739 739 740 740 * ''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). 741 * ''ima_levels.m'': provides images with modified grey scale intensity to avoid blinking effects on particles. ''''''''''741 * ''ima_levels.m'': provides images with modified grey scale intensity to avoid blinking effects on particles. 742 742 * ''ima2vol.m'' produce volume images for 3D3C PIV. 743 743 * ''turb_stat.m'': produces turbulent statistics (Reynolds stress tensor). 744 744 745 These can be used as template to create other functions. The general input of these functions in Matlab structure 'Param' which contains all the input parameters as given by the GUI series (see comments in the function for details). For batch operations, as needed for the cluster, this input is replaced by the name of an XML file which contains these parameters (this is the file produced in the floder '''/0_XML''' under the result directrory Output Subdir). The first part of the function must give some options for the requested input information and may interactively introduce specific parameters needed for the function. The second part of the function, where the processing itself takes place, is then free from any input (so the operation can be easily dispatched to a remote computer).746 747 The first part of the function is activated when the function is selected in the menu !ActionName of the GUI '''series''', which yields the input !Param.Action.RUN=0. It is aimed at setting the GUI configuration appropriate for the specific function, and to provide all the needed input parameters. The second part is activated by the action RUNand should not contain any interactive input to allow for batch mode outside the current Matlab session.745 These can be used as template to create other functions. The general input of these functions in Matlab structure 'Param' which contains all the input parameters as given by the GUI '''series''' (see comments in the function for details). For batch operations, as needed for the cluster, this input is replaced by the name of an XML file which contains these parameters (this is the file produced in the floder '''/0_XML''' under the result directrory Output Subdir). The first part of the function must give some options for the requested input information and may interactively introduce specific parameters needed for the function. The second part of the function, where the processing itself takes place, is then free from any input (so the operation can be easily dispatched to a remote computer). 746 747 The first part of the function is activated when the function is selected in the menu '''[!ActionName]''' of the GUI '''series''', which yields the input Param.Action.RUN=0. It is aimed at setting the GUI configuration appropriate for the specific function, and to provide all the needed input parameters. The second part is activated by the action '''[RUN]''' and should not contain any interactive input to allow for batch mode outside the current Matlab session. 748 748 749 749 The settings of the GUI ''' series''' are controlled by the following parameters (fields of the Matlab structure 'Param'): 750 750 751 ||''' name'''||'''values'''||'''default'''||'''role'''||751 ||'''Name'''||'''Values'''||'''Default'''||'''Role'''|| 752 752 ||.!WholeIndexRange||'off'/'on'||'off'||prescribes the file index ranges from min to max (the whole file series is needed)|| 753 753 ||.!AllowInputSort||'off'/'on'||'off'||for multiple lines in the input file table, provides an automatic alphabetic sorting of the list of input files !SubDir (so that the order of intput file series used does not depend on the order of introduction)|| … … 776 776 777 777 * '''PIV''': makes image comparisons on sliding index pairs, as usual for measuring velocities by particle displacements. A second menu '''[!ListPairMode]''' in the panel '''[!PairIndices]''' then selects one among three possibilities (not always available depending on the file indexing): 778 * ''pair j1-j2:'' selects a given j index pair (sometimes denoted by letter index) for the whole time series. This is the most common case for PIV. Pair selection is performed in the menu '''[!ListPairCiv1]''' and '''[!ListPairCiv2]''' for the second iteration Civ2, see below. If timing from an XML file [#a3.5Imagedocumentationfiles.xml < !ImaDoc>] has been detected, this is indicated in the edit box '''[!ImaDoc]''' and the corresponding time intervals are indicated (in ms). For some applications, this time interval may evolve in time, so that reference indices ref_i and ref_j are chosen for the display.778 * ''pair j1-j2:'' selects a given j index pair (sometimes denoted by letter index) for the whole time series. This is the most common case for PIV. Pair selection is performed in the menu '''[!ListPairCiv1]''' and '''[!ListPairCiv2]''' for the second iteration Civ2, see below. If timing from an XML file [#a3.5Imagedocumentationfiles.xml <ImaDoc>] has been detected, this is indicated in the edit box '''[!ImaDoc]''' and the corresponding time intervals are indicated (in ms). For some applications, this time interval may evolve in time, so that reference indices ref_i and ref_j are chosen for the display. 779 779 * series (Di): selects a given index interval for the i index, around a set of reference i indices. The intervals are denoted Di=0|1, -1|1, -1|2, -2|2 ... , corresponding to the index pairs i|i+1, i-1|i+1, i-1|i+2, i-2|i+2 ...around each reference index i. Pair selection is then performed in the menu '''[!ListPairCiv1]''' and '''[!ListPairCiv2]''' like for 'pair j1-j2'. 780 780 * series (Dj): same as series (Di) but with the j index. … … 803 803 Examples of XML files are provides in /XML_SCHEMAS/ImaDoc_templates. 804 804 805 ('''[num_!CorrBoxSize_1,_2,_3])''' set the size (in pixels) of the 'correlation box', the sliding window used to get image correlations. '''[num_!SearchBoxSize_1,_2,_3]''' 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 ( [num_!SearchBoxShift_1,_2,_3]). This is useful in the presence of a known mean flow. The default value !SearchBoxSize=(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).805 ('''[num_!CorrBoxSize_1,_2,_3])''' set the size (in pixels) of the 'correlation box', the sliding window used to get image correlations. '''[num_!SearchBoxSize_1,_2,_3]''' 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 ('''[num_!SearchBoxShift_1,_2,_3]'''). This is useful in the presence of a known mean flow. The default value '''[!SearchBoxSize]'''=(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). 806 806 807 807 A parameter '''[num_CorrSmooth]''' controls the smoothing of the image corelation curves used in civ, the default value 1 is generally used. 808 808 809 The search parameters ( !SearchBoxSize,!SearchBoxShift) can be estimated using the press button '''[search range]'''. First introduce the estimated minimum and maximum values of each velocity component u and v (expressed in pixel displacement). The result depends on the time interval of the image pair.809 The search parameters ('''[!SearchBoxSize]''', '''[!SearchBoxShift]''') can be estimated using the press button '''[search range]'''. First introduce the estimated minimum and maximum values of each velocity component u and v (expressed in pixel displacement). The result depends on the time interval of the image pair. 810 810 811 811 [[Image(11-2 CV1.png)]] 812 812 813 The button '''[TEST]''' allows the user to witness the correlation as a live plot. It first opens the source image in a new figure '''view_field'''. By moving the mouse in the figure, the local correlation box and the corresponding search box are drawn in the image, and the 2D correlation result then appears in a new figure 'Figure1 Image Correlation' which automatically pops up. It is possible to freeze the current correlation plot by left mouse selection. The figure belows shows the correlation process and the ''' !SearchBox''' and '''!CorrBox''' explained before.813 The button '''[TEST]''' allows the user to witness the correlation as a live plot. It first opens the source image in a new figure '''view_field'''. By moving the mouse in the figure, the local correlation box and the corresponding search box are drawn in the image, and the 2D correlation result then appears in a new figure 'Figure1 Image Correlation' which automatically pops up. It is possible to freeze the current correlation plot by left mouse selection. The figure belows shows the correlation process and the '''[!SearchBox]''' and '''[!CorrBox]''' explained before. 814 814 815 815 [[Image(civ1_test.jpg)]] 816 816 [[Image(Correlation for PIV.png)]] 817 817 818 The grid determines the positions of measured velocity vectors: it sets the central positions of the correlation boxes (in pixels) for the first image. A default regular grid can be set by the meshes '''[num_Dx] ''' and '''[num_Dy]''' (in pixels). Alternatively a custom [# MaskGridgrid] can be stored in a text file and selected by the check box '''[GET_GRID]'''. This is convenient to limitate the processing to a subregion or to fine tune the resolution.818 The grid determines the positions of measured velocity vectors: it sets the central positions of the correlation boxes (in pixels) for the first image. A default regular grid can be set by the meshes '''[num_Dx] ''' and '''[num_Dy]''' (in pixels). Alternatively a custom [#a9.2Grids grid] can be stored in a text file and selected by the check box '''[GET_GRID]'''. This is convenient to limitate the processing to a subregion or to fine tune the resolution. 819 819 820 820 A subregion can be alternatively selected by a mask image, selecting the edit box '''[Mask]'''. If a mask image with an appropriate name is found in the image directory, it wil be detected, and the indication 'xxmask' appears in the edit box. (xx is the number of slices, equal to 1 for a single mask). Otherwise a browser appears to select a (single) mask file. … … 825 825 The FIX operation is used after civ to mark false vectors, using different criteria: 826 826 827 ''' Warning flags: ''' these are flags (vec_F) indicating problems with the image correlation process.827 '''- Warning flags: ''' these are flags (vec_F) indicating problems with the image correlation process. 828 828 * vec_F=-2: select to eliminate vectors for which 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. 829 829 * vec_F=3: the optimisation of the correlation function is unstable or local Intensity rms of the image =0. Must be selected. 830 830 831 ''' Threshold on the image correlation: ''' (vec_C) can be introduced by the edit box '''[num_!MinCorr]''' (value between 0 and 1). It removes vectors with poor correlation.832 833 ''' Threshold on the velocity modulus: ''' (expressed in pixels). It can remove either excessive values (threshold set by '''[num_MaxVel]''') or too small values (threshold set by '''[num_MinVel]'''). Erratic zero velocity vectors, produced by a fixed image background, can be eliminated by the latter criterium.834 835 ''' Manual fix: ''' Interactive fixing with the mouse is also possible, see [#a4.2Contourplots section 4.2].831 '''- Threshold on the image correlation: ''' (vec_C) can be introduced by the edit box '''[num_!MinCorr]''' (value between 0 and 1). It removes vectors with poor correlation. 832 833 '''- Threshold on the velocity modulus: ''' (expressed in pixels). It can remove either excessive values (threshold set by '''[num_MaxVel]''') or too small values (threshold set by '''[num_MinVel]'''). Erratic zero velocity vectors, produced by a fixed image background, can be eliminated by the latter criterium. 834 835 '''- Manual fix: ''' Interactive fixing with the mouse is also possible, see [#a4.2Contourplots section 4.2]. 836 836 837 837 … … 840 840 841 841 === 11.5 CIV2 === 842 - '''CIV2:''' provides a refined calculation of the velocity field, using the civ1 result as previous estimate. The civ1 field provides an estimated shift for each measurement point, so there is no edit box to enter shift parameter. The other parameters, in particular '''[!CorrBoxSize]''' and '''[!SearchBoxSize]''', have the same meaning as for Civ1. The image pair for civ2 ( set by the menu '''[!ListPairCiv2]''', can be different than the one used in civ1. It is generally advised to use a moderate time interval for civ1, to provide a first estimate avoiding false vectors, and to take a larger intervel for civ2, in order to optimize precision. As civ2 already knows where to look and takes into account image strain and rotation (with the option 'deformation') it allows for higher time intervals.842 - '''CIV2:''' provides a refined calculation of the velocity field, using the civ1 result as previous estimate. The civ1 field provides an estimated shift for each measurement point, so there is no edit box to enter shift parameter. The other parameters, in particular '''[!CorrBoxSize]''' and '''[!SearchBoxSize]''', have the same meaning as for Civ1. The image pair for civ2 ( set by the menu '''[!ListPairCiv2]''', can be different than the one used in civ1. It is generally advised to use a moderate time interval for civ1, to provide a first estimate avoiding false vectors, and to take a larger intervel for civ2, in order to optimize precision. As civ2 already knows where to look and takes into account image strain and rotation (with the option 'deformation') it allows for higher time intervals. 843 843 844 844 Image deformation and rotation can be introduced before calculating the correlations, by selecting '''[!CheckDeformation]'''. This option is useful in the presence of strong shear or vorticity. 845 845 846 - '''FIX2:''' like FIX1, except for a new possible flag value vec_F=4 which indicates that the difference between the estimator and the result is more than 1 pixel. This should be selected for excellent data (otherwise it may be too strict).847 848 849 - '''PATCH2:''' like PATCH1846 - '''FIX2:''' like '''[FIX1]''', except for a new possible flag value vec_F=4 which indicates that the difference between the estimator and the result is more than 1 pixel. This should be selected for excellent data (otherwise it may be too strict). 847 848 849 - '''PATCH2:''' like '''[PATCH1]''' 850 850 851 851 Further iterations: improvements can be obtained by further iterations of the civ2-fix2-patch2 process. Open again the interface, and consider the previous civ2 result as the prior guess civ1. It will be recopied and relabelled as civ1 in the new NetCDF file produced. … … 862 862 Perform usual PIV for each image series. 863 863 864 For PIV near a staigth wall, it is advised to create a grid for each image series, corresponding to a common array of physical positions. This can be done by the upper menu bar option ''' !Tools/Make Grid''' in the GUI '''uvmat'''( see section [#a9.2Grids Grids]).864 For PIV near a staigth wall, it is advised to create a grid for each image series, corresponding to a common array of physical positions. This can be done by the upper menu bar option '''[!Tools/Make Grid]''' in the GUI '''uvmat'''( see section [#a9.2Grids Grids]). 865 865 866 866 Combine PIV fields: TO UPDATE**. … … 871 871 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. 872 872 873 - '''List of constants (global attributes):''',873 - '''List of constants (global attributes):''', 874 874 875 875 Conventions 'uvmat/civdata'. … … 902 902 ||Civ2_CheckDeformation||=1 if image deformation option is used|| 903 903 904 - '''List of variables:'''904 - '''List of variables:''' 905 905 906 906 Conventions 'uvmat/civdata'. … … 926 926 ||Civ1_W_tps||tps weights for z vel component|| 927 927 928 - '''List of constants, old CIVx conventions:'''928 - '''List of constants, old CIVx conventions:''' 929 929 930 930 * nb_coord: =2 for PIV in a plane, =3 for PIV in a volume. … … 951 951 * ro2_patch: smoothing coefficient rho used for patch2. 952 952 953 - '''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).953 - '''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). 954 954 955 955 The names of the fields (variables) resulting from each operation are given in the following table. Each column corresponds to an operation. 'filter1' and 'interp1' both result from the patch1 interpolation on the same points, with and without smoothing respectively. The first line is the name of the constant representing the number of vectors (the dimension of the arrays). The next successive lines indicate the variable names for the position and velocity components, the image correlation 'c', the 'flag' about civ quality and 'fix' flag (only available for civ1 and civ2), and the spatial derivatives obtained from the patch operations. 956 956 957 - *Names of field variables for civ1 and patch1957 - '''Names of field variables for civ1 and patch1''' 958 958 959 959 ||''' '''||civ1||'''interp1'''||'''filter1 '''|| … … 973 973 ||dv/dy||||vec_patch0_DVDY||vec_patch_DVDY|| 974 974 975 - *Names of field variables for civ2 and patch2975 - '''Names of field variables for civ2 and patch2''' 976 976 977 977 same as previous, replacing 'vec' by 'vec2'.