de.thaw.comb.util

Interface Vector

All Known Subinterfaces:

Segment

All Known Implementing Classes:

AbstractSegment, AbstractSegment.Fragment, SimpleVector, SourceSegment

public interface Vector

A free spatial vector in the euclidian space. Vectors offer methods to obtain their components in the cartesian and the polar coordinate system. They also offer methods for comparing themselves with other Vectors.

This interface does not specify any particular unit of length to be used. Implementations are expected to have some sort of internal plane coordinate system (like a single UTM zone) which all coordinate values and vectors refer to. Angular units are defined to be the natural unit (radians).

See Also:

Euclidean vector (Wikipedia)

Field Summary

Fields

Modifier and Type	Field and Description
static double	FULL_CIRCLE 2 π is the angle of a full circle (in radians; equal to 360°).
static double	RIGHT_ANGLE ½ π is a right angle (in radians; equal to 90°).
static double	SEMI_CIRCLE π is the angle of a semi-circle (in radians; equal to 180°).

Method Summary

Modifier and Type	Method and Description
Vector	aligned(Vector v) Compares this vector to the specified vector with regards to their convergence.
double	bearing() The angle from grid north to the vector's direction, measured clockwise.
double	distance() The vector's length (norm).
double	easting() The ordinate (horizontal / longitudinal) aspect of the vector's coordinate representation.
boolean	isAligned(Vector v) Compares this vector's bearing to the specified vector's bearing.
double	northing() The abscissa (vertical / latitudinal) aspect of the vector's coordinate representation.
double	relativeBearing(Vector v) The angle from this vector's direction to the specified vector's direction, measured counterclockwise or clockwise, whichever is nearer.
Vector	reversed() Returns a reversed representation of this vector.

Field Detail

FULL_CIRCLE

static final double FULL_CIRCLE

2 π is the angle of a full circle (in radians; equal to 360°).

See Also:

Constant Field Values

SEMI_CIRCLE

static final double SEMI_CIRCLE

π is the angle of a semi-circle (in radians; equal to 180°).

See Also:

Constant Field Values

RIGHT_ANGLE

static final double RIGHT_ANGLE

½ π is a right angle (in radians; equal to 90°).

See Also:

Constant Field Values

Method Detail

easting

double easting()

The ordinate (horizontal / longitudinal) aspect of the vector's coordinate representation.

Returns:

the difference in easting (in internal units)

northing

double northing()

The abscissa (vertical / latitudinal) aspect of the vector's coordinate representation.

Returns:

the difference in northing (in internal units)

distance

double distance()

The vector's length (norm).

Returns:

the length (in internal units)

bearing

double bearing()

The angle from grid north to the vector's direction, measured clockwise. This value must always be returned in radians, facilitating easy use with Math.

For example, if a vector pointed to the west, this method would return 3/2 π (equal to 270°).

It is strongly recommended for implementations to return bearings normalised to the interval [0, 2 π), but clients should not depend upon this behaviour.

Returns:

the vector's bearing (direction)

See Also:

SimpleVector.normaliseAbsoluteBearing(double), Bearing (Wikipedia)

relativeBearing

double relativeBearing(Vector v)

The angle from this vector's direction to the specified vector's direction, measured counterclockwise or clockwise, whichever is nearer. Clockwise measurements return positive values, counterclockwise ones return negative values. This value must always be returned in radians, facilitating easy use with java.lang.Math.

For example, if this vector pointed to the south and the specified vector pointed east, this method would return −½ π (equal to −90°).

It is strongly recommended for implementations to return bearings normalised to the interval [−π, π), but clients should not depend upon this behaviour.

Parameters:

v - the vector to calculate the bearing of in relation to this vector

Returns:

the relative bearing (difference in direction) from this vector to the specified vector; if the specified vector is zero-length, +0.0 must be returned

Throws:

NullPointerException - iff v == null

See Also:

SimpleVector.normaliseRelativeBearing(double), Relative bearing (Wikipedia)

reversed

Vector reversed()

Returns a reversed representation of this vector.

Returns:

a view of this vector, reversed

aligned

Vector aligned(Vector v)

Compares this vector to the specified vector with regards to their convergence. Implementations might use code that basically produces the same result as the following line does:

 return isAligned(v) ? clone() : reversed();
 

If the vectors already are aligned, implementations are free to return either this itself or another Vector object of equivalent value, at their option.

Parameters:

v - the vector to be compared with this one

Returns:

a view of this vector that is aligned with v

Throws:

NullPointerException - iff v == null

See Also:

isAligned(de.thaw.comb.util.Vector)

isAligned

boolean isAligned(Vector v)

Compares this vector's bearing to the specified vector's bearing. For the purpose of this interface, two vectors are defined as being "aligned" if the absolute value of their relative bearing is less than a right angle. In other words, they are aligned if they form an acute angle and not aligned if they form an obtuse angle.

Implementations might use code that basically produces the same result as the following line does:

 return Math.abs( relativeBearing(v) ) < RIGHT_ANGLE;
 

The result of this method if the vectors are orthogonal is undefined.

Parameters:

v - the vector to be compared with this one

Returns:

whether the two vectors differ by an acute angle

Throws:

NullPointerException - iff v == null.

See Also:

relativeBearing(de.thaw.comb.util.Vector)