next_inactiveupprevious
 

UVMAT ONLINE HELP

Joël Sommeria, revised October 2005

Contents

1 Generalities:

2 File input and navigation:

3 Output data

4 view_field

5 movie

6 aver_field

7 time_series

  • Peaklocking

    • 8 fix_vel

    9 CIV

    10 check_file

    11 usr_defined

    12 makemask:

  • About this document ...

    • 1 Generalities:

    1.1 aim:

    This Matlab toolbox is designed to scan and analyse images and velocity fields. Images can be in any standard format recognized by Matlab (function imread.m of Matlab), as well as .avi movies. The velocity fields are stored in files with the netcdf format. It provides an interface to run the Correlation Image Velocimetry CIVx software of civproject. See http://www.civproject.org for further documentation and tutorial.

    1.2 The package:

    The core programme is a Matlab Graphic User interface, made of a Matlab figure uvmat.fig and an associated set of functions in the file uvmat.m. Pushbuttons and editing box in the figure start the matlab functions in uvmat.m (Callback functions). A set of auxiliary functions are called outside the main file uvmat.m.

    To install the toolbox, copy the whole directory UVMAT and read the instructions in the file 'README_INSTALL.txt' contained in this directory. It can be used without any knowledge of Matlab, but interfacing with Matlab functions allows flexibility for further data analysis. The package also contains a civ interface to run the civ software, a makemask interface to mask regions (for instance fluid boundaries), a plotgaph interface to plot results of time series and histograms. These interfaces are linked with uvmat but can be also opened directly from the Matlab prompt.

    1.3 Opening uvmat:

    Type uvmat in the Matlab prompt to display the interface. Then the location and date of the version of uvmat.m used is displayed in the central visualization window. During opening, the programme checks that all the functions called by uvmat are in the same directory UVMAT as uvmat.m, using the function 'UVMAT/check_functions'. Indeed a function with a priority path could override a function of the toolbox with the same name. This is annouced by a warning message.

    A 'TMP' directory is created on the Matlab working directory at the opening of 'uvmat'. It is used to store auxiliary data (writting access to the working directory must be provided).

    The input file data and field numbers are dispayed on the upper left. This input file name is stored in a file ('uvmat_perso.mat') created in the user preference directory of Matlab (indicated by the Matlab command 'prefdir'). The last used input file is then displayed in the browser when uvmat is opened again by the same user.

    The menu FIELDS on the right allows to select raw images, the velocity fields and their spatial derivatives, and scalar fields.

    The menu ACTION on the left allows to select the processing action. The option view_field allows to scan manually through the fields. The option movie makes an animation. The option aver_field provides a field average over a sequence of images or vector fields. The option time_series provides the velocity components versus time at any chosen point, or in a rectangular subdomain. It also provides the mean, min and max and rms velocity vs time or images over this domain, as well as the corresponding global histogram. The option civ provides access to the interface to run the civ program, including interpolation (patch) and removing of false vectors using different criteria (fix). The option fix_vel also allows to remove false velocity vectors (older programme). Finally the user can add any Matlab function and call it by its name, using the option usr_defined .

    Each action is started by the pushbutton RUN (or equivalently by pressing carriage return with the mouse over the interface), or by the pushbuttons +d and -d in the view_field mode.

    To get the section of this help file corresponding to each action, press the help button in the frame ACTION. Short help on any pushbutton or editbox is also provided by moving the mouse cursor above it. Further documentation is provided as a heading in each function file: type 'help fct_name.m' on the Matlab prompt to display it. Type 'help uvmat' to get a summary of the functions of the toolbox.

    1.4 Display and output:

    For all actions, corresponding histograms are plotted, providing probability distribution functions of image intensity or velocity components, over the chosen time ranges and region of interest. Profiles of velocity or scalar intensity along any line can be obtained by selecting the pushbutton select_line.

    A zoom can be used. The scale of image contrast and vector scale can be set by the min and max edit box. A pointer can be activated by the select pushbutton. This provides the coordinates of any point, and in case of vector fields it selects a particular vector for manual correction.

    In addition to figures, the corresponding data are made available as Matlab data files (.mat files) or put as global variables available  in the Matlab command window.

    The uvmat interface records the Matlab working directory in which it was opened. By default, it restores this working directory for each RUN action. However, when a consistent 'ImaDoc' documentation file is opened, corresponding to a project directory 'Project', it moves to the working directory Project/0_MATLAB_WORK attached to this project (it creates it if it does not exist yet). Then all the Matlab figures and output data about this project remain in this directory by default.

    2 File input and navigation:

    2.1 Nomenclature:

    A key ingredient of the interface is the use of nomenclatures, building file names form a base name 'root'', a nomenclature type 'nom_type', and field numbers: the names are generated from these parameters by a function 'name_generator.m' in UVMAT. The root name characterizes a series of images and associated velocity fields. Any sequence of analysis begins by introducing this root name in the upper left window (by opening any image or .nc file with browse or directly by typing the name followed by carriage return). The root name, nomenclature type, numbers, and file extension are automatically recognized from the file name by the browser (using the function 'name2display.m').

    The fields in the sequence are labelled by numbers displayed in the edit windows below the 'root' file name (see 2.2). The first number is the usual field number in the sequence of images (as obtained for instance from a digital photo camera), or the frame number in a movie file. The other numbers depend on the nomenclature 'nom_type', as specified below. The corresponding absolute names must include the path to the base directory, which contains the whole image series, as well as the processing results (netcdf files) in subdirectories and auxiliary files.

    Switch between the image and the corresponding velocity fields are performed when the FIELDS option is switched from images to velocity.

    File naming for images:

    File naming for netcdf velocity files (contained in a subdirectory SUBDIR)

    Other file names:

    The nomenclature is set by the functions 'name_generator.m', 'name2display.m', 'display2name.m' in UVMAT. A new nomenclature can be introduced by consistently modifying these three functions.

    2.2 Navigation among file numbers:

    The field numbers are set by the 'index' edit boxes on the upper left of the interface, below the 'root' file name display. For images, the two boxes in the first line are used. The first one on the left stands for the index i while the second one stands for j . The second line of index boxes is used to define image pairs, in association with the first line. A third line, with smaller characters, is used to indicate the last field index of the series (read from the .civ file or the movie info section).

    An image pair can be visualized as a small movie by simultaneously writting the field numbers i1 and i2, or j1 and j2 (or the letters a,b for the 'png_old' nomenclature) in each line, and selecting the checkbox '-' between the two lines of field numbers, see also 4.2. Netcdf files are similarly defined by field numbers, i1 and i2, or j1 and j2, in each line.

    You can navigate through the fields in the view_field action, setting an increment d , by the pushbuttons +d and -d. The other actions are performed among a series of field indices, defined by a first number range1, a last number range2 and the increment d. By default, navigation is performed among the indices i, as set by the check box above the first column. The bounds range1 and range2 can automatically adjust to the first and last available files in the selected range of action. If increment d is not defined, all the existing files with indices in the defined interval are selected.

    In the case of netcdf files depending on two indices i1 and i2, the range of action refers to the 'reference' indices, defined as the integer part of (i1+i2)/2. In the case of 'bursts', while navigating over i, the pair j1-j2 is either imposed (by selecting the check box between the two index lines), either free. In the later case (default option), the available pair is automatically detected for each index i of the series, and the most recent file is selected in the case of multiple choice.

    By selecting the check box above the second column, one navigates among the second indices j, (or corresponding letters a, b, c, d ). If the check boxes above both columns are selected, the operation is performed over all the fields (then run from 1 to the total number of images (nbre of bursts x nbre of images in a burst, with increment 1). This is convenient for instance to determine a background image obtained by an averaging over all the images.

    The series of file names currently selected for the run command can be displayed by the action check_files.

    If the root name filebase ends in the form [root '_xx' 'mmmm' ], where xx is a number and 'mmmm' a string of four letters beginning with m (like 'mask' or 'mean'), then the file number is taken modulo xx . This is convenient to visualize a mask for each slice or for substracting a field average calculated on each slice. The mask image can be displayed in 'uvmat' by selecting the check box mask on the upper left. with the velocity vectors if the .png file with appropriate name is available in the image directory. In case of mutiple levels, the number of slices detected (xx in the mask name) is displayed in the edit box nbslice on the bottom left.

    2.3 netcdf files:

    These contain the velocity fields and their spatial derivatives, as well as information about the CIV processing (correlation values and flags). The content of any netcdf file can be checked directly by the Matlab command ncbrowser. The vorticity, divergence, or strain are read in the same netcdf files. This information is available only after a PATCH operation has been run in the CIV software. Details about the netcdf files are provided in the .htm file files_doc.

    One of the field options civ1, interp1 and filter1, civ2, interp2 and filter2 can be chosen, using the check boxes on the left. The first CIV processing is visualized by the CIV1 option. Then filter1 and interp1 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 civ2 or interp2 to filter2, from civ1 or interp1 to filter2. If a refined CIV processing has been realised, it can be visualized by civ2, patch2, filter2. If more than two iterations have been performed, only the last two are stored, with the names civ1 and 2.

    If no field option is selected, it will be automatically chosen. For velocity, 'civ2' is chosen in priority, or 'civ1' if it does not exist. For scalar fields, like vort, 'filter2' is chosen in priority, or 'filter1' if it does not exist. This choice is motivated by the fact that civ2 results are supposedly better than civ1, that the velocity fields are most reliably defined by the uninterpolated civ fileds, while filter is needed for spatial derivatives.

    The choice of field names in the .nc file is set by the function 'varname_generator.m' of the UVMAT toolbox.

    2.4 Comparing fields:

    Two fields can be simultaneously opened and compared, using the check box - on the upper left. When this box is activated, the current input file name is copied in the window below, and the current settings of the interface are recorded. Then a second file series can be opened as usual. Then the two file series will be scanned simultaneously, according to their own nomenclature.

    If the two files are both images, their difference is introduced as the input field (they must be the same size). It can be viewed and analyzed, using the available tools for time_series and histograms.

    If the second file is an image (or scalar), while the first 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 raw image, or to relate vorticity to the vector field. This option is also activated by the check box mask, to visualize the mask as a background image in the velocity field, see Makemask for details.

    If the two files are vector fields, their difference is taken as the input field, and is then displayed and analyzed. If the two fields are not at the same points, the velocities of the second field are linearly interpolated at the positions of the first one (using the matlab function griddata) . If the two vector fields are in the same file (for instance civ1 and interp1), their difference can be also obtained without using the check box - , by just selecting them both.

    Any other operations on two fields can be performed, activating a custom function with the usr option in the ACTION menu.

    3 Output data:

    The interface provides graphic visualization, either in the interface itself , or in a distinct figure. The latter option allows to use all the figure editing tools of matlab, and to export it in appropriate format, like postcript. The default values set to 0, when it is set to any even value. The figure number used for visualization is set by the edit box window. With the default value 0, visualization is performed on the interface itself. When 'avi' is typed in this window for the ACTION movie, the animation seen on the screen is recorded as a movie with the .avi format.

    The currently displayed field is accessible from the Matlab prompt as a global variable, whose name is specified in the upper right display window. To get the current image, type global A, and to get the current velocity field, type global vec_X vec_Y vec_U vec_V.

    A whole time sequence of fields can be obtained in a data file timeseries.mat, obtained with the ACTION time_series. This option also provides time records of field statistics and global histogramms in another data file statseries.mat. Coordinates obtained with the mouse are stored in a file mousedata.mat. These data files are created in a subdirectory TMP of the current Matlab working directory.

    4 view_field ACTION

    This visualizes a single frame of the selection field in the FIELDS menu, either as an image or a vector field with arrows. This action is automatically activated when a new file is selected by the input file browser.

    4.1 Images:

    The images are matrices of integers, visualized by the image Matlab function.

    True color images are described by a matrix A(nx,ny,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 images are described by a matrix A(nx,ny,1) of integers, whose range depends on the camera dynamics (0 to 255 for 8 bit images, 0 to 4095 for 12 bit images). They are represented with grey levels, according to the colorbar displayed on the right. The luminosity and contrast can be adjusted using the min and max: the luminosity level min (and levels below) is represented in pure black, and the luminosity level max (or levels above) in pure white. Selecting the auto check box, min and max 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 unselect the option auto, and choose a lower value for max.

    Two images can be visually compared by switching back and forth between them as a small movie. This is quite useful to get a visual feeling of the image correlation. This effect is obtained by introducing two image numbers, for instance a, b in a burst, and selecting the checkbox '-' between the two lines of field numbers. Press STOP to stop the motion. The speed can be adjusted by the slider movie speed on the right.

    The image histogram is represented on the right, indicating the number of pixels versus the luminosity value. 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.

    The pixel matrix indices, coordinates, and image intensity of any point can be obtained with the mouse, using the select pushbutton, like for vectors. The whole image matrix A is available, by typing 'global A' in the matlab command window. The coordinates of the first and last pixel centers are also available, typing 'global rangx0 rangy0'.  To visualize the image by yourselves, type then 'image(rangx0,rangy0,A)'.

    4.2 Scalars:

    The div, vort, strain or other scalars are descibed by matrices A(nx,ny,1) of floating numbers, obtained from the netcdf files. A linear interpolation is used when the resolution of the data is low. The standard colorcode of matlab is used, ranging from blue (minimum) to red (maximum). Other color codes can be set by the interactive matlab menu (then display the image outside the interface, introducing an even number different from in the edit box window).

    The reading and calculation of scalars from the netcdf files is done by the function 'UVMAT/calc_scal.m'. New scalars can be defined by modifying this function. They will appear in the FIELDS menu as a submenu scalar.The same scalars can be also displayed as colors of the vectors.

    4.2 Velocity vectors:

    The vector fields are represented as arrows. The length of the arrows can be adjusted by the max edit box. For max=1, the unit vector has a unit length in the figure.

    The velocity histograms for each component are also represented. In the histogram, they are rescaled in pixel displacement to observe peacklocking (accumulation at integer values in pixels).

    Colors represent scalars associated with the vectors. With the default option 'ima_cor', the value of the image correlation (vec_C) is represented by a code with three colors. 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 on the upper right.

    Other color representations can be specified by the menu on the upper right. 'Black' and 'white' provides arrows with this fixed color. The other options provide a choice of scalars, for instance the vector norm ('norm_vec') or vorticity ('vort'). The list of available scalars is set by the function 'UVMAT/calc_scal.m'. A quasi-continuous color representation with 64 levels can be used instead of the three colors by mouse clicking the color band between the two sliders. A second click switches back to the three color representation. The color thresholds can be relative to the min-max scalar values or remain fixed, depending on the 'auto' check box on the upper right.

    If the option show flags is selected, the correlation colors are taken over by flag colors indicating dubious or false vectors.  False vectors are detected by various criteria: they are not removed from the files but marqued by flags, so that the process is reversible. By default these vectors are displayed in magenta, and they can be just removed from the view by deselecting the option magenta on. But in all cases these magenta vectors are not taken into account in processing: they are ignored in statistics or replaced by interpolation from neighboors when needed, in particular to get the fields interp or filter on a regular grid. The black color indicates some warning from the CIV process, but the corresponding vectors are taken into account in the processing (see the FIX in the civ interface or the ACTION fix_vel to remove  dubious vectors using different criteria). The display of black color can be desactivated by unselecting the option show black. Then their correlation color is seen.

    You can manually remove a vector with the mouse. First activate the zoom, then press the pushbutton select, then the mouse cursor appears. A selected vector becomes magenta. Inversely, if you select a magenta vector, it is rehabilitated and gets back its initial color.  Press the right button to remove the mouse cursor. The selections are  preserved in the data file by pressing the pushbutton record.

    You can also use the same mouse operation to display information on any vector in the text window on the upper right (there will be no change in the data if the pushbutton record is not pressed). These are the position coordinates vec_X and vec_Y, the velocity components vec_U and vec_V, the correlation vec_C, and flags vec_F and FixFlag in case of anomaly. Their meaning is explained below.

    The fields interp and filter are interpolations from several vectors, so they bear no color information (and cannot be removed by the mouse). If a first  velocity field civ1 or civ2 is substracted to a second field (by activating the two fields simultaneously or by using the pushbutton -),the colors are set by the first field, and the removed vectors of field 2 are not taken into account for the interpolation to the grid points of the first field.

    The current vector field information is available in the Command window as matlab vectors by the command 'global vec_X vec_Y ....'. Type then 'quiver(vec_X,vec_Y,vec_U,vec_V)' to plot the vector field by yourselves. To remove the false vectors, type 'global flagmagenta', then 'index=find(flagmagenta~=0)' to select the indices of good vectors, and 'quiver(vec_X(index),vec_Y(index),vec_U(index),vec_V(index))' to plot only them.

                    Code for vec_F:

    magenta vectors: these represent all the vectors removed (only available as global in Matlab, not stored in itself in the netcdf file)

    4.3 Profiles along a line:

    Profiles of velocity image intensity or scalar along any line can be obtained by selecting the pushbutton select_line on the right, which yields the mouse cursor. Draw the line while pressing the left mouse button, then click the central button to end the line. Polygonal curves can be similarly drawn by pressing several times on the left mouse button to mark angles. The line coordinates are displayed in the yellow edit boxes above the image, with the x coordinates on the top and the y coordinates on the bottom, separated by blanks. Two positions, beginning and end, are needed for a single segment. The coordinates can be also entered by hand in the edit boxes.

    Then as you use the "run" command, in addition to the whole field, a display window appears. The abscissa corresponds to the distance along the line, from its origin. For velocities, the longitudinal and transverse velocity components with respect to the line direction are plotted. The corresponding integrals, the velocity flux and circulation along the line, are written under the plot. For image, the luminosity is represented, or the luminosities of the three color components.

    In the display window all the standard matlab manipulations on figures (save, export the figure or the data...) can be done. The successive profiles are put on the same graph. Curves can be removed by the figure editing menu. To start a blank graph, just close the display window.

    A smoothing scale l can be specified by the third yellow edit box. For each point on the line, the velocity vectors in the neighborhood are taken into acount with a weight decreasing as a Gaussian function of the distance r, exp(-r/l)^2, with a cutoff outside the band delimited by the dashed lines. For images or scalar fields, values on the line are obtained by a linear interpolation, and default the default display '1 px' is shown on the edit box.

    To remove this option line profile, press again the select_line button. Then you are able to draw a new line.


    5 movie ACTION

    This shows successive views as a movie, from field range1 to range2, with a given increment. The speed can be controlled by the slider movie speed. The histogram then stands for the whole series of fields.

    This action works for any field, images, sclar, velocity vectors. The vectors can be visualized over a background image: first open the two first fields like for the 'view_field' action, then run 'movie'.

    The animation seen on the screen can be exported as an avi movie. For that purpose, type ' avi ' in the edit box window and answer the dialog box asking for the output file name.


    6 aver_field ACTION

    This provides a field resulting from the average of fields from range1 to range2, with a given increment. The result is stored in a .png file (for images) or netcdf file (for velocities). This average field can be later displayed by uvmat using the view_field option, or substracted to each field in the series uing the '-' check box on the upper left.


    7 Time_series

    The image intensity of velocity components are plotted versus time from range1 to range2, with a given increment d. Processing is limited to a rectangular region.

    The first field in the series is initially displayed, allowing to select this subregion interactively. For a first use, answer 'No' to the question 'range of analysis OK', then press the button set_rect above the field and draw the rectangle with the mouse (this requires the matlab image processing toolbox). Alternatively, the coordinates can be edited in the DOMAIN OF ANALYSIS window, with the format 'r[x1 x2 y1 y2]', with x1 and x2 the x coordinates, y1 y2 the y coordinates defining the four rectangle corners. Press carriage return to record the change, then the rectangle must appear in the field. When you are satisfied, answer 'Yes' to the question 'range of analysis OK'

    For images, the mean value, min max and root mean square of the image intensity over the selected region of interest are displayed versus time. By selecting a point on the curves with the mouse, using the select pushbutton, one can get the  corresponding time index and time value, displayed in the upper right text window.

    For velocity, the mean value of each component and the correlation are displayed versus time. A new interface, 'plotgraph', is displayed at the end of the processing, allowing to plot the other quantiites versus time, as well as their global histograms over the series. The removed vectors are ignored in the statistics, and the velocity is put to zero on the curve if none of the selected vectors is good in the selected subdomain..

     The whole time series is available in the file TMP/timeseries.mat, if the initial question 'only the global statistics' is answered by 'No'. This is therefore a convenient way to extract data from the files.  For images the ranges x12 and y12 in x and y coordinates are stored, data are stored as well as a vector of times, and an array A(timeindex,yindex,xindex) of the (sub)image versus time. For velocities, the file timeseries contains index , the selected list of vector indices, or x12 and y12, the selected region of interest. Then the data time Xtime Ytime Utime Vtime Ctime Ftime provide the vector properties as arrays of timeindex and vector index.

    The results are stored in the file 'statseries.mat'. For velocity , the fields are  .index (list of selected indices) or  x12, y12 ranges of the region of interest in x and y directions. time, Umoy, Vmoy, rms, Umin, Umax, Vmin, Vmax  represent the series of times, mean values in u and v, the square root of the mean u^2+v^2.  Uhist Vhist Chist reprent the global histograms of velocity components, obtained at values Uval Vval Cval. To plot for instance the histogram of the corelation, type 'load statseries Cval Chist', and 'plot(Cval,Chist)'.

    For images or scalars, the image mean, root mean square, min and max and histogram are stored as Amoy Arms Amin Amax Aval Ahist respectively.

    Peaklocking errors:

    By selecting the press button 'peaklocking' on the 'plotgraph' interface, you smooth the current velocity histograms while preserving its integral over each unity (in pixels). This appears in red. Then an estimate of the peaklocking error is obtained by comparing the initial histogram to the smooth one.

    8 fix_vel

    This option flags for removal velocity vectors according to various criteria.
    1) With a single civ1 or civ2 field selected, the program removes vectors with different values of vec_F and correlation smaller than the threshold set by the first slider (red vectors). Select the options on the menu ( type the Control  key to select several choices). For civ1 results, the standard choice is to remove all vec_F except vec_F= 2 (Hart), and for civ2 all vec_F (the option Hart is not used then).
    2) With a civ field selected and a second field, for instance filter, you can remove all vectors whose difference with the second field exceeds a threshold.


    rmq: These operations can be now performed wiith the civ interface.

    9 civ

    The civ interface processing can be directly opened by the civ command on the Matlab prompt. Then a .civ file should be enter to begin. It can be also opened by uvmat with the civ ACTION.. With the fields option images it sets the interface at the default starting operation civ1. With the other fields options, it detects the state of processing of the existing netcdf files, and proposes the next operation (fix1, patch1, civ2...). A third way of opening the interface is just to open the Matlab image (.fig file) stored after each processing in the directory of the .civ file. Then just edit it and run a new calculation.

    First check the root name in the top edit box, and the series of fields, as well as the scaling pxcmx pxcmy (pix/cm) which should be automatically read in the .civ file. Then set the chosen series of operation by the check boxes on the left; The corresponding menus appear.

    CIV1: The main parameters is the chosen image pair in the left menu, the size of the correlation box (ibx, iby), the search range defined by its size in pixels (isx, isy) and a systematic shift (shift x,y). The default value 21x21 is generally good, use a larger size for images with few particles, use an elongated box (e.g. 11x41) to optimize the resolution in one direction (for instance in a boundary layer). The search parameters (isx, isy,shift x,y) can be estimated using the press button calcul search range. First introduce the estimated minimum and maximum values of each velocity component u and v. The result depends on the time interval of the image pair. Change the selected image pair if the maximum displacement (ibsx-ibx)/2 is too small (lack of precision) or too large (bad image correlations and risks of faulse vectors). A good typical displacement is 5-10 pixels. A parameter rho controls the smoothing of the image corelation curves used in civ, the default value 1 is generally used.

    The grid determines the central positions of the correlation boxes (in pixels). A default regular grid can be set by the meshes dx and dy (in pixels). A custom grid can be stored in a text file, and selected by the GET_GRID push button. This is convenient to limitate the processing to a subregion or to fine tune the resolution. See the site http://www.civproject.org/documentation for the file format. The function MISC_FCT/makegrid.m in UVMAT creates an example. An alternating way to select a subregion is to use a mask image. If a mask image with an appropriate name is found in the image directory, it wil be detected by the pushbutton GET_MASK, and the indication xxmask appears in the edit box. xx is the number of slides (1 for a single mask). Else the menu Makemask appears (see the corresponding help). The velocity results are stored in the subdirectory set by SUBDIR_CIV1.

    FIX1: used after civ1 to remove some false vectors using different criteria. Use generally the default options on vec_F. A threshold on the image correlation values (vec_C) can be introduced. Use first a small threshold 0.2, look at the resulting fields, by looking at red vectors in the view_field menu. If many red vectors appear, redo the fix operation with a higher threshold. A threshold on the velocity values can be also introduced: erratic zero velocity vectors can be indeed produced by a fixed image background. A mask image can be also introduced. It has the same effect as the one used in civ1, but the removed vectors are kept in memory, and labelled as false.

    PATCH1: interpolates the velocity values on a regular grid with a smoothing parameter rho. This also provides the spatial derivatives (vorticity, divergence) needed for the refined processing civ2. The numbers of grid points in x and y are set by nx and ny. The vectors which are too far from the smoothed field (erratic vectors) can be eliminated, using a threshold expressed in pixel displacement. The thin plate spline method must be done by subdomains for computational saving, use the default value 300.

    CIV2: provides a refined calculation of the velocity field, using the civ1 result as previous estimate. The search range is determined by the civ1 field so there is no parameter. Use the option decimal shift to reduce peaklocking effects (advised). The option deformation is useful in the presence of strong shear or vorticity. Then image deformation and rotation is introduced before calculating the correlations. The other parameters (rho, ibx,iby, grid, mask) are used like for civ1 (take the same by default). The image pair for civ2 can be different than the one used in civ1 to get the first estimate. It is generally advised to use a moderate time interval for civ1, to avoid false vectors, and to take a larger intervel for civ2, in order to optimize precision. As civ2 already knows where to look and takes into account image strain and rotation (with the option deformation) it allows for higher time intervals.

    FIX2: like FIX1, except for the different flags vec_F provided by civ2. Use the default options.

    PATCH2: like PATCH1

    Further iterations: improvements can be obtained by further iterations of the civ2-fix2-patch2 process. Open again the interface, and consider the previous civ2 result as the prior guess civ1. It will be recopied and relabelled as civ1 in the new netcdf file produced.

    RUN and BATCH: RUN controls the computation from the Matlab window, which you cannot use until the computations are finished, while BATCH sends the same computations as background computing tasks in the network. In the first option, the civ1 computations are first perfomed fo all the fields, then the fix1, then the patch1.... In the batch option, the whole series of computations is performed for the first field, and then repeated for each successive field.

    In both cases, the status of the computations can be checked by opening .cmx and .log files, using the uvmat browser or any text editor. These files are writtent in the same subdirectory as the netcdf result files. Each .cmx file contains the set of parameters used for a civ computation. It is written by the civ interface just before ordering the computations. By contrast , the .log file is produced after completion of the computations, and it contains some information on the process, including possibly error messages.

    10 check_files

    Gives the series of files selected for processing and checks their existence. The oldest modified file is indicated, which is useful to detect whether any file in a civ processing is missing (then the oldest file is not updated).

    For netcdf files, the last operation made (civ1, fix1, patch1, civ2, fix2, patch2) is indicated. The details of each netcdf file can be dispalyed by selecting it with the mouse on the list.

    11 usr_defined

    This action calls any user defined function by its name, acting on the series of fields defiend for ACTION. Any processing function can be extracted from uvmat, and modified as a user defined function without any risk of perturbation for uvmat. To use it, you may need to copy some subfunctions of uvmat outside its file, to be recognized by usrfunction.

    Another kind of user defined functions can be used to make a systemetic processing on each field just after reading. It is activated by the check box usr in the ACTION menu. An example is to transform a color image in a balck and white image obtained by a combination on the three colors (see usr_fct.m in IMA_TRANSFORM). The function can also act on two fields simultaneously, checking the sub option on the upper left.

    Some examples of usr_defined functions are in the subdirectory UVMAT/USR_FCT.

    List of available functions:

    -sub_background: used to removed a mean background to the images. This is useful before CIV processing when some fiked features are visible in the background (when the laser sheet is close to the bottom).

    -aver_multilevel: average velocity fields over nbslice levels (at each laser position)

    -uvprofile: calculate the mean velocity profile and Reynolds stress u'v' along a band, averaged over the series of fields.

    -view_ima3D: provides a perspective view of a 3D image defined by a series of slice 2D images. The isosurfaces of the scalar field are represented.

    -part_stat: count particles and provides their density and luminosity histogramm


    12 Makemask:

    Mask files are used to restrict the domain of CIV processing, to take into account fluid boundaries or invalid image zones. They must be stored as .png images with 8 bits, with names [filebase '_xxmask_' 'filenumber' '.png'], where xx is the number of masks (nbslices) used when the series of fields corresponds physically to a set of nbslices positions. The mask filenumber used is the image field number modulo nbslices. Use xx=1 in the default case of a fixed position and a single mask. Masks can be made by the interface makemask or by other image processing software.

    This function opens a GUI to make mask. It can be called directly from the Matlab prompt by the commande makemask, or from the interface civ with the press buttons GET_MASK when an appropriate mask name is not already availbale. First open an input image file name with the browser, or the edit box and carriadge return. From the image name, a corresponding mask name is proposed in the lower edit box. It should be edited if a series of masks is made, in case of mutipositions (number nbslices) of the laser sheet in a series. The names must be [filebase '_xxmask' 'filenumber' '.png'], where xx is the number of masks (nbslices). The mask filenumber used is the image field number modulo nbslices. The filenumber can be incremented by the NEXT press button.

    You can adjust the image luminosity by the contrast edit box.

    With the push button image_maxi, you can see the image maximum along the y direction, which helps finding boundaries. This is just a visual aid.

    Holes can be made by the press button mask_hole which allows to draw a polygon on the image (the matlab image processing toolbox is needed). The inside of this polygone is masked.

    An alternative way is convenient to remove corners. The mask is made by manually drawing straight lines, using the standard matlab menu on the top of the figure. First draw a set of lines defining a convex polygone boundary, in the clockwise direction to mask the outside. By selecting a line with the mouse, then clicking the pushbutton mask_left , the left side of the line is masked (to select the other side the line has to be drawn in the opposit direction). By selecting successively all the lines, the outside of the polygone is masked. The advantage of this method is that lines persist on a series of images, and they can be easily adjusted in position. But only convex domains can by made by this method (no holes or concavities).

    Press save_mask to save the mask. The saved mask is then displayed. A new image can be then entered.

    About this document ...

    UVMAT HELP

    This document was generated using the LaTeX2HTML translator Version 2002 (1.62)

    Copyright © 1993, 1994, 1995, 1996, Nikos Drakos , Computer Based Learning Unit, University of Leeds.
    Copyright © 1997, 1998, 1999, Ross Moore , Mathematics Department, Macquarie University, Sydney.

    The command line arguments were:
    latex2html -no_subdir -split 0 -show_section_numbers /tmp/lyx_tmpdir24503WtIvn5/lyx_tmpbuf24503v5Erql/uvmat_doc.tex

    The translation was initiated by Joel Sommeria on 2002-12-04

    next_inactiveupprevious
    Joel Sommeria 2002-12-04