Data organisation in PIVMat

Visualization tools

All visualizations of vector or scalar fields, either for still images or movies, are based on the PIVMat function showf (which means show field).

When the first input parameter of showf is a single PIVMat structure, it is displayed as a still image. When it is a structure array, it is displayed as a movie (see the page Data Organization to learn more about PIVMat structures and structure arrays.)

This documentation describes how to control 'in live' the movies displayed by showf, and lists all the available input parameters.

Live control

During the visualization of a movie, several 'live' controls are possible by pressing the following keys:

Keys Description
Space bar Make a pause (press space bar again to resume)
* and / Stretch/compress the colormap
+ and - Increase/decrease the vector arrow length
Right arrow, or n Next frame.
Left arrow, or b Previous frame.
g or j Jump to a specified frame.
Esc or x or q or Ctrl+C Exit

Input Parameters of showf

The general syntax of showf is:

showf(V, 'PropertyName1', PropertyValue1, 'PropertyName2', etc.)

The list of available PropertyName/PropertyValue pairs is given in the table below.

There are however two convenient shortcuts:

PropertyName PropertyValue Description
Background BGMODE specifies the scalar field, computed from the input vector field, displayed in the background. BGMODE may be 'norm', 'rot', 'div', 'ken', etc. See vec2scal for a complete list of available backgrounds.
Spacing [NX NY] or N displays 1 vector every NX (resp. NY) in the X (resp. Y) direction. If only one number N is specified, take NX=NY=N. By default, NX and NY are such that 32 vectors are displayed in each direction.
ScaleArrow SA Specifies the scale for the vector arrows. SA is such that a vector of norm L in vector units, e.g. m/s) has length SA*L (in units of space coordinates, e.g. mm). If not specified, or if SA = 0, a default value is automatically chosen. Use the keys '+' and '-' to modify this parameter during a movie. If SA < 0, the arrows are not displayed.
Colorvec COL Color of the vector arrows. COL may be any Matlab compatible color specification: a string ('r', 'k' etc) or an array of 3 numbers in the form [R G B].
CMap COL Specifies the colormap, where COL may be a string ('gray', 'jet', etc.) or a m-by-3 matrix of real numbers between 0.0 and 1.0. See the reference page for COLORMAP.
CLim [CMIN CMAX] specifies the min and max of the colormap. Use the keys '*' and '/' to modify this range during a movie.
CLim CMAX specifies the max of the colormap; the min is taken as 0 or -CMAX, depending on the nature of the scalar field (strictly positive or not).
CLim 'all' or 0 normalize the colormap using the min and max of all the scalar fields (by default).
CLim 'each' or -1 normalize the colormap using the min and max of each field taken one by one.
Contour n Displays n contour lines
Contourf n Displays n filled contour lines
Streamline [NX,NY] display streamlines. The starting points of the streamlines are chosen on a uniform grid with spacing [NX,NY]. (NX=NY=16 by default)
Loop - loop the movie (press 'esc' to exit)
Backward - plays the movie backward
Delay n waits n seconds between each frame
Pause - directly enter in the 'pause' mode (press 'space' to exit the pause mode)
Title TIT specifies the string TIT of the title displayed above the figure. The string TIT may contain the following commands:
- '%n' : name of the field
- '%s' : name of the set (directory where the fields are stored)
- '%i' : field number in the set
- '%t' : time in sec. (see getpivtime)
- '%t0' : time, with origin t(1)=0.
By default, TIT = '%s [#%i]'.

The following additional PropertyName/PropertyValue pairs is available only for scalar fields:

PropertyName PropertyValue Description
Contour3 n Displays n contour lines beneath the 3D view of the scalar fields(n=8 by default)
Surf - 3-D shaded surface (see SURF)
Surfc - 3-D shaded surface with a contour plot beneath the surface (see SURFC)
Surfl - 3-D shaded surface with colormap-based lighting (see SURFL)
Mesh - 3-D wireframe parametric surface (see MESH)
Meshc - 3-D wireframe parametric surface with a contour plot beneath the surface (see MESCHC)
ResetCameraSettings - refresh the camera angle, view etc.
Command STR Specifies a string STR to be evaluated at each frame. STR may contain any Matlab commands, groups of commands (separated by ;), user-defined functions etc.


See the documentation of showf and the FAQ for examples.


2005-2016 PIVMat Toolbox