001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.geometry.euclidean.threed;
018
019import java.util.List;
020
021import org.apache.commons.geometry.core.RegionEmbedding;
022import org.apache.commons.geometry.core.partitioning.HyperplaneBoundedRegion;
023import org.apache.commons.geometry.core.partitioning.HyperplaneSubset;
024import org.apache.commons.geometry.euclidean.threed.line.Line3D;
025import org.apache.commons.geometry.euclidean.threed.line.LineConvexSubset3D;
026import org.apache.commons.geometry.euclidean.twod.Vector2D;
027
028/** Interface representing a subset of points in a plane in Euclidean 3D space. Instances
029 * may represent finite, infinite, convex, non-convex, and/or disjoint regions of the plane.
030 */
031public interface PlaneSubset extends HyperplaneSubset<Vector3D> {
032
033    /** Get the plane containing this subset. This is equivalent to {@link #getHyperplane()}.
034     * @return the plane containing this subset
035     * @see #getHyperplane()
036     */
037    Plane getPlane();
038
039    /** {@inheritDoc} */
040    @Override
041    Plane getHyperplane();
042
043    /** {@inheritDoc} */
044    @Override
045    List<PlaneConvexSubset> toConvex();
046
047    /** Return a list of triangles representing the same subset region as this instance. An
048     * {@link IllegalStateException} is thrown if the subset has infinite size and therefore
049     * cannot be converted to triangles. If the subset has zero size (is empty), an empty list is
050     * returned.
051     * @return a list of triangles representing the same subset region as this instance
052     * @throws IllegalStateException if the subset has infinite size and therefore cannot
053     *      be converted to triangles
054     */
055    List<Triangle3D> toTriangles();
056
057    /** Get a {@link Bounds3D} object defining an axis-aligned bounding box containing all
058     * vertices for this subset. Null is returned if the subset is infinite or does not
059     * contain any vertices.
060     * @return the bounding box for this instance or null if no valid bounds could be determined
061     */
062    Bounds3D getBounds();
063
064    /** Return an object containing the plane subset as an embedded 2D subspace region.
065     * @return an object containing the plane subset as an embedded 2D subspace region
066     */
067    PlaneSubset.Embedded getEmbedded();
068
069    /** Get the unique intersection of this plane subset with the given line. Null is
070     * returned if no unique intersection point exists (ie, the line and plane are
071     * parallel or coincident) or the line does not intersect the plane subset.
072     * @param line line to intersect with this plane subset
073     * @return the unique intersection point between the line and this plane subset
074     *      or null if no such point exists.
075     * @see Plane#intersection(Line3D)
076     */
077    Vector3D intersection(Line3D line);
078
079    /** Get the unique intersection of this plane subset with the given line subset. Null
080     * is returned if the underlying line and plane do not have a unique intersection
081     * point (ie, they are parallel or coincident) or the intersection point is unique
082     * but is not contained in both the line subset and plane subset.
083     * @param lineSubset line subset to intersect with
084     * @return the unique intersection point between this plane subset and the argument or
085     *      null if no such point exists.
086     * @see Plane#intersection(Line3D)
087     */
088    Vector3D intersection(LineConvexSubset3D lineSubset);
089
090    /** Interface used to represent plane subsets as embedded 2D subspace regions.
091     */
092    interface Embedded extends RegionEmbedding<Vector3D, Vector2D> {
093
094        /** Get the plane embedding the subspace region.
095         * @return the plane embedding the subspace region
096         */
097        EmbeddingPlane getPlane();
098
099        /** {@inheritDoc} */
100        @Override
101        HyperplaneBoundedRegion<Vector2D> getSubspaceRegion();
102    }
103}