Changes between Version 147 and Version 148 of UvmatHelp


Ignore:
Timestamp:
Jan 14, 2015, 2:40:04 PM (6 years ago)
Author:
sommeria
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UvmatHelp

    v147 v148  
    4040
    4141----
    42 == 2 - Overview of the GUI uvmat.fig ==
     42== 2 - Overview of the GUI uvmat ==
    4343=== 2.1 Opening the GUI ===
    44 Type '>>uvmat' in the Matlab prompt to display the GUI. If the function is unknown by Matlab, add the appropriate path to the folder '''UVMAT''' where the toolbox has been installed (see the Matlab command '>>help path'). When the GUI is opening, the date of last modfication is displayed in the central window. During opening, the program checks the Matlab path to all the functions of the package (using the function ''check_functions.m''). If a function is missing, or if it is overridden by a function with the same name at another path location, a message is  displayed in the central window at the opening of the  GUI '''uvmat.fig'''. Finally, if the svn server is accessible by line-command, the latest version number of the UVMAT package is indicated.
     44Type '>>uvmat' in the Matlab prompt to display the GUI. If the function is unknown by Matlab, add the appropriate path to the folder '''UVMAT''' where the toolbox has been installed (see the Matlab command '>>help path'). When the GUI is opening, the date of last modfication is displayed in the central window. During opening, the program checks the Matlab path to all the functions of the package (using the function ''check_functions.m''). If a function is missing, or if it is overridden by a function with the same name at another path location, a message is  displayed in the central window at the opening of the  GUI '''uvmat'''. Finally, if the svn server is accessible by line-command, the latest version number of the UVMAT package is indicated.
    4545
    4646The GUI contains an upper menu bar, a central graphic display window, a lower left window for histogram, a top right text display window, columns of edit boxes and command buttons on both side.
     
    7474
    7575 * '''[Run] ''':
    76    * '''[field series]''': gives access to the GUI [#a10-Processingfieldseries "''series.fig''"] for processing field series.
    77    * ''' [PIV'''] : gives access to the PIV program under Matlab (using the GUI '''series.fig''').
    78    * '''[CivX(Fortran)]''':  gives access to the GUI [#a11-PIV:ParticleImagingVelocimetry "''civ.fig''"] for Particle Imaging Velocimetry (CivX version in Fortran).
     76   * '''[field series]''': gives access to the GUI [#a10-Processingfieldseries "''series''"] for processing field series.
     77   * ''' [PIV'''] : gives access to the PIV program under Matlab (using the GUI '''series''').
     78   * '''[CivX(Fortran)]''':  gives access to the GUI [#a11-PIV:ParticleImagingVelocimetry "''civ''"] for Particle Imaging Velocimetry (CivX version in Fortran).
    7979
    8080 * '''[Help] ''': displays this help file using the Matlab browser.
     
    109109uvmat 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.
    110110
    111 ''UVMAT'' can also read various kinds of data in the binary format NetCDF, as described in [#a7Netcdffilesandget_field.fig section 7]. Velocity fields obtained by PIV and results of data processing are stored in this format. Derived quantities (vorticity, divergence...) can be directly obtained. The input file type is recognized by the function ''get_file_type.m'' of UVMAT and the file is opened by the function ''read_field.m'' according to this file type. It is possible to include new input file types by a modification of these two functions.
     111''UVMAT'' can also read various kinds of data in the binary format NetCDF, as described in [#a7Netcdffilesandget_field section 7]. Velocity fields obtained by PIV and results of data processing are stored in this format. Derived quantities (vorticity, divergence...) can be directly obtained. The input file type is recognized by the function ''get_file_type.m'' of UVMAT and the file is opened by the function ''read_field.m'' according to this file type. It is possible to include new input file types by a modification of these two functions.
    112112
    113113The PIV software provided in UVMAT can deal with any image or movie format recognised by Matlab, while the older fortran version 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.
     
    124124The choice can be imposed by selecting a check box, or can be left automatic. The second iteration (civ2, filter2), presumed to be of higher quality,  is prefered by default. The filter fields are interpolated on a regular grid, with or without smoothing respectively. It allows to fill holes and get spatial derivatives. If a scalar depending on spatial derivatives, like vort, is selected, the field option switches automatically from civ  to filter.
    125125
    126 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.
     126The 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'''. This is the only available option when the input file is not from CIV.
    127127
    128128=== 3.3 File naming and indexing ===
     
    135135-'''Pair  indexing:''' new file series can result from the processing of primary series. For a sequential processing limited to a single file, the output index naturally reproduces  the input index. Other processing functions involve pairs of input files, for instance Particle Imaging Velocity from image pairs. In a simple series, the result from the two primary fields *_i1 and *_i2 is then labeled as *_i1-i2 with the file extension indicating  the output format. More generally,  the result from any processing involving a range of primary indices from  i1 to i2  is  labeled as _i1-i2.  If i1=i2 or j1=j2, the two indices are merged in a single label i, or j respectively.
    136136
    137 -'''Nomenclature types:''' The ''nomenclature type'' is defined as the character string representing the index (or indices) for the first file  in the series, for instance '_1' for a ''single indexing'' and '_1-2' for a  ''pair indexing'', '_1_1' for a ''double index'' series. The second index j can be also represented as a letter suffix, for instance '01a'.  For a field series in a single file, like a movie, the  nomenclature type is defined as '*'. The functions ''fullfile_uvmat.m'' generates a file name from a root name, four numerical indices i1,i2,j1,j2 and  the ''nomenclature type''. The reverse operation, splitting a name into a root and indices while detecting the ''nomenclature type'', is performed by the function ''fileparts_uvmat.m''. The function ''find_file_series.m'' is also needed to scan the whole file series, leading to a possible adjustement of the nomenclature type (for instance distinguishing '_001' from '_1' when the file with index 1000 has been opened). Once the nomenclature type has been detected by the browser of '''uvmat.fig''', it is displayed in the edit box '''[!NomType]''' and used to generate all the file names when the series is scanned.
     137-'''Nomenclature types:''' The ''nomenclature type'' is defined as the character string representing the index (or indices) for the first file  in the series, for instance '_1' for a ''single indexing'' and '_1-2' for a  ''pair indexing'', '_1_1' for a ''double index'' series. The second index j can be also represented as a letter suffix, for instance '01a'.  For a field series in a single file, like a movie, the  nomenclature type is defined as '*'. The functions ''fullfile_uvmat.m'' generates a file name from a root name, four numerical indices i1,i2,j1,j2 and  the ''nomenclature type''. The reverse operation, splitting a name into a root and indices while detecting the ''nomenclature type'', is performed by the function ''fileparts_uvmat.m''. The function ''find_file_series.m'' is also needed to scan the whole file series, leading to a possible adjustement of the nomenclature type (for instance distinguishing '_001' from '_1' when the file with index 1000 has been opened). Once the nomenclature type has been detected by the browser of the GUI '''uvmat''', it is displayed in the edit box '''[!NomType]''' and used to generate all the file names when the series is scanned.
    138138
    139139=== 3.4 Navigation among field indices ===
     
    157157Image series in UVMAT are documented by a file providing image timing, geometric calibration, camera type and illumination. This file is in the format ''XML'', a hierarchically organised text file. The content is labelled by tags, represented by brackets <.>, whose names and organisation are specified by a schema file (.xsd). A general introduction to the XML language and schemas is provided for instance in http://www.w3schools.com/xml. The schema used for image documentation is ''!ImaDoc.xsd'', available in the UVMAT package in a sub-directory ''/Schemas''. Simple templates of XML files are also provided there.
    158158
    159 When a new file series is opened in UVMAT, the XML documentation file is automatically sought (by the function ''find_imadoc.m'') in the folder containing the data series folder: the documentation of the file series !RootPath/SubDir/RootFile,... is sought in the file !RootPath/RootFile.xml. As a second choice (corresponding to an earlier convention), the XML file will be sought inside the data series folder, as !RootPath/SubDir/RootFile.xml (if this file does not exist, a text file with the same root name but extension .civ is sought as an obsolete option). The detection of the image documentation 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. In UVMAT, it is read by the function ''imadoc2struct.m''.
     159When a new file series is opened in UVMAT, the XML documentation file is automatically sought (by the function ''find_imadoc.m'') in the folder containing the data series folder: the documentation of the file series !RootPath/SubDir/RootFile,... is sought in the file !RootPath/RootFile.xml. As a second choice (corresponding to an earlier convention), the XML file will be sought inside the data series folder, as !RootPath/SubDir/RootFile.xml (if this file does not exist, a text file with the same root name but extension .civ is sought as an obsolete option). The detection of the image documentation file is indicated by the visibility of the pushbutton '''[view_xml]''' on the upper right of the GUI '''uvmat'''. Press this button to see the content through an XML editor '''editxml''' (described in [#a10-Processingfieldseries section 10]). The XML file can be also opened directly by the UVMAT browser, or by any text editor. In UVMAT, it is read by the function ''imadoc2struct.m''.
    160160
    161161The XML file <!ImaDoc> can contain the following sections, as prescribed by the schema file ''!ImaDoc.xsd''.:
     
    172172   * Intensity < 20: ('black mask') the vector in this place will be set to zero.
    173173   * 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 '''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.
     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.
    175175
    176176 * ''' 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
     
    181181The 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
    183  * '''.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'''.
    184 
    185  * '''.civ ''' (obsolete)  ASCII text file containing the list of image times and the scaling in pixels/cm. This is an obsolete version of the XML image documentation file. It is stored in the same directory as the corresponding series of images, with name ''root .civ''. It is automatically sought by '''uvmat.fig''' and '''series.fig''', in the absence of an xml file <!ImaDoc> (it is read by the function ''read_imatext.m''). The following example is from an experience with 19 bursts of 4 images, named aa001a,aa001b,aa001c,aa001d,aa002a,aa002b,...,aa019c,aa019d, with an extension .png. The corresponding .civ file is named aa.civ. Comments (not included in the file) are indicated with %...
     183 * '''.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 the GUI '''uvmat'''.
     184
     185 * '''.civ ''' (obsolete)  ASCII text file containing the list of image times and the scaling in pixels/cm. This is an obsolete version of the XML image documentation file. It is stored in the same directory as the corresponding series of images, with name ''root .civ''. It is automatically sought by '''uvmat''' and '''series''', in the absence of an xml file <!ImaDoc> (it is read by the function ''read_imatext.m''). The following example is from an experience with 19 bursts of 4 images, named aa001a,aa001b,aa001c,aa001d,aa002a,aa002b,...,aa019c,aa019d, with an extension .png. The corresponding .civ file is named aa.civ. Comments (not included in the file) are indicated with %...
    186186{{{
    18718719                              % number of bursts
     
    200200}}}
    201201
    202  * '''.cmx''' ASCII text files containing the parameters sent by the GUI '''civ.fig''' to the CIV fortran programmes. Each velocity field named *.nc results from a parameter file *.cmx. It can be opened by the browser of '''uvmat.fig'''. In a later version of CIVx**, the .cmx file is replaced by a .xml ’!CivDoc’ file.
    203 
    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 '''uvmat.fig'''.
     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.
     203
     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'''.
    205205
    206206=== 3.7 Data organisation in a  project ===
     
    214214'''Mirror data trees''' can be created to process a source data set in 'read only' mode, to preserve the safety of the data source, and to allow several users to work in parallel without interference.
    215215
    216 The data organisation can be controlled and managed by the GUI '''browse_data.fig'''. This is called by the menu bar option '''[Open/browse campaign]''' in UVMAT: with this browser select the path of the folder considered as 'Campaign' (instead of the data file itself). Then the GUI '''browse_data.fig''' appears with a list of 'Experiments' and a list of '!DataSeries'. Select your choice to open the corresponding file series in '''uvmat.fig'''. The selected campaign path is then recorded for future opening under '''[Open/browse campaign]''' in the menu bar of '''uvmat.fig'''.
    217 
    218 Instead of directly opening a file series with '''browse_data.fig''', you can create a 'mirror data tree' by pressing 'create_mirror', then selecting the path chosen for the new mirror folder 'Campaign'.  Inside this mirror folder, a set of folders is then created for each experiment. Furthermore, an XML file 'mirror.xml' is created to recall the source directory (under the label <!SourceDir>). Inside each mirror folder 'Experiment', the source is reproduced as symbolic  links. Data processing in the mirror campaign then produces 'real' !DataSeries folders.
    219 
    220 Once created, this mirror campaign folder can be opened instead of the source.  It can be regularly updated from the source folder by pressing the button 'update_mirror' in '''browse_data.fig'''.
     216The data organisation can be controlled and managed by the GUI '''browse_data'''. This is called by the menu bar option '''[Open/browse campaign]''' in UVMAT: with this browser select the path of the folder considered as 'Campaign' (instead of the data file itself). Then the GUI '''browse_data''' appears with a list of 'Experiments' and a list of '!DataSeries'. Select your choice to open the corresponding file series in '''uvmat'''. The selected campaign path is then recorded for future opening under '''[Open/browse campaign]''' in the menu bar of the '''uvmat'''.
     217
     218Instead of directly opening a file series with '''browse_data''', you can create a 'mirror data tree' by pressing 'create_mirror', then selecting the path chosen for the new mirror folder 'Campaign'.  Inside this mirror folder, a set of folders is then created for each experiment. Furthermore, an XML file 'mirror.xml' is created to recall the source directory (under the label <!SourceDir>). Inside each mirror folder 'Experiment', the source is reproduced as symbolic  links. Data processing in the mirror campaign then produces 'real' !DataSeries folders.
     219
     220Once created, this mirror campaign folder can be opened instead of the source.  It can be regularly updated from the source folder by pressing the button 'update_mirror' in '''browse_data'''.
    221221
    222222----