View Javadoc

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