org.apache.commons.geometry.euclidean.threed

Class Planes

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.

Method Summary

Modifier and Type	Method and Description
static ConvexPolygon3D	convexPolygonFromVertices(Collection<Vector3D> pts, Precision.DoubleEquivalence precision) Create a new convex polygon from the given sequence of vertices.
static List<PlaneConvexSubset>	extrude(LinePath path, EmbeddingPlane plane, Vector3D extrusionVector, 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, 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, Precision.DoubleEquivalence precision) Get the boundaries of a 3D region created by extruding a polygon defined by a list of vertices.
static Plane	fromNormal(Vector3D normal, Precision.DoubleEquivalence precision) Build a plane from a normal.
static Plane	fromPointAndNormal(Vector3D p, Vector3D normal, Precision.DoubleEquivalence precision) Build a plane from a point and a normal.
static EmbeddingPlane	fromPointAndPlaneVectors(Vector3D p, Vector3D u, Vector3D v, Precision.DoubleEquivalence precision) Build a plane from a point and two (on plane) vectors.
static Plane	fromPoints(Collection<Vector3D> pts, Precision.DoubleEquivalence precision) Construct a plane from a collection of points lying on the plane.
static Plane	fromPoints(Vector3D p1, Vector3D p2, Vector3D p3, Precision.DoubleEquivalence precision) Build a plane from three points.
static List<ConvexPolygon3D>	indexedConvexPolygons(List<? extends Vector3D> vertices, int[][] faceIndices, Precision.DoubleEquivalence precision) Construct a list of ConvexPolygon3D instances from a set of vertices and arrays of face indices.
static List<ConvexPolygon3D>	indexedConvexPolygons(Vector3D[] vertices, int[][] faceIndices, Precision.DoubleEquivalence precision) Construct a list of ConvexPolygon3D instances from a set of vertices and arrays of face indices.
static List<Triangle3D>	indexedTriangles(List<? extends Vector3D> vertices, int[][] faceIndices, Precision.DoubleEquivalence precision) Construct a list of Triangle3D instances from a set of vertices and arrays of face indices.
static List<Triangle3D>	indexedTriangles(Vector3D[] vertices, int[][] faceIndices, Precision.DoubleEquivalence precision) Construct a list of Triangle3D instances from a set of vertices and arrays of face indices.
static PlaneConvexSubset	subsetFromConvexArea(EmbeddingPlane plane, ConvexArea area) Create a new plane subset from a plane and an embedded convex subspace area.
static Triangle3D	triangleFromVertices(Vector3D p1, Vector3D p2, Vector3D p3, Precision.DoubleEquivalence precision) Construct a triangle from three vertices.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

fromPointAndPlaneVectors

public static EmbeddingPlane fromPointAndPlaneVectors(Vector3D p,
                                                      Vector3D u,
                                                      Vector3D v,
                                                      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,
                               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,
                                       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,
                               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,
                               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,
                                                        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:

fromPoints(Collection, Precision.DoubleEquivalence)

triangleFromVertices

public static Triangle3D triangleFromVertices(Vector3D p1,
                                              Vector3D p2,
                                              Vector3D p3,
                                              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,
                                                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,
                                                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:

indexedTriangles(Vector3D[], int[][], Precision.DoubleEquivalence)

indexedConvexPolygons

public static List<ConvexPolygon3D> indexedConvexPolygons(Vector3D[] vertices,
                                                          int[][] faceIndices,
                                                          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,
                                                          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:

indexedConvexPolygons(Vector3D[], int[][], Precision.DoubleEquivalence)

extrudeVertexLoop

public static List<PlaneConvexSubset> extrudeVertexLoop(List<Vector2D> vertices,
                                                        EmbeddingPlane plane,
                                                        Vector3D extrusionVector,
                                                        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:

LinePath.fromVertexLoop(Collection, Precision.DoubleEquivalence), extrude(LinePath, EmbeddingPlane, Vector3D, Precision.DoubleEquivalence)

extrude

public static List<PlaneConvexSubset> extrude(LinePath path,
                                              EmbeddingPlane plane,
                                              Vector3D extrusionVector,
                                              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(RegionBSPTree2D, EmbeddingPlane, Vector3D, Precision.DoubleEquivalence)

extrude

public static List<PlaneConvexSubset> extrude(RegionBSPTree2D region,
                                              EmbeddingPlane plane,
                                              Vector3D extrusionVector,
                                              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