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 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