Class S1ChordAngle
- java.lang.Object
-
- com.google.common.geometry.S1ChordAngle
-
- All Implemented Interfaces:
java.io.Serializable
,java.lang.Comparable<S1ChordAngle>
@GwtCompatible(serializable=true) public final class S1ChordAngle extends java.lang.Object implements java.lang.Comparable<S1ChordAngle>, java.io.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 Summary
Fields Modifier and Type Field Description static S1ChordAngle
INFINITY
A chord angle larger than any finite chord angle.private double
length2
static double
MAX_LENGTH2
Max value that can be returned fromgetLength2()
.static S1ChordAngle
NEGATIVE
A chord angle smaller thanZERO
.static S1ChordAngle
RIGHT
The chord angle of 90 degrees (a "right angle").static S1ChordAngle
STRAIGHT
The chord angle of 180 degrees (a "straight angle").static S1ChordAngle
ZERO
The zero chord angle.
-
Constructor Summary
Constructors Modifier Constructor Description private
S1ChordAngle(double length2)
S1ChordAngles are represented by the squared chord length, which can range from 0 toMAX_LENGTH2
.S1ChordAngle(S2Point x, S2Point y)
Constructs the S1ChordAngle corresponding to the distance between the two given points.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description 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.int
compareTo(S1ChordAngle that)
static double
cos(S1ChordAngle a)
Returns Math.cos(toAngle().radians()), but computed more efficiently.boolean
equals(java.lang.Object other)
static S1ChordAngle
fromLength2(double length2)
Construct an S1ChordAngle from the squared chord length.static S1ChordAngle
fromS1Angle(S1Angle angle)
Returns a new chord angle approximated fromangle
(seegetS1AngleConstructorMaxError()
for the max magnitude of the error).double
getLength2()
The squared length of the chord.double
getS1AngleConstructorMaxError()
Returns the error infromS1Angle(com.google.common.geometry.S1Angle)
.double
getS2PointConstructorMaxError()
There is a relative error of2.5 * DBL_EPSILON
when computing the squared distance, plus a relative error of2 * DBL_EPSILON
and an absolute error of16 * DBL_EPSILON^2
because the lengths of the input points may differ from 1 by up to2 * DBL_EPSILON
each.int
hashCode()
boolean
isInfinity()
Returns whether the chord distance is exactly (positive) infinity.boolean
isNegative()
Returns whether the chord distance is negative.boolean
isSpecial()
Returns true if the angle is negative or infinity.boolean
isValid()
Returns true if getLength2() is within the normal range of 0 to 4 (inclusive) or the angle is special.boolean
isZero()
Returns whether the chord distance is exactly 0.static S1ChordAngle
max(S1ChordAngle a, S1ChordAngle b)
Returns the larger of the given instances.static S1ChordAngle
min(S1ChordAngle a, S1ChordAngle b)
Returns the smaller of the given instances.S1ChordAngle
plusError(double error)
Returns a new S1ChordAngle that has been adjusted by the given error bound (which can be positive or negative).S1ChordAngle
predecessor()
Assuccessor()
, but returns the largest representable S1ChordAngle less than this object.static double
sin(S1ChordAngle a)
Returns Math.sin(toAngle().radians()), but computed more efficiently.static double
sin2(S1ChordAngle a)
Returns the square of Math.sin(toAngle().radians()), but computed more efficiently.static S1ChordAngle
sub(S1ChordAngle a, S1ChordAngle b)
Subtract one S1ChordAngle from another.S1ChordAngle
successor()
Returns the smallest representable S1ChordAngle larger than this object.static double
tan(S1ChordAngle a)
Returns Math.tan(toAngle().radians()), but computed more efficiently.S1Angle
toAngle()
Convert the chord angle to anS1Angle
.java.lang.String
toString()
Returns the string of the closestS1Angle
to this chord distance.
-
-
-
Field Detail
-
MAX_LENGTH2
public static final double MAX_LENGTH2
Max value that can be returned fromgetLength2()
.- See Also:
- Constant Field Values
-
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 onINFINITY
are comparisons andS1Angle
conversions.
-
NEGATIVE
public static final S1ChordAngle NEGATIVE
-
length2
private final double length2
-
-
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.
-
S1ChordAngle
private S1ChordAngle(double length2)
S1ChordAngles are represented by the squared chord length, which can range from 0 toMAX_LENGTH2
.INFINITY
uses an infinite squared length.
-
-
Method Detail
-
fromS1Angle
public static S1ChordAngle fromS1Angle(S1Angle angle)
Returns a new chord angle approximated fromangle
(seegetS1AngleConstructorMaxError()
for the max magnitude of the error).Angles outside the range [0, Pi] are handled as follows:
S1Angle.INFINITY
is mapped toINFINITY
- negative angles are mapped to
NEGATIVE
- finite angles larger than Pi are mapped to
STRAIGHT
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 toS1Angle
s 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 ofMAX_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 anS1Angle
.INFINITY
is converted toS1Angle.INFINITY
, andNEGATIVE
is converted to a negativeS1Angle
. 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 "<" comparison to a "<=" comparison.Note the following special cases:
- NEGATIVE.successor() == ZERO
- STRAIGHT.successor() == INFINITY
- INFINITY.Successor() == INFINITY
-
predecessor
public S1ChordAngle predecessor()
Assuccessor()
, 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 returnthis
.
-
getS1AngleConstructorMaxError
public double getS1AngleConstructorMaxError()
Returns the error infromS1Angle(com.google.common.geometry.S1Angle)
.
-
getS2PointConstructorMaxError
public double getS2PointConstructorMaxError()
There is a relative error of2.5 * DBL_EPSILON
when computing the squared distance, plus a relative error of2 * DBL_EPSILON
and an absolute error of16 * DBL_EPSILON^2
because the lengths of the input points may differ from 1 by up to2 * DBL_EPSILON
each. (This is the maximum length error inS2Point.normalize()
).
-
toString
public java.lang.String toString()
Returns the string of the closestS1Angle
to this chord distance.- Overrides:
toString
in classjava.lang.Object
-
compareTo
public int compareTo(S1ChordAngle that)
- Specified by:
compareTo
in interfacejava.lang.Comparable<S1ChordAngle>
-
equals
public boolean equals(java.lang.Object other)
- Overrides:
equals
in classjava.lang.Object
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
-