Changes between Version 43 and Version 44 of UvmatHelp


Ignore:
Timestamp:
Jun 5, 2013, 9:51:34 PM (7 years ago)
Author:
sommeria
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UvmatHelp

    v43 v44  
    5757 * '''[Open]''': gives access to the browser for the main input field. 
    5858   * '''[browse...]''': open a general file browser ''browser_uvmat''. In the displayed list, a file can be selected for opening  (by a single mouse click),or directories are marqued by '+/'.  Select the first line '+/..' to move up in the directory tree, and the arrow <-- to move backward. The dates of file creation can be displayed by pressing the button '''[dates]'''. file ordering by name or date can be chosen by the popumenu above. A path can be directly entered by copy-paste in the upper edit window of the browser.
    59    * '''[browse campaign...]''':  scan the data organised as a project/campaign, see [wiki:#a3.7Dataorganisationinaproject section 3.7].
     59   * '''[browse campaign...]''':  scan the data organised as a project/campaign, see [#a3.7Dataorganisationinaproject section 3.7].
    6060   *  Previously opened fields are memorised in the menu and can be  directly selected again.
    6161
     
    8484After selection by the browser, the path and file names are determined. The path is split into the two first edit boxes '''[!RootPath]''' and '''[!SubDir],''' while the file name is split into a root name '''[!RootFile]''', file index string '''[!FileIndex]''', and file extension '''[!FileExt]'''. The input file name can be directly entered and modified in these edit boxes, without the browser.
    8585
    86 Once a root name has been introduced, navigation among  the file indices is provided by the red push buttons '''[runplus]''' ( '''[+>]''')  and   '''[runmin] ''' ('''[<-]'''). The central push button '''[run0]''' ('''[0]''') refreshes the current plot. See [wiki:#a3.4Navigationamongfileindices: section 3.4] for more details.
    87 
    88 When available, the time of each frame or field is displayed in the edit box '''[TimeValue]''', at the very right. In the case of image pairs, the time interval Dt is displayed between the edit boxes '''[i1], [j1]''' and '''[i2], [j2]'''. This timing information can be read directly in the input file, in the case of movies or Netcdf files, or can be defined in an image documentation file, see [wiki:#a3.5Imagedocumentationfiles.xml: section 3.5] (in case of conflict, the latter prevails).
     86Once a root name has been introduced, navigation among  the file indices is provided by the red push buttons '''[runplus]''' ( '''[+>]''')  and   '''[runmin] ''' ('''[<-]'''). The central push button '''[run0]''' ('''[0]''') refreshes the current plot. See [#a3.4Navigationamongfileindices: section 3.4] for more details.
     87
     88When available, the time of each frame or field is displayed in the edit box '''[TimeValue]''', at the very right. In the case of image pairs, the time interval Dt is displayed between the edit boxes '''[i1], [j1]''' and '''[i2], [j2]'''. This timing information can be read directly in the input file, in the case of movies or Netcdf files, or can be defined in an image documentation file, see [#a3.5Imagedocumentationfiles.xml: section 3.5] (in case of conflict, the latter prevails).
    8989
    9090'''Note: ''' the five last input file names, as well as other pieces of personal information, are stored for convenience in a file (''uvmat_perso.mat'') automatically created in the user preference directory of Matlab (indicated by the Matlab command '>>prefdir'. Browsers then  read default input in this file. A corruption of this file ''uvmat_perso.mat'' may lead to problems for  opening uvmat, type '>>reinit' on the Matlab prompt to delete it and reinitialise the configuration of uvmat.
     
    108108uvmat can read any image format recognised by the Matlab image reading function ''imread.m''. Images can be in true color or B&W, with 8 bit or 16 bit grey levels. Image files containing multiple frames are handled. Movie files can be also opened, using the Matlab function ''!VideoReader.m'', or ''mmreader.m'' for older versions of Matlab.
    109109
    110 Velocity fields and all results of data processing are stored in the Netcdf format, see [wiki:#a7Netcdffilesandget_field.fig: section 7-] for details. They are read by the function ''nc2struct.m''. Then different quantities (vorticity, divergence...) can be obtained.
     110Velocity fields and all results of data processing are stored in the Netcdf format, see [#a7Netcdffilesandget_field.fig: section 7-] for details. They are read by the function ''nc2struct.m''. Then different quantities (vorticity, divergence...) can be obtained.
    111111
    112112The PIV software CIVx requires B&W images in the format png (portable network graphics). It is a binary format for images with lossless (reversible) compression, recommended by w3c (http://www.w3.org/Graphics/PNG). It is an open source patent-free replacement of GIF and can also replace many common uses of TIFF. It can be read directly by all standard programs of image visualisation and processing.  Compressing a raw binary image to its png form typically saves disk storage by a factor of 3.
     
    156156Information on image series is provided by a documentation file in the format xml. This file can include sections about image timing, geometric calibration, camera type and illumination. An xml file is a text file in which each element of information, or group of elements, is labelled by a tag. The list of tags and their hierarchical organisation is specified by a schema file (.xsd). The schema used for image documentation is ''ImaDoc.xsd'', available in the uvmat package at the path indicated in {PARAM.xml}). For a general introduction to the xml language, see http://www.w3schools.com/xml.
    157157
    158 When a new file series is opened in uvmat, a documentation file is automatically sought, whose path and name are displayed by ''!RootPath'' and  ''!RootFile'' respectively, with extension {.xml} (''!RootPath'' and ''!RootFile'' are the contents of the edit boxes '''[!RootPath]''' and ''' [!RootFile]''').  The detection of this file is indicated by the visibility of the pushbutton '''[view_xml]''' on the upper right of the GUI '''uvmat.fig'''. Press this button to see the content through an xml editor '''editxml.fig''' (described in [wiki:#a10-Processingfieldseries: section 10]). The xml file can be also opened directly by the uvmat browser, or by any text editor.
     158When a new file series is opened in uvmat, a documentation file is automatically sought, whose path and name are displayed by ''!RootPath'' and  ''!RootFile'' respectively, with extension {.xml} (''!RootPath'' and ''!RootFile'' are the contents of the edit boxes '''[!RootPath]''' and ''' [!RootFile]''').  The detection of this file is indicated by the visibility of the pushbutton '''[view_xml]''' on the upper right of the GUI '''uvmat.fig'''. Press this button to see the content through an xml editor '''editxml.fig''' (described in [#a10-Processingfieldseries: section 10]). The xml file can be also opened directly by the uvmat browser, or by any text editor.
    159159
    160160The xml file <!ImaDoc> can contain the following sections:
     
    162162 * <Heading>: contains elements <Campaign>, <Experiment>, <!DataSeries>, which recall the position of the file in the tree structure of data files. This allows the user  to check that the document file has not been displaced.
    163163 * <Camera> contains information on the camera settings, as well as the timing of all the images in a subsection <!BurstTiming>. <!TranslationMotor> and <Oscillator> contains information on the mechanical devices used to produce the laser sheet and scan volumes.
    164  * <!GeometryCalib> contains the parameters of the geometric calibration relating the pixel position to the real space coordinates (see [wiki:#a8-Geometriccalibration: section 8]]). In the case of volume scanning, it also describes the set of laser plane positions and angles.
     164 * <!GeometryCalib> contains the parameters of the geometric calibration relating the pixel position to the real space coordinates (see [#a8-Geometriccalibration: section 8]]). In the case of volume scanning, it also describes the set of laser plane positions and angles.
    165165 * <Illumination> describes the illumination system used, including the position of the laser source.
    166166 * <Tracor> describes the properties of the flow tracor (particle, dye...)
     
    173173   * 20 < Intensity < 200:('gray mask') the vector in this place will be absent 
    174174   * Intensity>200  the vector will be computed
    175  The mask corresponding to an image or velocity field can be displayed in '''uvmat.fig''' by selecting the check box '''[view_mask]([CheckMask])''' on the upper left. Images with appropriate name can be automatically recognised by '''uvmat.fig''' and civ functions, see [wiki:#a9-Masksandgrids: section 9.1]. Otherwise file selection by a browser is proposed when '''[view_mask]''' is selected.
     175 The mask corresponding to an image or velocity field can be displayed in '''uvmat.fig''' by selecting the check box '''[view_mask]([CheckMask])''' on the upper left. Images with appropriate name can be automatically recognised by '''uvmat.fig''' and civ functions, see [#a9-Masksandgrids: section 9.1]. Otherwise file selection by a browser is proposed when '''[view_mask]''' is selected.
    176176
    177177 * ''' 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
     
    179179n X1 Y1 X2 Y2  ......  Xn Yn
    180180}}}
    181 The coordinates correspond to the center of the correlation box on the first image of the pair (the actual vector position will be shifted by half the displacement found between the two images). A tool to create grids is described in [wiki:#a9-Masksandgrids: section 9.2].
     181The coordinates correspond to the center of the correlation box on the first image of the pair (the actual vector position will be shifted by half the displacement found between the two images). A tool to create grids is described in [#a9-Masksandgrids: section 9.2].
    182182
    183183 * '''.fig''' Matlab figures represent plots but also Graphic User Interfaces (GUI). In that case Matlab functions (callbacks) are attached to the graphic objects in the figure and can be activated by the mouse. Matlab figures can be directly opened by the browser of '''uvmat.fig'''.
     
    234234Scalar fields are  represented like greyscale images, by default with a false color map ranging from blue (minimum values) to red (maximum), or as gray scale images by selecting the check box '''[CheckBW]'''. Other color maps can be used by extracting the figure with the menu bar button '''[Export/extract figure]''', then using the standard  Matlab button '''[!Edit/Colormap]''' in the figure menu bar.
    235235
    236 Scalar are represented by matrices with real ('double') values, unlike images which are integers. They can be alternatively defined with unstructured grid (see [wiki:#a5.1Gridingofdata section 5.1]): they are then linearly interpolated on a regular grid before visualisation (a fairly slow process).
     236Scalar are represented by matrices with real ('double') values, unlike images which are integers. They can be alternatively defined with unstructured grid (see [#a5.1Gridingofdata section 5.1]): they are then linearly interpolated on a regular grid before visualisation (a fairly slow process).
    237237
    238238Scalars (or image intensity) can be also represented with contour plots, by switching the popup menu '''[Contours] ''' from the setting 'image' to the setting 'contours'. Contours for positive scalar values are in sold line while contours for negative values are dashed. The interval between contours can be set by the edit box '''[num_IncrA]'''.
     
    293293
    294294=== 5.1 Griding of data: ===
    295 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  [wiki:#a6-Projectionobjects: next section).  The three possibilities of griding are defined as follows:
     295Physical fields can be defined either on regular grids, either scattered on an unstructured set of positions. Some measurements techniques, like PIV or particle tracking, provided unstructured data, while most methods of analysis require data  on a regular grid. This can be done by interpolation, defining a projection on a plane (with ProjMode='interp', see  [#a6-Projectionobjects: next section]).  The three possibilities of griding are defined as follows:
    296296
    297297-'''Regular grid:'''
     
    301301-'''Structured orthogonal grid''':
    302302
    303 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 [wiki:#a7.1TheNetCDFformat: section 7.1]).
     303Each 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]).
    304304
    305305-'''Unstructured coordinates:'''
     
    320320Data are kept in memory in the GUI uvmat as a Matlab structure, stored as ''!UserData'' in the GUI figure. This structure can be extracted by the menu bar command '''[Export/field in work space]''', then typing the Matlab command '>>Data_uvmat'. It contains the current input field as a substructure ''Data_uvmat.Field''.
    321321
    322 This field has a specific organisation, mirroring the structure of netcdf files (see [wiki:#a7-Netcdffilesandget_field.fig: section 7]). The field is described by a set of (single or multidimensional) data arrays, called the ''variables''. The ''dimensions'' of these arrays have names, in order to identify correspondance between different arrays. For instance the arrays representing the velocity components U and V must have the same dimensions. A dimension has a specific value, which sets the common size of all arrays sharing this dimension. Field description furthermore involves optional ''attributes'' to document the field data, for instance to specify the role of variables or to provide units. These attributes can be global, or can be attached to a specific variable.
     322This field has a specific organisation, mirroring the structure of netcdf files (see [#a7-Netcdffilesandget_field.fig: section 7]). The field is described by a set of (single or multidimensional) data arrays, called the ''variables''. The ''dimensions'' of these arrays have names, in order to identify correspondance between different arrays. For instance the arrays representing the velocity components U and V must have the same dimensions. A dimension has a specific value, which sets the common size of all arrays sharing this dimension. Field description furthermore involves optional ''attributes'' to document the field data, for instance to specify the role of variables or to provide units. These attributes can be global, or can be attached to a specific variable.
    323323
    324324In summary, the ''field structure'' is specified by the following elements: 
     
    345345 * 'Conventions':
    346346   * ='uvmat': indicate that the conventions described here are followed
    347    * ='uvmat/civdata': indicate that the variables are named according to [wiki:#civdata]. 
     347   * ='uvmat/civdata': indicate that the variables are named according to [#civdata]. 
    348348 * '!CoordMesh': typical mesh for coordinates, used to define default projection grids and mouse selection action. Calculated automatically from the data if not specified.
    349349 * '!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).
     
    614614The 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.
    615615
    616 The processing function is chosen in the menu '''[ActionName]'''.  All actions operate on the same series of input files, whose list can be obtained with the first option 'check_data_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. The option civ_series gives acees to the PIV processsing, see section [wiki:#a11-PIV:ParticleImagingVelocimetry: section 11]. Finally any additional function can be called and included in the menu by selecting the option 'more...' . The corresponding path is displayed in '''ActionPath'''.
     616The processing function is chosen in the menu '''[ActionName]'''.  All actions operate on the same series of input files, whose list can be obtained with the first option 'check_data_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. The option civ_series gives acees to the PIV processsing, see section [#a11-PIV:ParticleImagingVelocimetry: section 11]. Finally any additional function can be called and included in the menu by selecting the option 'more...' . The corresponding path is displayed in '''ActionPath'''.
    617617
    618618Each function in series can be run in local mode, i;e. on the current Matlab session, or as background, by selecting the corresponding option in '''!RunMode'''. In background mode, calculation is done a new Matlab session (without graphics) so that the current Matlab session is free for new operations. If a cluster system has been detected, a third option 'cluster' appears in the menu, allowing to dispatch parallel computations on a computer cluster. For the latter option, a compiled version of the Action function is useful, to avoid installing Matlab on each node of the cluster. This is achieved by selecting the option .sh in the menu '''ActionExt'''. If the compiled version is not yet available, or outdated, the GUI proposes a new compilation of the selected function.