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.Arrays;
20 import java.util.Collection;
21 import java.util.List;
22 import java.util.stream.Stream;
23
24 import org.apache.commons.geometry.core.partitioning.BoundarySource;
25 import org.apache.commons.geometry.core.precision.DoublePrecisionContext;
26 import org.apache.commons.geometry.euclidean.threed.line.LineConvexSubset3D;
27 import org.apache.commons.geometry.euclidean.threed.line.LinecastPoint3D;
28 import org.apache.commons.geometry.euclidean.threed.line.Linecastable3D;
29 import org.apache.commons.geometry.euclidean.threed.mesh.SimpleTriangleMesh;
30 import org.apache.commons.geometry.euclidean.threed.mesh.TriangleMesh;
31
32 /** Extension of the {@link BoundarySource} interface for Euclidean 3D space.
33 */
34 public interface BoundarySource3D extends BoundarySource<PlaneConvexSubset>, Linecastable3D {
35
36 /** Return a BSP tree constructed from the boundaries contained in this instance. This is
37 * a convenience method for quickly constructing BSP trees and may produce unbalanced trees
38 * with unacceptable performance characteristics when used with large numbers of boundaries.
39 * In these cases, alternate tree construction approaches should be used, such as
40 * {@link RegionBSPTree3D.PartitionedRegionBuilder3D}.
41 * @return a BSP tree constructed from the boundaries in this instance
42 * @see RegionBSPTree3D#partitionedRegionBuilder()
43 */
44 default RegionBSPTree3D toTree() {
45 final RegionBSPTree3D tree = RegionBSPTree3D.empty();
46 tree.insert(this);
47
48 return tree;
49 }
50
51 /** Construct a triangle mesh from the boundaries in this instance.
52 * @param precision precision context used in boundaries generated by the resulting mesh
53 * @return a triangle mesh representing the boundaries in this instance
54 * @throws IllegalStateException if any boundary in this boundary source is infinite
55 */
56 default TriangleMesh toTriangleMesh(final DoublePrecisionContext precision) {
57 return SimpleTriangleMesh.from(this, precision);
58 }
59
60 /** Return the boundaries of this instance as a stream of {@link Triangle3D}
61 * instances. An {@link IllegalStateException} exception is thrown while reading
62 * from the stream if any boundary cannot be converted to a triangle (i.e. if it
63 * has infinite size).
64 * @return a stream of triangles representing the instance boundaries
65 * @see org.apache.commons.geometry.euclidean.threed.PlaneSubset#toTriangles()
66 */
67 default Stream<Triangle3D> triangleStream() {
68 return boundaryStream().flatMap(b -> b.toTriangles().stream());
69 }
70
71 /** {@inheritDoc} */
72 @Override
73 default List<LinecastPoint3D> linecast(final LineConvexSubset3D subset) {
74 return new BoundarySourceLinecaster3D(this).linecast(subset);
75 }
76
77 /** {@inheritDoc} */
78 @Override
79 default LinecastPoint3D linecastFirst(final LineConvexSubset3D subset) {
80 return new BoundarySourceLinecaster3D(this).linecastFirst(subset);
81 }
82
83 /** Get a {@link Bounds3D} object defining the axis-aligned box containing all vertices
84 * in the boundaries for this instance. Null is returned if any boundary is infinite
85 * or no vertices are found.
86 * @return the bounding box for this instance or null if no valid bounds could be determined
87 */
88 default Bounds3D getBounds() {
89 return new BoundarySourceBoundsBuilder3D().getBounds(this);
90 }
91
92 /** Return a {@link BoundarySource3D} instance containing the given boundaries.
93 * @param boundaries boundaries to include in the boundary source
94 * @return a boundary source containing the given boundaries
95 */
96 static BoundarySource3D from(final PlaneConvexSubset... boundaries) {
97 return from(Arrays.asList(boundaries));
98 }
99
100 /** Return a {@link BoundarySource3D} instance containing the given boundaries. The given
101 * collection is used directly as the source of the boundaries; no copy is made.
102 * @param boundaries boundaries to include in the boundary source
103 * @return a boundary source containing the given boundaries
104 */
105 static BoundarySource3D from(final Collection<PlaneConvexSubset> boundaries) {
106 return boundaries::stream;
107 }
108 }