How to...

...use single pixel ensemble correlation image preprocessing
...process directories vector post processing
...estimate flow rates
...reconstruct a 3d flow
...export vector fields into a graphics format
...plot a cross-correlation function a cross-correlation function
...use JPIV as a front-end for PIVware

Single pixel ensemble correlation

For single pixel ensemble correlation, you need hundreds or even thousands of small images of a steady flow. The interrogation window size can then be reduced to a single pixel (see Westerweel et al., Exp Fluids, 37:3 375-384, 2004 for details). Single pixel ensemble correlation (or two-point correlation) is escpecially useful, if you want to measure steady flows at high magnifications, e.g. in microfluidics. Load the files that you want to process into the "Files" window and select them. In the "Settings" window, open the tab PIV - Single Pixel Correlation and modify the parameters. Start the evaluation by choosing PIV - run single-pixel-sum-of-correlation from the menu bar. You are asked about a filename for the output. Wait until the link to the result file is added to the list of files in the "Files" window.

single pixel ensemble evaluation

Single pixel ensemble evaluation of 1000 64×64 pixel images with sparse seeding


Process directories

First, dowload and install the library files, as explained on the download page. Then, use Script - process_directories.


Image preprocessing

Image preprocessing tools are not integrated in JPIV. I recommend to use ImageJ.


A common imge preprocessing task is to remove some static background prior to the PIV evaluation (see the images below).

1. Open a couple of images.
2. Execute the menu item 'Image - Stack - Images to Stack'.
3. Extract the background by executing 'Image - Stack - ZProjection' and selecting 'Min Intensity' in the user dialog.
4. Substract the background using the command 'Process - Image Calculator'. Use 'Stack' as the source, 'Substract' as the operation and 'MIN_Stack' as the substrahend.
5. Dissolve your stack with 'Image - Stack - Stack to Images'.
6. Save the images.

PIV image with static background

Particle image with static features in the background (spawning goby, courtesy of Benjamin Meunier, Corkum Lab, University of Windsor ).

PIV image without static background

The same image as above, after preprocessing.


Vector postprocessing

The drop-down menu Vector contains a collection of vector postprocessing and vector analysis tools. The corresponding parameters can be altered in the "Settings" window on the Vector Processing panels. A very robust outlier detection is the normalized median test. It can successfully be applied to almost every PIV evaluation. See the documentation for a detailed description. The detected ouliers can be visualized by selecting the checkbox Label invalid vectors on the panel JPIV - Preferences - Vector Plot, and redisplaying the vector file. Vectors marked invalid can be replaced by executing Vector - replace invalid vectors by median. See the images below for an example. Here, also the script Script - wall_filter was applied to remove the random correlations outside the vector field. Also check the script Script - batch_vector_filtering for applying a set of repetitive filters at one go.

PIV image prior to filtering

A raw PIV evaluation result (blood flow in an embryonic chicken heart).

filtered PIV image

The same image as above, after postprocessing. Replaced vectors are marked pink.


Estimation of flow rates

In the "Settings" window, open the panel Vector Processing - Profile Extraction and modify the parameters. Open a velocity field and display the context menu by right clicking somewhere on the vector plot. Select draw profile line. Set the first end point of your velocity profile with the left mouse button. Keep the button pressed and drag the mouse to draw a line. Release the mouse button to mark the end point of the profile. The velocity field is interpolated along the line. Depending on your settings on the Vector Processing - Profile Extraction panel, some profile properties are printed into the "Cmd" window. From the area of the profile you may derive a flow rate.

a velocity profile

A velocity profile.


3d flow field reconstruction

Under some circumstances, you can reconstruct the fully three-dimensional flow field from a set of parallel-plane-measurements. The conditions and the procedure are shortly explained in the documentation. A more detailed explanation and some notes about the accuracy and sensitivity can be found in chapter 4.7 of my thesis).

3d flow reconstruction

An example for a 3d reconstruction of a parallel-plane measurement (see figure 5.7 of my thesis for more information.


Export vector plots into a graphics format

Display the context menu of a vector field plot (right mouse button). Select export as pixel image for pgm, tiff, and png or export as vector graphics for swf, emf, svg, eps, and pdf.


Plot a cross-correlation function

Display a PIV image and right click somewhere in the image to display the context menu. Select show correlation map. The correlation function is calculated for a rectangle that has its upper, left corner at the position of the mouse. At the moment, this function is only supported for double images. The size of the interrogation area is defined on the JPIV - PIV - Interrogation Window panel. Only the parameters Interrogation window width and Interrogation window height of the first pass are considered. The magnification of the correlation function is identical to the image magnification (set on the Preferences - Image Display panel). The correlation functions float on top of your image. You can delete them by clicking on them.

a correlation function

A correlation function of 64×64 pixel.


Save a cross-correlation function

Select the check box Export correlation functions on the JPIV - PIV - Interrogation Window panel. The correlation functions are exported as 32 bit tif files. Use the Vector input field to specify the correlation map you want to export. The correlation maps are counted from left to right and from top to bottom, starting with zero for the first vector in the upper left corner. Fill in -1, if you want to export the correlation maps of all vectors. Fill in -1 into the Pass input field, if you want to export the correlation maps of all evaluation passes. If you want to export only the correlation functions of a specific pass, specify the number of the pass here, starting with zero for the first one. Check Only Sum Of Correlation if you prefer exporting only after all correlations are summed up. You find the correlation functions in the same directory as the vector files.

You may want to use ImageJ for displaying the correlation function.

3d correlation function plot

ImageJ plots of exported correlation functions belonging to the second vector in the second row (number 31). The 64×64 pixel correlation function belongs to the first pass. The smaller function belongs to the second pass. The correlation peak of the second pass is almost in the centre of the correlation function, because of pre-shifting the correlation windows according to the first pass. In this way, the second correlation peak is also higher than the one of the first pass, although a smaller window was chosen.


Use JPIV as a front-end for PIVware.

At the AHD Laboratory of the TU Delft, you can use JPIV as a front-end for the command line PIV analysis package PIVware, by Jerry Westerweel. PivWare is integrated into JPIV via two scrips. They are stored in the directory /usr/local/pivware/jpiv/jlib/jsc/. Define the jlib directory as your jpiv library directory, as described in the documentation section. The two scripts pivware_piv_evaluation.jsc and pivware_tools_collection.jsc should be directly accessible via the Script menu in the menu bar. Execute them, to see a description.


Use the PIVware tools script, to calculate the vorticity distribution of your flow field. First, select some velocity data files in the "Files" window. Execute the script by choosing Script - pivware_tools_collection from the menu bar. The following dialog appears.

vector processing dialog

The PIVware vector processing dialog.

Select the command flipy | vortlp | flipy and press execute. Afterwards you are asked about an output filename. Wait until the result appears in the "Files" window. You can visualize the vorticity in the vector plots as a color coded background. Just expand the tree nodes in the "Settings" frame to see the "Preferences - Vector Plot" panel. Select Color coding for the background and set the Data column to 4. Deselect color coding for Vectors and choose a dark vector color. Now display one of the post-processed vector fields.