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