Class ConvexArea2S

All Implemented Interfaces:
BoundarySource<GreatArc>, HyperplaneBoundedRegion<Point2S>, Splittable<Point2S,HyperplaneBoundedRegion<Point2S>>, Region<Point2S>, Sized, BoundarySource2S

public final class ConvexArea2S extends AbstractConvexHyperplaneBoundedRegion<Point2S,GreatArc> implements BoundarySource2S
Class representing a convex area in 2D spherical space. The boundaries of this area, if any, are composed of convex great circle arcs.
  • Field Details

    • FULL

      private static final ConvexArea2S FULL
      Instance representing the full spherical area.
    • FULL_SIZE

      private static final double FULL_SIZE
      Constant containing the area of the full spherical space.
      See Also:
    • HALF_SIZE

      private static final double HALF_SIZE
      Constant containing the area of half of the spherical space.
      See Also:
    • TRIANGLE_FAN_CENTROID_COMPUTE_THRESHOLD

      private static final double TRIANGLE_FAN_CENTROID_COMPUTE_THRESHOLD
      Empirically determined threshold for computing the weighted centroid vector using the triangle fan approach. Areas with boundary sizes under this value use the triangle fan method to increase centroid accuracy.
      See Also:
  • Constructor Details

    • ConvexArea2S

      private ConvexArea2S(List<GreatArc> boundaries)
      Construct an instance from its boundaries. Callers are responsible for ensuring that the given path represents the boundary of a convex area. No validation is performed.
      Parameters:
      boundaries - the boundaries of the convex area
  • Method Details

    • boundaryStream

      public Stream<GreatArc> boundaryStream()
      Return a stream containing the boundaries for this instance.
      Specified by:
      boundaryStream in interface BoundarySource<GreatArc>
      Returns:
      a stream containing the boundaries for this instance
    • getBoundaryPath

      public GreatArcPath getBoundaryPath()
      Get a path instance representing the boundary of the area. The path is oriented so that the minus sides of the arcs lie on the inside of the area.
      Returns:
      the boundary path of the area
    • getInteriorAngles

      public double[] getInteriorAngles()
      Get an array of interior angles for the area. An empty array is returned if there are no boundary intersections (ie, it has only one boundary or no boundaries at all).

      The order of the angles corresponds with the order of the boundaries returned by AbstractConvexHyperplaneBoundedRegion.getBoundaries(): if i is an index into the boundaries list, then angles[i] is the angle between boundaries i and (i+1) % boundariesSize.

      Returns:
      an array of interior angles for the area
    • getSize

      public double getSize()
      Get the size of the instance.
      Specified by:
      getSize in interface Sized
      Returns:
      the size of the instance
    • getCentroid

      public Point2S getCentroid()
      Get the centroid, or geometric center, of the region or null if no centroid exists or one exists but is not unique. A centroid will not exist for empty or infinite regions.

      The centroid of a geometric object is defined as the mean position of all points in the object, including interior points, vertices, and other points lying on the boundary. If a physical object has a uniform density, then its center of mass is the same as its geometric centroid.

      Specified by:
      getCentroid in interface Region<Point2S>
      Returns:
      the centroid of the region or null if no unique centroid exists
      See Also:
    • getWeightedCentroidVector

      Vector3D getWeightedCentroidVector()
      Return the weighted centroid vector of the area. The returned vector points in the direction of the centroid point on the surface of the unit sphere with the length of the vector proportional to the effective mass of the area at the centroid. By adding the weighted centroid vectors of multiple convex areas, a single centroid can be computed for the combined area.
      Returns:
      weighted centroid vector.
      See Also:
    • split

      public Split<ConvexArea2S> split(Hyperplane<Point2S> splitter)
      Split this instance with the given hyperplane.
      Specified by:
      split in interface Splittable<Point2S,HyperplaneBoundedRegion<Point2S>>
      Parameters:
      splitter - the hyperplane to split this object with.
      Returns:
      result of the split operation
    • toTree

      public RegionBSPTree2S toTree()
      Return a BSP tree representing the same region as this instance.
      Specified by:
      toTree in interface BoundarySource2S
      Returns:
      a BSP tree constructed from the boundaries in this instance
    • transform

      public ConvexArea2S transform(Transform<Point2S> transform)
      Return a new instance transformed by the argument.
      Parameters:
      transform - transform to apply
      Returns:
      a new instance transformed by the argument
    • trim

      Trim the given hyperplane subset to the portion contained inside this instance.
      Overrides:
      trim in class AbstractConvexHyperplaneBoundedRegion<Point2S,GreatArc>
      Parameters:
      sub - hyperplane subset to trim. Null is returned if the subset does not intersect the instance.
      Returns:
      portion of the argument that lies entirely inside the region represented by this instance, or null if it does not intersect.
    • full

      public static ConvexArea2S full()
      Return an instance representing the full spherical 2D space.
      Returns:
      an instance representing the full spherical 2D space.
    • fromVertices

      public static ConvexArea2S fromVertices(Collection<Point2S> vertices, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
      Construct a convex area by creating great circles between adjacent vertices. The vertices must be given in a counter-clockwise around order the interior of the shape. If the area is intended to be closed, the beginning point must be repeated at the end of the path.
      Parameters:
      vertices - vertices to use to construct the area
      precision - precision context used to create new great circle instances
      Returns:
      a convex area constructed using great circles between adjacent vertices
      See Also:
    • fromVertexLoop

      public static ConvexArea2S fromVertexLoop(Collection<Point2S> vertices, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
      Construct a convex area by creating great circles between adjacent vertices. An implicit great circle is created between the last vertex given and the first one, if needed. The vertices must be given in a counter-clockwise around order the interior of the shape.
      Parameters:
      vertices - vertices to use to construct the area
      precision - precision context used to create new great circles instances
      Returns:
      a convex area constructed using great circles between adjacent vertices
      See Also:
    • fromVertices

      public static ConvexArea2S fromVertices(Collection<Point2S> vertices, boolean close, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
      Construct a convex area from great circles between adjacent vertices.
      Parameters:
      vertices - vertices to use to construct the area
      close - if true, an additional great circle will be created between the last and first vertex
      precision - precision context used to create new great circle instances
      Returns:
      a convex area constructed using great circles between adjacent vertices
    • fromPath

      public static ConvexArea2S fromPath(GreatArcPath path)
      Construct a convex area from an arc path. The area represents the intersection of all of the negative half-spaces of the great circles in the path. The boundaries of the returned area may therefore not match the arcs in the path.
      Parameters:
      path - path to construct the area from
      Returns:
      a convex area constructed from the great circles in the given path
    • fromBounds

      public static ConvexArea2S fromBounds(GreatCircle... bounds)
      Create a convex area formed by the intersection of the negative half-spaces of the given bounding great circles. The returned instance represents the area that is on the minus side of all of the given circles. Note that this method does not support areas of zero size (ie, infinitely thin areas or points.)
      Parameters:
      bounds - great circles used to define the convex area
      Returns:
      a new convex area instance representing the area on the minus side of all of the bounding great circles or an instance representing the full area if no circles are given
      Throws:
      IllegalArgumentException - if the given set of bounding great circles do not form a convex area, meaning that there is no region that is on the minus side of all of the bounding circles.
    • fromBounds

      public static ConvexArea2S fromBounds(Iterable<GreatCircle> bounds)
      Create a convex area formed by the intersection of the negative half-spaces of the given bounding great circles. The returned instance represents the area that is on the minus side of all of the given circles. Note that this method does not support areas of zero size (ie, infinitely thin areas or points.)
      Parameters:
      bounds - great circles used to define the convex area
      Returns:
      a new convex area instance representing the area on the minus side of all of the bounding great circles or an instance representing the full area if no circles are given
      Throws:
      IllegalArgumentException - if the given set of bounding great circles do not form a convex area, meaning that there is no region that is on the minus side of all of the bounding circles.
    • computeHemisphereWeightedCentroidVector

      private static Vector3D computeHemisphereWeightedCentroidVector(GreatArc arc)
      Compute the weighted centroid vector for the hemisphere formed by the given arc.
      Parameters:
      arc - arc defining the hemisphere
      Returns:
      the weighted centroid vector for the hemisphere
      See Also:
    • computeLuneWeightedCentroidVector

      private static Vector3D computeLuneWeightedCentroidVector(GreatArc a, GreatArc b)
      Compute the weighted centroid vector for the lune formed by the given arcs.
      Parameters:
      a - first arc for the lune
      b - second arc for the lune
      Returns:
      the weighted centroid vector for the lune
      See Also:
    • computeArcPoleWeightedCentroidVector

      private static Vector3D computeArcPoleWeightedCentroidVector(List<GreatArc> arcs)
      Compute the weighted centroid vector for the triangle or polygon formed by the given arcs by adding together the arc pole vectors multiplied by their respective arc lengths. This algorithm is described in the paper The Centroid and Inertia Tensor for a Spherical Triangle by John E Brock.

      Note: This algorithm works well in general but is susceptible to floating point errors on very small areas. In these cases, the computed centroid may not be in the expected location and may even be outside of the area. The computeTriangleFanWeightedCentroidVector(List) method can produce more accurate results in these cases.

      Parameters:
      arcs - boundary arcs for the area
      Returns:
      the weighted centroid vector for the area
      See Also:
    • computeTriangleFanWeightedCentroidVector

      private static Vector3D computeTriangleFanWeightedCentroidVector(List<GreatArc> arcs)
      Compute the weighted centroid vector for the triangle or polygon formed by the given arcs using a triangle fan approach. This method is specifically designed for use with areas of very small size, where use of the standard algorithm from computeArcPoleWeightedCentroidVector(List) can produce inaccurate results. The algorithm proceeds as follows:
      1. The polygon is divided into spherical triangles using a triangle fan.
      2. For each triangle, the vectors of the 3 spherical points are added together to approximate the direction of the spherical centroid. This ensures that the computed centroid lies within the area.
      3. The length of the weighted centroid vector is determined by computing the sum of the contributions that each arc in the triangle would make to the centroid using the algorithm from computeArcPoleWeightedCentroidVector(List). This essentially performs part of that algorithm in reverse: given a centroid direction, compute the contribution that each arc makes.
      4. The sum of the weighted centroid vectors for each triangle is computed and returned.
      Parameters:
      arcs - boundary arcs for the area; must contain at least 3 arcs
      Returns:
      the weighted centroid vector for the area
      See Also:
    • computeArcCentroidContribution

      private static double computeArcCentroidContribution(Vector3D.Unit a, Vector3D.Unit b, Vector3D.Unit triangleCentroid)
      Compute the contribution made by a single arc to a weighted centroid vector.
      Parameters:
      a - first point in the arc
      b - second point in the arc
      triangleCentroid - the centroid vector for the area
      Returns:
      the contribution made by the arc ab to the length of the weighted centroid vector