| Data organisation in PIVMat |
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.
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 |
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.