Class ConvexArea

    • Field Detail

      • NON_CONVEX_PATH_ERROR

        private static final java.lang.String NON_CONVEX_PATH_ERROR
        Error message used when attempting to construct a convex polygon from a non-convex line path.
        See Also:
        Constant Field Values
      • FULL

        private static final ConvexArea FULL
        Instance representing the full 2D plane.
    • Constructor Detail

      • ConvexArea

        protected ConvexArea​(java.util.List<LineConvexSubset> boundaries)
        Simple constructor. 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

      • getBoundaryPaths

        public java.util.List<LinePath> getBoundaryPaths()
        Get the connected line subset paths comprising the boundary of the area. The line subsets are oriented so that their minus sides point toward the interior of the region. The size of the returned list is
        • 0 if the convex area is full,
        • 1 if at least one boundary is present and a single path can connect all line subsets (this will be the case for most instances), and
        • 2 if only two boundaries exist and they are parallel to each other (in which case they cannot be connected as a single path).
        Returns:
        the line subset paths comprising the boundary of the area.
      • getVertices

        public java.util.List<Vector2D> getVertices()
        Get the vertices for the area in a counter-clockwise order. Each vertex in the returned list is unique. If the boundary of the area is closed, the start vertex is not repeated at the end of the list.

        It is important to note that, in general, the list of vertices returned by this method is not sufficient to completely characterize the area. For example, a simple triangle has 3 vertices, but an infinite area constructed from two parallel lines and two lines that intersect between them will also have 3 vertices. It is also possible for non-empty areas to contain no vertices at all. For example, an area with no boundaries (representing the full space), an area with a single boundary, or an area with two parallel boundaries will not contain any vertices.

        Returns:
        the list of vertices for the area in a counter-clockwise order
      • transform

        public ConvexArea transform​(Transform<Vector2D> transform)
        Return a new instance transformed by the argument.
        Parameters:
        transform - transform to apply
        Returns:
        a new instance transformed by the argument
      • getSize

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

        public Vector2D 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<Vector2D>
        Returns:
        the centroid of the region or null if no unique centroid exists
        See Also:
        Centroid
      • full

        public static ConvexArea full()
        Return an instance representing the full 2D area.
        Returns:
        an instance representing the full 2D area.
      • convexPolygonFromVertices

        public static ConvexArea convexPolygonFromVertices​(java.util.Collection<Vector2D> vertices,
                                                           org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Construct a convex polygon from the given vertices.
        Parameters:
        vertices - vertices to use to construct the polygon
        precision - precision context used for floating point comparisons
        Returns:
        a convex polygon constructed using the given vertices
        Throws:
        java.lang.IllegalStateException - if vertices contains only a single unique vertex
        java.lang.IllegalArgumentException - if the constructed path does not define a closed, convex polygon
        See Also:
        LinePath.fromVertexLoop(Collection, Precision.DoubleEquivalence)
      • convexPolygonFromPath

        public static ConvexArea convexPolygonFromPath​(LinePath path)
        Construct a convex polygon from a line path.
        Parameters:
        path - path to construct the polygon from
        Returns:
        a convex polygon constructed from the given line path
        Throws:
        java.lang.IllegalArgumentException - if the path does not define a closed, convex polygon
      • fromBounds

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

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