Circle (Apache Commons Math 3.3 API)

org.apache.commons.math3.geometry.spherical.twod

## Class Circle

- java.lang.Object
- - org.apache.commons.math3.geometry.spherical.twod.Circle

- All Implemented Interfaces:
    Embedding<Sphere2D,Sphere1D>, Hyperplane<Sphere2D>

      public class Circle
      extends Object
      implements Hyperplane<Sphere2D>, Embedding<Sphere2D,Sphere1D>

  This class represents an oriented great circle on the 2-sphere.

  An oriented circle can be defined by a center point. The circle is the the set of points that are in the normal plan the center.

  Since it is oriented the two spherical caps at its two sides are unambiguously identified as a left cap and a right cap. This can be used to identify the interior and the exterior in a simple way by local properties only when part of a line is used to define part of a spherical polygon boundary.

  Since:
    3.3
  Version:
    $Id: Circle.java 1560115 2014-01-21 17:49:13Z luc $

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Circle(Circle circle)` Copy constructor.
    `Circle(S2Point first, S2Point second, double tolerance)` Build a great circle from two non-aligned points.
    `Circle(Vector3D pole, double tolerance)` Build a great circle from its pole.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Circle` | `copySelf()` Copy the instance.
    `Arc` | `getInsideArc(Circle other)` Get the arc of the instance that lies inside the other circle.
    `double` | `getOffset(Point<Sphere2D> point)` Get the offset (oriented distance) of a point.
    `double` | `getOffset(Vector3D direction)` Get the offset (oriented distance) of a direction.
    `double` | `getPhase(Vector3D direction)` Get the phase angle of a direction.
    `Vector3D` | `getPointAt(double alpha)` Get a circle point from its phase around the circle.
    `Vector3D` | `getPole()` Get the pole of the circle.
    `Circle` | `getReverse()` Get the reverse of the instance.
    `double` | `getTolerance()` Get the tolerance below which points are considered to belong to the hyperplane.
    `static Transform<Sphere2D,Sphere1D>` | `getTransform(Rotation rotation)` Get a `Transform` embedding a 3D rotation.
    `Vector3D` | `getXAxis()` Get the X axis of the circle.
    `Vector3D` | `getYAxis()` Get the Y axis of the circle.
    `Point<Sphere2D>` | `project(Point<Sphere2D> point)` Project a point to the hyperplane.
    `void` | `reset(Vector3D newPole)` Reset the instance as if built from a pole.
    `void` | `revertSelf()` Revert the instance.
    `boolean` | `sameOrientationAs(Hyperplane<Sphere2D> other)` Check if the instance has the same orientation as another hyperplane.
    `S2Point` | `toSpace(Point<Sphere1D> point)` Transform a sub-space point into a space point.
    `S1Point` | `toSubSpace(Point<Sphere2D> point)` Transform a space point into a sub-space point.
    `SubCircle` | `wholeHyperplane()` Build a sub-hyperplane covering the whole hyperplane.
    `SphericalPolygonsSet` | `wholeSpace()` Build a region covering the whole space.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Circle

          public Circle(Vector3D pole,
                double tolerance)

      Build a great circle from its pole.

      The circle is oriented in the trigonometric direction around pole.

      Parameters:
        `pole` - circle pole
        `tolerance` - tolerance below which close sub-arcs are merged together

    - #### Circle

          public Circle(S2Point first,
                S2Point second,
                double tolerance)

      Build a great circle from two non-aligned points.

      The circle is oriented from first to second point using the path smaller than \( \pi \).

      Parameters:
        `first` - first point contained in the great circle
        `second` - second point contained in the great circle
        `tolerance` - tolerance below which close sub-arcs are merged together

    - #### Circle

          public Circle(Circle circle)

      Copy constructor.

      The created instance is completely independent from the original instance, it is a deep copy.

      Parameters:
        `circle` - circle to copy

  - ### Method Detail

    - #### copySelf

          public Circle copySelf()

      Copy the instance.

      The instance created is completely independant of the original one. A deep copy is used, none of the underlying objects are shared (except for immutable objects).

      Specified by:
        `copySelf` in interface `Hyperplane<Sphere2D>`
      Returns:
        a new hyperplane, copy of the instance

    - #### reset

          public void reset(Vector3D newPole)

      Reset the instance as if built from a pole.

      The circle is oriented in the trigonometric direction around pole.

      Parameters:
        `newPole` - circle pole

    - #### revertSelf

          public void revertSelf()

      Revert the instance.

    - #### getReverse

          public Circle getReverse()

      Get the reverse of the instance.

      Get a circle with reversed orientation with respect to the instance. A new object is built, the instance is untouched.

      Returns:
        a new circle, with orientation opposite to the instance orientation

    - #### project

          public Point<Sphere2D> project(Point<Sphere2D> point)

      Project a point to the hyperplane.
      Specified by:
        `project` in interface `Hyperplane<Sphere2D>`
      Parameters:
        `point` - point to project
      Returns:
        projected point

    - #### getTolerance

          public double getTolerance()

      Get the tolerance below which points are considered to belong to the hyperplane.
      Specified by:
        `getTolerance` in interface `Hyperplane<Sphere2D>`
      Returns:
        tolerance below which points are considered to belong to the hyperplane

    - #### toSubSpace

          public S1Point toSubSpace(Point<Sphere2D> point)

      Transform a space point into a sub-space point.
      Specified by:
        `toSubSpace` in interface `Embedding<Sphere2D,Sphere1D>`
      Parameters:
        `point` - n-dimension point of the space
      Returns:
        (n-1)-dimension point of the sub-space corresponding to the specified space point
      See Also:
        `getPhase(Vector3D)`

    - #### getPhase

          public double getPhase(Vector3D direction)

      Get the phase angle of a direction.

      The direction may not belong to the circle as the phase is computed for the meridian plane between the circle pole and the direction.

      Parameters:
        `direction` - direction for which phase is requested
      Returns:
        phase angle of the direction around the circle
      See Also:
        `toSubSpace(Point)`

    - #### toSpace

          public S2Point toSpace(Point<Sphere1D> point)

      Transform a sub-space point into a space point.
      Specified by:
        `toSpace` in interface `Embedding<Sphere2D,Sphere1D>`
      Parameters:
        `point` - (n-1)-dimension point of the sub-space
      Returns:
        n-dimension point of the space corresponding to the specified sub-space point
      See Also:
        `getPointAt(double)`

    - #### getPointAt

          public Vector3D getPointAt(double alpha)

      Get a circle point from its phase around the circle.
      Parameters:
        `alpha` - phase around the circle
      Returns:
        circle point on the sphere
      See Also:
        `toSpace(Point)`, `getXAxis()`, `getYAxis()`

    - #### getXAxis

          public Vector3D getXAxis()

      Get the X axis of the circle.

      This method returns the same value as `getPointAt(0.0)` but it does not do any computation and always return the same instance.

      Returns:
        an arbitrary x axis on the circle
      See Also:
        `getPointAt(double)`, `getYAxis()`, `getPole()`

    - #### getYAxis

          public Vector3D getYAxis()

      Get the Y axis of the circle.

      This method returns the same value as `getPointAt(0.5 * FastMath.PI)` but it does not do any computation and always return the same instance.

      Returns:
        an arbitrary y axis point on the circle
      See Also:
        `getPointAt(double)`, `getXAxis()`, `getPole()`

    - #### getPole

          public Vector3D getPole()

      Get the pole of the circle.

      As the circle is a great circle, the pole does not belong to it.

      Returns:
        pole of the circle
      See Also:
        `getXAxis()`, `getYAxis()`

    - #### getInsideArc

          public Arc getInsideArc(Circle other)

      Get the arc of the instance that lies inside the other circle.
      Parameters:
        `other` - other circle
      Returns:
        arc of the instance that lies inside the other circle

    - #### wholeHyperplane

          public SubCircle wholeHyperplane()

      Build a sub-hyperplane covering the whole hyperplane.
      Specified by:
        `wholeHyperplane` in interface `Hyperplane<Sphere2D>`
      Returns:
        a sub-hyperplane covering the whole hyperplane

    - #### wholeSpace

          public SphericalPolygonsSet wholeSpace()

      Build a region covering the whole space.
      Specified by:
        `wholeSpace` in interface `Hyperplane<Sphere2D>`
      Returns:
        a region containing the instance (really a `SphericalPolygonsSet` instance)

    - #### getOffset

          public double getOffset(Point<Sphere2D> point)

      Get the offset (oriented distance) of a point.

      The offset is 0 if the point is on the underlying hyperplane, it is positive if the point is on one particular side of the hyperplane, and it is negative if the point is on the other side, according to the hyperplane natural orientation.

      Specified by:
        `getOffset` in interface `Hyperplane<Sphere2D>`
      Parameters:
        `point` - point to check
      Returns:
        offset of the point
      See Also:
        `getOffset(Vector3D)`

    - #### getOffset

          public double getOffset(Vector3D direction)

      Get the offset (oriented distance) of a direction.

      The offset is defined as the angular distance between the circle center and the direction minus the circle radius. It is therefore 0 on the circle, positive for directions outside of the cone delimited by the circle, and negative inside the cone.

      Parameters:
        `direction` - direction to check
      Returns:
        offset of the direction
      See Also:
        `getOffset(Point)`

    - #### sameOrientationAs

          public boolean sameOrientationAs(Hyperplane<Sphere2D> other)

      Check if the instance has the same orientation as another hyperplane.

      This method is expected to be called on parallel hyperplanes. The method should not re-check for parallelism, only for orientation, typically by testing something like the sign of the dot-products of normals.

      Specified by:
        `sameOrientationAs` in interface `Hyperplane<Sphere2D>`
      Parameters:
        `other` - other hyperplane to check against the instance
      Returns:
        true if the instance and the other hyperplane have the same orientation

    - #### getTransform

          public static Transform<Sphere2D,Sphere1D> getTransform(Rotation rotation)

      Get a `Transform` embedding a 3D rotation.
      Parameters:
        `rotation` - rotation to use
      Returns:
        a new transform that can be applied to either `Point`, `Line` or `SubHyperplane` instances

Copyright © 2003–2014 The Apache Software Foundation. All rights reserved.