Data organisation in PIVMat

Data organisation in PIVMat



Data storage

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.


Single fields

Single vector field

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

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


Single scalar field

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

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

Array of fields

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,

v(n).vx(5,1)
refers to the x-component of the vector field number n taken at point (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.


Matrix indexing

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:

m(row i, column j)   % Matlab convention
In PIVMat, the two components of a vector field are stored into the two matrices vx and vy of the structure v. To reference a particular element in one of those matrices, e.g. vx, you must specify the column (x) first and row (y) second:
v.vx(column x, row y)   % PIVMat convention
(the same goes for the matrix w of a scalar field).

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:

imagesc(v.vx');
Use the Matlab commands axis ij and axis xy if you want to switch from descending (default) to ascending vertical axis convention.


The history field

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.


DaVis Attributes

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-2016 PIVMat Toolbox