Version 7 (modified by sommeria, 8 years ago) (diff)

--

# Help for Uvmat

## 1 Generalities

### 1.1 Aim

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(see [section 7->#get_field]). 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.

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.

#get_field

### 1.2 The package

The master piece is a Matlab GUI, made of a Matlab figure uvmat.fig and an associated set of sub-functions in the file {uvmat.m}. The menu bar at the top of the GUI, push buttons and editing box in uvmat.fig activate the Matlab sub-functions (callback functions) in {uvmat.m}. The package also contains the following set of GUI (see [overview of the package->#overview] for a complete list).

-browse_data.fig scans the data directory of a project - civ.fig: runs the software for Particle Imaging Velocimetry - editxml.fig: displays and edits xml files according to an xml schema. xml reading and editing is performed by the toolbox [xmltree->http://www.artefact.tk/software/matlab/xml/] , copied in the subdirectory /@xmltree. - geometry_calib.fig: determines geometric calibration parameters for relating image to physical coordinates. The toolbox [->http://www.vision.caltech.edu/bouguetj/calib_doc/] is used, copied in the subdirectory /toolbox_calib. - get_field.fig: selects coordinates and field in a general NetCDF file. The subdirectory /get_field contains functions called by the GUI get_field. - series.fig: apply various processing functions to series of fields. These functions are stored in the subdirectory /series. -set_object.fig: creates and edits geometric objects used to project data: points, lines, planes... -view_field.fig: is a GUI complementing uvmat for plotting projected data.

Functions in the package are used to generate file names, read files and plot data, and perform various ancillary tasks.

### 1.3 Documentation and help

The present on-line file is the reference document for the version currently available on the svn server. A html version ({uvmat_doc.html}) of this document is provided with the package, and accessible by help buttons in the GUIs.

A short comment about each GUI uicontrol (push buttons, edit boxes, menus..), as well as the tag name of this uicontrol, is provided as a tool tip window by moving the mouse over it. In the present help document, the tags of GUI uicontrols are quoted as [uicontrol tag], names of files in the package are quoted as {fct name.m}, and commands on the Matlab workspace as '>> command’ . Features not yet implemented or tested (in particular 3D features) are marked by .

Information is also provided as comments in each function. Type '>>help fct_name' to get it, or open it with an editor.

Finally a on-line [tutorial->105] is also provided with test images and data files.

Copyright Joel Sommeria, 2008, LEGI / CNRS-UJF-INPG, joel.sommeria@….

The package UVMAT is free software; it can be redistributed and/or modified it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

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.

[<doc115|right>->#top]

[2-The GUI uvmat.fig<-]

## 2 Overview of the GUI uvmat.fig=

### 2.1 Opening the GUI

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).

<img55|center>

The GUI contains an upper menu bar, a central display window, a lower left window for histogram, edit boxes and command buttons.

Each of theses graphic elements is described by a tag name, which can be displayed by moving the mouse over it: a tool tip window appears with the tag name followed by a short help description. The element tag and content can be also displayed in a zoom window, and possibly edited there, by a right hand mouse selection on the element. As a rule, tag names for checkboxes begins by 'Check', while tags of elements with numerical content begins by 'num_'.

The red pushbuttons command the main actions. Their color changes to yellow while they are active.

The menu bar at the top of the GUI contains the following buttons: -[Open]: gives access to the browser for the main input field. Test for instance with any image, or data provided in [UV_DEMO->105]. Previously opened fields are memorised in the menu and can be directly selected again. -*[browse...]: usual file browser -*[browse campaign...]: scan the data organised as a project/campaign, see [section 3.7->#sec3.7].

-[Open_1] : used like [Open] to select a second field, for comparisons with the main one.

-[Export] : used to export the displayed data, either as arrays in the Matlab workspace, either as a figure or a movie (for a succession of views).

-[Projection object] : used to create projection objects (points, lines, patches, gridded planes) for data analysis and interpolation

- : used to edit projection objects or individual vectors in data fields.

-[Tools]: -*[Geometric calibration]: for geometric calibration of images -*[LIF calibration]: calibration of images for Laser Induced Fluorescence -*[Make mask]: for creating mask images (for PIV) -*[Make grid]:: for making measurement grids for PIV -*[ruler]: displays a ruler to measure lengths and angles of any line.

-[Run] : -*[Field series]: gives access to the GUI series.fig for analysis of field series -*[PIV(CIV)]: gives access to the GUI civ.fig for Particle Imaging Velocimetry

-[Help] : displays the html help file

<doc58|center>

### 2.3 Displaying the input file name

After selection by the browser, the path and file names are determined. The path is splitted into the two first edit boxes [RootPath?] and [SubDir?], while the file name is split into a root name [RootFile?], file index string [FileIndex?], and file extension [FileExt?]. The input file name can be directly entered and modified by these edit boxes, without the browser.

Once a root name has been introduced, navigation among the file indices is provided by the red push buttons [runplus] ( [+>]) and [runmin] (<HTML>[ <-]</HTML>). The central push button [run0] ([0]) refreshes the current plot. See [section 3.4->#sec3.4] for more details.

When available, the time of each frame or field is displayed in the edit box [abs_time], 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 [section 3.5->#sec3.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.

### 2.4 General tools

-Mouse motion: the local coordinates and field values are obtained by moving the mouse over a plotting axes. They are displayed in the text box [text_display] on the upper right.

-Zoom: is activated by selecting the check box [CheckZoom?] on the upper right. Zoom in by pressing the left mouse button on the graph. Zoom out by pressing the right mouse button. A zoomed region can be displayed as a new figure by drawing a rectangle with the mouse, while pressing the left mouse button (release the button to stop drawing). The zoomed region can be translated through the initial field by pressing the directional arrows of the key board.

-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].

-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.

-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. A movie can be produced using the command [Export/make movie avi].

-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.

[<doc115|right>->#top]

[3-Input files and navigation with uvmat<-]

## 3 Input files and navigation with uvmat=

[sec3.1<-]

### 3.1 Input data formats

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.

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}.

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.

For 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).

### 3.2 Selecting fields from CIV :

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].

<doc71|center>

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.

The 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.

The choice of fields, velocity, vorticity, divergence... is done by the popup menu [Fields]. The option 'image' gives access to an image file corresponding to the velocity field. The option 'get_field...' allows the user to display all the variables of the netcdf file in the GUI get_field.fig. This is the only available option when the input file is not from CIV.

### 3.3 File naming and indexing

Different kinds of file or image frame indexing are defined:

-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.

-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.

-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.

-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.

[sec3.4<-]

### 3.4 Navigation among file indices:

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].

<doc65|center>

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.

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).

The maximum value detected for each index is indicated by the boxes [last_i] and [last_j] respectively.

-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].

-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.

-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.

[sec3.5<-]

### 3.5 Image documentation files (.xml):

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.

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.

The xml file <code><ImaDoc?> </code> can contain the following sections:

-<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.

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]).

### 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 <cadre> n X1 Y1 X2 Y2 ...... Xn Yn </cadre> 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.

[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>

-.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.

[sec3.7<-]

### 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 <SourceDir?>. The mirror directory can be regularly updated by pressing the button 'update_mirror'.

[<doc115|right>->#top]

## 4 Field display: =

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.

<doc64|center>

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.

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).

Scalars (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].

[sec4.2<-]

### 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].

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.

<doc63|center>

-Warning flags: they indicate a vector resulting from a dubious image correlation process, but not removed from the data set. Their display in black can be desactivated by selecting the check box [CheckHideWarning?].

-Error flags: they mark in magenta color 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. They can be removed for visualisation by selecting the check box [CheckHideFalse?].

-Associated scalar: for PIV velocity fields, the color represents by default the image correlation, 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}). [ColorCode?] sets the kind of color representation: -*'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 [AutoVecColor?], these thresholds can be set to match the min and max scalar values. -*'black' or 'white': set the color for all vectors -*'brg': same as rgb but in reverse order, with blue for the lowest scalar values. -*'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].

-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 -* fist line: the position coordinates x, y, (z for 3D cases). -* second line: the vector components -* 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 [section 10.3->#sec10.3].

-Manual editing of vectors: vectors can be manually set as 'false' by pressing [Edit/Vectors?] in the menu bar, then selecting the vector with the mouse. The selected vector becomes magenta. Inversely, if a magenta vector is selected, it is rehabilitated and retrieves its initial color. The corrections are recorded as false flags in the data file by pressing the pushbutton [record].

### 4.3 Histograms

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.

### 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.

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.

The second field can be removed by unselecting the check box [SubField?] on the very right.

[sec4.5<-]

### 4.5 Field transforms:

A 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].

These functions can transform fields into polar coordinates, do image filtering, Fourier transform, signal analysis for a 1D input field... Other functions can be easily written using those as templates. The general form of such functions is DataOut?=transform_fct(DataIn?,XmlData?,DataIn_1,XmlData_1) where Data is an input field object, as described in [section 5.4->#sec5.4], and XmlData? the content of the xml file Imadoc, as stored in the uvmat GUI. XmlData? contains in particular the element .GeometryCalib? containing the calibration parameters, see [section 7->#geometry_calib].

### 4.6 Succession of operations:

[<doc115|right>->#top]

[field_structures<-] {5- Field objects:===

[sec5.1<-]

### Master GUI:

-'uvmat';...% master function for file scanning and visualisation of 2D fields

### Other GUIs:(function .m and associated figure .fig)

-'civ';... %function associated with the interface 'civ.fig' for PIV and spline interpolation -'create_grid';...% called by the GUI geometry_calib to create a physical grid - 'dataview';...% function for scanning directories in a campaign -'editxml';...%display and edit xml files using a xls schema -'geometry_calib';...%performs geometric calibration from a set of reference points -'get_field';...% choose and plot a field from a Netcdf file -'msgbox_uvmat';... associated with GUI msgbox_uvmat.fig to display message boxes, for error, warning or input calls -'rotate_points';...%'rotate_points': associated with GUI rotate_points.fig to introduce (2D) rotation parameters -'series';...% master function for analysis field series, with interface 'series.fig' -'set_grid';...% creates a grid for PIV -'set_object';...% edit a projection object -'translate_points';...% associated with GUI translate_points.fig to display translation parameters -'view_field';...% function for visualisation of projected fields'

### functions activated by mouse and keybord in GUI :

-'keyboard_callback';... % function activated when a key is pressed on the keyboard -'mouse_down';% function activated when the mouse button is pressed on a figure (callback for 'WindowButtonDownFcn?') -'mouse_motion';...% permanently called by mouse motion over a figure (callback for 'WindowButtonMotionFcn?') -'mouse_up';... % function to be activated when the mouse button is released (callback for 'WindowButtonUpFcn?')

### main functions used:

-'civ_matlab';...% civ programs, Matlab version (called by civ.m, option Civprogram/Matlab? in the upper menu bar) -'plot_field';...%displays a vector field and/or scalar or images -'plot_object';...%draws a projection object (points, line, plane...) -'proj_field';...%project a field on a projection object (plane, line,...) -'RUN_STLIN';...% combine 2 displacement fields for stereo PIV -'sub_field';...% combine the two input fields,

### ancillary functions:

-'calc_field';...% defines fields (velocity, vort, div...) from civx data (old conventions) and calculate them. -'calc_field_interp': defines fields (velocity, vort, div...) from civ data and calculate them for projection with linear interpolation -'calc_field_tps': defines fields (velocity, vort, div...) from civ data and calculate them with tps interpolation -calc_tps': calculate the thin plate spline (tps) coefficients for interpolation -'check_files';...% check the path, modification date and svn version for all the function in the toolbox UVMAT. -'close_fig';...% function activated when a figure is closed -'copyfields';...% copy fields between two matlab structures -'delete_object';...%delete a projection object, defined by its index in the Uvmat list or by its graphic handle 'fileparts_uvmat': splits a file name in root and indices and recognize file naming convention -'filter_tps';...% find the thin plate spline coefficients for interpolation-smoothing -'find_field_cells';...% group the variables of a nc-formated Matlab structure into 'fields' with common dimensions -find_field_cells': test field structure for input in proj_field and plot_field, group the variables into 'fields' with common dimensions -'find_file_series';...%check the content of an input file and find the corresponding file series -'fullfile_uvmat';...%creates a file name from a root name and indices. -'get_file_type': determine info about a file (image, multimage, civdata,...) -'griddata_uvmat';...%make 2D linear interpolation using griddata, with input appropriate for both Matlab 6.5 and 7

-'hist_update';...% update of a current global histogram by inclusion of a new field