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 Details

    • 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 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 circle
      u - u axis in the equator plane
      v - v axis in the equator plane
      precision - precision context used for floating point comparisons

  • Method Details

    • 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 the 0pi 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:

    • 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 interface Hyperplane<Point2S>
      Parameters:
      point - the point to compute the offset for
      Returns:
      the offset of the point
      See Also:

    • 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 of 0, 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 the Math#atan2(double, double) method and returns 0.
      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

      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 interface Hyperplane<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 interface Hyperplane<Point2S>
      Returns:
      a hyperplane with the opposite orientation

    • transform

      public GreatCircle transform(Transform<Point2S> transform)
      Transform this instance using the given Transform.
      Specified by:
      transform in interface Hyperplane<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 interface Hyperplane<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 a HyperplaneConvexSubset spanning this entire hyperplane. The returned subset contains all points lying in this hyperplane and no more.
      Specified by:
      span in interface Hyperplane<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 point
      end - 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 than pi

    • arc

      public GreatArc arc(Point1S start, Point1S end)
      Create an arc on this circle between the given subspace points.
      Parameters:
      start - start subspace point
      end - 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 than pi

    • arc

      public GreatArc arc(double start, double end)
      Create an arc on this circle between the given subspace azimuth values.
      Parameters:
      start - start subspace azimuth
      end - 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 than pi

    • 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

      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 to pt, 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 by angle(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 with
      pt - 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

      public Point1S toSubspace(Point2S point)
      Transform a space point into a subspace point.
      Specified by:
      toSubspace in interface Embedding<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

      public Point2S toSpace(Point1S point)
      Transform a subspace point into a space point.
      Specified by:
      toSpace in interface Embedding<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:

    • 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 equivalent pole, u, and v vectors.
      Parameters:
      other - great circle to compare with
      precision - 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()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object