Class 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:
    GreatCircles
    • Field Detail

      • 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 circle
        u - u axis in the equator plane
        v - v axis in the equator plane
        precision - 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 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:
        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 interface Hyperplane<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 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:
        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 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
      • 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
      • 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:
        java.lang.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:
        java.lang.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:
        java.lang.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(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 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:
        angle(GreatCircle)
      • 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:
        Embedding.toSpace(S)
      • 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:
        Vector3D.eq(Vector3D, Precision.DoubleEquivalence)
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object