com.partnersoft.geometry.xy
Class XyAngle

java.lang.Object
  com.partnersoft.geometry.xy.XyAngle

All Implemented Interfaces:

Immutable, java.lang.Comparable<XyAngle>

public class XyAngle
extends java.lang.Object
implements Immutable, java.lang.Comparable<XyAngle>

An angular magnitude.

XyAngle only deals with angular measurement, not compass position or rotational direction. It primarily serves as an encapsulation of an abstract angle with automatic conversion between the various units - degrees, radians, etc. It also supports mathematical operations such as plus, minus, etc. that work correctly regardless of the external units used.

No public constructors are provided to minimize errors caused by specifying the wrong coordinate system. This is a bit pedantic but will hopefully prove beneficial in the long run. You may construct an XyAngle using an numeric value via one of the following factory methods:

• forDegrees(double)
• forMinutes(double)
• forSeconds(double)
• forRadians(double)
• forRevolutions(double)

You can then get measurements out in any of those units with automatic conversion via:

• getDegrees()
• getMinutes()
• getSeconds()
• getRadians()
• getRevolutions()

Do note that these values are not clamped (e.g. 0 <= degrees < 360) by default, and that negative values are allowed as well as values greater than one circle. This allows you to use XyAngle to measure e.g. multiple rotations, spirals, etc. You can use the clampedUnsigned() method to get a clamped version guaranteed to be non-negative and less than a circle. In general clamping is handled by XyDirection, which clamps all angles appropriately.

The internal representation is in 64-bit fixed point micro-seconds (actually, 1/ (1024 * 1024)). Be aware that if you HAVE to work precisely, these "microns" are probably the best choice of units - however don't write confusing code for the sake of performance or precision at the second level. Instead, work in whatever units are most natural to the problem at hand.

Copyright 2007 Partner Software, Inc.

Version:

$Id: XyAngle.java 2328 2010-01-06 15:38:22Z paul $

Author:

Paul Reavis, Richard Fay

Method Summary

XyAngle	clampedSigned() Returns a clamped version of this angle whose numeric values are between positive and negative half circle.
XyAngle	clampedUnsigned() Returns a clamped version of this angle - guaranteed positive and less than a complete circle.
int	compareTo(XyAngle nother)
boolean	equals(java.lang.Object nother)
static XyAngle	forDegrees(double degrees) Returns an XyAngle with the given magnitude in degrees (1/60 circle).
static XyAngle	forMicrons(long microns) Returns an XyAngle with the given magnitude in microns (1/1048576 second, 1/62914560 minute, 1/3774873600 degree, 1/1358954496000 circle).
static XyAngle	forMinutes(double minutes) Returns an XyAngle with the given magnitude in minutes (1/60 degree, 1/3600 circle).
static XyAngle	forRadians(double radians) Returns an XyAngle with the given magnitude in radians.
static XyAngle	forRevolutions(double revolutions) Returns an XyAngle with the given magnitude in revolutions (fractional circles).
static XyAngle	forSeconds(double seconds) Returns an XyAngle with the given magnitude in seconds (1/60 minute, 1/3600 degree, 1/216000 circle).
double	getCosine() Returns the cosine of the angle.
double	getDegrees() Returns the angle as measured in decimal degrees.
long	getMicrons() Returns the angle as measured in 64-bit integer microns (1/1358954496000 circle).
double	getMinutes() Returns the angle as measured in decimal minutes.
double	getRadians() Returns the angle as measured in radians.
double	getRevolutions() Returns the angle as measured in fractions or multiples of a circle.
double	getSeconds() Returns the angle as measured in decimal seconds.
double	getSine() Returns the sine of the angle.
double	getTangent() Returns the tangent of the angle.
int	hashCode()
XyAngle	inverted() Inverts the angle.
boolean	isAcute() Returns true if the angle is positive and less than half a circle.
boolean	isObtuse() Returns true if the angle is greater than half a circle but less than a full circle.
boolean	isZero() Returns true if this is a zero-width angle.
XyAngle	minus(XyAngle nother) Subtracts the given angle from this one and gives the result.
XyAngle	plus(XyAngle nother) Adds the given angle to this one and gives the result.
XyAngle	times(double factor) Multiplies this angle by the given factor.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

forRevolutions

public static XyAngle forRevolutions(double revolutions)

Returns an XyAngle with the given magnitude in revolutions (fractional circles).

Parameters:

revolutions - magnitude in revolutions

forRadians

public static XyAngle forRadians(double radians)

Returns an XyAngle with the given magnitude in radians.

Parameters:

radians - magnitude in radians

forDegrees

public static XyAngle forDegrees(double degrees)

Returns an XyAngle with the given magnitude in degrees (1/60 circle).

Parameters:

degrees - magnitude in degrees

forMinutes

public static XyAngle forMinutes(double minutes)

Returns an XyAngle with the given magnitude in minutes (1/60 degree, 1/3600 circle).

Parameters:

minutes - magnitude in minutes

forSeconds

public static XyAngle forSeconds(double seconds)

Returns an XyAngle with the given magnitude in seconds (1/60 minute, 1/3600 degree, 1/216000 circle).

Parameters:

seconds - magnitude in seconds

forMicrons

public static XyAngle forMicrons(long microns)

Returns an XyAngle with the given magnitude in microns (1/1048576 second, 1/62914560 minute, 1/3774873600 degree, 1/1358954496000 circle).

XyAngle uses microns as its minimum resolution, this method requires an long to emphasize that.

Parameters:

microns - magnitude in microns

plus

public XyAngle plus(XyAngle nother)

Adds the given angle to this one and gives the result.

minus

public XyAngle minus(XyAngle nother)

Subtracts the given angle from this one and gives the result.

times

public XyAngle times(double factor)

Multiplies this angle by the given factor.

clampedUnsigned

public XyAngle clampedUnsigned()

Returns a clamped version of this angle - guaranteed positive and less than a complete circle. Use this to canonicalize after doing a series of additions or subtractions or to constrain input. Do not use this if (for whatever reason) negative values or values bigger than a single circle are valid - e.g. multiple revolutions.

clampedSigned

public XyAngle clampedSigned()

Returns a clamped version of this angle whose numeric values are between positive and negative half circle.

inverted

public XyAngle inverted()

Inverts the angle. This requires first clamping it (unsigned), then returning the difference between that and a full circle. For example, if this were the interior angle of a corner of a triangle, the inverted angle would be the exterior angle, and vice versa.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

equals

public boolean equals(java.lang.Object nother)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

compareTo

public int compareTo(XyAngle nother)

Specified by:

compareTo in interface java.lang.Comparable<XyAngle>

getRevolutions

public double getRevolutions()

Returns the angle as measured in fractions or multiples of a circle. For example, 0.25 revolutions = 90 degrees, -1.5 revolutions = -540 degrees.

getRadians

public double getRadians()

Returns the angle as measured in radians.

getDegrees

public double getDegrees()

Returns the angle as measured in decimal degrees.

getMinutes

public double getMinutes()

Returns the angle as measured in decimal minutes.

getSeconds

public double getSeconds()

Returns the angle as measured in decimal seconds.

getMicrons

public long getMicrons()

Returns the angle as measured in 64-bit integer microns (1/1358954496000 circle). Microns are the smallest representable magnitude of arc in an XyAngle.

isAcute

public boolean isAcute()

Returns true if the angle is positive and less than half a circle.

isObtuse

public boolean isObtuse()

Returns true if the angle is greater than half a circle but less than a full circle.

isZero

public boolean isZero()

Returns true if this is a zero-width angle.

getSine

public double getSine()

Returns the sine of the angle.

Returns:

getCosine

public double getCosine()

Returns the cosine of the angle.

Returns:

getTangent

public double getTangent()

Returns the tangent of the angle.

Returns: