Data organisation in PIVMat

Data storage

All PIV files imported in Matlab using loadvec are converted into a PIVMat specific data format. Vector or scalar fields are stored into structures. All the functions of the PIVMat toolbox are designed to operate directly with these structures.

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.

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:

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 (.VC7 files), the additional fields are:

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

v.vx(5,1)

Single scalar field

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:

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)

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

v.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:

imagesc(v.vx');

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 (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