1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.geometry.euclidean.threed;
18
19 import java.util.List;
20
21 import org.apache.commons.geometry.core.RegionEmbedding;
22 import org.apache.commons.geometry.core.partitioning.HyperplaneBoundedRegion;
23 import org.apache.commons.geometry.core.partitioning.HyperplaneSubset;
24 import org.apache.commons.geometry.euclidean.threed.line.Line3D;
25 import org.apache.commons.geometry.euclidean.threed.line.LineConvexSubset3D;
26 import org.apache.commons.geometry.euclidean.twod.Vector2D;
27
28 /** Interface representing a subset of points in a plane in Euclidean 3D space. Instances
29 * may represent finite, infinite, convex, non-convex, and/or disjoint regions of the plane.
30 */
31 public interface PlaneSubset extends HyperplaneSubset<Vector3D> {
32
33 /** Get the plane containing this subset. This is equivalent to {@link #getHyperplane()}.
34 * @return the plane containing this subset
35 * @see #getHyperplane()
36 */
37 Plane getPlane();
38
39 /** {@inheritDoc} */
40 @Override
41 Plane getHyperplane();
42
43 /** {@inheritDoc} */
44 @Override
45 List<PlaneConvexSubset> toConvex();
46
47 /** Return a list of triangles representing the same subset region as this instance. An
48 * {@link IllegalStateException} is thrown if the subset has infinite size and therefore
49 * cannot be converted to triangles. If the subset has zero size (is empty), an empty list is
50 * returned.
51 * @return a list of triangles representing the same subset region as this instance
52 * @throws IllegalStateException if the subset has infinite size and therefore cannot
53 * be converted to triangles
54 */
55 List<Triangle3D> toTriangles();
56
57 /** Get a {@link Bounds3D} object defining an axis-aligned bounding box containing all
58 * vertices for this subset. Null is returned if the subset is infinite or does not
59 * contain any vertices.
60 * @return the bounding box for this instance or null if no valid bounds could be determined
61 */
62 Bounds3D getBounds();
63
64 /** Return an object containing the plane subset as an embedded 2D subspace region.
65 * @return an object containing the plane subset as an embedded 2D subspace region
66 */
67 PlaneSubset.Embedded getEmbedded();
68
69 /** Get the unique intersection of this plane subset with the given line. Null is
70 * returned if no unique intersection point exists (ie, the line and plane are
71 * parallel or coincident) or the line does not intersect the plane subset.
72 * @param line line to intersect with this plane subset
73 * @return the unique intersection point between the line and this plane subset
74 * or null if no such point exists.
75 * @see Plane#intersection(Line3D)
76 */
77 Vector3D intersection(Line3D line);
78
79 /** Get the unique intersection of this plane subset with the given line subset. Null
80 * is returned if the underlying line and plane do not have a unique intersection
81 * point (ie, they are parallel or coincident) or the intersection point is unique
82 * but is not contained in both the line subset and plane subset.
83 * @param lineSubset line subset to intersect with
84 * @return the unique intersection point between this plane subset and the argument or
85 * null if no such point exists.
86 * @see Plane#intersection(Line3D)
87 */
88 Vector3D intersection(LineConvexSubset3D lineSubset);
89
90 /** Interface used to represent plane subsets as embedded 2D subspace regions.
91 */
92 interface Embedded extends RegionEmbedding<Vector3D, Vector2D> {
93
94 /** Get the plane embedding the subspace region.
95 * @return the plane embedding the subspace region
96 */
97 EmbeddingPlane getPlane();
98
99 /** {@inheritDoc} */
100 @Override
101 HyperplaneBoundedRegion<Vector2D> getSubspaceRegion();
102 }
103 }