Apache Commons Math 3.6.1 · org.apache.commons.math3.geometry.spherical.twod.SphericalPolygonsSet

Modifier and Type	Field and Description
private List<Vertex>	loops Boundary defined as an array of closed loops start vertices.

Access	Constructor and Description
public	SphericalPolygonsSet(final double below which points are consider to be identical tolerance) Build a polygons set representing the whole real 2-sphere.
public	SphericalPolygonsSet(final Vector3D pole of the hemisphere (the pole is in the inside half) pole, final double below which points are consider to be identical tolerance) Build a polygons set representing a hemisphere.
public	SphericalPolygonsSet(final Vector3D center of the polygon (the center is in the inside half) center, final Vector3D point defining the reference meridian for first polygon vertex meridian, final double distance of the vertices to the center outsideRadius, final int number of sides of the polygon n, final double below which points are consider to be identical tolerance) Build a polygons set representing a regular polygon.
public	SphericalPolygonsSet(final BSPTree<Sphere2D> inside/outside BSP tree representing the region tree, final double below which points are consider to be identical tolerance) Build a polygons set from a BSP tree.
public	SphericalPolygonsSet(final Collection<SubHyperplane<Sphere2D>> collection of boundary elements, as a collection of `SubHyperplane` objects boundary, final double below which points are consider to be identical tolerance) Build a polygons set from a Boundary REPresentation (B-rep).
public	SphericalPolygonsSet(final double tolerance below which points are considered to belong to the hyperplane (which is therefore more a slab) hyperplaneThickness, final S2Point... vertices of the simple loop boundary vertices) Build a polygon from a simple list of vertices.

Method Summary

Modifier and Type	Method and Description
public SphericalPolygonsSet	buildNew(final BSPTree<Sphere2D> inside/outside BSP tree representing the new region tree) Implements abstract org.apache.commons.math3.geometry.partitioning.AbstractRegion.buildNew. Implements org.apache.commons.math3.geometry.partitioning.Region.buildNew. Build a region using the instance as a prototype.
protected void	computeGeometricalProperties() Implements abstract org.apache.commons.math3.geometry.partitioning.AbstractRegion.computeGeometricalProperties. Compute some geometrical properties.
private static S2Point[]	Returns: vertices array createRegularPolygonVertices(final Vector3D center of the polygon (the center is in the inside half) center, final Vector3D point defining the reference meridian for first polygon vertex meridian, final double distance of the vertices to the center outsideRadius, final int number of sides of the polygon n) Build the vertices representing a regular polygon.
public List<Vertex>	Returns: boundary of the polygon, organized as an unmodifiable list of loops start vertices. getBoundaryLoops() Get the boundary loops of the polygon.
public EnclosingBall<Sphere2D, S2Point>	Returns: a spherical cap enclosing the polygon getEnclosingCap() Get a spherical cap enclosing the polygon.
private List<Vector3D>	Returns: list of points known to be strictly in all inside convex cells getInsidePoints() Gather some inside points.
private List<Vector3D>	Returns: list of points known to be strictly in all outside convex cells getOutsidePoints() Gather some outside points.
private static void	insertEdges(final double tolerance below which points are considered to belong to the hyperplane (which is therefore more a slab) hyperplaneThickness, final BSPTree<Sphere2D> current tree node (it is a leaf node at the beginning of the call) node, final List<Edge> list of edges to insert in the cell defined by this node (excluding edges not belonging to the cell defined by this node) edges) Recursively build a tree by inserting cut sub-hyperplanes.
private static BSPTree<Sphere2D>	Returns: the BSP tree of the input vertices verticesToTree(final double tolerance below which points are consider to belong to the hyperplane (which is therefore more a slab) hyperplaneThickness, final S2Point... vertices of the simple loop boundary vertices) Build the BSP tree of a polygons set from a simple list of vertices.

Field Detail

loops	back to summary
private List<Vertex> loops Boundary defined as an array of closed loops start vertices.

Constructor Detail

SphericalPolygonsSet	back to summary
public SphericalPolygonsSet(final double tolerance) Build a polygons set representing the whole real 2-sphere. Parameters tolerance:double below which points are consider to be identical

SphericalPolygonsSet

back to summary

public SphericalPolygonsSet(final double tolerance)

Build a polygons set representing the whole real 2-sphere.

Parameters

tolerance:double: below which points are consider to be identical

SphericalPolygonsSet	back to summary
public SphericalPolygonsSet(final Vector3D pole, final double tolerance) Build a polygons set representing a hemisphere. Parameters pole:Vector3D pole of the hemisphere (the pole is in the inside half) tolerance:double below which points are consider to be identical

SphericalPolygonsSet

back to summary

public SphericalPolygonsSet(final Vector3D pole, final double tolerance)

Build a polygons set representing a hemisphere.

Parameters

pole:Vector3D: pole of the hemisphere (the pole is in the inside half)
tolerance:double: below which points are consider to be identical

SphericalPolygonsSet	back to summary
public SphericalPolygonsSet(final Vector3D center, final Vector3D meridian, final double outsideRadius, final int n, final double tolerance) Build a polygons set representing a regular polygon. Parameters center:Vector3D center of the polygon (the center is in the inside half) meridian:Vector3D point defining the reference meridian for first polygon vertex outsideRadius:double distance of the vertices to the center n:int number of sides of the polygon tolerance:double below which points are consider to be identical

SphericalPolygonsSet

back to summary

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

Build a polygons set representing a regular polygon.

Parameters

center:Vector3D: center of the polygon (the center is in the inside half)
meridian:Vector3D: point defining the reference meridian for first polygon vertex
outsideRadius:double: distance of the vertices to the center
n:int: number of sides of the polygon
tolerance:double: below which points are consider to be identical

SphericalPolygonsSet back to summary

SphericalPolygonsSet	back to summary
public SphericalPolygonsSet(final BSPTree<Sphere2D> tree, final 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:BSPTree<Sphere2D> inside/outside BSP tree representing the region tolerance:double below which points are consider to be identical

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

Build a polygons set from a BSP tree.

Parameters

tree:BSPTree<Sphere2D>: inside/outside BSP tree representing the region
tolerance:double: below which points are consider to be identical

SphericalPolygonsSet back to summary

SphericalPolygonsSet	back to summary
public SphericalPolygonsSet(final Collection<SubHyperplane<Sphere2D>> boundary, final 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<SubHyperplane<Sphere2D>> collection of boundary elements, as a collection of `SubHyperplane` objects tolerance:double below which points are consider to be identical

public SphericalPolygonsSet(final Collection<SubHyperplane<Sphere2D>> boundary, final 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<SubHyperplane<Sphere2D>>: collection of boundary elements, as a collection of SubHyperplane objects
tolerance:double: below which points are consider to be identical

SphericalPolygonsSet back to summary

SphericalPolygonsSet	back to summary
public SphericalPolygonsSet(final double hyperplaneThickness, final 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:double tolerance below which points are considered to belong to the hyperplane (which is therefore more a slab) vertices:S2Point[] vertices of the simple loop boundary

public SphericalPolygonsSet(final double hyperplaneThickness, final 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:double: tolerance below which points are considered to belong to the hyperplane (which is therefore more a slab)
vertices:S2Point[]: vertices of the simple loop boundary

Method Detail

buildNew back to summary

buildNew	back to summary
public SphericalPolygonsSet buildNew(final BSPTree<Sphere2D> tree) Implements abstract org.apache.commons.math3.geometry.partitioning.AbstractRegion.buildNew. Implements org.apache.commons.math3.geometry.partitioning.Region.buildNew. Doc from org.apache.commons.math3.geometry.partitioning.AbstractRegion.buildNew. 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). Parameters tree:BSPTree<Sphere2D> Doc from org.apache.commons.math3.geometry.partitioning.Region.buildNew. inside/outside BSP tree representing the new region Returns:SphericalPolygonsSet Doc from org.apache.commons.math3.geometry.partitioning.Region.buildNew. the built region Annotations @Override

public SphericalPolygonsSet buildNew(final BSPTree<Sphere2D> tree)

Implements abstract org.apache.commons.math3.geometry.partitioning.AbstractRegion.buildNew.

Implements org.apache.commons.math3.geometry.partitioning.Region.buildNew.

Doc from org.apache.commons.math3.geometry.partitioning.AbstractRegion.buildNew.

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).

Parameters

tree:BSPTree<Sphere2D>

Doc from org.apache.commons.math3.geometry.partitioning.Region.buildNew.

inside/outside BSP tree representing the new region

Returns:SphericalPolygonsSet

Doc from org.apache.commons.math3.geometry.partitioning.Region.buildNew.

the built region

Annotations

@Override

computeGeometricalProperties	back to summary
protected void computeGeometricalProperties() throws MathIllegalStateException Implements abstract org.apache.commons.math3.geometry.partitioning.AbstractRegion.computeGeometricalProperties. Doc from org.apache.commons.math3.geometry.partitioning.AbstractRegion.computeGeometricalProperties. Compute some geometrical properties. The properties to compute are the barycenter and the size. Annotations @Override Exceptions MathIllegalStateException: if the tolerance setting does not allow to build a clean non-ambiguous boundary

computeGeometricalProperties

back to summary

protected void computeGeometricalProperties() throws MathIllegalStateException

Implements abstract org.apache.commons.math3.geometry.partitioning.AbstractRegion.computeGeometricalProperties.

Doc from org.apache.commons.math3.geometry.partitioning.AbstractRegion.computeGeometricalProperties.

Compute some geometrical properties.

The properties to compute are the barycenter and the size.

Annotations

@Override

Exceptions

MathIllegalStateException:: if the tolerance setting does not allow to build a clean non-ambiguous boundary

createRegularPolygonVertices	back to summary
private static S2Point[] createRegularPolygonVertices(final Vector3D center, final Vector3D meridian, final double outsideRadius, final int n) Build the vertices representing a regular polygon. Parameters center:Vector3D center of the polygon (the center is in the inside half) meridian:Vector3D point defining the reference meridian for first polygon vertex outsideRadius:double distance of the vertices to the center n:int number of sides of the polygon Returns:S2Point[] vertices array

createRegularPolygonVertices

back to summary

private static S2Point[] createRegularPolygonVertices(final Vector3D center, final Vector3D meridian, final double outsideRadius, final int n)

Build the vertices representing a regular polygon.

Parameters

center:Vector3D: center of the polygon (the center is in the inside half)
meridian:Vector3D: point defining the reference meridian for first polygon vertex
outsideRadius:double: distance of the vertices to the center
n:int: number of sides of the polygon

Returns:S2Point[]

vertices array

getBoundaryLoops back to summary

getBoundaryLoops	back to summary
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:List<Vertex> boundary of the polygon, organized as an unmodifiable list of loops start vertices. Exceptions MathIllegalStateException: if the tolerance setting does not allow to build a clean non-ambiguous boundary See Also `Vertex`, `Edge`

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:List<Vertex>

boundary of the polygon, organized as an unmodifiable list of loops start vertices.

Exceptions

MathIllegalStateException:: if the tolerance setting does not allow to build a clean non-ambiguous boundary

See Also

Vertex, Edge

getEnclosingCap back to summary

getEnclosingCap	back to summary
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:EnclosingBall<Sphere2D, S2Point> a spherical cap enclosing the polygon

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:EnclosingBall<Sphere2D, S2Point>: a spherical cap enclosing the polygon

getInsidePoints	back to summary
private List<Vector3D> getInsidePoints() Gather some inside points. Returns:List<Vector3D> list of points known to be strictly in all inside convex cells

getInsidePoints

back to summary

private List<Vector3D> getInsidePoints()

Gather some inside points.

Returns:List<Vector3D>: list of points known to be strictly in all inside convex cells

getOutsidePoints	back to summary
private List<Vector3D> getOutsidePoints() Gather some outside points. Returns:List<Vector3D> list of points known to be strictly in all outside convex cells

getOutsidePoints

back to summary

private List<Vector3D> getOutsidePoints()

Gather some outside points.

Returns:List<Vector3D>: list of points known to be strictly in all outside convex cells

insertEdges	back to summary
private static void insertEdges(final double hyperplaneThickness, final BSPTree<Sphere2D> node, final List<Edge> edges) Recursively build a tree by inserting cut sub-hyperplanes. Parameters hyperplaneThickness:double tolerance below which points are considered to belong to the hyperplane (which is therefore more a slab) node:BSPTree<Sphere2D> current tree node (it is a leaf node at the beginning of the call) edges:List<Edge> list of edges to insert in the cell defined by this node (excluding edges not belonging to the cell defined by this node)

insertEdges

back to summary

private static void insertEdges(final double hyperplaneThickness, final BSPTree<Sphere2D> node, final List<Edge> edges)

Recursively build a tree by inserting cut sub-hyperplanes.

Parameters

hyperplaneThickness:double: tolerance below which points are considered to belong to the hyperplane (which is therefore more a slab)
node:BSPTree<Sphere2D>: current tree node (it is a leaf node at the beginning of the call)
edges:List<Edge>: list of edges to insert in the cell defined by this node (excluding edges not belonging to the cell defined by this node)

verticesToTree back to summary

verticesToTree	back to summary
private static BSPTree<Sphere2D> verticesToTree(final double hyperplaneThickness, final S2Point... vertices) Build the BSP tree of a polygons set 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). This constructor handles only polygons with edges strictly shorter than \( \pi \). If longer edges are needed, they need to be broken up in smaller sub-edges so this constraint holds. For cases where this simple constructor applies, it is expected to be numerically more robust than the `general constructor` using `subhyperplanes`. Parameters hyperplaneThickness:double tolerance below which points are consider to belong to the hyperplane (which is therefore more a slab) vertices:S2Point[] vertices of the simple loop boundary Returns:BSPTree<Sphere2D> the BSP tree of the input vertices

private static BSPTree<Sphere2D> verticesToTree(final double hyperplaneThickness, final S2Point... vertices)

Build the BSP tree of a polygons set from a simple list of vertices.

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

This constructor handles only polygons with edges strictly shorter than \( \pi \). If longer edges are needed, they need to be broken up in smaller sub-edges so this constraint holds.

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

Parameters

hyperplaneThickness:double: tolerance below which points are consider to belong to the hyperplane (which is therefore more a slab)
vertices:S2Point[]: vertices of the simple loop boundary

Returns:BSPTree<Sphere2D>

the BSP tree of the input vertices

public Class SphericalPolygonsSet

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail