Package com.google.common.geometry

Class 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:
    Serialized Form

    • Field Detail

      • ZERO

        public static final S1ChordAngle ZERO
        The zero chord angle.

      • RIGHT

        public static final S1ChordAngle RIGHT
        The chord angle of 90 degrees (a "right 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.

    • Constructor Detail

      • 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.

    • Method Detail

      • 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.

      • 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 "<" comparison to a "<=" 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.

      • 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.

      • 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

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object