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.twod;
    18
    19  import java.util.Arrays;
    20  import java.util.Collection;
    21  import java.util.List;
    22
    23  import org.apache.commons.geometry.core.partitioning.BoundarySource;
    24
    25  /** Extension of the {@link BoundarySource} interface for Euclidean 2D space.
    26   */
    27  public interface BoundarySource2D extends BoundarySource<LineConvexSubset>, Linecastable2D {
    28
    29      /** Return a BSP tree constructed from the boundaries contained in this instance. This is
    30       * a convenience method for quickly constructing BSP trees and may produce unbalanced trees
    31       * with unacceptable performance characteristics when used with large numbers of boundaries.
    32       * In these cases, alternate tree construction approaches should be used, such as
    33       * {@link RegionBSPTree2D.PartitionedRegionBuilder2D}.
    34       * @return a BSP tree constructed from the boundaries in this instance
    35       * @see RegionBSPTree2D#partitionedRegionBuilder()
    36       */
    37      default RegionBSPTree2D toTree() {
    38          final RegionBSPTree2D tree = RegionBSPTree2D.empty();
    39          tree.insert(this);
    40
    41          return tree;
    42      }
    43
    44      /** {@inheritDoc} */
    45      @Override
    46      default List<LinecastPoint2D> linecast(final LineConvexSubset subset) {
    47          return new BoundarySourceLinecaster2D(this).linecast(subset);
    48      }
    49
    50      /** {@inheritDoc} */
    51      @Override
    52      default LinecastPoint2D linecastFirst(final LineConvexSubset subset) {
    53          return new BoundarySourceLinecaster2D(this).linecastFirst(subset);
    54      }
    55
    56      /** Get a {@link Bounds2D} object defining the axis-aligned box containing all vertices
    57       * in the boundaries for this instance. Null is returned if any boundaries are infinite
    58       * or no vertices were found.
    59       * @return the bounding box for this instance or null if no valid bounds could be determined
    60       */
    61      default Bounds2D getBounds() {
    62          return new BoundarySourceBoundsBuilder2D().getBounds(this);
    63      }
    64
    65      /** Return a {@link BoundarySource2D} instance containing the given boundaries.
    66       * @param boundaries line subsets to include in the boundary source
    67       * @return a boundary source containing the given boundaries
    68       */
    69      static BoundarySource2D from(final LineConvexSubset... boundaries) {
    70          return from(Arrays.asList(boundaries));
    71      }
    72
    73      /** Return a {@link BoundarySource2D} instance containing the given boundaries. The given
    74       * collection is used directly as the source of the line subsets; no copy is made.
    75       * @param boundaries line subsets to include in the boundary source
    76       * @return a boundary source containing the given boundaries
    77       */
    78      static BoundarySource2D from(final Collection<LineConvexSubset> boundaries) {
    79          return boundaries::stream;
    80      }
    81  }