Changes between Version 10 and Version 11 of UvmatHelp


Ignore:
Timestamp:
Jun 1, 2013, 3:47:09 PM (7 years ago)
Author:
sommeria
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UvmatHelp

    v10 v11  
    22== 1 Generalities ==
    33=== 1.1 Aim ===
    4   The package uvmat can be used with a wide variety of input data: all image and movie formats recognised by Matlab (see [section 3.1->#sec3.1]),  NetCDF binary files [#get_field get_field](see [#a3 section 3]). It is however particularly designed for laboratory data obtained  from imaging systems: it includes a GUI to run the Particle Image Velocimetry  software [CIVx ->3], as well as tools for geometric calibration, masks, grid generation and image pre-processing (e.g. background removal), and editing xml documentation files. Stereoscopic PIV, PIV-LIF and 3D PIV in a volume (still under development) are handled.
     4  The package uvmat can be used with a wide variety of input data: all image and movie formats recognised by Matlab (see [#a1.3Documentationandhelp section 3.1]),  NetCDF binary files [#get_field get_field](see [#a3 section 3]). It is however particularly designed for laboratory data obtained  from imaging systems: it includes a GUI to run the Particle Image Velocimetry  software [CIVx ->3], as well as tools for geometric calibration, masks, grid generation and image pre-processing (e.g. background removal), and editing xml documentation files. Stereoscopic PIV, PIV-LIF and 3D PIV in a volume (still under development) are handled.
    55
    66  This package can be used without knowledge of the Matlab language, but it is designed to be complemented by user defined Matlab functions, providing flexibility for further data analysis. It provides convenient tools to develop a set of processing functions with a standardised system for input-output.
     
    3232  UVMAT is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See theGNU General Public License (file {COPYING.txt}) for more details.
    3333
    34 [<doc115|right>->#top]
    35 
    36 ----
    37 [2-The GUI uvmat.fig<-]
    38 
    3934== 2 Overview of the GUI uvmat.fig ==
     35
    4036=== 2.1 Opening the GUI ===
    4137  Type '>>uvmat' in the Matlab prompt to display the GUI. If the function is unknown by Matlab, add the appropriate path (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 availlable,  the latest version number of the uvmat package is indicated (if  line-command version of svn is available).
     
    9288[<doc115|right>->#top]
    9389
    94 ----
    95 [3-Input files and navigation with uvmat<-]
    96 
    9790== 3 Input files and navigation with uvmat ==
    98 [sec3.1<-]
    9991
    10092=== 3.1  Input data formats ===
     
    129121-'''Nomenclature types:''' These different indexing systems are implemented by a  functions {fullfile_uvmat.m}. The inputs are the root name, four indices i1,i2,j1,j2 and a character string representing 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}. Once the nomenclature type has been detected by the browser of '''uvmat.fig''', it is displayed in the edit box '''[NomType]''' of u'''vmat.fig'''. This nomenclature type is defined as the index string for the first file in the series, for instance '_1' for a single indexing and '1_1-2' for a double indexing. For a field series in a single file, like a movie, the nomenclature type is '*'. For a set of indexed movies (or multimage files), the index i labels the files while the index j labels the frames within a file.
    130122
    131 [sec3.4<-]
    132 
    133123=== 3.4 Navigation among file indices: ===
    134124  The field indices can be incremented or decremented by the push buttons  '''[runplus] ''' ( ''''<code>+></code>'''') and  '''[runmin]''' (''''<code> <-</code>'''') respectively.  This scanning is performed  over the first index (i) or the second one (j), depending on the selection of the check boxes '''[scan_i] ''' or '''[scan_j] ''' respectively. The step for increment is set by the edit box '''[increment_scan]'''.
     
    148138-'''Keyboard short cuts:''' the activation of the push buttons  '''[runplus]''' and  '''[runmin]''' can be performed by typing the key board letters 'p' and 'm' respectively, after the uvmat figure has been selected by the mouse. Similarly the command of the push button '''[run0]''' can be performed by typing the 'return carriage' key.
    149139
    150 [sec3.5<-]
    151 
    152140=== 3.5  Image documentation files (.xml): ===
    153141Information 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->http://www.w3schools.com/xml].
     
    168156-'''.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 briowser of '''uvmat.fig'''.
    169157
    170 [sec3.6_civ<-] -''''.civ' '''  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} (instead of {root.xml}). It is automatically sought by '''uvmat.fig''' and '''civ.fig''', in the absence of an xml file ImaDoc. (it is read by the function {read_imatext.m}). -*Example : %... gives comments (not included in the file). This 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 correspopnding ;cvi file is named aa.civ.  <cadre> 19                                         % number of bursts 1024 1024                             % image size npx npy 4                                      % number of images per burst 2                                      % not used 0.016667                          % time of exposure (in seconds) 5.860000 5.860000           % scaling pixel/cm x and y directions 5.860000 5.860000           % same 0                                      % not used 1 0.000000 30 60 30 1 2 25.001003 30 60 30 1 ......................... 18 424.999847 30 60 30 1 19 450.000824 30 60 30 1 % for each line: burst number; time elapsed in second from the beginning; number of frames between image a and image b; number of frames between image b and image c; number of frames between image c and image d; image acquisition duration in frames. </cadre>
     158-''''.civ' '''  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} (instead of {root.xml}). It is automatically sought by '''uvmat.fig''' and '''civ.fig''', in the absence of an xml file ImaDoc. (it is read by the function {read_imatext.m}). -*Example : %... gives comments (not included in the file). This 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 correspopnding ;cvi file is named aa.civ.  <cadre> 19                                         % number of bursts 1024 1024                             % image size npx npy 4                                      % number of images per burst 2                                      % not used 0.016667                          % time of exposure (in seconds) 5.860000 5.860000           % scaling pixel/cm x and y directions 5.860000 5.860000           % same 0                                      % not used 1 0.000000 30 60 30 1 2 25.001003 30 60 30 1 ......................... 18 424.999847 30 60 30 1 19 450.000824 30 60 30 1 % for each line: burst number; time elapsed in second from the beginning; number of frames between image a and image b; number of frames between image b and image c; number of frames between image c and image d; image acquisition duration in frames. </cadre>
    171159
    172160-'''.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.
    173161
    174162-'''.log''' ascii text files, containing information about the CIV or PATCH processing. 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'''.
    175 
    176 [sec3.7<-]
    177163
    178164=== 3.7 Data organisation in a  project: ===
     
    185171[<doc115|right>->#top]
    186172
    187 ----
    188173== 4 Field display: ===
    189174
     
    207192Scalars (or image intensity) can be also represented with contour plots, by switching the popup menu '''[Contours] ''' from the setting 'mage' 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 '''[IncrA]'''.
    208193
    209 [sec4.2<-]
    210194
    211195=== 4.2 Vectors: ===
     
    242226The second field can be removed by unselecting the check box '''[SubField] ''' on the very right.
    243227
    244 [sec4.5<-]
    245 
    246228=== 4.5 Field transforms: ===
    247229A transform can be systematically applied after reading the input field, for instance the transform 'phys' which takes into account geometric calibration. This transform can possibly combine two input fields, for instance to substract a background from an image. The processing function is chosen  by the popup menu '''[transform_fct]''' on the left, and its path is displayed in the box '''[path_transform]'''. Select the option 'more...' to browse new functions. The same functions can be called in data processsing using the GUI '''series.fig'''. A few functions are provided in the folder /transform_fct, see list in  [annex->#overview].
     
    252234The following succession of operations is performed by '''uvmat.fig''': -'''File Reading:''' the input field is first read from the input file by the Matlab functions {imread.m}, {mmreader.m}, or {aviread.m} for images,  or the uvmat functions {nc2struct.m} or {read_civxdata.m} for netcdf files. -'''Second file reading:'''  The second input field is similarly read if selected. Note that it is kept in memory, so it is not read again if the file is unchanged (this is useful in the case of substraction of a fixed background for instance).  -'''Transform:''' by default the 'phys' option transforms each of the input fields from pixel to physical coordinates. This operation can also combine two input fields. -'''Histogram:''' This is obtained from the input field in transformed coordinates, or if applicable from the fields resulting from the two input fields. -'''Projection:''' on  the projection object selected in the menu '''[list_object_1]''', see [section 7->#get_field]. A second projection, on the object selected by '''[list_object_1]''', can be plotted in the anciillary figure '''view_field.fig'''. Function used: {proj_field.m}. -'''Field calculation:''' a scalar can be calculated from each of the input fields, as selected by the menu '''[Fields]'''. This is performed by the function {calc_field.m}. -'''Field comparison''': when two fields of the same nature are introduced, the difference is taken by the function {sub_field.m.}. This is skipped if the transform function has already led to a single field.  -'''Plotting:''' plot the results of projection. Function used: {plot_field.m}
    253235
    254 [<doc115|right>->#top]
    255 
    256 ----
    257 [field_structures<-] '''{5- Field objects:==='''
     236
     237== 5- Field objects: ==
    258238
    259239[sec5.1<-]
     
    323303[<doc115|right>->#top]
    324304
    325 ----
    326 [set_object<-] '''{6- Projection objects:==='''
     305== 6- Projection objects: ==
    327306
    328307=== 6.1 Definition and editing with the uvmat interface: ===
     
    386365-''' {Projection on volumes:**}  ''' This is used to delimitate a volume for 3D representation
    387366
    388 [sec6.5<-]
    389 
    390367=== 6.5 Object representation: ===
    391368Projections objects are drawn in magenta color when they are selected for creation or edition, and in blue otherwise.
     
    401378[<doc115|right>->#top]
    402379
    403 ----
    404 [get_field<-] '''{7- Netcdf files and get_field.fig:=== [netcdf<-]'''
     380== 7- Netcdf files and get_field.fig: ==
    405381
    406382=== 7.1 The NetCDF format: ===
     
    446422  In the case of a 3D input field, the fig is set to uvmat. A middle plane of cut is automatically selected. This can be moved then with the slider on the interface set_object (see section 5). The default cuts are made at constant z coordiante, but any of the three initial coordiantes can be used as z coordinate, using the menu coord_z.
    447423
    448 ----
    449 [geometry_calib<-] '''{8- Geometric calibration:==='''
     424== 8- Geometric calibration: ==
    450425
    451426=== 8.1 Generalities: ===
     
    501476[<doc115|right>->#top]
    502477
    503 ----
    504 '''{9- Masks and grids:=== [sec9.1<-]'''
     478
     479== 9- Masks and grids: ==
    505480
    506481=== 9.1 Masks: ===
     
    522497The grid will be limited to an  image , or to the common region of two images, depending whether one or two image names are indicated in the edit boxes image_1 and image_2. Press save to save the corresponding grid file (s). A dialog box appears to edit the name of the output grid file, and a second one in case of two images.
    523498
    524 [<doc115|right>->#top]
    525 
    526 ----
    527 [series<-] '''{10- Processing field series:==='''
     499
     500== 10- Processing field series: ==
    528501
    529502=== 10.1 The GUI series.fig: ===
     
    575548By selecting the press button 'peaklocking' on the 'plotgraph' interface, you smooth the current velocity histograms while preserving its integral over each unity (in pixels). This appears in red. Then an estimate of the peaklocking error is obtained by comparing the initial histogram to the smooth one.
    576549
    577 [<doc115|right>->#top]
    578 
    579 ----
    580 [civ<-] '''{11- PIV: Particle Imaging Velocimetry==='''
     550== 11- PIV: Particle Imaging Velocimetry ==
    581551
    582552{===11.1 Overview:===}