Data organisation in PIVMat |

In PIVMat, a vector or scalar field is stored into a *structure*. A *structure*
is one of the data type provided by Matlab, which allows the user to store several
variables (named 'fields') into a single variable. For instance, `v.x` refers
to the variable (field) `x` stored into the structure `v`.

The various features of a vector field, such as the two matrices of the vector components, the axes, labels, title etc., are stored into a single structure. This is because handling a single variable instead of a list of variables is very convenient for a number of operations. If you are not familiar with structures, please refer to the Matlab documentation.

All the functions of the PIVMat toolbox are designed to operate directly with those structures.

For instance, in order to display a vector field, the structure
`v` is given as the unique input parameter to the function `showf`,
which is able to display the vector field with the right physical coordinates
and the right axis names and units.

When extracting physical information from a raw vector field, the physical
units are automatically taken into account. For instance, if the vector field
is a velocity field in `m/s`, on a spatial grid in `mm`, then the vorticity (curl)
will be expressed consistently in `1/s`.

See also the Frequently Asked Questions, which provide some examples of how to access and process the data of PIVMat structures.

The structure containing a vector field is usually noted `v` in this
documentation. It is typically obtained from the function `loadvec`
(see Importing data into PIVMat).

The structure `v` contains serveral 'fields' (sub-variables). Below
are listed the basic fields which are common to all PIVMat vector field structures:

Field name |
Type |
Description |

vx, vy (vz) |
2 or 3 M-by-N matrices | 2 or 3 matrices containing the x, y (and
possibly z) components
of the vector field |

x, y |
A 1-by-M and a 1-by-N array | 2 arrays containing the physical coordinates of each x
and y collocation points. |

namex, namey |
strings | Name of the x and y axis (usually 'x' and 'y'). |

unitx, unity |
strings | Unit of the x and y coordinates (usually in millimeters, 'mm'). |

namevx, namevy (namevz) |
strings | Name of the x and y (and possibly z)
components of the vector field (usually 'u_x', 'u_y' and 'u_z'). |

unitvx, unitvy (unitvz) |
strings | Unit of the x and y (and possibly z)
components of the vector field (usually 'm/s'). |

ysign |
string | Specifies whether the y axis is upward or downward. The 'upward'
mode corresponds to Matlab's axis xy (cartesian) mode, with the coordinate system
origin in the lower left corner. The 'downward'
mode corresponds to Matlab's axis ij (matrix) mode, with the coordinate system
origin in the upper left corner. |

pivmat_version |
string | Version number of the PIVMat toolbox at the time at which the structure
has been created, for instance by the loadvec command. This information
is useful for compatibility. |

source |
string | Specifies the origin of the vector field: 'DaVis', 'DynamicStudio', 'MatPIV' etc. |

name |
string | Name of the input file. For DaVis file, the name is usually in the form
'B00001.VC7'. |

setname |
string | Name of the directory which contained the input file. |

history |
cell array | This cell array tracks the sequence of successive operations which have
been performed on the field. Each time an operation (e.g. filtering, scalar
extraction) is performed on a field, the corresponding Matlab command string is
added to this cell array. For instance, history{n} is the string
of the nth operation performed on the field. The first operation
is usually a loadvec command. |

In addition to these generic fields, a number of specific fields may also be present,
which depend on the source type. For vector fields originating from DaVis (`.VEC`
and `.VC7` files), these additional fields are:

Field name |
Type |
Description |

choice |
1-5 array | Contains the number of vectors computed as 1st, 2nd, 3rd, 4th choice, and the number of interpolated vectors. |

Attributes |
String | Contains several informations from DaVis. This string is composed
of independent lines, each specifying the value of a DaVis variable,
such that axis calibrations, date, acquisition time, etc. The values
of those variables may be obtained using the function getattribute. |

Simply type `v` to see the content of the structure:

>> cd sample/jet >> v=loadvec('B00001.VC7'); >> v v = x: [1x128 double] y: [1x128 double] vx: [128x128 double] vy: [128x128 double] choice: [0 0 0 0 15399 985] unitx: 'mm' unity: 'mm' namex: 'x' namey: 'y' unitvx: 'm/s' unitvy: 'm/s' namevx: 'u_x' namevy: 'u_y' pivmat_version: '1.90' ysign: 'Y axis upward' Attributes: [1x585 char] name: 'B00001.vc7' setname: 'jet' history: {'loadvec('B00001.vc7')'} source: 'DaVis 70'

In order to access to the value of a given field stored in the
structure `v`, say `unitx`, simply type

Similarly,v.unitx

refers to the x-component of the vector at point (5,1).v.vx(5,1)

A scalar field, usually noted `s` in this documentation, can be obtained
in two ways:

- Directly by loading an image field using
`loadvec`, for instance a Davis'`.IMX`or`.IM7`file:im = loadvec('B00001.IM7');

- By extracting a scalar quantity from a vector field
`v`, using`vec2scal`(vector-to-scalar), such as the divergence, vorticity, energy etc:v = loadvec('B00001.VC7'); r = vec2scal(filterf(v), 'rot');

The content of a scalar field is very similar to that of vector fields:

Field name |
Type |
Description |

w |
M-by-N matrix | Scalar field |

x, y |
A 1-by-M and a 1-by-N array | 2 arrays containing the physical coordinates of each x
and y collocation points. |

namex, namey |
strings | Name of the x and y axis (usually 'x' and 'y'). |

unitx, unity |
strings | Unit of the x and y coordinates (usually in millimeters, 'mm'). |

namew |
string | Name of scalar field, typically generated by vec2scal (e.g. 'div', 'rot'...). |

unitw |
string | Unit of the scalar field, typically generated by vec2scal (e.g. 's^{-1}', 'm^2 / s^2'...). |

ysign |
string | Specifies whether the y axis is upward or downward. The 'upward'
mode corresponds to Matlab's axis xy (cartesian) mode, with the coordinate system
origin in the lower left corner. The 'downward'
mode corresponds to Matlab's axis ij (matrix) mode, with the coordinate system
origin in the upper left corner. |

pivmat_version |
string | Version number of the PIVMat toolbox at the time at which the structure
has been created, for instance by the loadvec command. This information
is useful for compatibility. |

source |
string | Specifies the origin of the vector field: 'DaVis', 'MatPIV' or 'Optical Flow'. |

name |
string | Name of the input file. For DaVis file, the name is usually in the form
'B00001.VC7'. |

setname |
string | Name of the directory which contained the input file. (This is relevant for DaVis, where the vector files are stored into directories named 'sets'. |

history |
cell array | This cell array tracks the sequence of successive operations which have
been performed on the field. Each time an operation (e.g. filtering, scalar
extraction) is performed on a field, the corresponding Matlab command string is
added to this cell array. For instance, history{n} is the string
of the nth operation performed on the field. The first operation
is usually a loadvec command. |

In addition to these generic fields, a number of specific fields may also be present, which depend on the source type.

Simply type the name of the scalar field structure to see its content:

>> cd sample/jet >> v=loadvec('B00001.VC7'); >> rot=vec2scal(v,'rot'); >> rot rot = x: [1x128 double] y: [1x128 double] choice: [0 0 0 0 15399 985] unitx: 'mm' unity: 'mm' namex: 'x' namey: 'y' pivmat_version: '1.90' ysign: 'Y axis upward' Attributes: [1x585 char] name: 'B00001.vc7' setname: 'jet' history: {2x1 cell} source: 'DaVis 70' w: [128x128 double] namew: 'Curl' unitw: 's^{-1}'

It is possible to handle more than one field (e.g. a movie), either vector
or scalar, into a single variable. For this, PIVMat makes
use of a *structure array*, which is an array whose elements are structures.

Array of vector fields are usually obtained from the function
`loadvec`:

>> cd sample/jet >> v=loadvec('*'); >> v v = 1x3 struct array with fields: x y vx vy choice unitx unity namex namey unitvx unitvy namevx namevy pivmat_version ysign Attributes name setname history source

If `v` is a *structure array* containing an ensemble of vector fields,
then you simply access to the field number *n* by typing `v(n)`, as
for classical arrays. `v(n)` is a structure, whose elements are that
described in the previous section. For instance,

refers to the x-component of the vector field numberv(n).vx(5,1)

Most of the PIVMat functions are designed to work directly with arrays
of fields. If an array of fields is given as an input parameter to `showf`,
then the movie is displayed. See the help of `showf` for
more information about the display options of a movie (loop mode, frame per second, etc.),
or to export the movie into an `AVI` file.

The operations such as scalar extraction (`vec2scal`), filtering etc.
work for each element of the array of fields. It is essentially equivalent to call
the function for each element `v(i)` in a `for`-loop.

The statistical operations (spectra, histograms, structure functions etc.) return statistics averaged over all the elements of the array of fields.

**Different matrix indexing conventions are used in Matlab and PIVMat!**

To reference a particular element in a matrix `m`, in Matlab you must
specify the **row (i) first** and **column (j) second**:

In PIVMat, the two components of a vector field are stored into the two matricesm(row i, column j) % Matlab convention

(the same goes for the matrixv.vx(column x, row y) % PIVMat convention

The Matlab imaging tools, such that `image`, `contour`,
`pcolor` etc., use the `(i,j)` matrix indexing convention.
In this convention, the vertical axis (first index `i`) is descending
(top to bottom).

On the other
hand, the PIVMat imaging tool (`showf`) uses the `(x,y)` matrix indexing convention.
Here, the vertical axis (second index `y`) is either ascending (bottom to top)
or descending (top to bottom),
depending on the variable `v.ysign`.

If you want to perform your own data visualization using Matlab functions
from PIVMat structures, you will need to *transpose* the matrices (using
the prime: `m = v.vx'`). For instance:

Use the Matlab commandsimagesc(v.vx');

Among the fields available in a PIVMat structure, one is named `history`.
This field is a *cell array of strings*, which contain the succession
of operations performed on a given vector or scalar field. At each new operation,
a new string is added in this cell array, so that it is possible to check
which operations have been performed.

See the Frequently Asked Questions page, item no. 13.

Vector fields imported from DaVis (`VEC` and `VC7` files)
contain a string variable, named `Attributes`, which contains a number
of useful information from DaVis:

>> v=loadvec('B00001.VC7'); >> v.Attributes ans = _SCALE_X=0.115125;-134.395004;mm; _SCALE_Y=-0.115125;234.199997;mm; _SCALE_Z=1.000000;0.000000;pixel; _SCALE_I=2.878120;0.000000;m/s;velocity _SCALE_F=1.000000;0.000000;frame; _TIME=14:53:49.703 AttributeDisplayFrameInfo=SetupDialogBufferAttrFrameInfo(-1) ExpPathValue_Date=050728 ExpPathValue_Time=142639 FrameScaleI0=2.87812;0;m/s;velocity FrameScaleZ0=1;0;pixel; FrameScaleY0=-0.115125;234.2;mm; FrameScaleX0=0.115125;-134.395;mm; FrameDt0=40 us FrameProcessing0=0 AcqTimeSeries0=1529976 µs AcqTime0=4040 CameraName0=1 * 1 PeakRatioMode0=0 PivCalculationTime=11941.3 _DATE=28.07.05

In order to extract useful information from this lengthy string,
use the function `getattribute`:

>> attr = getattribute(v); >> attr.AcqTimeSeries0 ans = 1529976 µs

You can also use the following shorter syntax:

>> time = getattribute(v,'TIME') time = 14:53:49.703

If `v` is an array of field, then the output `time`
is a cell array of strings:

>> v=loadvec('*'); >> time = getattribute(v,'TIME') time = '14:53:49.703' '14:54:03.140' '14:54:15.296' >> time{1} ans = 14:53:49.703

2005-2017 PIVMat Toolbox