Class Planes


  • public final class Planes
    extends java.lang.Object
    Class containing factory methods for constructing Plane and PlaneSubset instances.
    • Constructor Detail

      • Planes

        private Planes()
        Utility class; no instantiation.
    • Method Detail

      • fromPointAndPlaneVectors

        public static EmbeddingPlane fromPointAndPlaneVectors​(Vector3D p,
                                                              Vector3D u,
                                                              Vector3D v,
                                                              org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Build a plane from a point and two (on plane) vectors.
        Parameters:
        p - the provided point (on plane)
        u - u vector (on plane)
        v - v vector (on plane)
        precision - precision context used to compare floating point values
        Returns:
        a new plane
        Throws:
        java.lang.IllegalArgumentException - if the norm of the given values is zero, NaN, or infinite.
      • fromNormal

        public static Plane fromNormal​(Vector3D normal,
                                       org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Build a plane from a normal. Chooses origin as point on plane.
        Parameters:
        normal - normal direction to the plane
        precision - precision context used to compare floating point values
        Returns:
        a new plane
        Throws:
        java.lang.IllegalArgumentException - if the norm of the given values is zero, NaN, or infinite.
      • fromPointAndNormal

        public static Plane fromPointAndNormal​(Vector3D p,
                                               Vector3D normal,
                                               org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Build a plane from a point and a normal.
        Parameters:
        p - point belonging to the plane
        normal - normal direction to the plane
        precision - precision context used to compare floating point values
        Returns:
        a new plane
        Throws:
        java.lang.IllegalArgumentException - if the norm of the given values is zero, NaN, or infinite.
      • fromPoints

        public static Plane fromPoints​(Vector3D p1,
                                       Vector3D p2,
                                       Vector3D p3,
                                       org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Build a plane from three points.

        The plane is oriented in the direction of (p2-p1) ^ (p3-p1)

        Parameters:
        p1 - first point belonging to the plane
        p2 - second point belonging to the plane
        p3 - third point belonging to the plane
        precision - precision context used to compare floating point values
        Returns:
        a new plane
        Throws:
        java.lang.IllegalArgumentException - if the points do not define a unique plane
      • fromPoints

        public static Plane fromPoints​(java.util.Collection<Vector3D> pts,
                                       org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Construct a plane from a collection of points lying on the plane. The plane orientation is determined by the overall orientation of the point sequence. For example, if the points wind around the z-axis in a counter-clockwise direction, then the plane normal will point up the +z axis. If the points wind in the opposite direction, then the plane normal will point down the -z axis. The u vector for the plane is set to the first non-zero vector between points in the sequence (ie, the first direction in the path).
        Parameters:
        pts - collection of sequenced points lying on the plane
        precision - precision context used to compare floating point values
        Returns:
        a new plane containing the given points
        Throws:
        java.lang.IllegalArgumentException - if the given collection does not contain at least 3 points or the points do not define a unique plane
      • subsetFromConvexArea

        public static PlaneConvexSubset subsetFromConvexArea​(EmbeddingPlane plane,
                                                             ConvexArea area)
        Create a new plane subset from a plane and an embedded convex subspace area.
        Parameters:
        plane - embedding plane for the area
        area - area embedded in the plane
        Returns:
        a new convex sub plane instance
      • convexPolygonFromVertices

        public static ConvexPolygon3D convexPolygonFromVertices​(java.util.Collection<Vector3D> pts,
                                                                org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Create a new convex polygon from the given sequence of vertices. The vertices must define a unique plane, meaning that at least 3 unique vertices must be given. The given sequence is assumed to be closed, ie that an edge exists between the last vertex and the first.
        Parameters:
        pts - collection of points defining the convex polygon
        precision - precision context used to compare floating point values
        Returns:
        a new convex polygon defined by the given sequence of vertices
        Throws:
        java.lang.IllegalArgumentException - if fewer than 3 vertices are given or the vertices do not define a unique plane
        See Also:
        fromPoints(Collection, Precision.DoubleEquivalence)
      • triangleFromVertices

        public static Triangle3D triangleFromVertices​(Vector3D p1,
                                                      Vector3D p2,
                                                      Vector3D p3,
                                                      org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Construct a triangle from three vertices. The triangle plane is oriented such that the points are arranged in a counter-clockwise order when looking down the plane normal.
        Parameters:
        p1 - first vertex
        p2 - second vertex
        p3 - third vertex
        precision - precision context used for floating point comparisons
        Returns:
        a triangle constructed from the three vertices
        Throws:
        java.lang.IllegalArgumentException - if the points do not define a unique plane
      • indexedTriangles

        public static java.util.List<Triangle3D> indexedTriangles​(Vector3D[] vertices,
                                                                  int[][] faceIndices,
                                                                  org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Construct a list of Triangle3D instances from a set of vertices and arrays of face indices. For example, the following code constructs a list of triangles forming a square pyramid.
         Precision.DoubleEquivalence precision = Precision.doubleEquivalenceOfEpsilon(1e-10);
        
         Vector3D[] vertices = {
              Vector3D.ZERO,
              Vector3D.of(1, 0, 0),
              Vector3D.of(1, 1, 0),
              Vector3D.of(0, 1, 0),
              Vector3D.of(0.5, 0.5, 4)
         };
        
         int[][] faceIndices = {
              {0, 2, 1},
              {0, 3, 2},
              {0, 1, 4},
              {1, 2, 4},
              {2, 3, 4},
              {3, 0, 4}
         };
        
         List<Triangle3D> triangles = Planes.indexedTriangles(vertices, faceIndices, TEST_PRECISION);
         
        Parameters:
        vertices - vertices available for use in triangle construction
        faceIndices - array of indices for each triangular face; each entry in the array is an array of 3 index values into vertices, defining the 3 vertices that will be used to construct the triangle
        precision - precision context used for floating point comparisons
        Returns:
        a list of triangles constructed from the set of vertices and face indices
        Throws:
        java.lang.IllegalArgumentException - if any face index array does not contain exactly 3 elements or a set of 3 vertices do not define a plane
        java.lang.IndexOutOfBoundsException - if any index into vertices is out of bounds
      • indexedTriangles

        public static java.util.List<Triangle3D> indexedTriangles​(java.util.List<? extends Vector3D> vertices,
                                                                  int[][] faceIndices,
                                                                  org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Construct a list of Triangle3D instances from a set of vertices and arrays of face indices.
        Parameters:
        vertices - vertices available for use in triangle construction
        faceIndices - array of indices for each triangular face; each entry in the array is an array of 3 index values into vertices, defining the 3 vertices that will be used to construct the triangle
        precision - precision context used for floating point comparisons
        Returns:
        a list of triangles constructed from the set of vertices and face indices
        Throws:
        java.lang.IllegalArgumentException - if any face index array does not contain exactly 3 elements or a set of 3 vertices do not define a plane
        java.lang.IndexOutOfBoundsException - if any index into vertices is out of bounds
        See Also:
        indexedTriangles(Vector3D[], int[][], Precision.DoubleEquivalence)
      • indexedConvexPolygons

        public static java.util.List<ConvexPolygon3D> indexedConvexPolygons​(Vector3D[] vertices,
                                                                            int[][] faceIndices,
                                                                            org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Construct a list of ConvexPolygon3D instances from a set of vertices and arrays of face indices. Each face must contain at least 3 vertices but the number of vertices per face does not need to be constant. For example, the following code constructs a list of convex polygons forming a square pyramid. Note that the first face (the pyramid base) uses a different number of vertices than the other faces.
         Precision.DoubleEquivalence precision = Precision.doubleEquivalenceOfEpsilon(1e-10);
        
         Vector3D[] vertices = {
              Vector3D.ZERO,
              Vector3D.of(1, 0, 0),
              Vector3D.of(1, 1, 0),
              Vector3D.of(0, 1, 0),
              Vector3D.of(0.5, 0.5, 4)
         };
        
         int[][] faceIndices = {
              {0, 3, 2, 1}, // square base
              {0, 1, 4},
              {1, 2, 4},
              {2, 3, 4},
              {3, 0, 4}
         };
        
         List<ConvexPolygon3D> polygons = Planes.indexedConvexPolygons(vertices, faceIndices, precision);
         
        Parameters:
        vertices - vertices available for use in convex polygon construction
        faceIndices - array of indices for each triangular face; each entry in the array is an array of at least 3 index values into vertices, defining the vertices that will be used to construct the convex polygon
        precision - precision context used for floating point comparisons
        Returns:
        a list of convex polygons constructed from the set of vertices and face indices
        Throws:
        java.lang.IllegalArgumentException - if any face index array does not contain at least 3 elements or a set of vertices do not define a planar convex polygon
        java.lang.IndexOutOfBoundsException - if any index into vertices is out of bounds
      • indexedConvexPolygons

        public static java.util.List<ConvexPolygon3D> indexedConvexPolygons​(java.util.List<? extends Vector3D> vertices,
                                                                            int[][] faceIndices,
                                                                            org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Construct a list of ConvexPolygon3D instances from a set of vertices and arrays of face indices. Each face must contain at least 3 vertices but the number of vertices per face does not need to be constant.
        Parameters:
        vertices - vertices available for use in convex polygon construction
        faceIndices - array of indices for each triangular face; each entry in the array is an array of at least 3 index values into vertices, defining the vertices that will be used to construct the convex polygon
        precision - precision context used for floating point comparisons
        Returns:
        a list of convex polygons constructed from the set of vertices and face indices
        Throws:
        java.lang.IllegalArgumentException - if any face index array does not contain at least 3 elements or a set of vertices do not define a planar convex polygon
        java.lang.IndexOutOfBoundsException - if any index into vertices is out of bounds
        See Also:
        indexedConvexPolygons(Vector3D[], int[][], Precision.DoubleEquivalence)
      • extrudeVertexLoop

        public static java.util.List<PlaneConvexSubset> extrudeVertexLoop​(java.util.List<Vector2D> vertices,
                                                                          EmbeddingPlane plane,
                                                                          Vector3D extrusionVector,
                                                                          org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Get the boundaries of a 3D region created by extruding a polygon defined by a list of vertices. The ends ("top" and "bottom") of the extruded 3D region are flat while the sides follow the boundaries of the original 2D region.
        Parameters:
        vertices - vertices forming the 2D polygon to extrude
        plane - plane to extrude the 2D polygon from
        extrusionVector - vector to extrude the polygon vertices through
        precision - precision context used to construct the 3D region boundaries
        Returns:
        the boundaries of the extruded 3D region
        Throws:
        java.lang.IllegalStateException - if vertices contains only a single unique vertex
        java.lang.IllegalArgumentException - if regions of non-zero size cannot be produced with the given plane and extrusion vector. This occurs when the extrusion vector has zero length or is orthogonal to the plane normal
        See Also:
        LinePath.fromVertexLoop(Collection, Precision.DoubleEquivalence), extrude(LinePath, EmbeddingPlane, Vector3D, Precision.DoubleEquivalence)
      • extrude

        public static java.util.List<PlaneConvexSubset> extrude​(LinePath path,
                                                                EmbeddingPlane plane,
                                                                Vector3D extrusionVector,
                                                                org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Get the boundaries of the 3D region created by extruding a 2D line path. The ends ("top" and "bottom") of the extruded 3D region are flat while the sides follow the boundaries of the original 2D region. The path is converted to a BSP tree before extrusion.
        Parameters:
        path - path to extrude
        plane - plane to extrude the path from
        extrusionVector - vector to extrude the polygon points through
        precision - precision precision context used to construct the 3D region boundaries
        Returns:
        the boundaries of the extruded 3D region
        Throws:
        java.lang.IllegalArgumentException - if regions of non-zero size cannot be produced with the given plane and extrusion vector. This occurs when the extrusion vector has zero length or is orthogonal to the plane normal
        See Also:
        extrude(RegionBSPTree2D, EmbeddingPlane, Vector3D, Precision.DoubleEquivalence)
      • extrude

        public static java.util.List<PlaneConvexSubset> extrude​(RegionBSPTree2D region,
                                                                EmbeddingPlane plane,
                                                                Vector3D extrusionVector,
                                                                org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Get the boundaries of the 3D region created by extruding a 2D region. The ends ("top" and "bottom") of the extruded 3D region are flat while the sides follow the boundaries of the original 2D region.
        Parameters:
        region - region to extrude
        plane - plane to extrude the region from
        extrusionVector - vector to extrude the region points through
        precision - precision precision context used to construct the 3D region boundaries
        Returns:
        the boundaries of the extruded 3D region
        Throws:
        java.lang.IllegalArgumentException - if regions of non-zero size cannot be produced with the given plane and extrusion vector. This occurs when the extrusion vector has zero length or is orthogonal to the plane normal
      • intersection

        static Vector3D intersection​(PlaneSubset planeSubset,
                                     Line3D line)
        Get the unique intersection of the plane subset with the given line. Null is returned if no unique intersection point exists (ie, the line and plane are parallel or coincident) or the line does not intersect the plane subset.
        Parameters:
        planeSubset - plane subset to intersect with
        line - line to intersect with this plane subset
        Returns:
        the unique intersection point between the line and this plane subset or null if no such point exists.
      • intersection

        static Vector3D intersection​(PlaneSubset planeSubset,
                                     LineConvexSubset3D lineSubset)
        Get the unique intersection of the plane subset with the given line subset. Null is returned if the underlying line and plane do not have a unique intersection point (ie, they are parallel or coincident) or the intersection point is unique but is not contained in both the line subset and plane subset.
        Parameters:
        planeSubset - plane subset to intersect with
        lineSubset - line subset to intersect with
        Returns:
        the unique intersection point between this plane subset and the argument or null if no such point exists.
      • validatePlanesEquivalent

        static void validatePlanesEquivalent​(Plane expected,
                                             Plane actual)
        Validate that the actual plane contains the same points as the expected plane, throwing an exception if not. The subspace orientations of embedding planes are not considered.
        Parameters:
        expected - the expected plane
        actual - the actual plane
        Throws:
        java.lang.IllegalArgumentException - if the actual plane is not equivalent to the expected plane
      • subspaceSplit

        static <T extends PlaneSubsetSplit<T> subspaceSplit​(Plane splitter,
                                                              T subset,
                                                              java.util.function.BiFunction<? super EmbeddingPlane,​? super HyperplaneBoundedRegion<Vector2D>,​T> factory)
        Generic split method that uses performs the split using the subspace region of the plane subset.
        Type Parameters:
        T - Plane subset implementation type
        Parameters:
        splitter - splitting hyperplane
        subset - the plane subset being split
        factory - function used to create new plane subset instances
        Returns:
        the result of the split operation
      • getNonIntersectingSplitResult

        private static <T extends PlaneSubsetSplit<T> getNonIntersectingSplitResult​(Plane splitter,
                                                                                      T subset)
        Get a split result for cases where the splitting plane and the plane containing the subset being split do not intersect. Callers are responsible for ensuring that the planes involved do not actually intersect.
        Type Parameters:
        T - Plane subset implementation type
        Parameters:
        splitter - plane performing the splitting
        subset - subset being split
        Returns:
        the split result for the non-intersecting split
      • fromConvexPlanarVertices

        static ConvexPolygon3D fromConvexPlanarVertices​(Plane plane,
                                                        java.util.List<Vector3D> vertices)
        Construct a convex polygon 3D from a plane and a list of vertices lying in the plane. Callers are responsible for ensuring that the vertices lie in the plane and define a convex polygon.
        Parameters:
        plane - the plane containing the convex polygon
        vertices - vertices defining the closed, convex polygon. The must must contain at least 3 unique vertices and should not include the start vertex at the end of the list.
        Returns:
        a new convex polygon instance
        Throws:
        java.lang.IllegalArgumentException - if the size of vertices if less than 3
      • convexPolygonToTriangleFan

        static java.util.List<Triangle3D> convexPolygonToTriangleFan​(Plane plane,
                                                                     java.util.List<Vector3D> vertices)
        Convert a convex polygon defined by a plane and list of points into a triangle fan.
        Parameters:
        plane - plane containing the convex polygon
        vertices - vertices defining the convex polygon
        Returns:
        a triangle fan representing the same area as the convex polygon
        Throws:
        java.lang.IllegalArgumentException - if fewer than 3 vertices are given