Package com.google.common.geometry

Class S1ChordAngle

java.lang.Object
com.google.common.geometry.S1ChordAngle
All Implemented Interfaces:
Serializable, Comparable<S1ChordAngle>
@GwtCompatible(serializable=true) public final class S1ChordAngle extends Object implements Comparable<S1ChordAngle>, Serializable
S1ChordAngle represents the angle subtended by a chord (i.e., the straight 3D Cartesian line segment connecting two points on the unit sphere). Its representation makes it very efficient for computing and comparing distances, but unlike S1Angle it is only capable of representing angles between 0 and Pi radians. Generally, S1ChordAngle should only be used in loops where many angles need to be calculated and compared. Otherwise it is simpler to use S1Angle.

S1ChordAngle also loses some accuracy as the angle approaches Pi radians. Specifically, the representation of (Pi - x) radians can be expected to have an error of about (1e-15 / x), with a maximum error of about 1e-7.

See Also:

  • Field Details

    • MAX_LENGTH2

      public static final double MAX_LENGTH2
      Max value that can be returned from getLength2().
      See Also:

    • ZERO

      public static final S1ChordAngle ZERO
      The zero chord angle.

    • STRAIGHT

      public static final S1ChordAngle STRAIGHT
      The chord angle of 180 degrees (a "straight angle"). This is the max finite chord angle.

    • INFINITY

      public static final S1ChordAngle INFINITY
      A chord angle larger than any finite chord angle. The only valid operations on INFINITY are comparisons and S1Angle conversions.

    • NEGATIVE

      public static final S1ChordAngle NEGATIVE
      A chord angle smaller than ZERO. The only valid operations on NEGATIVE are comparisons and S1Angle conversions.

    • length2

      private final double length2

  • Constructor Details

    • S1ChordAngle

      public S1ChordAngle(S2Point x, S2Point y)
      Constructs the S1ChordAngle corresponding to the distance between the two given points. The points must be unit length.

    • S1ChordAngle

      private S1ChordAngle(double length2)
      S1ChordAngles are represented by the squared chord length, which can range from 0 to MAX_LENGTH2. INFINITY uses an infinite squared length.

  • Method Details

    • fromS1Angle

      public static S1ChordAngle fromS1Angle(S1Angle angle)
      Returns a new chord angle approximated from angle (see getS1AngleConstructorMaxError() for the max magnitude of the error).

      Angles outside the range [0, Pi] are handled as follows:

      Note that this operation is relatively expensive and should be avoided. To use S1ChordAngle effectively, you should structure your code so that input arguments are converted to S1ChordAngles at the beginning of your algorithm, and results are converted back to S1Angles only at the end.

    • fromLength2

      public static S1ChordAngle fromLength2(double length2)
      Construct an S1ChordAngle from the squared chord length. Note that the argument is automatically clamped to a maximum of MAX_LENGTH2 to handle possible roundoff errors. The argument must be non-negative.

    • isZero

      public boolean isZero()
      Returns whether the chord distance is exactly 0.

    • isNegative

      public boolean isNegative()
      Returns whether the chord distance is negative.

    • isInfinity

      public boolean isInfinity()
      Returns whether the chord distance is exactly (positive) infinity.

    • isSpecial

      public boolean isSpecial()
      Returns true if the angle is negative or infinity.

    • isValid

      public boolean isValid()
      Returns true if getLength2() is within the normal range of 0 to 4 (inclusive) or the angle is special.

    • toAngle

      public S1Angle toAngle()
      Convert the chord angle to an S1Angle. INFINITY is converted to S1Angle.INFINITY, and NEGATIVE is converted to a negative S1Angle. This operation is relatively expensive.

    • getLength2

      public double getLength2()
      The squared length of the chord. (Most clients will not need this.)

    • successor

      public S1ChordAngle successor()
      Returns the smallest representable S1ChordAngle larger than this object. This can be used to convert a "invalid input: '<'" comparison to a "invalid input: '<'=" comparison.

      Note the following special cases:

      • NEGATIVE.successor() == ZERO
      • STRAIGHT.successor() == INFINITY
      • INFINITY.Successor() == INFINITY

    • predecessor

      public S1ChordAngle predecessor()
      As successor(), but returns the largest representable S1ChordAngle less than this object.

      Note the following special cases:

      • INFINITY.predecessor() == STRAIGHT
      • ZERO.predecessor() == NEGATIVE
      • NEGATIVE.predecessor() == NEGATIVE

    • add

      public static S1ChordAngle add(S1ChordAngle a, S1ChordAngle b)
      Returns a new S1ChordAngle whose chord distance represents the sum of the angular distances represented by the 'a' and 'b' chord angles.

      Note that this method is much more efficient than converting the chord angles to S1Angles and adding those. It requires only one square root plus a few additions and multiplications.

    • sub

      public static S1ChordAngle sub(S1ChordAngle a, S1ChordAngle b)
      Subtract one S1ChordAngle from another.

      Note that this method is much more efficient than converting the chord angles to S1Angles and adding those. It requires only one square root plus a few additions and multiplications.

    • min

      public static S1ChordAngle min(S1ChordAngle a, S1ChordAngle b)
      Returns the smaller of the given instances.

    • max

      public static S1ChordAngle max(S1ChordAngle a, S1ChordAngle b)
      Returns the larger of the given instances.

    • sin2

      public static double sin2(S1ChordAngle a)
      Returns the square of Math.sin(toAngle().radians()), but computed more efficiently.

    • sin

      public static double sin(S1ChordAngle a)
      Returns Math.sin(toAngle().radians()), but computed more efficiently.

    • cos

      public static double cos(S1ChordAngle a)
      Returns Math.cos(toAngle().radians()), but computed more efficiently.

    • tan

      public static double tan(S1ChordAngle a)
      Returns Math.tan(toAngle().radians()), but computed more efficiently.

    • plusError

      public S1ChordAngle plusError(double error)
      Returns a new S1ChordAngle that has been adjusted by the given error bound (which can be positive or negative). error should be the value returned by one of the error bound methods below. For example: 
          S1ChordAngle a = new S1ChordAngle(x, y);
    S1ChordAngle a1 = a.plusError(a.getS2PointConstructorMaxError());

      If this isSpecial(), we return this.

    • getS1AngleConstructorMaxError

      public double getS1AngleConstructorMaxError()
      Returns the error in fromS1Angle(com.google.common.geometry.S1Angle).

    • getS2PointConstructorMaxError

      public double getS2PointConstructorMaxError()
      There is a relative error of 2.5 * DBL_EPSILON when computing the squared distance, plus a relative error of 2 * DBL_EPSILON and an absolute error of 16 * DBL_EPSILON^2 because the lengths of the input points may differ from 1 by up to 2 * DBL_EPSILON each. (This is the maximum length error in S2Point.normalize()).

    • toString

      public String toString()
      Returns the string of the closest S1Angle to this chord distance.
      Overrides:
      toString in class Object

    • compareTo

      public int compareTo(S1ChordAngle that)
      Specified by:
      compareTo in interface Comparable<S1ChordAngle>

    • equals

      public boolean equals(Object other)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object