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