Class Angle

java.lang.Object
org.apache.sis.measure.Angle
All Implemented Interfaces:
Serializable, Comparable<Angle>, Formattable
Direct Known Subclasses:
ElevationAngle, Latitude, Longitude

public class Angle extends Object implements Comparable<Angle>, Formattable, Serializable
An angle in decimal degrees. An angle is the amount of rotation needed to bring one line or plane into coincidence with another. Various kind of angles are used in geographic information systems, some of them having a specialized class in Apache SIS:
  • Latitude is an angle ranging from 0° at the equator to 90° at the poles.
  • Longitude is an angle measured east-west from a prime meridian (usually Greenwich, but not necessarily).
  • Azimuth is a direction given by an angle between 0° and 360° measured clockwise from North.
  • Bearing is a direction given by an angle between 0° and 90° in a quadrant defined by a cardinal direction.
  • Bearing is also sometimes used in navigation for an angle relative to the vessel forward direction.
  • Deflection angle is the angle between a line and the prolongation of a preceding line.
  • Interior angle is an angle measured between two lines of sight.
  • Elevation angle is the angular height from the horizontal plane to an object above the horizon.

Formatting angles

The recommended way to format angles is to instantiate an AngleFormat once, then to reuse it many times. As a convenience, Angle objects can also be formatted by the "%s" conversion specifier of Formatter, but this is less efficient for this class.

Immutability and thread safety

This class and the Latitude / Longitude subclasses are immutable, and thus inherently thread-safe. Other subclasses may or may not be immutable, at implementation choice (see Number for an example of a similar in purpose class having mutable subclasses).
Since:
0.3
Version:
0.8
See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static Format
    A shared instance of AngleFormat.
    private static final long
    Serial number for inter-operability with different versions.
    private final double
    Angle value in decimal degrees.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Angle(double θ)
    Constructs a new angle with the specified value in decimal degrees.
    Angle(String text)
    Constructs a newly allocated Angle object that contain the angular value represented by the string.
  • Method Summary

    Modifier and Type
    Method
    Description
    int
    Compares two Angle objects numerically.
    double
    Returns the angle value in decimal degrees.
    boolean
    equals(Object object)
    Compares the specified object with this angle for equality.
    void
    formatTo(Formatter formatter, int flags, int width, int precision)
    Formats this angle using the provider formatter.
    private static Format
    Returns a shared instance of AngleFormat.
    int
    Returns a hash code for this Angle object.
    (package private) char
    hemisphere(boolean negative)
    Returns the hemisphere character for an angle of the given sign.
    (package private) double
    Upper threshold before to format an angle as an ordinary number.
    double
    Returns the angle value in radians.
    Returns a string representation of this Angle object.
    (package private) static double
    valueOf(org.opengis.geometry.DirectPosition position, org.opengis.referencing.cs.AxisDirection positive, org.opengis.referencing.cs.AxisDirection negative)
    Returns the angular value of the axis having the given direction.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      Serial number for inter-operability with different versions.
      See Also:
    • format

      private static Format format
      A shared instance of AngleFormat.
      See Also:
    • θ

      private final double θ
      Angle value in decimal degrees. We use decimal degrees as the storage unit instead of radians in order to avoid rounding errors, since there is no way to represent 30°, 45°, 90°, 180°, etc. in radians without errors.
  • Constructor Details

    • Angle

      public Angle(double θ)
      Constructs a new angle with the specified value in decimal degrees.
      Parameters:
      θ - angle in decimal degrees.
    • Angle

      public Angle(String text) throws NumberFormatException
      Constructs a newly allocated Angle object that contain the angular value represented by the string. The string should represent an angle in either fractional degrees (e.g. 45.5°) or degrees with minutes and seconds (e.g. 45°30').

      This is a convenience constructor mostly for testing purpose, since it uses a fixed locale. Developers should consider using AngleFormat for end-user applications instead of this constructor.

      Parameters:
      text - a string to be converted to an Angle.
      Throws:
      NumberFormatException - if the string does not contain a parsable angle.
      See Also:
  • Method Details

    • valueOf

      static double valueOf(org.opengis.geometry.DirectPosition position, org.opengis.referencing.cs.AxisDirection positive, org.opengis.referencing.cs.AxisDirection negative)
      Returns the angular value of the axis having the given direction. This helper method is used for subclass constructors expecting a DirectPosition argument.
      Parameters:
      position - the position from which to get an angular value.
      positive - axis direction of positive values.
      negative - axis direction of negative values.
      Returns:
      angular value in degrees.
      Throws:
      IllegalArgumentException - if the given coordinate it not associated to a CRS, or if no axis oriented toward the given directions is found, or if that axis does not use angular units.
    • degrees

      public double degrees()
      Returns the angle value in decimal degrees.
      Returns:
      the angle value in decimal degrees.
    • radians

      public double radians()
      Returns the angle value in radians.
      Returns:
      the angle value in radians.
    • hashCode

      public int hashCode()
      Returns a hash code for this Angle object.
      Overrides:
      hashCode in class Object
    • equals

      public boolean equals(Object object)
      Compares the specified object with this angle for equality.
      Overrides:
      equals in class Object
      Parameters:
      object - the object to compare with this angle for equality.
      Returns:
      true if the given object is equal to this angle.
    • compareTo

      public int compareTo(Angle that)
      Compares two Angle objects numerically. The comparison is done as if by the Double.compare(double, double) method.
      Specified by:
      compareTo in interface Comparable<Angle>
      Parameters:
      that - the angle to compare with this object for order.
      Returns:
      -1 if this angle is smaller than the given one, +1 if greater or 0 if equals.
    • maximum

      double maximum()
      Upper threshold before to format an angle as an ordinary number. This is set to 90° in the case of latitude numbers.
    • hemisphere

      char hemisphere(boolean negative)
      Returns the hemisphere character for an angle of the given sign. This is used only by toString(), not by AngleFormat.
    • toString

      public String toString()
      Returns a string representation of this Angle object. This is a convenience method mostly for debugging purpose, since it uses a fixed locale. Developers should consider using AngleFormat for end-user applications instead than this method.
      Overrides:
      toString in class Object
      See Also:
    • getAngleFormat

      private static Format getAngleFormat()
      Returns a shared instance of AngleFormat. The return type is Format in order to avoid class loading before necessary.

      This method must be invoked in a synchronized(Angle.class) block. We use synchronization instead of static class initialization because AngleFormat is not thread-safe, so it needs to be used in a synchronized block anyway. We could avoid synchronization by using ThreadLocal, but this brings other issues in OSGi context. Given that our Javadoc said that Angle(String) and toString() should be used mostly for debugging purpose, we consider not worth to ensure high concurrency capability here.

    • formatTo

      public void formatTo(Formatter formatter, int flags, int width, int precision)
      Formats this angle using the provider formatter. This method is invoked when an Angle object is formatted using the "%s" conversion specifier of Formatter. Users don't need to invoke this method explicitly.

      Special cases:

      • If the precision is 0, then this method formats an empty string.
      • If the precision is 1 and this angle is a Latitude or Longitude, then this method formats only the hemisphere symbol.
      • Otherwise the precision, if positive, is given to AngleFormat.setMaximumWidth(int).
      Specified by:
      formatTo in interface Formattable
      Parameters:
      formatter - the formatter in which to format this angle.
      flags - FormattableFlags.LEFT_JUSTIFY for left alignment, or 0 for right alignment.
      width - minimal number of characters to write, padding with ' ' if necessary.
      precision - maximal number of characters to write, or -1 if no limit.