com.partnersoft.geometry.xy
Class XyDirection

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

All Implemented Interfaces:

Immutable

public class XyDirection
extends java.lang.Object
implements Immutable

An angular direction. (as opposed to XyAngle,

Angles are one of the most problematic parts of a geometry model. There are a number of units of measure, starting angles, and standard directions. We have divided the problem into XyAngle, which deals with angular magnitude and unit conversion, and XyDirection, which deals with angular coordinates and coordinate system conversion.

Having separate angle and direction types also allows more semantic precision. For example, the angle of a line is an XyDirection, but the angle between two lines is just an XyAngle.

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 XyDirection using an XyAngle and one of the following factory methods:

• forBearing(XyAngle)
• forTheta(XyAngle)

or, one of the convenience factory methods:

• forBearingDegrees(double)
• forBearingRadians(double)
• forThetaDegrees(double)
• forThetaRadians(double)

  Copyright 2007 Partner Software, Inc.

  Version:

  $Id: XyDirection.java 1365 2008-06-16 13:54:49Z paul $

  Author:

  Paul Reavis, Richard Fay, Rich Stepanski

  Method Summary

  XyAngle	acuteAngleFrom(XyDirection nother) Returns the smallest circular angle formed by this direction and the one given.
  boolean	equals(java.lang.Object nother)
  static XyDirection	forBearing(XyAngle bearing) Create an XyDirection as an bearing angle measured clockwise from north (positive Y axis).
  static XyDirection	forBearingDegrees(double degrees) Convenience method equivalent to forBearing(XyAngle.forDegrees(degrees)).
  static XyDirection	forBearingRadians(double radians) Convenience method equivalent to forBearing(XyAngle.forRadians(radians)).
  static XyDirection	forLine(XyPoint start, XyPoint end) Factory method for creating a direction from a pair of points.
  static XyDirection	forTheta(XyAngle theta) Create an XyDirection as a Cartesian angle measured counter-clockwise from east (positive X axis).
  static XyDirection	forThetaDegrees(double degrees) Convenience method equivalent to forTheta(XyAngle.forDegrees(degrees)).
  static XyDirection	forThetaRadians(double radians) Convenience method equivalent to forTheta(XyAngle.forRadians(radians)).
  XyAngle	getBearing() Returns the bearing angle, measured clockwise from "north" (the positive y axis).
  double	getBearingDegrees() Convenience method equivalent to getBearing().getDegrees().
  double	getBearingRadians() Convenience method equivalent to getBearing().getRadians().
  XyAngle	getTheta() Returns the Cartesian angle, measured clockwise from "north" (the positive y axis).
  double	getThetaDegrees() Convenience method equivalent to getTheta().getDegrees().
  double	getThetaRadians() Convenience method equivalent to getTheta().getRadians().
  XyAngle	obtuseAngleFrom(XyDirection nother) Returns the largest circular angle formed by this direction and the one given.
  XyDirection	reversed() Returns the reverse of this direction by rotating it 180 degrees (pi radians).
  XyDirection	rotatedBy(XyRotation rotation) Uses the given rotation to rotate the direction the given amount and direction.
  XyRotation	rotationFrom(XyDirection nother) Returns the rotation required to convert the given direction to this one.
  java.lang.String	toString()
  XyVector	toUnitVector() Converts the direction to a vector of length 1.

  Methods inherited from class java.lang.Object

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

  Method Detail

  forBearing

  public static XyDirection forBearing(XyAngle bearing)

  Create an XyDirection as an bearing angle measured clockwise from north (positive Y axis). This is the most common system used in mapping and compass work. The input will be clamped so that it is positive and less than a full circle.

  forTheta

  public static XyDirection forTheta(XyAngle theta)

  Create an XyDirection as a Cartesian angle measured counter-clockwise from east (positive X axis). This is the most common system used in mathematics. The input will be clamped so that it is positive and less than a full circle.

  forBearingDegrees

  public static XyDirection forBearingDegrees(double degrees)

  Convenience method equivalent to forBearing(XyAngle.forDegrees(degrees)).

  forBearingRadians

  public static XyDirection forBearingRadians(double radians)

  Convenience method equivalent to forBearing(XyAngle.forRadians(radians)).

  forThetaDegrees

  public static XyDirection forThetaDegrees(double degrees)

  Convenience method equivalent to forTheta(XyAngle.forDegrees(degrees)).

  forThetaRadians

  public static XyDirection forThetaRadians(double radians)

  Convenience method equivalent to forTheta(XyAngle.forRadians(radians)).

  forLine

  public static XyDirection forLine(XyPoint start,
                                    XyPoint end)

  Factory method for creating a direction from a pair of points. The direction is that of a segment connection start to end.

  rotatedBy

  public XyDirection rotatedBy(XyRotation rotation)

  Uses the given rotation to rotate the direction the given amount and direction.

  reversed

  public XyDirection reversed()

  Returns the reverse of this direction by rotating it 180 degrees (pi radians).

  rotationFrom

  public XyRotation rotationFrom(XyDirection nother)

  Returns the rotation required to convert the given direction to this one. Sort of a circular minus operator, the opposite of rotatedBy(rotation). Returns a rotation with an acute angle.

  acuteAngleFrom

  public XyAngle acuteAngleFrom(XyDirection nother)

  Returns the smallest circular angle formed by this direction and the one given. If the directions were pointing the direction of two sides on a triangle connected to the same vertex, this would be the interior angle.

  obtuseAngleFrom

  public XyAngle obtuseAngleFrom(XyDirection nother)

  Returns the largest circular angle formed by this direction and the one given. If the directions were pointing the direction of two sides on a triangle connected to the same vertex, this would be the exterior angle.

  toUnitVector

  public XyVector toUnitVector()

  Converts the direction to a vector of length 1.

  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

  getBearing

  public XyAngle getBearing()

  Returns the bearing angle, measured clockwise from "north" (the positive y axis). Value will be clamped to be positive and within a single revolution. This is a common angular coordinate system for mapping, surveying and orienteering.

  Returns:

  bearing angle

  getTheta

  public XyAngle getTheta()

  Returns the Cartesian angle, measured clockwise from "north" (the positive y axis). Value will be clamped to be positive and within a single revolution. This is the standard angular coordinate system used in mathematics.

  Returns:

  bearing angle

  getBearingDegrees

  public double getBearingDegrees()

  Convenience method equivalent to getBearing().getDegrees().

  getBearingRadians

  public double getBearingRadians()

  Convenience method equivalent to getBearing().getRadians().

  getThetaDegrees

  public double getThetaDegrees()

  Convenience method equivalent to getTheta().getDegrees().

  getThetaRadians

  public double getThetaRadians()

  Convenience method equivalent to getTheta().getRadians().