Changes between Version 33 and Version 34 of UvmatHelp


Ignore:
Timestamp:
Jun 2, 2013, 8:52:32 PM (7 years ago)
Author:
sommeria
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UvmatHelp

    v33 v34  
    9797 * '''Graph limits:''' they automatically adjust to the field when the check box '''[!CheckFixLimits]''' is not selected (default). Otherwise they remain fixed, and can be adjusted by the check boxes '''[num_MinX]''', '''[num_MaxX]''', '''[num_MinY]''', '''[num_MaxY]'''.
    9898
    99  * '''Coordinate aspect ratio:''' when '''[!CheckFixAspectRatio]''' is selected (the default option for images), the scale ratio for the  x and y coordinates is fixed to 1 by default (it can be manually adjusted by the edit box '''[num_AspectRatio]'''. When '''[CheckFixAspectRatio]''' is not selected the graph scales along x and y automatically adjust to the figure size.
    100 
    101  * '''Extracting graphs:'''   The graph displayed in the central window can be copied to a separate figure by pressing the menu bar command '''[Export/extract figure]'''. This allows plot editing, exporting in image format and printing, using standard Matlab graphic tools. Plots can be also exported on an existing figure for data comparison, using the option '''[Export/export on axis]'''. A movie can be produced using the command [Export/make movie avi].
    102 
    103  * '''Extracting data''' as Matlab arrays. Information stored in the GUI uvmat  (as 'UserData' in the figure) can be extracted in the Matlab work space by the menu bar command  '''[Export/field in workspace]''' (or by pressing the right mouse button on the GUI). Type '>>Data_uvmat.Field' to get the current input field as a Matlab structure. An image or scalar matrix is for instance obtained as Data_uvmat.Field.A.
     99 * '''Coordinate aspect ratio:''' when '''[!CheckFixAspectRatio]''' is selected (the default option for images), the scale ratio for the  x and y coordinates is fixed to 1 by default (it can be manually adjusted by the edit box '''[num_AspectRatio]'''. When '''[!CheckFixAspectRatio]''' is not selected the graph scales along x and y automatically adjust to the figure size.
     100
     101 * '''Extracting graphs:'''   The graph displayed in the central window can be copied to a separate figure by pressing the menu bar command '''[Export/extract figure]'''. This allows plot editing, exporting in image format and printing, using standard Matlab graphic tools. Plots can be also exported on an existing figure for data comparison, using the option '''[Export/export on axis]'''. A movie can be produced using the command '''[Export/make movie avi]'''.
     102
     103 * '''Extracting data''' as Matlab arrays. Information stored in the GUI uvmat  (as ''!UserData'' in the figure) can be extracted in the Matlab work space by the menu bar command  '''[Export/field in workspace]''' (or by pressing the right mouse button on the GUI). Type '>>Data_uvmat.Field' to get the current input field as a Matlab structure. An image or scalar matrix is for instance obtained as Data_uvmat.Field.A.
    104104
    105105
    106106== 3 Input files and navigation with uvmat ==
    107107=== 3.1  Input data formats ===
    108 uvmat 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.
    109 
    110 Velocity fields and all results of data processing are stored in the Netcdf format, see [section 7->#get_field] for details. They are read by the function {nc2struct.m} . Then different quantities (vorticity, divergence...) can be calculated  by the function {calc_scal.m}.
    111 
    112 The 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 c png form typically saves disk storage by a factor of 3.
     108uvmat 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.
     109
     110Velocity 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.
     111
     112The 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.
    113113
    114114For 3D PIV**, 'volume' images, with file extension .vol are used. These are images in the  png format, where the npz slices are concatenated along the y direction, forming a composite image of dimension (npy x npz, npx) from the images (npy x npx).
    115115
    116116=== 3.2 Selecting fields from CIV : ===
    117   The uvmat package recognizes  the NetCDF fields obtained from the CIVx software.  This includes the velocity fields and their spatial derivatives, as well as information about the CIV processing (image correlation values and flags). The vorticity, divergence, or strain are read in the same NetCDF files, but are available only after a PATCH operation has been run in the CIVx software,  see [section 10->#civ].
     117The package uvmat recognizes the NetCDF fields obtained from the CIVx software.  This includes the velocity fields and their spatial derivatives, as well as information about the CIV processing (image correlation values and flags). The vorticity, divergence, or strain are read in the same NetCDF files, but are available only after a PATCH operation has been run in the CIVx software,  see [#a11-PIV:ParticleImagingVelocimetrys: section 11].
    118118
    119119<doc71|center>
    120120
    121 When a CIV field is recognised,  the popup menu '''[Fields]''' is set by default to 'velocity' while a menu '''[VelType]''' (with items 'civ1', 'filter1',..) appears at the upper right of the GUI.
     121When a CIV field is recognised,  the popup menu '''[Fields]''' is set by default to 'velocity' while a menu '''[!VelType]''' (with items 'civ1', 'filter1',..) appears at the upper right of the GUI.
    122122
    123123The 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.
     
    126126
    127127=== 3.3 File naming and indexing ===
    128   Different kinds of file or image frame indexing are defined:
    129 
    130 -'''Simple series:''' files in a series can be labeled by a single integer index i, with name obtained by concatenation of the full root ({RootPath/RootFile}), an index string suffix, and the file extension {FileExt} (example {Exp01/aa_45.png}).  A frame series can be alternatively read from a  singlemovie file. Then the index i stands for the frame index within the file.
     128Different kinds of file or image frame indexing are defined:
     129
     130-'''Simple series:''' files in a series can be labeled by a single integer index i, with name obtained by concatenation of the full root ''!RootPath/RootFile''), an index string suffix, and the file extension ''!FileExt'' (example ''Exp01/aa_45.png'').  A frame series can be alternatively read from a  single movie file. Then the index ''i'' stands for the frame index within the file.
    131131
    132132-'''Double index series: ''' they are labeled by two integer indices i and j, with names obtained by concatenating the full root, the suffix '_i_j' and the file extension(e.g. {Exp/aa_45_2.png}). This double index labeling is commonly used for bursts of images (index j or equivalently a letter appendix 'a', 'b') separated by longer time intervals (index i).  It can be also used for successive volume scanning by a laser sheet, with index j representing the position in the volume and i the time.
     
    134134-'''Pair file indexing:''' new file series can result from the processing of primary series. For a sequential processing limited to a single file, the output index naturally reproduces  the input index. Other processing functions involve pairs of input files, for instance Particle Imaging Velocity from image pairs. In a simple series, the result from the two primary fields *_i1 and *_i2 is then labeled as *_i1-i2 with the file extension indicating  the output format. More generally,  the result from any processing involving a range of primary indices from  i1 to i2  is  labeled as _i1-i2.  If i1=i2, the two indices are merged in a single label i, or a single index j if j1=j2.
    135135
    136 -'''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.
     136-'''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 '''uvmat.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.
    137137
    138138=== 3.4 Navigation among file indices: ===
    139   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]'''.
     139The field indices can be incremented or decremented by the push buttons  '''[runplus]''' ( '''+''') and  '''[runmin]''' ('''-''') 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]'''. If this box is blank (or does not contain a number) the next available file is opened.
    140140
    141141<doc65|center>
    142142
    143   The current indices are displayed in the four edit boxes '''[i1], [i2], [j1], [j2]'''. The two first indices i1 and j1 are used for image series, while the second line i2, j2 is used to label the image pairs used for PIV data. The file indices can be directly set in these edit boxes, or equivalently in the edit box '''[FileIndex]''' at the top of the GUI.
    144 
    145   For navigation with index pairs, the reference index, defined as the integer part of the mean value ((j1+j2)/2), is incremented. If the check box '''[fix_pair] ''' is selected,  the difference j1-j2 is then fixed while the reference index i or j is incremented. Else the pair with appropriate reference index is searched. In the case of multiple choices, the most largest index interval is chosen. This allows us to scan successive fields obtained with different image pairs (to deal with time evolving velocity fields).
     143The current indices are displayed in the four edit boxes '''[i1], [i2], [j1], [j2]'''. The two first indices i1 and j1 are used for image series, while the second line i2, j2 is used to label the image pairs used for PIV data. The file indices can be directly set in these edit boxes, or equivalently in the edit box '''[!FileIndex]''' at the top of the GUI.
     144
     145For navigation with index pairs, the reference index, defined as the integer part of the mean value ((j1+j2)/2), is incremented. If the check box '''[fix_pair] ''' is selected,  the difference j1-j2 is then fixed while the reference index i or j is incremented. Else the pair with appropriate reference index is searched. In the case of multiple choices, the most largest index interval is chosen. This allows us to scan successive fields obtained with different image pairs (to deal with time evolving velocity fields).
    146146
    147147The maximum  value detected for each index is indicated by the boxes '''[last_i]''' and '''[last_j] ''' respectively.
     
    149149-'''slices:''' Images may be obtained with laser scanning in a multilayer mode, introducing a periodicity for the index i. This can be accounted by pressing the pushbutton '''[slices]''' and introducing the period in the edit box '''[num_NbSlice]''' which then appears. The index i modulo nb_slice then appears in the edit box '''[z_index]'''.
    150150
    151 -'''Movie scan:''' Fields  can be continuously scanned as a movie by pressing  the pushbuttons '''[Movie]''' ( '''[++>]''') or '''[MovieBackward]''' . The movie speed can be adjusted by the slider '''[speed]'''. Press '''[STOP] ''' to stop the movie.
     151-'''Movie scan:''' Fields  can be continuously scanned as a movie by pressing  the pushbuttons '''[Movie]''' ( '''[++>]''') or '''[!MovieBackward]''' . The movie speed can be adjusted by the slider '''[speed]'''. Press '''[STOP] ''' to stop the movie.
    152152
    153153-'''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.
    154154
    155155=== 3.5  Image documentation files (.xml): ===
    156 Information 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].
    157 
    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 [section 9 ->#series]). The xml file can be also opened directly by the uvmat browser, or by any text editor.
    159 
    160   The xml file <code><ImaDoc> </code> can contain the following sections:
     156Information 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.
     157
     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 [wiki:#a10-Processingfieldseries: section 10]). The xml file can be also opened directly by the uvmat browser, or by any text editor.
     159
     160The xml file <code><ImaDoc> </code> can contain the following sections:
    161161
    162162-<code><Heading></code>: contains elements <code><Campaign>, <Experiment>, <Device></code>, 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. -<code><Camera></code> contains information on the camera settings, as well as the timing of all the images in a subsection <code><BurstTiming></code>. -<code><TranslationMotor></code> and <code><Oscillator></code> contains information on the mechanical devices used to produce the laser sheet and scan volumes. -<code><GeometryCalib></code> contains the parameters of the geometric calibration relating the pixel position to the real space coordinates (see [section 7->#geometry_calib]). In the case of volume scanning, it also describes the set of laser plane positions and angles. -<code><Illumination></code> describes the illumination system used, including the position of the laser source. -<code><Tracor></code> describes the properties of the flow tracor (particle, dye...) -<code><ImageTransform></code> describes  the image processing which may have been performed.
     
    389389== 7- Netcdf files and get_field.fig: ==
    390390=== 7.1 The NetCDF format: ===
    391 NetCDF (network Common Data Form) is a machine-independent format for representing scientific data, suitable for large arrays ([->http://www.unidata.ucar.edu/software/netcdf/]). Each piece of data can be directly accessed by its name without reading the whole file. New records can be added to the file without perturbing the remaining information. The next release of NetCDF is intended to be compatible with the newly developed and more general hdf format.
    392 
    393   The NetCDF format has been initially developed for meteorological data, but has been progressively chosen by many scientific communities. This format has been for instance proposed by the European network PIVNet ( http://www.meol.cnrs.fr/LML/EuroPIV2/Proceedings/p251.pdf ) to inter compare data obtained by various techniques of Particle Imaging Velocimetry.
    394 
    395   Libraries for reading-writing and data visualisation with usual computer languages can be freely downloaded. Recent releases of Matlab contain built in functions for reading and writting netcdf files. For old versions, a free toolbox must be downloaded from from http://sourceforge.net/projects/mexcdf/. Uvmat deals with both cases.
     391NetCDF (network Common Data Form) is a machine-independent format for representing scientific data, suitable for large arrays (http://www.unidata.ucar.edu/software/netcdf/). Each piece of data can be directly accessed by its name without reading the whole file. New records can be added to the file without perturbing the remaining information. The next release of NetCDF is intended to be compatible with the newly developed and more general hdf format.
     392
     393The NetCDF format has been initially developed for meteorological data, but has been progressively chosen by many scientific communities. This format has been for instance proposed by the European network PIVNet (http://www.meol.cnrs.fr/LML/EuroPIV2/Proceedings/p251.pdf ) to inter compare data obtained by various techniques of Particle Imaging Velocimetry.
     394
     395Libraries for reading-writing and data visualisation with usual computer languages can be freely downloaded. Recent releases of Matlab contain built in functions for reading and writting netcdf files. For old versions, a free toolbox must be downloaded from from http://sourceforge.net/projects/mexcdf/. Uvmat deals with both cases.
    396396
    397397The NetCDF data model consists of variables, dimensions, and attributes.