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.Collections;
020import java.util.List;
021
022import org.apache.commons.geometry.core.Transform;
023import org.apache.commons.geometry.core.partitioning.Hyperplane;
024import org.apache.commons.geometry.core.partitioning.HyperplaneConvexSubset;
025import org.apache.commons.geometry.core.partitioning.Split;
026import org.apache.commons.geometry.euclidean.twod.ConvexArea;
027
028/** Interface representing a finite or infinite convex subset of points in a plane in Euclidean 3D
029 * space.
030 */
031public interface PlaneConvexSubset extends PlaneSubset, HyperplaneConvexSubset<Vector3D> {
032
033    /** {@inheritDoc} */
034    @Override
035    PlaneConvexSubset reverse();
036
037    /** {@inheritDoc} */
038    @Override
039    PlaneConvexSubset transform(Transform<Vector3D> transform);
040
041    /** {@inheritDoc} */
042    @Override
043    Split<PlaneConvexSubset> split(Hyperplane<Vector3D> splitter);
044
045    /** {@inheritDoc} */
046    @Override
047    PlaneConvexSubset.Embedded getEmbedded();
048
049    /** Get the vertices for the convex subset in a counter-clockwise order as viewed looking down the plane
050     * normal. Each vertex in the returned list is unique. If the boundary of the subset is closed, the start
051     * vertex is <em>not</em> repeated at the end of the list.
052     *
053     * <p>It is important to note that, in general, the list of vertices returned by this method
054     * is not sufficient to completely characterize the subset. For example, a simple triangle
055     * has 3 vertices, but an infinite area constructed from two parallel lines and two lines that
056     * intersect between them will also have 3 vertices. It is also possible for non-empty subsets to
057     * contain no vertices at all. For example, a subset with no boundaries (representing the full
058     * plane), a subset with a single boundary (ie, a half-plane), or a subset with two parallel boundaries will
059     * not contain any vertices.</p>
060     * @return the list of vertices for the plane convex subset in a counter-clockwise order as viewed looking
061     *      down the plane normal
062     */
063    List<Vector3D> getVertices();
064
065    /** {@inheritDoc}
066     *
067     * <p>This method simply returns a singleton list containing this object.</p>
068     */
069    @Override
070    default List<PlaneConvexSubset> toConvex() {
071        return Collections.singletonList(this);
072    }
073
074    /** Interface used to represent plane convex subsets as embedded 2D subspace regions.
075     */
076    interface Embedded extends PlaneSubset.Embedded {
077
078        /** {@inheritDoc} */
079        @Override
080        ConvexArea getSubspaceRegion();
081    }
082}