Class S1ChordAngle
- All Implemented Interfaces:
Serializable
,Comparable<S1ChordAngle>
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 Summary
FieldsModifier and TypeFieldDescriptionstatic final S1ChordAngle
A chord angle larger than any finite chord angle.private final double
static final double
Max value that can be returned fromgetLength2()
.static final S1ChordAngle
A chord angle smaller thanZERO
.static final S1ChordAngle
The chord angle of 90 degrees (a "right angle").static final S1ChordAngle
The chord angle of 180 degrees (a "straight angle").static final S1ChordAngle
The zero chord angle. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
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
Modifier and TypeMethodDescriptionstatic 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
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
The squared length of the chord.double
Returns the error infromS1Angle(com.google.common.geometry.S1Angle)
.double
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
Returns whether the chord distance is exactly (positive) infinity.boolean
Returns whether the chord distance is negative.boolean
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.plusError
(double error) Returns a new S1ChordAngle that has been adjusted by the given error bound (which can be positive or negative).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.Returns the smallest representable S1ChordAngle larger than this object.static double
tan
(S1ChordAngle a) Returns Math.tan(toAngle().radians()), but computed more efficiently.toAngle()
Convert the chord angle to anS1Angle
.toString()
Returns the string of the closestS1Angle
to this chord distance.
-
Field Details
-
MAX_LENGTH2
public static final double MAX_LENGTH2Max value that can be returned fromgetLength2()
.- See Also:
-
ZERO
The zero chord angle. -
RIGHT
The chord angle of 90 degrees (a "right angle"). -
STRAIGHT
The chord angle of 180 degrees (a "straight angle"). This is the max finite chord angle. -
INFINITY
A chord angle larger than any finite chord angle. The only valid operations onINFINITY
are comparisons andS1Angle
conversions. -
NEGATIVE
-
length2
private final double length2
-
-
Constructor Details
-
S1ChordAngle
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 Details
-
fromS1Angle
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
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
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
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
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
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
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
Returns the smaller of the given instances. -
max
Returns the larger of the given instances. -
sin2
Returns the square of Math.sin(toAngle().radians()), but computed more efficiently. -
sin
Returns Math.sin(toAngle().radians()), but computed more efficiently. -
cos
Returns Math.cos(toAngle().radians()), but computed more efficiently. -
tan
Returns Math.tan(toAngle().radians()), but computed more efficiently. -
plusError
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
Returns the string of the closestS1Angle
to this chord distance. -
compareTo
- Specified by:
compareTo
in interfaceComparable<S1ChordAngle>
-
equals
-
hashCode
public int hashCode()
-