jpiv2
Class PivData

java.lang.Object
  jpiv2.PivData

public class PivData
extends java.lang.Object

This class provides some functionality for 2D-PIV-data processing. PIV-data is organized in at least four columns. The first column contains the x-coordinate and the second the y-coordinate of a data point. The third and fourth columns contain the x- and the y-velocity components. Other columns might contain some additional information. The columns are separated by whitespaces. The data type is UTF-8. The file might contain a header
e.g:
TITLE = "Example"
VARIABLES = "x", "y", "ux", "uy", "s"
ZONE I=3, J=3, F=POINT
16 16 +0.4 +0.1 0.94
32 16 +0.9 +0.0 0.92
48 16 +1.2 -0.1 0.93
16 32 +1.7 -0.0 0.97
32 32 +2.1 +0.2 0.89
48 32 +1.6 -0.0 0.92
16 48 +1.2 -0.1 0.91
32 48 +1.0 -0.0 0.91
48 48 +0.1 +0.0 0.94

Constructor Summary

PivData(double[][] data)
Construction of PIV-data from a two dimensional array.

PivData(int x0, int y0, int dx, int dy, int nx, int ny, double ux, double uy, double s)
Construction of PIV-data from initial parameters

PivData(java.lang.String pathname)
Construction of a jpiv2.PivData object from a single file.

PivData(java.lang.String[] pathnames)
Construction of a jpiv2.PivData object from a list of files.

Method Summary

void	add(PivData pivDataToAdd) Adds annother PIV data set to the current data.
void	addRandomNoise(double maxNoise) Adds the product of a random number (-1 < random number < 1) and maxNoise to the values of the third and fourth column.
void	appendColumn(double defaultValue) Appending a column of defaultData.
double[]	getAbsValue(int col1, int col2) Calculates the absolute values of two vector components.
double[]	getDataColumn(int col) Extracts a single data column from the PIV data.
int[]	getDimension() Returns the width and heigth of the vector field.
double[][][]	getFirstDerivative() Calculates the first derivative of the velocity field (central differences, forward/backward differences at the border).
double[][][]	getFirstDerivativeLinReg() Calculates the first derivative of the velocity field (linear regression over five points, forward/backward differences at the border, central differences along the second row from the border).
double[][]	getFreeProfile(float x1, float y1, float x2, float y2, float spacing) Extracting a profile between two points.
double[][][]	getFreeProfiles(float x1, float y1, float x2, float y2, float spacing, int numberOf, int distance) Extracting and averaging a number of profiles between two points.
double[][]	getHorizontalProfile(int row) Extracting a horizontal profile.
int[]	getImgSize() Trys to reconstruct the original image size from the vector field.
double[]	getInterpVectorAt(float x, float y) Returns a vector that has been interpolated between the three nearest neighbours of the position x, y.
int	getInvalidVectorCount() Counts the number of invalid vecors.
int	getNumOfColumns() Returns the number of data columns, typically five (x, y, dx, dy, flag).
double[][]	getPivData() Returns the PIV-data set as a two dimensional array.
double[][]	getPivDataShift() Returns the PIV-data set as a two dimensional array.
double[][][]	getShearField() Calculates the shear field (central differences, forward/backward differences at the border).
int[]	getSpacing() Returns the horizontal and vertical spacing between two adjacent vectors.
double[][]	getThreeNearestNeighbours(float x, float y) Returns the three data points that are closest to x and y and don't lie on a straight line.
double[]	getVectorAt(int x, int y) Returns the data point that is closest to x and y.
double[][]	getVerticalProfile(int col) Extracting a vertical profile.
void	invalidateIsolatedVectors(int numOfNeighbours) Invalidates a vector if the number of valid neighbours is less than specified.
void	normalizedMedianTest(double noiseLevel, double threshold) Mark vectors as invalid using the normalized median test proposed by Jerry Westerweel and Fulvio Scarano (Experiments in Fluids (2005) 39: 1096-1100).
void	removeInvalidVectors() Remove invalid vectors (set velocity components to zero).
void	replaceByMedian(boolean all, boolean includeInvalid) Replaces invalid vectors by the median of their surrounding vectors.
void	resample(int x0, int y0, int x1, int y1, int dx, int dy) Resamples the vector field by nearest neighbour interpolation.
void	setHeader(java.lang.String header) Set the header string of the data file.
void	smooth(boolean includeInvalid) Replaces every vector by the average of the three by three neighbourhood (inclusive center point).
void	subsRefDisp(double dxRef, double dyRef) Substract a constant reference displacement.
void	wallFilterVertical(int xStart, int yStart, double threshold) Delete vectors outside a flow domain.
void	writeDataToFile(java.lang.String pathname, boolean writeHeader) Saves a data set as a space delimited unicode (UTF-8) file.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PivData

public PivData(java.lang.String pathname)

Construction of a jpiv2.PivData object from a single file.

Parameters:

pathname - Absolute pathname of a file containing PIV-data.

PivData

public PivData(java.lang.String[] pathnames)

Construction of a jpiv2.PivData object from a list of files. Only the displacement components (third and fourth column) are averaged. All other columns are taken from the first file.

Parameters:

pathnames - An array containing absolute pathnames of files containing PIV-data.

PivData

public PivData(double[][] data)

Construction of PIV-data from a two dimensional array.

Parameters:

data - A two dimensional array containing PIV-data.

PivData

public PivData(int x0,
               int y0,
               int dx,
               int dy,
               int nx,
               int ny,
               double ux,
               double uy,
               double s)

Construction of PIV-data from initial parameters

Parameters:

x0 - x-coordinate of first vector location

y0 - y-coordinate of first vector location

dx - horizontal vector spacing

dy - vertical vector spacing

nx - number of horizontal nodes

ny - number of vertical nodes

ux - initial value for horizontal displacement

uy - initial value for vertical displacement

s - inital value for fifth column

Method Detail

getPivData

public double[][] getPivData()

Returns the PIV-data set as a two dimensional array.

Returns:

A two dimensional array containing PIV-data.

getPivDataShift

public double[][] getPivDataShift()

Returns the PIV-data set as a two dimensional array. The displacement is rounded to the closest even, integer value. This data may be used for integer pre-shifts of interrogation windows.

Returns:

A two dimensional array containing PIV-data.

add

public void add(PivData pivDataToAdd)

Adds annother PIV data set to the current data. Only the two displacement components are added to the currend PIV data set.

Parameters:

pivDataToAdd - The data to add.

subsRefDisp

public void subsRefDisp(double dxRef,
                        double dyRef)

Substract a constant reference displacement.

Parameters:

dxRef - horizontal reference velocity

dyRef - vertical reference velocity

removeInvalidVectors

public void removeInvalidVectors()

Remove invalid vectors (set velocity components to zero).

invalidateIsolatedVectors

public void invalidateIsolatedVectors(int numOfNeighbours)

Invalidates a vector if the number of valid neighbours is less than specified.

Parameters:

numOfNeighbours - Specify the least number of neighbours to keep the vector.

getFirstDerivative

public double[][][] getFirstDerivative()

Calculates the first derivative of the velocity field (central differences, forward/backward differences at the border).

Returns:

A double array that contains the first derivatives of the velocity field in x- and y-direction. The data is organized in a three dimensional array. The first index indicates the vertical (y) grid-index, the second one the horizontal (x) grid-index. The last index indicates the direction of the derivative at this point (0 = x-direction, 1 = y-direction).

getFirstDerivativeLinReg

public double[][][] getFirstDerivativeLinReg()

Calculates the first derivative of the velocity field (linear regression over five points, forward/backward differences at the border, central differences along the second row from the border). This method is more robust against noise than getFirstDerivative().

Returns:

A double array that contains the first derivatives of the velocity field in x- and y-direction. The data is organized in a three dimensional array. The first index indicates the vertical (y) grid-index, the second one the horizontal (x) grid-index. The last index indicates the direction of the derivative at this point (0 = x-direction, 1 = y-direction).

getShearField

public double[][][] getShearField()

Calculates the shear field (central differences, forward/backward differences at the border). This is bascially the same as the first derivative with ux and uy flipped.

Returns:

A double array that contains the shear values of the velocity field in x- and y-direction. The data is organized in a three dimensional array. The first index indicates the vertical (y) grid-index, the second one the horizontal (x) grid-index. The last index indicates the direction of the derivative at this point (0 = x-direction, 1 = y-direction).

getDimension

public int[] getDimension()

Returns the width and heigth of the vector field.

Returns:

An array containing the horizontal and the vertical number of data points.

getNumOfColumns

public int getNumOfColumns()

Returns the number of data columns, typically five (x, y, dx, dy, flag).

Returns:

The number of data columns.

getSpacing

public int[] getSpacing()

Returns the horizontal and vertical spacing between two adjacent vectors.

Returns:

An array that contains the horizontal and the vertical vector spacing in the first and second position, respectively.

getImgSize

public int[] getImgSize()

Trys to reconstruct the original image size from the vector field. A length (width, height) is assumed to be the sum of the distances between tow data points plus twice the distance from 0 to the first data point.

Returns:

The size of the image (widht at index 0, height at index 1).

writeDataToFile

public void writeDataToFile(java.lang.String pathname,
                            boolean writeHeader)

Saves a data set as a space delimited unicode (UTF-8) file.

Parameters:

pathname - The absolute pathname of a destination file.

writeHeader - Specifies whether a Tecplot header file should be written true or not false.

getVectorAt

public double[] getVectorAt(int x,
                            int y)

Returns the data point that is closest to x and y.

Parameters:

x - The approximate x co-ordinate.

y - The approximate y co-ordinate.

Returns:

A line of the data-set or null if the data point is outside the vector field.

getInterpVectorAt

public double[] getInterpVectorAt(float x,
                                  float y)

Returns a vector that has been interpolated between the three nearest neighbours of the position x, y. The third and forth column of PIV data is interpolated. The first and second columns are replaced by x and y. Other columns are ignored.

Parameters:

x - The x co-ordinate.

y - The y co-ordinate.

Returns:

The interpolated vector (x, y, interp u, interp v).

getThreeNearestNeighbours

public double[][] getThreeNearestNeighbours(float x,
                                            float y)

Returns the three data points that are closest to x and y and don't lie on a straight line.

Parameters:

x - The approximate x co-ordinate

y - The approximate y co-ordinate

Returns:

Three lines of the data-set

resample

public void resample(int x0,
                     int y0,
                     int x1,
                     int y1,
                     int dx,
                     int dy)

Resamples the vector field by nearest neighbour interpolation. This method is useful for grid refinement during multipass PIV evaluations.

Parameters:

x0 - horizontal position of first vector

y0 - vertical position of first vector

x1 - horizontal positin of last vector

y1 - vertical position of last vector

dx - horizontal vector spacing

dy - vertical vector spacing

normalizedMedianTest

public void normalizedMedianTest(double noiseLevel,
                                 double threshold)

Mark vectors as invalid using the normalized median test proposed by Jerry Westerweel and Fulvio Scarano (Experiments in Fluids (2005) 39: 1096-1100). The velocity data remains unchanged, but the value in the fifth column (generally the peak height) is set to -1.

Parameters:

noiseLevel - Noise Level of the velocity data in pixel units.

threshold - Data above this threshold will be discarted (the default is 2).

replaceByMedian

public void replaceByMedian(boolean all,
                            boolean includeInvalid)

Replaces invalid vectors by the median of their surrounding vectors. A vector is considered to be invalid if its fifth column (peak height) is negative or null.

Parameters:

all - If all is set true every data-point is replaced by the median of a 3x3 array inclusive center point (median filtering).

includeInvalid - set false to exclude invalid vectors in the median calculation.

smooth

public void smooth(boolean includeInvalid)

Replaces every vector by the average of the three by three neighbourhood (inclusive center point).

Parameters:

includeInvalid - Set to false to exclude invalid vectors in the average calculation.

addRandomNoise

public void addRandomNoise(double maxNoise)

Adds the product of a random number (-1 < random number < 1) and maxNoise to the values of the third and fourth column.

Parameters:

maxNoise - the scaling factor of the random noise

appendColumn

public void appendColumn(double defaultValue)

Appending a column of defaultData.

Parameters:

defaultValue - The default data for the new data fields.

getHorizontalProfile

public double[][] getHorizontalProfile(int row)

Extracting a horizontal profile.

Parameters:

row - The row to extract.

Returns:

The reduced data.

getVerticalProfile

public double[][] getVerticalProfile(int col)

Extracting a vertical profile.

Parameters:

col - The column to extract.

Returns:

The reduced data.

getFreeProfile

public double[][] getFreeProfile(float x1,
                                 float y1,
                                 float x2,
                                 float y2,
                                 float spacing)

Extracting a profile between two points. The data points are linearily interpolated between the closed three neighbours of the given coordinate. The point density along the profile is about the smallest grid size of the original data.

Parameters:

x1 - The x co-ordinate of the first point.

y1 - The y co-ordinate of the first point.

x2 - The x co-ordinate of the second point.

y2 - The y co-ordinate of the second point.

spacing - The distance between the data points. If this value is zero, the smallest spacing of the vector field is used.

Returns:

The interpolated profile.

getFreeProfiles

public double[][][] getFreeProfiles(float x1,
                                    float y1,
                                    float x2,
                                    float y2,
                                    float spacing,
                                    int numberOf,
                                    int distance)

Extracting and averaging a number of profiles between two points. The data points are linearily interpolated between the closed three neighbours of the given coordinate. The point density along the profile is about the smallest grid size of the original data.

Parameters:

x1 - The x co-ordinate of the first point.

y1 - The y co-ordinate of the first point.

x2 - The x co-ordinate of the second point.

y2 - The y co-ordinate of the second point.

numberOf - Total number of profiles.

spacing - The distance between the data points. If this value is zero, the smallest spacing of the vector field is used.

distance - The distance between the profiles in pixels.

Returns:

An array that contains all profiles. The averaged profile is stored in the last element.

getDataColumn

public double[] getDataColumn(int col)

Extracts a single data column from the PIV data. This function is used to do statistics.

Parameters:

col - The column to extract.

Returns:

The extracted data column.

getAbsValue

public double[] getAbsValue(int col1,
                            int col2)

Calculates the absolute values of two vector components.

Parameters:

col1 - The column that contains the first vector component.

col2 - The column that contains the second vector component.

Returns:

An array containing the length of the 2D vectors.

getInvalidVectorCount

public int getInvalidVectorCount()

Counts the number of invalid vecors. Take care that a fifth column exists.

Returns:

The number of lines where the value in the fifth column is smaller than zero.

setHeader

public void setHeader(java.lang.String header)

Set the header string of the data file.

Parameters:

header - The header.

wallFilterVertical

public void wallFilterVertical(int xStart,
                               int yStart,
                               double threshold)

Delete vectors outside a flow domain. This filter starts at grid position x = 0 and y = yStart. It first moves up, and searches for a point where the velocity is a) below the threshold and b) increases in magnitude. From here on, all vectors are set to zero. Then, it does the same for moving down. Then, x is increased by 1 and the next column is processed. This is repeated, until the whole vector field is filtered. This filter might be used to set vectors outside a presumed wall to zero.

Parameters:

xStart - The horizontal index of a vector grid line. The wall detection starts from here.

yStart - The vertical index of a vector grid line. The wall detection starts from here.

threshold - Consider velocities below this value to be close to a wall.