Changes between Version 175 and Version 176 of UvmatHelp


Ignore:
Timestamp:
Jan 23, 2015, 10:59:50 AM (6 years ago)
Author:
vaillant1p
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UvmatHelp

    v175 v176  
    107107== 3 - Input files and navigation with UVMAT ==
    108108=== 3.1  Input data formats ===
    109 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.
     109Uvmat 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
    111111''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.
     
    129129Different kinds of file or image frame indexing are defined:
    130130
    131 -'''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.
    132 
    133 -'''Double index series: ''' they are labeled by two integer indices i and j. 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. 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.
    134 
    135 -'''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.
    136 
    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.
     131- '''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.
     132
     133- '''Double index series: ''' they are labeled by two integer indices i and j. 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. 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.
     134
     135- '''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.
     136
     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 ===
     
    148148The maximum  value detected for each index is indicated by the boxes '''[last_i]''' and '''[last_j] ''' respectively.
    149149
    150 -'''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]'''.
    151 
    152 -'''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.
     150- '''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]'''.
     151
     152- '''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.
    153153
    154154-'''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.
     
    253253[[Image(help_vectors_titres.jpg)]]
    254254
    255 -'''Warning flags''': they indicate a vector resulting from a dubious image correlation process, but not removed from the data set. They are displayed in black by default. This feature can be desactivated by selecting the check box '''[!CheckHideWarning]'''.
    256 
    257 -'''Error flags''': they mark vectors considered as false. These vectors are kept in the data set so that their elimination can be reversed, but they must not be taken into account for data processing. These false vectors are displayed in magenta. They can be also removed from the plot by selecting the check box '''[!CheckHideFalse]'''.
    258 
    259 -'''Associated scalar: '''  for PIV velocity fields, the color  represents by default the image correlation '''C''', ranging from 0 to 1.  The red values correspond to poor correlations, green to fair values, and blue to good ones. The value range covered by each of the three colors is set by the pair of sliders  '''[Slider1]''' and '''[Slider2]''', or equivalently by the edit boxes '''[num_ColCode1]''' and '''[num_ColCode2]'''. Other color representations can be specified. '''[!ColorScalar]''' sets the scalar used for color representation, for instance the vector norm 'norm_vec' or vorticity 'vort' (the list of available scalars is set by the function {calc_scal.m}).
    260 
    261 -'''[!ColorCode] ''' sets the kind of color representation:
     255- '''Warning flags''': they indicate a vector resulting from a dubious image correlation process, but not removed from the data set. They are displayed in black by default. This feature can be desactivated by selecting the check box '''[!CheckHideWarning]'''.
     256
     257- '''Error flags''': they mark vectors considered as false. These vectors are kept in the data set so that their elimination can be reversed, but they must not be taken into account for data processing. These false vectors are displayed in magenta. They can be also removed from the plot by selecting the check box '''[!CheckHideFalse]'''.
     258
     259- '''Associated scalar: '''  for PIV velocity fields, the color  represents by default the image correlation '''C''', ranging from 0 to 1.  The red values correspond to poor correlations, green to fair values, and blue to good ones. The value range covered by each of the three colors is set by the pair of sliders  '''[Slider1]''' and '''[Slider2]''', or equivalently by the edit boxes '''[num_ColCode1]''' and '''[num_ColCode2]'''. Other color representations can be specified. '''[!ColorScalar]''' sets the scalar used for color representation, for instance the vector norm 'norm_vec' or vorticity 'vort' (the list of available scalars is set by the function {calc_scal.m}).
     260
     261- '''[!ColorCode] ''' sets the kind of color representation:
    262262
    263263 * 'rgb':  color ranging from red, for the scalar value set by '''[num_MinVec]''', to blue, for the scalar value set by  '''[num_MaxVec]'''. The  color thresholds from red to green and green to blue are set by '''[ColCode1]''' and '''[ColCode2]''' respectively, or the sliders  '''[Slider1]''' and '''[Slider2]'''. By unselecting the check box [!CheckFixVecColor], these thresholds can be set to match the min and max scalar values.
     
    266266 * '64 colors': quasi-continuous color representation, ranging from blue (for the scalar value given by '''[num_MinVec]''', to red, for the scalar value given by '''[num_MaxVec]'''.
    267267
    268 -'''Mouse display''': when the mouse is moved over a vector, it is marked by a circle, and its features appear in the display text boxes on the upper right. These are
     268- '''Mouse display''': when the mouse is moved over a vector, it is marked by a circle, and its features appear in the display text boxes on the upper right. These are
    269269
    270270 * fist line: the position coordinates ''x'', ''y'', ''z'' for 3D cases).
     
    272272 * third line: the vector index in the file, the values of the scalar (C), the warning flag (F) and the error flag (FF). The meaning of the flag values is given in [#a11.3FIX section 11.3].
    273273
    274 -'''Manual editing of vectors''': error flags are automatically produced by the PIV operation, see [#a11.3FIX section 11.3]. It is also possible to introduce them manually by checking '''[edit_vect]''' and selecting a vector with the mouse. The flag can be removed by selecting it again. To record the changes in the input file, press the button '''[record]'''.
     274- '''Manual editing of vectors''': error flags are automatically produced by the PIV operation, see [#a11.3FIX section 11.3]. It is also possible to introduce them manually by checking '''[edit_vect]''' and selecting a vector with the mouse. The flag can be removed by selecting it again. To record the changes in the input file, press the button '''[record]'''.
    275275
    276276=== 4.4 Histograms ===
     
    299299The following succession of operations is performed by '''uvmat.fig''':
    300300
    301 -'''File identification:''' the nomenclature type and file type (for instance image, movie, or NetCDF file) are identified from the opened file (using the function ''find_file_series.m'').
    302 
    303 -'''File Reading:''' the input field is first read from the input file by the Matlab function ''read_field.m''.
    304 
    305 -'''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).
    306 
    307 -'''Transform:''' by default the 'phys' option transforms each of the input fields from pixel to physical coordinates. This operation can also combine two input field structures into a single field structure.
    308 
    309 -'''Histogram:''' This is obtained from the input field in transformed coordinates, or if applicable from the fields resulting from the two input fields.
    310 
    311 -'''Projection:''' on  the projection object selected in the menu '''[!ListObject_1]''', see [#ProjObject section 6]. A second projection, on the object selected by '''[!ListObject]''', can be plotted in the ancillary figure '''view_field.fig'''. Projection is performed by the function ''proj_field.m''.
    312 
    313 -'''Field calculation:''' a scalar can be calculated after projection, as selected by the menu '''[Fields]'''.
    314 
    315 -'''Field comparison''': when two fields of the same nature are introduced, the difference is taken. This is skipped if the transform function has already led to a single field.
    316 
    317 -'''Plotting:''' plot the results of projection, using the function ''plot_field.m''.
    318 
    319 
     301- '''File identification:''' the nomenclature type and file type (for instance image, movie, or NetCDF file) are identified from the opened file (using the function ''find_file_series.m'').
     302
     303- '''File Reading:''' the input field is first read from the input file by the Matlab function ''read_field.m''.
     304
     305- '''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).
     306
     307- '''Transform:''' by default the 'phys' option transforms each of the input fields from pixel to physical coordinates. This operation can also combine two input field structures into a single field structure.
     308
     309- '''Histogram:''' This is obtained from the input field in transformed coordinates, or if applicable from the fields resulting from the two input fields.
     310
     311- '''Projection:''' on  the projection object selected in the menu '''[!ListObject_1]''', see [#ProjObject section 6]. A second projection, on the object selected by '''[!ListObject]''', can be plotted in the ancillary figure '''view_field.fig'''. Projection is performed by the function ''proj_field.m''.
     312
     313- '''Field calculation:''' a scalar can be calculated after projection, as selected by the menu '''[Fields]'''.
     314
     315- '''Field comparison''': when two fields of the same nature are introduced, the difference is taken. This is skipped if the transform function has already led to a single field.
     316 
     317- '''Plotting:''' plot the results of projection, using the function ''plot_field.m''.
     318
     319----
    320320== 5 - Field structures ==
    321321=== 5.1 Griding of data ===
     
    525525The NetCDF data model consists of variables, dimensions, and attributes.
    526526
    527 -'''Variables:''' N-dimensional arrays of data. Variables in NetCDF files can be one of six types (char, byte, short, int, float, double). Variables are used to store the bulk of the data in a NetCDF dataset. A variable represents an array of values of the same type and unit. A variable has a name, a data type, and a shape described by its list of dimensions specified when the variable is created. A variable may also have associated attributes, which may be added, deleted or changed after the variable is created.
    528 
    529 -'''Dimensions:''' describe the axes of the data arrays. A dimension has a name and a length. The naming can be useful to identify groups of variables with one to one correspondence, sharing the same dimensions. It is legal for a variable to have the same name as a dimension, it is then called a coordinate variable. Such variables have no special meaning to the NetCDF library, but they can be used in processing software to link the arrays of coordinate values to their corresponding field variables.
    530 
    531 -'''Attributes: ''' annotate variables or files (global attributes) with small notes or supplementary meta data. Attributes are always scalar values or 1D arrays, which can be associated with either a variable or the file as a whole. Although there is no enforced limit, the user is expected to keep attributes small. Attribute names with specific meaning are defined in http://www.unidata.ucar.edu/software/netcdf/docs_beta/netcdf.html#Attribute-Conventions. An attribute '.Conventions' can be used to refer to additional sets of conventions used in a particular community.
     527- '''Variables:''' N-dimensional arrays of data. Variables in NetCDF files can be one of six types (char, byte, short, int, float, double). Variables are used to store the bulk of the data in a NetCDF dataset. A variable represents an array of values of the same type and unit. A variable has a name, a data type, and a shape described by its list of dimensions specified when the variable is created. A variable may also have associated attributes, which may be added, deleted or changed after the variable is created.
     528
     529- '''Dimensions:''' describe the axes of the data arrays. A dimension has a name and a length. The naming can be useful to identify groups of variables with one to one correspondence, sharing the same dimensions. It is legal for a variable to have the same name as a dimension, it is then called a coordinate variable. Such variables have no special meaning to the NetCDF library, but they can be used in processing software to link the arrays of coordinate values to their corresponding field variables.
     530
     531- '''Attributes: ''' annotate variables or files (global attributes) with small notes or supplementary meta data. Attributes are always scalar values or 1D arrays, which can be associated with either a variable or the file as a whole. Although there is no enforced limit, the user is expected to keep attributes small. Attribute names with specific meaning are defined in http://www.unidata.ucar.edu/software/netcdf/docs_beta/netcdf.html#Attribute-Conventions. An attribute '.Conventions' can be used to refer to additional sets of conventions used in a particular community.
    532532
    533533In contrast to variables, which are intended for bulk data, attributes are intended for ancillary data, or information about the data. The total amount of ancillary data associated with a NetCDF object, and stored in its attributes, is typically small enough to be memory-resident. However variables are often too large to entirely fit in memory and must be split into sections for processing.
     
    546546When 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]'''.
    547547
    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 
    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.
    551 
    552 -'''vectors:''' to plot vector fields. The x and y vector components are selected in the first (...) and second columns, while the coordinates are selected in '''[coord_x_vector] ''' and '''[coord_y_vector]'''. If no variable is selected in '''[coord_x_scalar] '''  or '''[coord_y_scalar] ''' ( blank selected at first line), the index is used as coordinate. A scalar, set in ..., can be represented as vector color.
     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
     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.
     551
     552- '''vectors:''' to plot vector fields. The x and y vector components are selected in the first (...) and second columns, while the coordinates are selected in '''[coord_x_vector] ''' and '''[coord_y_vector]'''. If no variable is selected in '''[coord_x_scalar] '''  or '''[coord_y_scalar] ''' ( blank selected at first line), the index is used as coordinate. A scalar, set in ..., can be represented as vector color.
    553553
    554554The attribute or variable considered as 'time' can be also chosen in the Panel '''[Time]'''. From the menu '''[!SwitchVarIndexTime]''', the time can be considered as the ''file index'', a global ''attribute'', a dimension ''variable'', or a ''dimension index''. Selection of ''attribute'' gives way to a list of global attribute tags in the menu '''[!TimeName]'''. Selection of variable gives way to a list of variables, while selection of ''dimension'' gives a list of dimension names.
     
    773773An alternative possibility is to use the older Fortran program ''CivX'' from the GUI '''civ.fig'''. This can be called directly on the Matlab prompt, by typing  ''>>civ'', or from UVMAT by the menu bar command '''[RUN/PIV (old civ)]'''.
    774774
    775 '''-Modes of frame pair indexing''': A first menu '''[!ListCompareMode]''' on the top left selects one among four modes of operation:
     775'''- Modes of frame pair indexing''': A first menu '''[!ListCompareMode]''' on the top left selects one among four modes of operation:
    776776
    777777 * '''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):
     
    980980== 12 - Tridimensional features:(to update **) ==
    981981=== 12-1 Multilevel image scanning ===
    982 or multiplane scanning, it also describes the set of laser planes. Then the current plane index is indicated by the text box z_index and the total number of planes by the text box nb_slice.
     982Or multiplane scanning: it also describes the set of laser planes. Then the current plane index is indicated by the text box z_index and the total number of planes by the text box nb_slice.
    983983
    984984=== 12-2 Volume image scanning ===
     
    990990  This GUI '''editxml.fig''' visualises and edits XML files. It is automatically called by the browser of '''uvmat.fig''' when a file with extension .xml is opened.
    991991
    992   When an input file is opened, editxml detects the title key, e.g. <!ImaDoc>, and looks for the corresponding XML schema (e.g. {!ImaDoc.xsd} ). This schema is sought  in the directory defined by <!SchemaPath> in the installation file {PARAM.xml} of UVMAT. If the schema is found, the hierarchical structure and keys given by the schema are diplayed.  Otherwise the  keys of the XML file are displayed.
    993 
    994   Simple elements in the XML file are listed in the forme 'key'='value', and the corresponding attributes are shown in green. Comments from the schema are dispalyed in blue. Complex elements are indicated by '+'. Selecting them on the list gives access to the lower hierarchical level.  Press the  arrow '''[<---]''' to move back upward in the hierarchy.
    995 
    996   Manual editing of element value is possible. Select the element and use the lower edit box. This edit box transforms in a menu when a preselected list of allowed input values has been set by the schema.
     992When an input file is opened, editxml detects the title key, e.g. <!ImaDoc>, and looks for the corresponding XML schema (e.g. {!ImaDoc.xsd} ). This schema is sought  in the directory defined by <!SchemaPath> in the installation file {PARAM.xml} of UVMAT. If the schema is found, the hierarchical structure and keys given by the schema are diplayed.  Otherwise the  keys of the XML file are displayed.
     993
     994Simple elements in the XML file are listed in the forme 'key'='value', and the corresponding attributes are shown in green. Comments from the schema are dispalyed in blue. Complex elements are indicated by '+'. Selecting them on the list gives access to the lower hierarchical level.  Press the  arrow '''[<---]''' to move back upward in the hierarchy.
     995
     996Manual editing of element value is possible. Select the element and use the lower edit box. This edit box transforms in a menu when a preselected list of allowed input values has been set by the schema.
    997997
    998998----