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 vectorsu
andv
lie in the great circle plane, while the vectorw
(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:
GreatCircles
-
-
Field Summary
Fields Modifier and Type Field Description private Vector3D.Unit
pole
Pole or circle center.private Vector3D.Unit
u
First axis in the equator plane, origin of the azimuth angles.private Vector3D.Unit
v
Second axis in the equator plane, in quadrature with respect to u.
-
Constructor Summary
Constructors Constructor Description GreatCircle(Vector3D.Unit pole, Vector3D.Unit u, Vector3D.Unit v, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
Simple constructor.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description double
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.GreatArc
arc(double start, double end)
Create an arc on this circle between the given subspace azimuth values.GreatArc
arc(AngularInterval.Convex interval)
Create an arc on this circle consisting of the given subspace interval.GreatArc
arc(Point1S start, Point1S end)
Create an arc on this circle between the given subspace points.GreatArc
arc(Point2S start, Point2S end)
Create an arc on this circle between the given points.double
azimuth(Vector3D vector)
Get the azimuth angle of a vector in the range[0, 2pi)
.double
azimuth(Point2S pt)
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
equals(java.lang.Object obj)
Vector3D.Unit
getPole()
Get the pole of the great circle.Point2S
getPolePoint()
Get the spherical point located at the positive pole of the instance.Vector3D.Unit
getU()
Get the u axis of the great circle.Vector3D.Unit
getV()
Get the v axis of the great circle.Vector3D.Unit
getW()
Get the w (pole) axis of the great circle.int
hashCode()
Point2S
intersection(GreatCircle other)
Return one of the two intersection points between this instance and the argument.double
offset(Vector3D vec)
Get the offset (oriented distance) of a direction.double
offset(Point2S point)
Get the offset (oriented distance) of a point with respect to this instance.Point2S
project(Point2S point)
Project a point onto this instance.GreatCircle
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.GreatArc
span()
Return aHyperplaneConvexSubset
spanning this entire hyperplane.Point2S
toSpace(Point1S point)
Transform a subspace point into a space point.java.lang.String
toString()
Point1S
toSubspace(Point2S point)
Transform a space point into a subspace point.GreatCircle
transform(Transform<Point2S> transform)
Transform this instance using the givenTransform
.Vector3D
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 Detail
-
pole
private final Vector3D.Unit pole
Pole or circle center.
-
u
private final Vector3D.Unit u
First axis in the equator plane, origin of the azimuth angles.
-
v
private final Vector3D.Unit v
Second axis in the equator plane, in quadrature with respect to u.
-
-
Constructor Detail
-
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 Detail
-
getPole
public Vector3D.Unit 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
public Point2S 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
public Vector3D.Unit 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
public Vector3D.Unit 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
public Vector3D.Unit 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:
getPole()
-
offset
public double offset(Point2S point)
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(Vector3D)
-
offset
public double offset(Vector3D vec)
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
public double azimuth(Point2S pt)
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
public double azimuth(Vector3D vector)
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:
toSubspace(Point2S)
-
vectorAt
public Vector3D vectorAt(double azimuth)
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
public Point2S project(Point2S point)
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
public GreatCircle 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
public GreatCircle transform(Transform<Point2S> 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
public 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. 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
public GreatArc 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
public GreatArc arc(Point2S start, Point2S end)
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:
java.lang.IllegalArgumentException
- if the specified interval is not convex (ie, the angle between the points is greater thanpi
-
arc
public GreatArc arc(Point1S start, Point1S end)
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:
java.lang.IllegalArgumentException
- if the specified interval is not convex (ie, the angle between the points is greater thanpi
-
arc
public GreatArc arc(double start, double end)
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:
java.lang.IllegalArgumentException
- if the specified interval is not convex (ie, the angle between the points is greater thanpi
-
arc
public GreatArc arc(AngularInterval.Convex interval)
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
public Point2S intersection(GreatCircle other)
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
public double angle(GreatCircle other)
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(GreatCircle, Point2S)
-
angle
public 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. 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:
angle(GreatCircle)
-
toSubspace
public Point1S toSubspace(Point2S point)
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:
Embedding.toSpace(S)
-
toSpace
public Point2S toSpace(Point1S point)
Transform a subspace point into a space point.- Specified by:
toSpace
in interfaceEmbedding<Point2S,Point1S>
- Parameters:
point
- lower-dimension point of the subspace- Returns:
- n-dimension point of the space corresponding to the specified subspace point
- See Also:
Embedding.toSubspace(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:
Vector3D.eq(Vector3D, Precision.DoubleEquivalence)
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
equals
public boolean equals(java.lang.Object obj)
- Overrides:
equals
in classjava.lang.Object
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
-