org.hermit.geometry
Class Point

java.lang.Object
  extended by org.hermit.geometry.Point
All Implemented Interfaces:
java.lang.Comparable<Point>

public class Point
extends java.lang.Object
implements java.lang.Comparable<Point>

An immutable point in the plane. This immutable class represents a point as an X and Y co-ordinate.


Field Summary
static Point INFINITE
          A constant representing a point at infinity.
static Point UNKNOWN
          A constant representing an unknown point (the 2-D equivalent of NaN).
static int X_INDEX
          Index value which specifies the X co-ordinate within a point.
static int Y_INDEX
          Index value which specifies the Y co-ordinate within a point.
 
Constructor Summary
Point(double x, double y)
          Create a Point from individual co-ordinates.
 
Method Summary
 int compareTo(Point o)
          Compares this object with the specified object for order.
 double dist(Point o)
          Calculate the distance between this point and another.
 boolean equals(java.lang.Object obj)
          Indicates whether some other object is "equal to" this one.
 double getComponent(int i)
          Get the specified co-ordinate of this point.
 double getX()
          Get the X co-ordinate of this point.
 float getXf()
          Get the X co-ordinate of this point as a float.
 double getY()
          Get the Y co-ordinate of this point.
 float getYf()
          Get the Y co-ordinate of this point as a float.
 int hashCode()
          Returns a hash code value for the object.
 boolean isInfinite()
          Determine whether this point is infinite.
 boolean isNaN()
          Determine whether this point is NaN.
static Point mid(Point a, Point b)
          Calculate the midpoint between two points.
 java.lang.String toString()
          Convert this instance to a String suitable for display.
static Vector vector(Point a, Point b)
          Calculate the Vector between two points.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

INFINITE

public static final Point INFINITE
A constant representing a point at infinity. This is the only Point whose co-ordinates can be infinite.


UNKNOWN

public static final Point UNKNOWN
A constant representing an unknown point (the 2-D equivalent of NaN). This is the only Point whose co-ordinates can be NaN.


X_INDEX

public static final int X_INDEX
Index value which specifies the X co-ordinate within a point.

See Also:
getComponent(int), Constant Field Values

Y_INDEX

public static final int Y_INDEX
Index value which specifies the Y co-ordinate within a point.

See Also:
getComponent(int), Constant Field Values
Constructor Detail

Point

public Point(double x,
             double y)
Create a Point from individual co-ordinates.

Parameters:
x - The X co-ordinate.
y - The Y co-ordinate.
Method Detail

isInfinite

public boolean isInfinite()
Determine whether this point is infinite.

Returns:
True if this point is at infinity.

isNaN

public boolean isNaN()
Determine whether this point is NaN.

Returns:
True if this point is an undefined point.

getX

public double getX()
Get the X co-ordinate of this point.

Returns:
The X co-ordinate of this point.

getY

public double getY()
Get the Y co-ordinate of this point.

Returns:
The Y co-ordinate of this point.

getComponent

public double getComponent(int i)
                    throws java.lang.IllegalArgumentException
Get the specified co-ordinate of this point. This method is useful where Points are passed to methods which can work on either co-ordinate.

Parameters:
i - Index of the desired co-ordinate; either X_INDEX or Y_INDEX.
Returns:
The specified co-ordinate of this point.
Throws:
java.lang.IllegalArgumentException - Bad index.

getXf

public float getXf()
Get the X co-ordinate of this point as a float. This can be convenient for graphics methods, for example.

Returns:
The X co-ordinate of this point as a float.

getYf

public float getYf()
Get the Y co-ordinate of this point as a float. This can be convenient for graphics methods, for example.

Returns:
The Y co-ordinate of this point as a float.

dist

public double dist(Point o)
Calculate the distance between this point and another.

Parameters:
o - The other point.
Returns:
The scalar distance between this point and o -- always positive.

vector

public static Vector vector(Point a,
                            Point b)
Calculate the Vector between two points.

Parameters:
a - The starting point.
b - The ending point.
Returns:
A Vector which would translate a to b.

mid

public static Point mid(Point a,
                        Point b)
Calculate the midpoint between two points.

Parameters:
a - One point.
b - The other point.
Returns:
The point midway between a and b.

equals

public boolean equals(java.lang.Object obj)
Indicates whether some other object is "equal to" this one. This method implements an equivalence relation on non-null object references.

This method simply compares the co-ordinates of the two points, with a limited precision.

Note that the precision of the test is limited by the precision set in MathTools.setPrecision(double). That is, only as many fractional digits are compared as configured there; hence, two very close points will be considered equal.

Overrides:
equals in class java.lang.Object
Parameters:
obj - The reference object with which to compare.
Returns:
true if this object is the same as the obj argument, to within the given precision; false otherwise.

compareTo

public int compareTo(Point o)
Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

This method compares the co-ordinates of the two points, with a limited precision. The Y co-ordinate is given precedence; that is, the smaller Y will be considered less than the larger Y. If the Y values are equal to within the configured precision, then the X values are compared.

Note that the precision of the test is limited by the precision set in MathTools.setPrecision(double). That is, only as many fractional digits are compared as configured there; hence, two very close points will be considered equal.

Specified by:
compareTo in interface java.lang.Comparable<Point>
Parameters:
o - The object to be compared to this one.
Returns:
A negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.
Throws:
java.lang.ClassCastException - The specified object's type prevents it from being compared to this object.

hashCode

public int hashCode()
Returns a hash code value for the object. This method is supported for the benefit of hashtables.

The hash code returned here is based on the co-ordinates of this Point, and is designed to be different for different points. The least significant bits of the co-ordinates are not compared, in line with the precision set in MathTools.setPrecision(double). Hence, this method should be consistent with equals() and compareTo().

Overrides:
hashCode in class java.lang.Object
Returns:
A hash code value for this object.

toString

public java.lang.String toString()
Convert this instance to a String suitable for display.

Overrides:
toString in class java.lang.Object
Returns:
String representation of this instance.