PIVMat Release Notes

Major improvement

• New file formats accepted by loadvec:
  • Insight (TSI) (VEC files)
  • PIVLab (W. Thielicke) (MAT files)
  • PIV plugin (Qingzong Tseng, 2015) for ImageJ (NIH) / Fiji (TXT files)
  • OpenPIV (R. Gurka & A. Liberzon) (VEC, TXT files)

Compatibility issue

• Old VEC files from DaVis (versions 6 and earlier) are no longer supported. Use VC7 format instead (introduced in Davis 7). If you have old DaVis VEC files, use PIVMat 4.10 and convert them in MAT files using vec2mat.

Bug fixes

• showf: Option 'colorvec' (to change the color of the vector arrows) now works properly

Major improvements

• The creation of movies using movie2avi is no longer supported by Matlab (since 2016). Movies using showf are now created using Matlab's videoWriter objects (see the new option 'savevideo' in showf).
• loadvec: import of AVI and MP4 movies is now supported.

New functions

• im2pivmat: Convert an image into a PIVMat structure.
• spatiotempf: Spatio-temporal diagram.
• timederivativef: Time derivative (central finite difference).
• probeaverf: Time series of a probe averaged over a rectangular area.

New features

• showf: new options 'hprofile', 'vprofile', to add horizontal or vertical profiles of scalar fields embedded in the figure.
• extractf: allows to select a rectangle using the mouse.
• probef: allows to select more than one probe point. Allows to select probe point(s) using the mouse.
• operf: now includes field binarization (e.g., keeps only scalar values satisfying F >= Fc, where Fc is a threshold).
• tempfilterf, tempspecf: run faster (x4).
• imvectomovie: movies are now generated from VideoWriter objects.

Minor changes

• averf: The 2nd and 3rd output parameters of averf are now the standard deviation STD and root-mean-square RMS respectively, in agreement with the output parameters of statf. Definitions: STD = <(u-< u >)^2>^(1/2), and RMS = < u^2 >^(1/2), where <...> denotes a temporal average.
• histf and histscal_disp: better default binning for fields with non-zero mean.

Bug fixes

• azprofile: Argument NA now properly taken into account.
• tempspecf: now works properly when fields contain zero or NaN data.
• statvec_disp: now uses the field data for the labels and legends.

New functions

• tempfilterf: Applies a (Fourier) temporal filtering to a time series of vector or scalar fields, for instance a band-pass / low-pass / high-pass filtering. In case of a band-pass filtering at a single frequency (Dirac band-pass), this allows to reconstruct the spatial structure of a given eigenmode. It is also possible to remove oscillations, due to unwanted vibrations in an acquisition system.
• spatiotempcorrf: Computes the spatio-temporal correlation of a time-series of scalar fields. This is useful to detect the convective velocity of a flow pattern (e.g., a wave).

Bug fix

• Warning removed for obsolete function nargchk in Matlab R2016a (thanks Antoine Hector).

Major improvements

• PIVMat is now compatible with the new release ReadIMX 2.x for DaVis files.
• Beta test: PIVMat now supports DAT and MAT files exported from DynamicStudio (Dantec). See loadvec for details.

New functions

• probef: Record the time evolution of a probe in a field.
• maskrectf: Mask a rectangular area in a vector/scalar field (thanks N. Machicoane).
• azprofile: Azimuthal profile (profile along a perimeter).

Minor change

• showf: option 'scalearrow' with SA<0 does not display the vector arrows (thanks N. Machicoane).

Bug fix

• File selection by dialog box (using loadvec without input argument) works.

Minor improvement

• showf and vec2scal: new options 'eps2d', 'eps3d', 'epsaxi' (squared strain rate, = dissipation rate / viscosity) for 2-component fields, 3-component fields, and 3-component fields with axisymmetry with respect to the vertical (y) axis.

Bug fixes

• surfheight: option 'remap' (for parallax corrections) now works correctly with array of fields, and with fields of size odd.

New file format supported

• loadvec now accepts MAT files from DPIVSoft (Meunier & Leweke, Exp. in Fluids 35 (5), 408-421, 2003).

Bug fixes

• averf now computes correctly the RMS fields containing 0 data (thanks M. Bujalski).

Bug fixes

• The y-component (i.e., vertical) of the velocity was inverted for 3-component vector fields having an ascending y axis (thanks M. Bujalski).
• medianf: the 4 corner matrix elements were set to zero (this bug actually originates from the function medfilt2 from Mathworks' Image Processing toolbox). The corner elements are now given by the average of the closest neighbors.

New function

• stresstensor: computes the Reynolds stress tensor from 2- or 3-components velocity fields.

Minor change

• vsf now works with the Parallel Computing toolbox (thanks Antoine Campagne).

Compatibility issue

• By default, subaverf now subtracts the 'ensemble' (or 'temporal') average. In order to subtract a 'spatial' average instead, specify the second input parameter AXIS.

Major change

The PIVMat toolbox is now compatible with 3-components fields from DaVis (e.g. from stereo-PIV). Typical use:
showf(v,'uz'); displays the 3rd component as background
showf(v,'norm3d'); displays the 3D norm as background
uz = vec2scal(v,'uz'); generate scalar fields given by the 3rd component.
See vec2scal for the new available 3D-fields to scalar conversions. Most of the functions are compatible with 3-component fields.

New functions

• convert3dto2df: Convert 3D vector fields to 2D vector fields.
• multivortex: Generate velocity fields containing randomly distributed Burgers vortices.

Compatibility issues

• Scalar fields computed from spatial derivative using 1st order finite difference (denoted by rot1, duxdy1 etc.) have been removed. Now all spatial derivative are computed from 2nd order differences (denoted by rot, duxdy etc.)
• In previous releases of PIVMat, option 'uz' in showf or vec2scal was equivalent to 'uy'. Since PIVMat 3.00, for compatibility with 3-component fields, option 'uz' now specifies the 3rd component of the vector field.

New function

• tempcorrf: Temporal correlation function of vector or scalar fields.

Minor change

• The normalization of the vector arrows in showf is simplified. Option 'ScaleArrow' now specifies the vector normalization directly in absolute units. Option 'ScaleMode' has been removed (the previous behaviour 'absolute' is now by default).

Bug fix

• Transverse structure functions of odd order are now correctly defined in vsf (thanks Basile)

New documentation

• The new page Visualization tools describes how to control 'in live' the movies displayed by showf, and lists all the available input parameters.

New feature

• Keys '+' and '-' allow to increase/decrease the length of the arrow in live during movies (see showf).

Compatibility issue

• showvec and showscal have been removed. These functions are replaced by showf, which applies for both vector and scalar fields.

New function:

• matrixcoordf: Returns the matrix-coordinates of a point in a field.

Minor upgrade:

• DAT files exported from VidPIV (Oxford Laser) are now accepted.

Bug fix:

• The window header is no longer blinking when displaying movies of vector or scalar fields (this bug was only present for non-docked windows).

New functions:

• remapf: Remap vector/scalar fields to a new grid. This function allows the user to increase/decrease the resolution (linear interpolation, similar to resizef), but also to truncate/enlarge a field. This is useful to compare or perform operations on fields obtained with different settings/calibration.
• setoriginf: Redefine the origin (0,0) of fields.
• changefieldf: Modify attributes in PIVMat structures (e.g., rename the axis, change the title, change the axis calibration, etc.)
• imvectomovie: Create an AVI movie from a large set of files (compatible with all PIVMat compatible files, including DaVis IM7 and VC7 and other formats).

Minor changes:

• tempspecf:
  • Points containing zero or NaN values are not considered in the computation of the temporal energy spectrum (thanks Antoine).
  • Only the peak numbers of the highest peaks are displayed (this feature avoids producing too heavy figures).
• addnoisef now adds a normally-distributed (instead of uniformly-distributed) white noise.
• New operations available in operf: real, imag, conj, etc.
• surfheight (for Free-Surface Synthetic Schlieren applications): new implementation of the remap procedure, which now corrects properly for parallax distorsions.
• The directory name ('setname' field) is no longer displayed in the title of showvec and showscal when it is empty.

Bug fix:

• loadvec accepts .SET files again (this feature was buggy in v2.01)
• vec2scal computes correctly the norm and energy for complex vector fields.

Bug fix:

• loadvec is now compatible with the new releases (Dec. 2010) of the ReadIMX package. When importing DaVis files, the PIVMat toolbox is now compatible with all platforms and Matlab releases supported by the ReadIMX package (thanks A. Mishra).

New function:

• flipf: Flip vector/scalar fields about vertical or horizontal axis.

Compatibility issue:

• loadset has been removed. Use loadvec with wildcards (*) instead.

New Feature:

• Two new documention pages: Data organisation in PIVMat and Importing data into PIVMat.

New functions:

• resamplef: Re-sample a time series of vector or scalar fields using linear interpolation (e.g., re-sample the fields with a different sampling frequency).
• phaseaverf: Performs a phase average from a time series of vector or scalar fields (work with integer of non-integer periods; performs a linear interpolation for non-integer periods).
• tempspecf: Temporal power spectrum (spatially averaged) of a time series of vector or scalar fields.

Minor changes:

• The scaling of the length of the vector arrows in quiver plots (as produced by showvec and showf) is now absolute, i.e. the pixel / physical unit calibration remains unchanged during a movie. The previous behavior (relative scaling) is still available, using the option showvec(..., 'scalemode','relative').
• loadvec now accepts every .mat file containing at least one Pivmat-compatible structure. If, for example, the file mydata.mat contains a Pivmat structure named myfield, then v = loadvec('mydata.mat') will load the Pivmat structure into the variable v.
• rdir (and other functions based on rdir, like loadvec) now accepts file number indexing using non-integer indices. For instance, v = loadvec('Myfiles_dt=[1:0.5:2,5.2]s.*') loads the files 'Myfiles_dt=01.00s.*', 'Myfiles_dt=01.50s.*', 'Myfiles_dt=02.00s.*'.
• corrf now works correctly when zero elements (interpreted as wrong data) are present (thanks J.I. Cardesa-Duenas!)
• extractf now accepts rectangle coordinates outside the physical domain (a truncation is performed if this occurs).
• New scalar field conversion available in vec2scal: The 3 measurable components of the Reynolds stress tensor (options txx, txy and tyy, with tauij = ui uj).
• The remapping procedure has been removed from surfheight. The option noremap has been removed (since it is now by default).
• expandstr not available any more (moved to the private directory). The features of expandstr (file number indexing) are now directly explained in the documentation of rdir.
• Help text improved for several functions.

Bugs fixed:

• rdir (and other functions based on rdir, like loadvec) now works properly with './' and with absolute path names (path names starting as D:\mydir\etc). This is useful when working through network disks.
• loadarrayvec now works when directories and subdirectories have wildcards ('*'), e.g. v = loadarrayvec('dir*/PIV*','*.vc7').
• renamefile now works when filenames contain '=' (thanks Cyril and Pierre).
• vortex now does not produce strictly zero velocity components, so that they are not interpreted as wrong vectors when displayed by showvec.

Compatibility issue:

• Since 2009, the package readimx from LaVision (version 1.0, revision 1.8 or higher) is now compatible with the 32 and 64 bits editions of Windows (Vista and 7 only), so PIVMat is now also compatible with Windows 64 bits.
• loadset is going to be removed from the toolbox in a future version. Use loadvec with wildcards (*) instead.

New Feature:

• When a DaVis file is double-clicked on the Current Directory Browser, it is imported into the Workspace (multiple file selection not allowed). Vector files are imported into the varibale v and images are imported into im. Accepted file formats are: VEC, VC7, IMX, IM7, IMG, SET. If a SET file is selected, all the files contained in the corresponding folder are imported.

New functions:

• spec2f: 2D power spectrum, both for scalar and vector fields, including 2D iso-contours and azimuthal average.
• nam: Implementation of the "Normalized Angular Momentum" method for vortex detection.

Minor changes:

• loadvec now accepts multi-frame images. Use the option 'frame' to specify the frame to load.
• New option 'streamline' in showvec (and showf).
• New option 'rmax' in azaverf (to save computation time).
• filterf and bwfilterf now accept arguments as scalars or arrays. The width of the border truncation for bwfilterf has been increased (some border effects were still present).
• loadvec now converts IMX/IM7 image files to double (this allows to use image files for statistics, histograms etc).
• The Revision 7 (Date 8.12.08) of the ReadIMX package from LaVision is now required for loadvec. Please upgrade.
• New fields 'min' and 'max' in statf.
• showscal displays the unit of the scalar field only if it is defined.
• New option 'fullsize' in showscal and showvec. This is useful to export a vector/scalar field as an image, without the labels, ticks, colorbar etc.
• specf now accepts string exponents for compensated spectra. For instance, use the input argument '5/3' in order to display 'k^{5/3} E(k)' instead of 'k^{1.6667} E(k)'.
• renamefile and renumberfile now work much faster for large files (Thanks Mohammad!). From FileSeries 1.40.

Bugs fixed:

• showscal and showvec: Setting equal bounds in the colormap of a scalar field caused an error.
• truncf now works properly for fields with more rows than columns (thanks Alex!).
• The definition of the enstrophy in vec2scal now includes the usual factor 1/2 (i.e., Z = w^2/2, where w is the vorticity).
• The definition of the Q factor in vec2scal has been corrected: Q = (Z - S^2)/2, with Z = w^2/2 the enstrophy (see above) and S^2 the squared strain.
• specf: The factor 1/2 is no longer included in the computation of the spectra.
• loadvec: now works correctly with files of IType=2. Mutiple selection in dialog box now works.
• Legends and labels of compensated spectra in specf corrected.

New functions:

• interpf: Interpolate missing data (fills holes). Based on John D'Errico' inpaint_nans function (Matlab Central).
• ssf: Structure functions of scalar field, and histograms of scalar increments.
• getframedt: Get the time intervals between the frames of multiframe DaVis image file (.IMX/.IM7).
• makebospattern: Produce a random dot pattern for BOS (Background-oriented Schlieren) / SS (Synthetic Schlieren) / FS-SS (Free-Surface Synthetic Schlieren) applications (see the FS-SS tutorial).
• zerotonanfield and nantozerofield: Converts the zero elements (standing for missing data) of vector or scalar fields as NaN elements and vice-versa.
• cdw and lsw: Work as CD and LS, but allow for wildcards (*). From FileSeries 1.30.

Major changes:

• Missing data are now handled properly for the computation of derivative fields (using vec2scal) or for filtering (using filterf). For instance, when computing the divergence of a vector field, a point will be considered as "missing" (i.e., its value is set to 0) if the finite difference uses a missing value from the input vector field. This new behavior avoids propagation of errors.
• Camera can be rotated during a movie for 3D scalar displays using showscal.

Minor changes:

• Arrows of length zero are not displayed any more by showvec for missing data.
• Option 'keepcamarasettings' removed in showscal. Now the camera view, angle, position, are kept for 3D views at each call of showscal. To reset those camera settings, use the option 'resetcamerasettings'.
• surfheight (surface height reconstruction for FS-SS, Free-Surface Synthetic Schlieren): now includes finite distance effects and remapping.
• New option 'verbose' (display the work in progress) added in a number of functions: loadvec, medianf, rdelete, ...
• New option 'nowarning' in corrf.
• Option 'zeros' removed in filterf. Interpolations are now (much better) performed by interpf.
• bwfilterf now works with non-square fields.

Bugs fixed:

• Color limits in showscal are now correct when using options contour and contourf.
• 3D visualisations in showscal now respect the x/y aspect ratio.
• showf now accepts .imx and .im7 files as input arguments.
• specf and bwfilterf now accept fields with odd dimension.
• loadvec now does not issue the warning "Concatenation involves an empty array..." for numeric input argument.
• Methods 'gauss' and 'igauss' were inverted in filterf.

New functions:

• smoothf: Smoothing (or running average) over consecutive fields. This is useful for a temporal smoothing of time-resolved velocity fields.
• medianf: Apply a median filter to a vector or scalar field (requires the Image Processing Toolbox)
• resizef: Resize a field (requires the Image Processing Toolbox)
• subsbr: Substract the mean rotation (solid-body rotation) of a vector field
• specf: 1D power spectrum of vector/scalar fields
• getvar: Extract some variable informations from a string (usually a filename where parameter values are specified).

Minor changes:

• New examples in the sample directory: rotating turbulence (3 fields) and apparent displacement from a refraction experiment (3 fields).
• New colormap features in showscal:
  • New option 'ampclim', to specify the colormap bounds in the form MEAN +/- AMP.
  • Scalar fields made of small oscillations around a large mean have now a colormap centered on the mean.
  • New commands '*' and '/' to stretch/compress the colormap during the movie.
  • If the scalar field originates from a IMX/IM7 file, the gray colormap is selected by default.
• New option 'command' in showscal.
• vec2mat: Now can convert files into different destination directory. New option 'verbose'.
• subaverf now considers that zero elements are erroneous, and keeps those elements as zeros instead of substracting the (spatial and/or ensemble) average.
• batchvec is renamed batchf
• loadvec now accepts .UWO files (Optical Flow fields).
• The PDF documentation has been removed (was it really useful?)

Bugs fixed:

• loadvec now recognizes correctly the label names and units (e.g. mm, m/s) from DaVis vector/scalar files. Make sure you use the last version of the ReadIMX 1.4 package (DLL Version: 1.0, Date: 8/06/07 16:38, Revision: 6) or newer. If not, download it from the LaVision website (www.lavision.de).
• Bugs fixed in the history field for some functions (e.g., filterf).

Major change: Scalar fields built from derivatives (e.g., curl, divergence, strain rate etc.) are now computed from 2nd order centered differences, using Matlab's built-in numerical derivative functions, whereas they were computed from a 1st order scheme in the previous versions (see vec2scal). The resulting scalar field has now the same size as the original vector field. Specify 'rot1','div1' etc. instead of 'rot', 'div' to use the old 1st order scheme (for which the resulting scalar field is smaller than the original vector field).

Movie player improved (both showvec and showscal):

• Movies may now be displayed within docked windows. If the window is not docked, it will stay in front of all other windows ('modal' WindowStyle).
• Option 'Jump' (or 'Go') by pressing the key 'j' or 'g'.
• Enter into the pause mode by pressing the arrow keys
• Escape the movie by pressing ESC, 'q', 'x' or Ctrl+C (works only with selected windows if they are docked) or simply by closing the window if it is undocked.

New functions:

• showf: shortcut for showvec or showscal.
• vsf (vector structure functions) and vsf_disp (displays the result of vsf).
• jpdfscal (joint probability density function of two scalar fields) and jpdfscal_disp (displays the result of jpdfscal).
• surfheight: Computes the surface height from a displacement vector field.

New file format supported: loadvec now accepts Mat-files saved from MatPIV (see http://www.math.uio.no/~jks/matpiv/).

Minor changes:

• showvec: New option 'colorvec' (specifies the color of the vector arrows).
• showvec and showscal: New options 'cmap' (specifies the color map, 'gray','jet'...) and 'title' (e.g., display the time of the field in the title).
• loadvec: The structure V contains a new field choice, where the number of 1st, 2nd etc. choice vectors are stored.
• renumberfile, getfilenum and renamefile: New options 'fileonly', ''dironly'.
• getfilenum now works with both integer and real indices.
• batchvec: New option 'nodisp'.

Compatibility issue: Since Matlab 7.4 (R2007a), the behavior of the command doc has changed: the command doc pivmat does not display the PIVMat toolbox start page in the help browser any more. If you use Matlab 7.4, type docpivmat to display the start page, or type docpivmat function_name to display the html documention of function_name in the help browser. If you use Matlab 7.3 or before, doc and docpivmat will produce the same result.

Bugs fixed: loadvec (scalar fields, IMX/IM7, were transposed), gradientf (wrong definition, the gradient was transposed), vortex (the undefined field setname caused problems with showvec), operf (minor bug for scalar outputs).

Minor change: vec2mat now works with all the file formats suported by loadvec (VEC/VC7/IMX/IM7/IMG/TXT/SET).

Minor change: azaverf now does not return the leading zeros when the center is outside the field, and does not include zero (erroneous) elements in the computation of the azimuthal average by default (see option 'keepzero').

New Frequently Asked Questions section.

Major change: New syntax for showvec and showscal: now works on the basis of PropertyName/PropertyValue pairs.

New options ('surfl', 'mesh', 'delay', 'backward', 'loop'...).

Movie viewer improved (showvec and showscal): it is now possible to enter/exit the 'pause' mode during movies.

showscal now does not refresh the camera settings for 3D views (see the option 'KeepCameraSettings').

New functions azaverf (azimuthal average) and gradientf.

rotatef can now rotate a field about a point different from the center.

New options for shiftf (bottomright, topleft...).

Coordinates in extractf and truncf may now be specified in physical or mesh units.

loadvec now accepts old IMG files (uncompressed DaVis 6 images).

New function corrf (correlation function).

vec2scal now considers vectors with a zero component as erroneous (or masked), and does not use them for the computation of derivative fields (rot, div, duxdx...)

New option for truncf: truncates to the smallest rectangular excluding zero (erroneous or masked) elements.

Bugs fixed with randvec (history field) and showvec (lines of other figures were turned to black).

loadvec and loadset now accept both vector fields (VEC/VC7) and images (IMX/IM7).

New functions getattribute, readsetfile and getpivtime. Function getimxtime obsolete.

loadvec now checks that the ReadIMX package (LaVision) is installed.

Field 'history' is now a cumulative cell array of strings.

Bugs fixed for bwfilterf and rotatef.

Several functions moved to a subdirectory 'private'.

Better compatibility of the documentation with the MATLAB help browser.

The toolbox is now called PIVMat.

Documentation improved. New 'Known bugs' section.

Standard items for the toolbox in the MATLAB 'Start' menu.

New about and checkupdate. New home page (www.fast.u-psud.fr/pivmat).

File 'readme.txt' retired.

Bugs fixed for loadvec, due to changes in ReadIMX 1.4 (changes in the VY sign for Y-upward fields).

Multiple file selection allowed.

Bug fixed for showvec (bounds).

LaVision's MATLABIMX package not included any more; it has to be installed separately.

showvec now accepts file numbers as input arguments.

New option 'angle' in vec2scal.

New functions vec2mat, operf, batchvec, addnoisef.

Bug fixed for filterf.

statf improved (history field).

The bugs with up/downward Y axis are fixed in loadvec, loadpivtxt, vec2scal, showvec and showscal.

New functions shiftf and loadarrayvec.

showvec and showscal improved (pause mode).

vec2scal improved (option minus).

spaverf now computes average of non zero elements.

vortex improved (burgers vortex with divergence).

Online help files from m2html.

truncf, extractf, bwfilterf, filterf, rotatef, averf, subaverf and ensaverf work now for both vector and scalar fields (truncvec, truncscal etc. retired).

readpivtxt and dav2mat retired, replaced by loadpivtxt.

loadvec now accepts TXT, SET and MAT files.

New functions from Fileseries toolbox 1.01 (rrmdir, rdelete).

New functions getfilenum, rdir, renamefile.

renumberfile improved.

completefilename and pickfile retired (see rdir).

loadvec and loadset improved (uses rdir, txt files allowed).

showvec(-scal) improved (colormap label, titles and arrow scaling).

submeanvec improved, now called subavervec(scal).

New functions avervec(scal) and ensavervec(scal).

loadset and loadvec improved ('nosave' option added, filename expansion).

filtervec(-scal) improved.

New functions expandstr and pickfile.

buildfilename retired.

Upward and Downward Y-axis recognized: Files that have a downward Y-axis have the v_y component inversed.

Sample directory and readme.txt file (this one) added.

loadset and showvec improved.

loadvec and loadset improved: multiple files/sets and wildcards allowed.

First online release.

Compatible with DaVis 7.

New functions included (filters, stats...)

First release (original name: davis toolbox)