SphericalPolygonsSet (Apache Commons Math 3.3 API)

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

## Class SphericalPolygonsSet

- java.lang.Object
- - org.apache.commons.math3.geometry.partitioning.AbstractRegion<Sphere2D,Sphere1D>
  - - org.apache.commons.math3.geometry.spherical.twod.SphericalPolygonsSet

- All Implemented Interfaces:
    Region<Sphere2D>

      public class SphericalPolygonsSet
      extends AbstractRegion<Sphere2D,Sphere1D>

  This class represents a region on the 2-sphere: a set of spherical polygons.
  Since:
    3.3
  Version:
    $Id: SphericalPolygonsSet.java 1591835 2014-05-02 09:04:01Z tn $

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface org.apache.commons.math3.geometry.partitioning.Region

      `Region.Location`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SphericalPolygonsSet(BSPTree<Sphere2D> tree, double tolerance)` Build a polygons set from a BSP tree.
    `SphericalPolygonsSet(Collection<SubHyperplane<Sphere2D>> boundary, double tolerance)` Build a polygons set from a Boundary REPresentation (B-rep).
    `SphericalPolygonsSet(double tolerance)` Build a polygons set representing the whole real 2-sphere.
    `SphericalPolygonsSet(double hyperplaneThickness, S2Point... vertices)` Build a polygon from a simple list of vertices.
    `SphericalPolygonsSet(Vector3D pole, double tolerance)` Build a polygons set representing a hemisphere.
    `SphericalPolygonsSet(Vector3D center, Vector3D meridian, double outsideRadius, int n, double tolerance)` Build a polygons set representing a regular polygon.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `SphericalPolygonsSet` | `buildNew(BSPTree<Sphere2D> tree)` Build a region using the instance as a prototype.
    `protected void` | `computeGeometricalProperties()` Compute some geometrical properties.
    `List<Vertex>` | `getBoundaryLoops()` Get the boundary loops of the polygon.
    `EnclosingBall<Sphere2D,S2Point>` | `getEnclosingCap()` Get a spherical cap enclosing the polygon.

    - ### Methods inherited from class org.apache.commons.math3.geometry.partitioning.AbstractRegion

      `applyTransform, checkPoint, checkPoint, checkPoint, checkPoint, contains, copySelf, getBarycenter, getBoundarySize, getSize, getTolerance, getTree, intersection, isEmpty, isEmpty, isFull, isFull, projectToBoundary, setBarycenter, setBarycenter, setSize, side`

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

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

- - ### Constructor Detail

    - #### SphericalPolygonsSet

          public SphericalPolygonsSet(double tolerance)

      Build a polygons set representing the whole real 2-sphere.
      Parameters:
        `tolerance` - below which points are consider to be identical

    - #### SphericalPolygonsSet

          public SphericalPolygonsSet(Vector3D pole,
                              double tolerance)

      Build a polygons set representing a hemisphere.
      Parameters:
        `pole` - pole of the hemisphere (the pole is in the inside half)
        `tolerance` - below which points are consider to be identical

    - #### SphericalPolygonsSet

          public SphericalPolygonsSet(Vector3D center,
                              Vector3D meridian,
                              double outsideRadius,
                              int n,
                              double tolerance)

      Build a polygons set representing a regular polygon.
      Parameters:
        `center` - center of the polygon (the center is in the inside half)
        `meridian` - point defining the reference meridian for first polygon vertex
        `outsideRadius` - distance of the vertices to the center
        `n` - number of sides of the polygon
        `tolerance` - below which points are consider to be identical

    - #### SphericalPolygonsSet

          public SphericalPolygonsSet(BSPTree<Sphere2D> tree,
                              double tolerance)

      Build a polygons set from a BSP tree.

      The leaf nodes of the BSP tree must have a `Boolean` attribute representing the inside status of the corresponding cell (true for inside cells, false for outside cells). In order to avoid building too many small objects, it is recommended to use the predefined constants `Boolean.TRUE` and `Boolean.FALSE`

      Parameters:
        `tree` - inside/outside BSP tree representing the region
        `tolerance` - below which points are consider to be identical

    - #### SphericalPolygonsSet

          public SphericalPolygonsSet(Collection<SubHyperplane<Sphere2D>> boundary,
                              double tolerance)

      Build a polygons set from a Boundary REPresentation (B-rep).

      The boundary is provided as a collection of `sub-hyperplanes`. Each sub-hyperplane has the interior part of the region on its minus side and the exterior on its plus side.

      The boundary elements can be in any order, and can form several non-connected sets (like for example polygons with holes or a set of disjoint polygons considered as a whole). In fact, the elements do not even need to be connected together (their topological connections are not used here). However, if the boundary does not really separate an inside open from an outside open (open having here its topological meaning), then subsequent calls to the `checkPoint` method will not be meaningful anymore.

      If the boundary is empty, the region will represent the whole space.

      Parameters:
        `boundary` - collection of boundary elements, as a collection of `SubHyperplane` objects
        `tolerance` - below which points are consider to be identical

    - #### SphericalPolygonsSet

          public SphericalPolygonsSet(double hyperplaneThickness,
                              S2Point... vertices)

      Build a polygon from a simple list of vertices.

      The boundary is provided as a list of points considering to represent the vertices of a simple loop. The interior part of the region is on the left side of this path and the exterior is on its right side.

      This constructor does not handle polygons with a boundary forming several disconnected paths (such as polygons with holes).

      For cases where this simple constructor applies, it is expected to be numerically more robust than the `general constructor` using `subhyperplanes`.

      If the list is empty, the region will represent the whole space.

      Polygons with thin pikes or dents are inherently difficult to handle because they involve circles with almost opposite directions at some vertices. Polygons whose vertices come from some physical measurement with noise are also difficult because an edge that should be straight may be broken in lots of different pieces with almost equal directions. In both cases, computing the circles intersections is not numerically robust due to the almost 0 or almost π angle. Such cases need to carefully adjust the `hyperplaneThickness` parameter. A too small value would often lead to completely wrong polygons with large area wrongly identified as inside or outside. Large values are often much safer. As a rule of thumb, a value slightly below the size of the most accurate detail needed is a good value for the `hyperplaneThickness` parameter.

      Parameters:
        `hyperplaneThickness` - tolerance below which points are considered to belong to the hyperplane (which is therefore more a slab)
        `vertices` - vertices of the simple loop boundary

  - ### Method Detail

    - #### buildNew

          public SphericalPolygonsSet buildNew(BSPTree<Sphere2D> tree)

      Build a region using the instance as a prototype.

      This method allow to create new instances without knowing exactly the type of the region. It is an application of the prototype design pattern.

      The leaf nodes of the BSP tree must have a `Boolean` attribute representing the inside status of the corresponding cell (true for inside cells, false for outside cells). In order to avoid building too many small objects, it is recommended to use the predefined constants `Boolean.TRUE` and `Boolean.FALSE`. The tree also must have either null internal nodes or internal nodes representing the boundary as specified in the `getTree` method).

      Specified by:
        `buildNew` in interface `Region<Sphere2D>`
      Specified by:
        `buildNew` in class `AbstractRegion<Sphere2D,Sphere1D>`
      Parameters:
        `tree` - inside/outside BSP tree representing the new region
      Returns:
        the built region

    - #### computeGeometricalProperties

          protected void computeGeometricalProperties()
                                               throws MathIllegalStateException

      Compute some geometrical properties.

      The properties to compute are the barycenter and the size.

      Specified by:
        `computeGeometricalProperties` in class `AbstractRegion<Sphere2D,Sphere1D>`
      Throws:
        `MathIllegalStateException` - if the tolerance setting does not allow to build a clean non-ambiguous boundary

    - #### getBoundaryLoops

          public List<Vertex> getBoundaryLoops()
                                        throws MathIllegalStateException

      Get the boundary loops of the polygon.

      The polygon boundary can be represented as a list of closed loops, each loop being given by exactly one of its vertices. From each loop start vertex, one can follow the loop by finding the outgoing edge, then the end vertex, then the next outgoing edge ... until the start vertex of the loop (exactly the same instance) is found again once the full loop has been visited.

      If the polygon has no boundary at all, a zero length loop array will be returned.

      If the polygon is a simple one-piece polygon, then the returned array will contain a single vertex.

      All edges in the various loops have the inside of the region on their left side (i.e. toward their pole) and the outside on their right side (i.e. away from their pole) when moving in the underlying circle direction. This means that the closed loops obey the direct trigonometric orientation.

      Returns:
        boundary of the polygon, organized as an unmodifiable list of loops start vertices.
      Throws:
        `MathIllegalStateException` - if the tolerance setting does not allow to build a clean non-ambiguous boundary
      See Also:
        `Vertex`, `Edge`

    - #### getEnclosingCap

          public EnclosingBall<Sphere2D,S2Point> getEnclosingCap()

      Get a spherical cap enclosing the polygon.

      This method is intended as a first test to quickly identify points that are guaranteed to be outside of the region, hence performing a full `checkPoint` only if the point status remains undecided after the quick check. It is is therefore mostly useful to speed up computation for small polygons with complex shapes (say a country boundary on Earth), as the spherical cap will be small and hence will reliably identify a large part of the sphere as outside, whereas the full check can be more computing intensive. A typical use case is therefore:

             // compute region, plus an enclosing spherical cap
             SphericalPolygonsSet complexShape = ...;
             EnclosingBall cap = complexShape.getEnclosingCap();

             // check lots of points
             for (Vector3D p : points) {

               final Location l;
               if (cap.contains(p)) {
                 // we cannot be sure where the point is
                 // we need to perform the full computation
                 l = complexShape.checkPoint(v);
               } else {
                 // no need to do further computation,
                 // we already know the point is outside
                 l = Location.OUTSIDE;
               }

               // use l ...

             }

      In the special cases of empty or whole sphere polygons, special spherical caps are returned, with angular radius set to negative or positive infinity so the `ball.contains(point)` method return always false or true.

      This method is not guaranteed to return the smallest enclosing cap.

      Returns:
        a spherical cap enclosing the polygon

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