## jrobots.utils
Class Angle

    java.lang.Object
      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

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, 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,
                 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