org.geotoolkit.math
Class VectorPair

Object
  VectorPair

All Implemented Interfaces:

Serializable

public class VectorPair
extends Object
implements Serializable

Utility methods related to a pair of Vector objects. The VectorPair constructor expects two vectors in argument, namely X and Y. Every operations defined in this class create views of the given vectors; they never copy or calculate data values. Because they are views, callers should not change the values of the original vectors, unless propagation to the views is really wanted.

Since:

3.00

Version:

3.00

Author:

Martin Desruisseaux (Geomatys)

See Also:

Serialized Form

Module:

utility/geotk-utility (download)

View source code for this class

Field Summary

protected Vector	X The vectors specified to the VectorPair constructor, or the result of the last operation performed on this object.
protected Vector	Y The vectors specified to the VectorPair constructor, or the result of the last operation performed on this object.

Constructor Summary

VectorPair(Vector X, Vector Y)
Creates a new pair of vector.

Method Summary

Vector	getX() Returns the vector of x values.
Vector	getY() Returns the vector of y values.
int	length() Returns the length of the two vectors, or thrown an exception if they don't have the same length.
void	makeStepwise(int direction) Computes views of (X,Y) vectors where every diagonal line is replaced by a horizontal line followed by a vertical line.
void	omitColinearPoints(double xTolerance, double yTolerance) Merges consecutive colinear segments, if any.

Methods inherited from class Object

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

Field Detail

X

protected Vector X

The vectors specified to the VectorPair constructor, or the result of the last operation performed on this object.

Y

protected Vector Y

The vectors specified to the VectorPair constructor, or the result of the last operation performed on this object.

Constructor Detail

VectorPair

public VectorPair(Vector X,
                  Vector Y)

Creates a new pair of vector. Whatever the two given vectors need to have the same length or not depends on the operation to be applied on this pair of vectors.

Parameters:

X - The first vector of the pair.

Y - The second vector of the pair.

Method Detail

getX

public Vector getX()

Returns the vector of x values.

Returns:

The vector of x values.

getY

public Vector getY()

Returns the vector of y values.

Returns:

The vector of y values.

length

public int length()
           throws MismatchedSizeException

Returns the length of the two vectors, or thrown an exception if they don't have the same length.

Returns:

The vector length, which is the same for the two vectors.

Throws:

MismatchedSizeException - if the two vectors don't have the same length.

omitColinearPoints

public void omitColinearPoints(double xTolerance,
                               double yTolerance)
                        throws MismatchedSizeException

Merges consecutive colinear segments, if any. More specifically for any index i, if the point having the coordinate (x[i], y[i]) lies on the line segment defined by the two end points (x[i-1], y[i-1]) and (x[i+1], y[i+1]), then the point at index i will be dropped.

If the (X,Y) vectors are data to be plotted, then this method can be used for simplifying the data without visual impact.

Parameters:

xTolerance - The maximal distance measured along the x axis to consider that a point lies on a line segment.

yTolerance - The maximal distance measured along the y axis to consider that a point lies on a line segment.

Throws:

MismatchedSizeException - If the X and Y vectors don't have the same length.

makeStepwise

public void makeStepwise(int direction)
                  throws MismatchedSizeException

Computes views of (X,Y) vectors where every diagonal line is replaced by a horizontal line followed by a vertical line. For this purpose, every x and y values are repeated once. A graph of the resulting vectors would have the visual appareance of a stair, or the outer limit of a histogram.

When invoked with direction=0, This method can be used before to plot (X,Y) data where X can takes only some fixed values, in order to visualy emphase its discontinuous nature. When invoked with positive or negative direction argument, this method can be used for plotting upper or lower limit respectively (for example computed from a standard deviation) of the above data.

On input
Starting with X_i and Y_i as the input vectors before this method is invoked, take s to be the length of the Y_i vector, then the length of the X_i vector must be s+1.

On output
Let define X_o and Y_o the output vectors after this method has been invoked. The length of those two vectors will be at most 2s (they will be exactly of that length if abs(direction) <= 1). The first point and the last point in the output vectors will be the same than the first point and the last point in the input vectors. More specifically, assuming that the output vectors have the maximal length:

• (X_o[0], Y_o[0]) = (X_i[0], Y_i[0])
• (X_o[2s-1], Y_o[2s-1]) = (X_i[s], Y_i[s-1])

It is often a good idea to invoke omitColinearPoints(double, double) after this method.

Parameters:

direction - Controls the order of horizontal and vertical lines.

• If zero (neutral), then the order of line segments will always be horizontal line followed by vertical line, which produce the appearance of a histogram outer limit.
• If +1 or -1, then some vertical lines may appear before their horizontal counterpart, when it makes the value of y higher (if direction is +1) or lower (if direction is -1) than they would otherwise be. So direction can be interpreted as the sign of the allowed change of y values.
• If +2 or -2, then the same reordering than +1 or -1 is executed, followed by:
  • If direction is +2, the removal of lower point when the y values are going down and up again at the same x value.
  • If direction is -2, the removal of higher point when the y values are going up and down again at the same x value.
  So +2 and -2 argument can be interpreted as shifting the main y value toward positive or negative infinity slightly more than what +1 or -1 does.

Throws:

MismatchedSizeException - If the length of the X vector is not equal to the length of the Y vector + 1.