Class ConvexArea2S

    • Field Detail

      • 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:
        Constant Field Values
      • HALF_SIZE

        private static final double HALF_SIZE
        Constant containing the area of half of the spherical space.
        See Also:
        Constant Field Values
      • 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:
        Constant Field Values
    • Constructor Detail

      • ConvexArea2S

        private ConvexArea2S​(java.util.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 Detail

      • boundaryStream

        public java.util.stream.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:
        Centroid
      • 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:
        The Centroid and Inertia Tensor for a Spherical Triangle - John E. Brock
      • 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

        public GreatArc trim​(HyperplaneConvexSubset<Point2S> sub)
        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​(java.util.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(Collection, Precision.DoubleEquivalence)
      • fromVertexLoop

        public static ConvexArea2S fromVertexLoop​(java.util.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(Collection, Precision.DoubleEquivalence)
      • fromVertices

        public static ConvexArea2S fromVertices​(java.util.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:
        java.lang.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​(java.lang.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:
        java.lang.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:
        getWeightedCentroidVector()
      • 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:
        getWeightedCentroidVector()
      • computeArcPoleWeightedCentroidVector

        private static Vector3D computeArcPoleWeightedCentroidVector​(java.util.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(List)
      • computeTriangleFanWeightedCentroidVector

        private static Vector3D computeTriangleFanWeightedCentroidVector​(java.util.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:
        computeArcPoleWeightedCentroidVector(List)
      • 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