Class Planes
java.lang.Object
org.apache.commons.geometry.euclidean.threed.Planes
Class containing factory methods for constructing
Plane
and PlaneSubset
instances.-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static final class
Internal helper class used to construct planes from sequences of points.private static final class
Class designed to create 3D regions by taking a 2D region and extruding from a base plane through an extrusion vector. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic ConvexPolygon3D
convexPolygonFromVertices
(Collection<Vector3D> pts, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Create a new convex polygon from the given sequence of vertices.(package private) 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.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.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.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.(package private) 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.static Plane
fromNormal
(Vector3D normal, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Build a plane from a normal.static Plane
fromPointAndNormal
(Vector3D p, Vector3D normal, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Build a plane from a point and a normal.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.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.static Plane
fromPoints
(Vector3D p1, Vector3D p2, Vector3D p3, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Build a plane from three points.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.static List
<ConvexPolygon3D> indexedConvexPolygons
(List<? extends Vector3D> vertices, int[][] faceIndices, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Construct a list ofConvexPolygon3D
instances from a set of vertices and arrays of face indices.static List
<ConvexPolygon3D> indexedConvexPolygons
(Vector3D[] vertices, int[][] faceIndices, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Construct a list ofConvexPolygon3D
instances from a set of vertices and arrays of face indices.static List
<Triangle3D> indexedTriangles
(List<? extends Vector3D> vertices, int[][] faceIndices, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Construct a list ofTriangle3D
instances from a set of vertices and arrays of face indices.static List
<Triangle3D> indexedTriangles
(Vector3D[] vertices, int[][] faceIndices, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Construct a list ofTriangle3D
instances from a set of vertices and arrays of face indices.(package private) static Vector3D
intersection
(PlaneSubset planeSubset, Line3D line) Get the unique intersection of the plane subset with the given line.(package private) static Vector3D
intersection
(PlaneSubset planeSubset, LineConvexSubset3D lineSubset) Get the unique intersection of the plane subset with the given line subset.static PlaneConvexSubset
subsetFromConvexArea
(EmbeddingPlane plane, ConvexArea area) Create a new plane subset from a plane and an embedded convex subspace area.(package private) 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.static Triangle3D
triangleFromVertices
(Vector3D p1, Vector3D p2, Vector3D p3, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Construct a triangle from three vertices.(package private) 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.
-
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 planeprecision
- 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 planenormal
- normal direction to the planeprecision
- 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 planep2
- second point belonging to the planep3
- third point belonging to the planeprecision
- 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. Theu
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 planeprecision
- 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
Create a new plane subset from a plane and an embedded convex subspace area.- Parameters:
plane
- embedding plane for the areaarea
- 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 polygonprecision
- 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 vertexp2
- second vertexp3
- third vertexprecision
- 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 ofTriangle3D
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 constructionfaceIndices
- array of indices for each triangular face; each entry in the array is an array of 3 index values intovertices
, defining the 3 vertices that will be used to construct the triangleprecision
- 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 planeIndexOutOfBoundsException
- if any index intovertices
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 ofTriangle3D
instances from a set of vertices and arrays of face indices.- Parameters:
vertices
- vertices available for use in triangle constructionfaceIndices
- array of indices for each triangular face; each entry in the array is an array of 3 index values intovertices
, defining the 3 vertices that will be used to construct the triangleprecision
- 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 planeIndexOutOfBoundsException
- if any index intovertices
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 ofConvexPolygon3D
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 constructionfaceIndices
- array of indices for each triangular face; each entry in the array is an array of at least 3 index values intovertices
, defining the vertices that will be used to construct the convex polygonprecision
- 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 polygonIndexOutOfBoundsException
- if any index intovertices
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 ofConvexPolygon3D
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 constructionfaceIndices
- array of indices for each triangular face; each entry in the array is an array of at least 3 index values intovertices
, defining the vertices that will be used to construct the convex polygonprecision
- 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 polygonIndexOutOfBoundsException
- if any index intovertices
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 extrudeplane
- plane to extrude the 2D polygon fromextrusionVector
- vector to extrude the polygon vertices throughprecision
- precision context used to construct the 3D region boundaries- Returns:
- the boundaries of the extruded 3D region
- Throws:
IllegalStateException
- ifvertices
contains only a single unique vertexIllegalArgumentException
- 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 extrudeplane
- plane to extrude the path fromextrusionVector
- vector to extrude the polygon points throughprecision
- 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 extrudeplane
- plane to extrude the region fromextrusionVector
- vector to extrude the region points throughprecision
- 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
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 withline
- 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
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 withlineSubset
- 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
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 planeactual
- 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 hyperplanesubset
- the plane subset being splitfactory
- 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 splittingsubset
- subset being split- Returns:
- the split result for the non-intersecting split
-
fromConvexPlanarVertices
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 polygonvertices
- 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 ofvertices
if less than 3
-
convexPolygonToTriangleFan
Convert a convex polygon defined by a plane and list of points into a triangle fan.- Parameters:
plane
- plane containing the convex polygonvertices
- 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
-