jrobots.utils
Class Angle

java.lang.Object
  extended by jrobots.utils.Angle
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable

public class Angle
extends java.lang.Object
implements java.io.Serializable, java.lang.Cloneable

This class represents an angle. The angle can be given as degrees (360 are a full circle) as well as in radians (2Pi are a full circle).
A zero angle points in the right or east direction. The angle increases in clockwise direction.

Fields are immutable - the values are fixed at construction. Thus, every calculation will construct a new object.

See Also:
Angle(double, String), getValueAsDegrees(), getValueAsRadians(), isPositive(), getNegative(), getNextQuadrant(), getPreviousQuadrant(), getOpposite(), sub(Angle), add(Angle), mult(double), normalize(), coneAngle(Angle, Angle), angularDistance(Angle), Serialized Form

Nested Class Summary
static class Angle.Units
           
 
Field Summary
 double angle
          representation in radians
static Angle EAST
          The angle points to the right or east.
static Angle NORTH
          The angle points upward or to the north.
static Angle SOUTH
          The angle points downward or to the south.
static Angle WEST
          The angle points to the left or west.
 
Constructor Summary
Angle()
          Constructs an Angle pointing to 0 degrees.
Angle(double value, Angle.Units units)
          Constructs an Angle with the given value.
Angle(double value, java.lang.String units)
          Constructs an Angle with the given value.
 
Method Summary
 Angle add(Angle a)
          Rotates this Angle in clockwise direction
 Angle angularDistance(Angle a)
          Calculates the angular distance of a - this.
 Angle clone()
           
static double coneAngle(Angle d1, Angle d2)
          calculates the not commutative cone angle between d1 and d2 The cone is assumed to emanate from d1 in the direction where d2 lies closest.
 Angle getNegative()
          Results in a negated copy of this Angle Be aware that negation does not necessarily point into the opposite direction
 Angle getNextQuadrant()
          Results in an Angle 90° in clockwise direction and normalized.
 Angle getOpposite()
          Results in an Angle pointing to the opposite direction.
 Angle getPreviousQuadrant()
          Results in an Angle 90° in anticlockwise direction and normalized.
 double getValueAsDegrees()
          Gives the value of this Angle in degrees.
 double getValueAsRadians()
          Gives the value of this Angle as radians.
 boolean isPositive()
          There may be unnormalized Angles.
 Angle mult(double factor)
          Multiplies this Angle by a given factor
 Angle normalize()
          Angles in degrees smaller than zero or greater than 360° are readjusted into that range.
 Angle sub(Angle a)
          Rotates this Angle in anticlockwise direction
 java.lang.String toString()
          Gets a string representation in the form "Angle:1.23°" zurück.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

angle

public final double angle
representation in radians


EAST

public static final Angle EAST
The angle points to the right or east. The value is 0° or 0 Pi.


NORTH

public static final Angle NORTH
The angle points upward or to the north. The value is 270° or 3/2 Pi.


SOUTH

public static final Angle SOUTH
The angle points downward or to the south. The value is 90° or 1/2 Pi.


WEST

public static final Angle WEST
The angle points to the left or west. The value is 180° or Pi.

Constructor Detail

Angle

public Angle()
Constructs an Angle pointing to 0 degrees.


Angle

public Angle(double value,
             Angle.Units units)
Constructs an Angle with the given value. The value can be given as degrees as well as in radians.
Examples:
new Angle(3.14, Angle.Units.RADIANS)
new Angle(180, Angle.Units.DEGREES)

Parameters:
value - - value of the angle to construct
units - - defines how the value is to be treated (degrees or radians)

Angle

public Angle(double value,
             java.lang.String units)
Constructs an Angle with the given value. The value can be given as degrees as well as in radians.
Examples:
new Angle(3.14, "Radians")
new Angle(180, "Degrees")
Note: "r" oder "d" suffices.

Parameters:
value - - value of the angle to construct
units - - defines how the value is to be treated (degrees or radians)
Method Detail

add

public Angle add(Angle a)
Rotates this Angle in clockwise direction

Parameters:
a - Angle to add
Returns:
new rotated Angle

angularDistance

public Angle angularDistance(Angle a)
Calculates the angular distance of a - this.
Returned is a not normalized Angle in ]-Pi;Pi[, which signs the direction a is of this Angle.

Parameters:
a -
Returns:
unnormalized angle
>0 means a is in clockwise direction of this Angle
<0 means a is in anticlockwise direction of this Angle

clone

public Angle clone()
Overrides:
clone in class java.lang.Object

coneAngle

public static final double coneAngle(Angle d1,
                                     Angle d2)
calculates the not commutative cone angle between d1 and d2

The cone is assumed to emanate from d1 in the direction where d2 lies closest. A clockwise direction results in a positive angle, a anticlockwise direction in a negative angle. Opposite directions result in the Angle Pi.

Note: calculation will normalize both angles.

This method is a gift from the 2SEPS project.

Parameters:
d1 -
d2 -
Returns:
angle of the cone spanned by the two given directions in ]-Pi; Pi];

getNegative

public Angle getNegative()
Results in a negated copy of this Angle

Be aware that negation does not necessarily point into the opposite direction

Returns:
negated copy

getNextQuadrant

public Angle getNextQuadrant()
Results in an Angle 90° in clockwise direction and normalized.

Returns:
this Angle + 90°

getOpposite

public Angle getOpposite()
Results in an Angle pointing to the opposite direction.

Returns:
new Angle pointing to the other directon.

getPreviousQuadrant

public Angle getPreviousQuadrant()
Results in an Angle 90° in anticlockwise direction and normalized.

Returns:
this Angle - 90°

getValueAsDegrees

public double getValueAsDegrees()
Gives the value of this Angle in degrees.

Returns:
double value in degrees

getValueAsRadians

public double getValueAsRadians()
Gives the value of this Angle as radians.
Note: If you use the Math library you may need radians.

Returns:
double value in radians

isPositive

public boolean isPositive()
There may be unnormalized Angles. They are helpful to resemble for example rotational velocities. This function gives the direction of rotation.

Returns:
true, if Angle > 0
false, if Angle <= 0

mult

public Angle mult(double factor)
Multiplies this Angle by a given factor

Parameters:
factor - scaling factor
Returns:
new scaled Angle

normalize

public Angle normalize()
Angles in degrees smaller than zero or greater than 360° are readjusted into that range.

Returns:
normalized copy of this Angle

sub

public Angle sub(Angle a)
Rotates this Angle in anticlockwise direction

Parameters:
a - Angle to subtract
Returns:
new rotated Angle

toString

public java.lang.String toString()
Gets a string representation in the form "Angle:1.23°" zurück. Die Zahl ist im Gradmaß zu interpretieren.

Overrides:
toString in class java.lang.Object
Returns:
String