# Changes between Version 34 and Version 35 of UvmatHelp

Ignore:
Timestamp:
Jun 2, 2013, 10:45:15 PM (8 years ago)
Comment:

--

### Legend:

Unmodified
 v34 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). -'''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. '''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. === 2.4 General tools === 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. The xml file can contain the following sections: -: contains elements , , , 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. - contains information on the camera settings, as well as the timing of all the images in a subsection . - and contains information on the mechanical devices used to produce the laser sheet and scan volumes. - 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. - describes the illumination system used, including the position of the laser source. - describes the properties of the flow tracor (particle, dye...) - describes  the image processing which may have been performed. The detailed commented structure is provided  in the schema file {ImaDoc.xsd}. The xml documentation file is read by the function {imadoc2struct.m}. If this file does not exist, a file with the same root name but extension .civ is sought (see [section 3.6->#sec3.6_civ]). The xml file can contain the following sections: * : contains elements , , , 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. * contains information on the camera settings, as well as the timing of all the images in a subsection . and contains information on the mechanical devices used to produce the laser sheet and scan volumes. * 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. * describes the illumination system used, including the position of the laser source. * describes the properties of the flow tracor (particle, dye...) The detailed commented structure is provided  in the schema file ''ImaDoc.xsd''. The xml documentation file is read by the function ''imadoc2struct.m''. If this file does not exist, a file with the same root name but extension .civ is sought (obsolete format). === 3.6 Ancillary input files: === [sec3.6_mask<-] -''' Mask:''' Masks are used to avoid PIV computations in specified areas. The file is a B&W 8 bit png image, with the same size as the image it has to mask. The grayscale code used is : -* Intensity < 20: ('black mask') the vector in this place will be set to zero -*  20 < Intensity < 200:('gray mask') the vector in this place will be absent  -*  Intensity>200  the vector will be computed _ .png imageswith appropriate name in the image directory can be automatically recognised by '''uvmat.fig''' and '''civ.fig''', see [section 8.1->#sec8.1].  The mask corresponding to an image or velocity field can be displayed in '''uvmat.fig''' by selecting the check box '''[view_mask]''' on the upper right. [sec3.6_grid<-] -''' 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 n X1 Y1 X2 Y2  ......  Xn Yn  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 [section->#sec8.2]. -'''.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'''. -''''.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.  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. * ''' Mask:''' Masks are used to avoid PIV computations in specified areas. The file is a B&W 8 bit png image, with the same size as the image it has to mask. The grayscale code used is : * Intensity < 20: ('black mask') the vector in this place will be set to zero * 20 < Intensity < 200:('gray mask') the vector in this place will be absent * 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 [wiki:#a9-Masksandgrids: section 9.1]. Otherwise file selection by a browser is proposed when '''[view_mask]''' is selected. * ''' 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 {{{ n X1 Y1 X2 Y2  ......  Xn Yn }}} 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]. * '''.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'''. * ''''.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'' (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 .civ file is named aa.civ. {{{ 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. }}} -'''.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. -'''.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'''. -'''.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'''. === 3.7 Data organisation in a  project: === The package is designed to foster a good data organisation. The raw data from a project should be organised as  Project/Campaign/Experiment/DataSeries/data files. -'Project': contains all information from a project. -'Campaign'' corresponds to a series of experiments obtained by varying a given set of physical parameters. A set of  parameter names (with units) is expected to be associated to a campaign. A project may involve several campaigns corresponding to different configurations, hence different relevant parameters. For a single configuration, 'Campaign' can be at the top of the data tree, without an additional 'Project' level. The uvmat package does not manage levels above 'Campaign'.  -'Experiment' is a directory containing all the data for a particular experiment, defined by a choice of values for the physical parameters. -'DataSeries' contains an image series or movie from a camera, or more generally a data series from a device. Its name must correspond to the device and remain the same for all the experiments using this device. The results from data processing, as provided by 'civ' or 'series', are stored at the same level in a DataSeries directory, named from the source one with a extension specific to the processing program, for instance .civ for civ. '' '''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. This is done by opening the source Campaign with the menu bar option Open/browse campaign from uvmat. Select the source campaign directory with the browser. Then the GUI 'browse_data' appears. Then press 'create_mirror' and select the directory which must contain the mirror Campaign. A set of directory is then created for each experiment, in which are created symbolic  links to the DataSeries directories. Data processing then results in real DataSeriies directories created in the Experiment directory.  An xml mirror.xml is created inside the directory mirror to mark its role; This xml file contains  the path and name of the source directory under the label . The mirror directory can be regularly updated by pressing the button 'update_mirror'. * 'Project': contains all information from a project. * 'Campaign'' corresponds to a series of experiments obtained by varying a given set of physical parameters. A set of  parameter names (with units) is expected to be associated to a campaign. A project may involve several campaigns corresponding to different configurations, hence different relevant parameters. For a single configuration, 'Campaign' can be at the top of the data tree, without an additional 'Project' level. The uvmat package does not manage levels above 'Campaign'. * 'Experiment' is a directory containing all the data for a particular experiment, defined by a choice of values for the physical parameters. * 'DataSeries' contains an image series or movie from a camera, or more generally a data series from a device. Its name must correspond to the device and remain the same for all the experiments using this device. The results from data processing, as provided by 'civ' or 'series', are stored at the same level in a DataSeries directory, named from the source one with a extension specific to the processing program, for instance .civ for civ. '' '''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. This is done by opening the source Campaign with the menu bar option Open/browse campaign from uvmat. Select the source campaign directory with the browser. Then the GUI 'browse_data' appears. Then press 'create_mirror' and select the directory which must contain the mirror Campaign. A set of directory is then created for each experiment, in which are created symbolic  links to the DataSeries directories. Data processing then results in real DataSeries directories created in the Experiment directory.  An xml mirror.xml is created inside the directory mirror to mark its role; This xml file contains  the path and name of the source directory under the label . The mirror directory can be regularly updated by pressing the button 'update_mirror'. == 4 Field display == The uvmat interface primarily reads and visualises two-dimensional fields, which can be images or scalars, or vector fields. The uvmat interface primarily reads and visualises two-dimensional fields, which can be images or scalars, or vector fields. === 4.1  Images and scalars: === Images are matrices of integers, visualised by the Matlab function  {imagesc.m}. True color images are described by a matrix A(npy,npx,3) of integers between 0 and 255, the last index labeling the color component red, green or blue. They are displayed directly as color images. Images are matrices of integers, visualised by the Matlab function ''imagesc.m''. True color images are described by a matrix A(npy,npx,3) of integers between 0 and 255, the last index labeling the color component red, green or blue. They are displayed directly as color images. The black and white (B/W) images are described by a matrix A(npy,npx) of integers, whose range depends on the camera dynamics (0 to 255 for 8 bit images, 0 to 65535 for 16 bit images). They are represented with gray levels, according to the colorbar displayed on the right. The luminosity and contrast can be adjusted using the edit boxes '''[MinA]''' and '''[MaxA]''' on the right of the interface: the luminosity level set by '''[MinA]''' (and levels below) is represented as black, and the luminosity level set by '''[MaxA]''' (or levels above) as white. When the check box '''[AutoScal]''' is selected, '''AMin''' and '''AMax''' are set automatically to the image minimum and maximum respectively. Then the image may appear dark if a single point is very bright, in that case a lower value must be set for '''AMax'''. B/W images can be displayed with false colors, from blue to red, by unselecting the check box '''[BW]'''. Two images can be visually compared by switching back and forth between them as a short movie. This is quite useful to get a visual feeling of the image correlation for PIV. This effect is obtained by introducing two image indices in the edit boxes j1 and j2 (or i1 and i2), and selecting the button  '''[movie_pair] ''' (''''[<-->]'''') to switch between these two indices. The speed of the movie can be adjusted by the slider '''[speed]'''. Press '''[movie_pair] ''' again, or '''[STOP]''', to stop the motion. Scalar fields are  represented like B/W 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 '''[BW]'''. 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. The greyscale images are described by a matrix A(npy,npx) of integers, whose range depends on the camera dynamics (0 to 255 for 8 bit images, 0 to 65535 for 16 bit images). They are represented with gray levels, according to the colorbar displayed on the right. The luminosity and contrast can be adjusted using the edit boxes '''[num_MinA]''' and '''[num_MaxA]''' on the right of the interface: the luminosity level set by '''[num_MinA]''' (and levels below) is represented as black, and the luminosity level set by '''[num_MaxA]''' (or levels above) as white. When the check box '''[CheckFixScalar]''' is not selected, these bounds are set automatically to the image minimum and maximum respectively. Then the image may appear dark if a single point is very bright, in that case a lower value must be set by '''[num_MaxA]'''. Greyscale images can be displayed with false colors, from blue to red, by unselecting the check box '''[CheckBW]'''. Two images can be visually compared by switching back and forth between them as a short movie. This is quite useful to get a visual feeling of the image correlation for PIV. This effect is obtained by introducing two image indices in the edit boxes j1 and j2 (or i1 and i2), and selecting the button  '''[movie_pair] ''' (''''[<-->]'''') to switch between these two indices. The speed of the movie can be adjusted by the slider '''[speed]'''. Press '''[movie_pair] ''' again, or '''[STOP]''', to stop the motion. Scalar fields are  represented like B/W 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 '''[BW]'''. 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. Scalar are represented by matrices with real ('double') values, unlike images which are integers. They can be alternatively defined with unstructured grid (see [section 5.3->#sec5.3]): they are then linearly interpolated on a regular grid before visualisation (a fairly slow process). === 4.2 Vectors: === The vector fields are represented by arrows. The length of the arrows is automatically set when the check box'''[CheckFixVectors]''' is not selected, or it can be adjusted by the edit box '''[num_VecScale]'''.  For clarity of visualisation, the number of displayed vectors can be divided by 2 in each direction by selecting the check box '''[CheckDecimate4]'''. The vector fields are represented by arrows. The length of the arrows is automatically set when the check box'''[CheckFixVectors]''' is not selected, or it can be adjusted by the edit box '''[num_VecScale]'''.  For clarity of visualisation, the number of displayed vectors can be divided by 2 in each direction by selecting the check box '''[CheckDecimate4]'''. Each vector has a color, ranging from blue to red, which can represent an associated  scalar value. In addition, black and magenta colors represent warning and error flags respectively. This color system is primarily designed for PIV data but can be used in other contexts as well. Histograms of the input fields are represented on the bottom left. The choice of the variable is done by the menu '''[histo1_menu]'''. For color images, the histogram of each color component, r, g, b, is given with a curve of the corresponding color. In case of saturation, the proportion of pixels beyond the max limit is written on the graph. For color images, the histogram of each color component, r, g, b, is given with a curve of the corresponding color. In case of saturation, the proportion of pixels beyond the max limit is written on the graph. === 4.4 Comparing two fields === A second field series can be opened and compared to the first one, using the menu bar command '''[Open_1]'''.  Then a new file name and indices appear on the second line, as well as the check box '''[SubField]''' on the very right. The second field can be alternatively obtained by selecting a field in the popup menu '''[Fields_1] ''' (under '''[Fields]'''). If the two files are both images or scalar, their difference is introduced as the input field. If one field  is an image (or scalar), while the other one is a vector field, the image will appear as a background in the vector field. This is convenient for instance to relate the CIV result to the quality of the images, or to relate vorticity to the vector field. If  two vector fields are compared, their difference is taken as the input field, and is then displayed and analysed. If the two fields are not at the same points, the velocity of the second field is linearly interpolated at the positions of the first one (using the Matlab function {griddata.m}). The color and flags are then taken from the first field. A second field series can be opened and compared to the first one, using the menu bar command '''[Open_1]'''.  Then a new file name and indices appear on the second line, as well as the check box '''[SubField]''' on the very right. The second field can be alternatively obtained by selecting a field in the popup menu '''[Fields_1] ''' (under '''[Fields]'''). If the two files are both images or scalar, their difference is introduced as the input field. If one field  is an image (or scalar), while the other one is a vector field, the image will appear as a background in the vector field. This is convenient for instance to relate the CIV result to the quality of the images, or to relate vorticity to the vector field. If  two vector fields are compared, their difference is taken as the input field, and is then displayed and analysed. If the two fields are not at the same points, the velocity of the second field is linearly interpolated at the positions of the first one (using the Matlab function {griddata.m}). The color and flags are then taken from the first field. The two file series will be scanned simultaneously by '''[runplus]''' ( '->') and  '''[runmin]''' ('<-') , according to their own nomenclature. It is also possible to manually edit the second file indices '''[FieldIndex_1] ''' to compare two fields with different indices.  If available, the time of the second field is indicated in the edit box '''[abs_time_1] ''' at the very right, below the time of the main field. -'''Thin plate shell (tps) interpolation:''' This is a multi-dimensional generalisation of the spline interpolation/smoothing, an optimum way to interpolate data with minimal  curvature of the interpolating function. The result at an interpolation {site} $'''r'''$ is expressed in the form, see [thin plate spline->73]. This is a multi-dimensional generalisation of the spline interpolation/smoothing, an optimum way to interpolate data with minimal  curvature of the interpolating function. The result at an interpolation {site} $'''r'''$ is expressed in the form, see [thin plate spline->73]. $$\label{sol_gene} f({\bf r})=\sum S_i \phi({\bf|r-r_i}|)+a_0+a_1x+a_2y\;$$ where {\bf r_i} are the positions of the measurement points (the {centres}). Each centre can be viewed as the source of an axisymmetric  field  $\phi$ of the form $\phi(r)=r^2\log (r)$. The weights $S_i$ and the linar coefficients $a_0,a_1,a_2$ are the tps coefficients which determine the interpolated value at any point. The spatial derivatives are similarly obtained at any point by analytical differentiation of the source functions $\phi(r)$. These tps coefficients therefore contain all the information for interpolation at any point. ^ These are geometrical objects used to define cuts along lines or planes, to interpolate fields on a regular grid, to restrict the analysis or visualisation of fields to subregions. Objects are created by the menu bar command  '''[Projection object]''' in '''uvmat.fig'''.  The creation of a new object ('points', 'line'....) can be initiated by selecting the corresponding item in the menu. Alternatively, an existing xml object file can be opened by the option 'browse...'. In each case an auxiliary GUI '''set_object.fig''' describing the object properties appears, see next [sub-section->#sec6.2] for their definitions. This GUI  can be  edited by mouse drawing in the plotted field or by direct input. In the latter case, refresh the plots by pressing''' [PLOT] ''' in '''set_object.fig''' . Objects can be saved as xml files with the button ''' [SAVE]''' of '''set_object.fig'''. In each case an auxiliary GUI '''set_object.fig''' describing the object properties appears, see next [sub-section->#sec6.2] for their definitions. This GUI  can be  edited by mouse drawing in the plotted field or by direct input. In the latter case, refresh the plots by pressing''' [PLOT] ''' in '''set_object.fig''' . Objects can be saved as xml files with the button ''' [SAVE]''' of '''set_object.fig'''. The projection of fields on objects is performed by the function {proj_field.m}, which can be used also in data processing. The projected field resulting form a projection object drawn in the main plotting window of uvmat will be plotted in the secondary plotting GUI '''[view_field]'''.    The list of currently opened projection objects is displayed in the menus '''[list_object_1]''' and '''[list_object_2]''' at the bottom right of '''uvmat.fig'''.  One object can be selected in each of these menus: the projection on the object selected in '''[list_object_1]''' is viewed in '''uvmat.fig''' while that of the object selected in '''[list_object_2]''' is viewed in '''view_field.fig'''. All the created objects are sketched in both views, except the one on which projection leads to the currently plotted field (see [subsection 6.4->#sec6.4] for object representation). The active objects are plotted in magenta, while the inactive ones are in blue. -''' {Projection on planes:}  ''' Data in the range of action (RangeZ on each side of the plane) are projected normally to the plane, and its position expressed with respect to the coordinate system attached to the plane. This coordinate system is defined by an origin, the plane position XObject,YObject, ZObject, the ranges [RangeX(1) RangeX(2)]  and [RangeY(1) RangeY(2)] for X and Y, and the Euler angles Phi, Theta, Psi. -*ProjMode='projection': in the case of unstructured coordinates, all field variables are projected onto the plane.  For structured coordinates with meshes DX,DY (DZ),  data are interpolated on the line with a mesh =min(DX,DY,DZ).  -* ProjMode='interp': non-false data are linearly interpolated on the grid defined by the plane coordinate system and and meshes DX, DY. Data which are 'discrete','warnflag' or 'errorflag' (as defined by the attribute 'Role') are not projected. non-false data are linearly interpolated on the grid defined by the plane coordinate system and and meshes DX, DY. Data which are 'discrete','warnflag' or 'errorflag' (as defined by the attribute 'Role') are not projected. -''' {Projection on volumes:**}  ''' This is used to delimitate a volume for 3D representation