Class GreatCircle
java.lang.Object
org.apache.commons.geometry.core.partitioning.AbstractHyperplane<Point2S>
org.apache.commons.geometry.spherical.twod.GreatCircle
- All Implemented Interfaces:
Embedding<Point2S,
,Point1S> EmbeddingHyperplane<Point2S,
,Point1S> Hyperplane<Point2S>
public final class GreatCircle
extends AbstractHyperplane<Point2S>
implements EmbeddingHyperplane<Point2S,Point1S>
Class representing a great circle on the 2-sphere. A great circle is the
intersection of a sphere with a plane that passes through its center. It is
the largest diameter circle that can be drawn on the sphere and partitions the
sphere into two hemispheres. The vectors
u
and v
lie in the great
circle plane, while the vector w
(the pole) is perpendicular to it. The
pole vector points toward the minus side of the hyperplane.
Instances of this class are guaranteed to be immutable.
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final Vector3D.Unit
Pole or circle center.private final Vector3D.Unit
First axis in the equator plane, origin of the azimuth angles.private final Vector3D.Unit
Second axis in the equator plane, in quadrature with respect to u. -
Constructor Summary
ConstructorsConstructorDescriptionGreatCircle
(Vector3D.Unit pole, Vector3D.Unit u, Vector3D.Unit v, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Simple constructor. -
Method Summary
Modifier and TypeMethodDescriptiondouble
angle
(GreatCircle other) Compute the angle between this great circle and the argument.double
angle
(GreatCircle other, Point2S pt) Compute the angle between this great circle and the argument, measured at the intersection point closest to the given point.arc
(double start, double end) Create an arc on this circle between the given subspace azimuth values.arc
(AngularInterval.Convex interval) Create an arc on this circle consisting of the given subspace interval.Create an arc on this circle between the given subspace points.Create an arc on this circle between the given points.double
Get the azimuth angle of a vector in the range[0, 2pi)
.double
Get the azimuth angle of a point relative to this great circle instance, in the range[0, 2pi)
.boolean
eq
(GreatCircle other, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Return true if this instance should be considered equivalent to the argument, using the given precision context for comparison.boolean
getPole()
Get the pole of the great circle.Get the spherical point located at the positive pole of the instance.getU()
Get the u axis of the great circle.getV()
Get the v axis of the great circle.getW()
Get the w (pole) axis of the great circle.int
hashCode()
intersection
(GreatCircle other) Return one of the two intersection points between this instance and the argument.double
Get the offset (oriented distance) of a direction.double
Get the offset (oriented distance) of a point with respect to this instance.Project a point onto this instance.reverse()
Return a hyperplane that has the opposite orientation as this instance.boolean
similarOrientation
(Hyperplane<Point2S> other) Return true if this instance has a similar orientation to the given hyperplane, meaning that they point in generally the same direction.span()
Return aHyperplaneConvexSubset
spanning this entire hyperplane.Transform a subspace point into a space point.toString()
toSubspace
(Point2S point) Transform a space point into a subspace point.Transform this instance using the givenTransform
.vectorAt
(double azimuth) Get the vector on the great circle with the given azimuth angle.Methods inherited from class org.apache.commons.geometry.core.partitioning.AbstractHyperplane
classify, contains, getPrecision
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.apache.commons.geometry.core.Embedding
toSpace, toSubspace
Methods inherited from interface org.apache.commons.geometry.core.partitioning.Hyperplane
classify, contains
-
Field Details
-
pole
Pole or circle center. -
u
First axis in the equator plane, origin of the azimuth angles. -
v
Second axis in the equator plane, in quadrature with respect to u.
-
-
Constructor Details
-
GreatCircle
GreatCircle(Vector3D.Unit pole, Vector3D.Unit u, Vector3D.Unit v, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Simple constructor. Callers are responsible for ensuring the inputs are valid.- Parameters:
pole
- pole vector of the great circleu
- u axis in the equator planev
- v axis in the equator planeprecision
- precision context used for floating point comparisons
-
-
Method Details
-
getPole
Get the pole of the great circle. This vector is perpendicular to the equator plane of the instance.- Returns:
- pole of the great circle
-
getPolePoint
Get the spherical point located at the positive pole of the instance.- Returns:
- the spherical point located at the positive pole of the instance
-
getU
Get the u axis of the great circle. This vector is located in the equator plane and defines the0pi
location of the embedded subspace.- Returns:
- u axis of the great circle
-
getV
Get the v axis of the great circle. This vector lies in the equator plane, perpendicular to the u-axis.- Returns:
- v axis of the great circle
-
getW
Get the w (pole) axis of the great circle. The method is equivalent to#getPole()
.- Returns:
- the w (pole) axis of the great circle.
- See Also:
-
offset
Get the offset (oriented distance) of a point with respect to this instance. Points with an offset of zero lie on the hyperplane itself.The returned offset values are in the range
[-pi/2, +pi/2]
, with a point directly on the circle's pole vector having an offset of-pi/2
and its antipodal point having an offset of+pi/2
. Thus, the circle's pole vector points toward the minus side of the hyperplane.- Specified by:
offset
in interfaceHyperplane<Point2S>
- Parameters:
point
- the point to compute the offset for- Returns:
- the offset of the point
- See Also:
-
offset
Get the offset (oriented distance) of a direction.The offset computed here is equal to the angle between the circle's pole and the given vector minus
pi/2
. Thus, the pole vector has an offset of-pi/2
, a point on the circle itself has an offset of0
, and the negation of the pole vector has an offset of+pi/2
.- Parameters:
vec
- vector to compute the offset for- Returns:
- the offset (oriented distance) of a direction
-
azimuth
Get the azimuth angle of a point relative to this great circle instance, in the range[0, 2pi)
.- Parameters:
pt
- point to compute the azimuth for- Returns:
- azimuth angle of the point in the range
[0, 2pi)
-
azimuth
Get the azimuth angle of a vector in the range[0, 2pi)
. The azimuth angle is the angle of the projection of the argument on the equator plane relative to the plane's u-axis. Since the vector is projected onto the equator plane, it does not need to belong to the circle. Vectors parallel to the great circle's pole do not have a defined azimuth angle. In these cases, the method follows the rules of theMath#atan2(double, double)
method and returns0
.- Parameters:
vector
- vector to compute the great circle azimuth of- Returns:
- azimuth angle of the vector around the great circle in the range
[0, 2pi)
- See Also:
-
vectorAt
Get the vector on the great circle with the given azimuth angle.- Parameters:
azimuth
- azimuth angle in radians- Returns:
- the point on the great circle with the given phase angle
-
project
Project a point onto this instance.- Specified by:
project
in interfaceHyperplane<Point2S>
- Parameters:
point
- the point to project- Returns:
- the projection of the point onto this instance. The returned point lies on the hyperplane.
-
reverse
Return a hyperplane that has the opposite orientation as this instance. That is, the plus side of this instance is the minus side of the returned instance and vice versa.The returned instance has the same u-axis but opposite pole and v-axis as this instance.
- Specified by:
reverse
in interfaceHyperplane<Point2S>
- Returns:
- a hyperplane with the opposite orientation
-
transform
Transform this instance using the givenTransform
.- Specified by:
transform
in interfaceHyperplane<Point2S>
- Parameters:
transform
- object to transform this instance with- Returns:
- a new, transformed hyperplane
-
similarOrientation
Return true if this instance has a similar orientation to the given hyperplane, meaning that they point in generally the same direction. This method is not used to determine exact equality of hyperplanes, but rather to determine whether two hyperplanes that contain the same points are parallel (point in the same direction) or anti-parallel (point in opposite directions).- Specified by:
similarOrientation
in interfaceHyperplane<Point2S>
- Parameters:
other
- the hyperplane to compare with- Returns:
- true if the hyperplanes point in generally the same direction and could possibly be parallel
-
span
Return aHyperplaneConvexSubset
spanning this entire hyperplane. The returned subset contains all points lying in this hyperplane and no more.- Specified by:
span
in interfaceHyperplane<Point2S>
- Returns:
- a
HyperplaneConvexSubset
containing all points lying in this hyperplane
-
arc
Create an arc on this circle between the given points.- Parameters:
start
- start pointend
- end point- Returns:
- an arc on this circle between the given points
- Throws:
IllegalArgumentException
- if the specified interval is not convex (ie, the angle between the points is greater thanpi
-
arc
Create an arc on this circle between the given subspace points.- Parameters:
start
- start subspace pointend
- end subspace point- Returns:
- an arc on this circle between the given subspace points
- Throws:
IllegalArgumentException
- if the specified interval is not convex (ie, the angle between the points is greater thanpi
-
arc
Create an arc on this circle between the given subspace azimuth values.- Parameters:
start
- start subspace azimuthend
- end subspace azimuth- Returns:
- an arc on this circle between the given subspace azimuths
- Throws:
IllegalArgumentException
- if the specified interval is not convex (ie, the angle between the points is greater thanpi
-
arc
Create an arc on this circle consisting of the given subspace interval.- Parameters:
interval
- subspace interval- Returns:
- an arc on this circle consisting of the given subspace interval
-
intersection
Return one of the two intersection points between this instance and the argument. If the circles occupy the same space (ie, their poles are parallel or anti-parallel), then null is returned. Otherwise, the intersection located at the cross product of the pole of this instance and that of the argument is returned (ie,thisPole.cross(otherPole)
. The other intersection point of the pair is antipodal to this point.- Parameters:
other
- circle to intersect with- Returns:
- one of the two intersection points between this instance and the argument
-
angle
Compute the angle between this great circle and the argument. The return value is the angle between the poles of the two circles, in the range[0, pi]
.- Parameters:
other
- great circle to compute the angle with- Returns:
- the angle between this great circle and the argument in the
range
[0, pi]
- See Also:
-
angle
Compute the angle between this great circle and the argument, measured at the intersection point closest to the given point. The value is computed as if a tangent line was drawn from each great circle at the intersection point closest topt
, and the angle required to rotate the tangent line representing the current instance to align with that of the given instance was measured. The return value lies in the range[-pi, pi)
and has an absolute value equal to that returned byangle(GreatCircle)
, but possibly a different sign. If the given point is equidistant from both intersection points (as evaluated by this instance's precision context), then the point is assumed to be closest to the point opposite the cross product of the two poles.- Parameters:
other
- great circle to compute the angle withpt
- point determining the circle intersection to compute the angle at- Returns:
- the angle between this great circle and the argument as measured at the
intersection point closest to the given point; the value is in the range
[-pi, pi)
- See Also:
-
toSubspace
Transform a space point into a subspace point.- Specified by:
toSubspace
in interfaceEmbedding<Point2S,
Point1S> - Parameters:
point
- n-dimension point of the space- Returns:
- lower-dimension point of the subspace corresponding to the specified space point
- See Also:
-
toSpace
Transform a subspace point into a space point. -
eq
public boolean eq(GreatCircle other, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Return true if this instance should be considered equivalent to the argument, using the given precision context for comparison. Instances are considered equivalent if have equivalentpole
,u
, andv
vectors.- Parameters:
other
- great circle to compare withprecision
- precision context to use for the comparison- Returns:
- true if this instance should be considered equivalent to the argument
- See Also:
-
hashCode
public int hashCode() -
equals
-
toString
-