java.lang.Object
org.apache.commons.geometry.euclidean.threed.Planes

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

    • Planes

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

    • 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:
      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:
      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:
      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:
      IllegalArgumentException - if the points do not define a unique plane
    • fromPoints

      public static Plane fromPoints(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:
      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(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:
      IllegalArgumentException - if fewer than 3 vertices are given or the vertices do not define a unique plane
      See Also:
    • 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:
      IllegalArgumentException - if the points do not define a unique plane
    • indexedTriangles

      public static 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:
      IllegalArgumentException - if any face index array does not contain exactly 3 elements or a set of 3 vertices do not define a plane
      IndexOutOfBoundsException - if any index into vertices is out of bounds
    • indexedTriangles

      public static List<Triangle3D> indexedTriangles(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:
      IllegalArgumentException - if any face index array does not contain exactly 3 elements or a set of 3 vertices do not define a plane
      IndexOutOfBoundsException - if any index into vertices is out of bounds
      See Also:
    • indexedConvexPolygons

      public static 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:
      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
      IndexOutOfBoundsException - if any index into vertices is out of bounds
    • indexedConvexPolygons

      public static List<ConvexPolygon3D> indexedConvexPolygons(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:
      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
      IndexOutOfBoundsException - if any index into vertices is out of bounds
      See Also:
    • extrudeVertexLoop

      public static List<PlaneConvexSubset> extrudeVertexLoop(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:
      IllegalStateException - if vertices contains only a single unique vertex
      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

      public static 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:
      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

      public static 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:
      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:
      IllegalArgumentException - if the actual plane is not equivalent to the expected plane
    • subspaceSplit

      static <T extends PlaneSubset> Split<T> subspaceSplit(Plane splitter, T subset, 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 PlaneSubset> Split<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, 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:
      IllegalArgumentException - if the size of vertices if less than 3
    • convexPolygonToTriangleFan

      static List<Triangle3D> convexPolygonToTriangleFan(Plane plane, 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:
      IllegalArgumentException - if fewer than 3 vertices are given