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.mesh;
018
019import java.util.List;
020
021import org.apache.commons.geometry.core.Transform;
022import org.apache.commons.geometry.euclidean.threed.BoundarySource3D;
023import org.apache.commons.geometry.euclidean.threed.ConvexPolygon3D;
024import org.apache.commons.geometry.euclidean.threed.Vector3D;
025
026/** Interface representing a 3D mesh data structure.
027 * @param <F> Mesh face implementation type
028 * @see <a href="https://en.wikipedia.org/wiki/Polygon_mesh">Polygon Mesh</a>
029 */
030public interface Mesh<F extends Mesh.Face> extends BoundarySource3D {
031
032    /** Get an iterable containing the vertices in the mesh.
033     * @return an iterable containing the vertices in the mesh
034     */
035    Iterable<Vector3D> vertices();
036
037    /** Get a list containing all vertices in the mesh.
038     * @return a list containing all vertices in the mesh
039     */
040    List<Vector3D> getVertices();
041
042    /** Get the number of vertices in the mesh.
043     * @return the number of vertices in the mesh
044     */
045    int getVertexCount();
046
047    /** Get an iterable containing all faces in the mesh.
048     * @return an iterable containing all faces in the mesh
049     */
050    Iterable<F> faces();
051
052    /** Get a list containing all faces in the mesh.
053     * @return a list containing all faces in the mesh
054     */
055    List<F> getFaces();
056
057    /** Get the number of faces in the mesh.
058     * @return the number of faces in the mesh
059     */
060    int getFaceCount();
061
062    /** Get a face from the mesh by its index.
063     * @param index the index of the mesh to retrieve
064     * @return the face at the given index
065     * @throws IndexOutOfBoundsException if the index is out of bounds
066     */
067    F getFace(int index);
068
069    /** Return a new, transformed mesh by applying the given transform to
070     * all vertices. Faces and vertex ordering are not affected.
071     * @param transform transform to apply
072     * @return a new, transformed mesh
073     */
074    Mesh<F> transform(Transform<Vector3D> transform);
075
076    /** Interface representing a single face in a mesh.
077     */
078    interface Face {
079
080        /** Get the 0-based index of the face in the mesh.
081         * @return the 0-based index of the face in the mesh
082         */
083        int getIndex();
084
085        /** Get an array containing the 0-based indices of the vertices defining
086         * this face. The indices are references to the vertex positions in
087         * the mesh vertex list.
088         * @return an array containing the indices of the vertices defining
089         *      this face
090         * @see Mesh#getVertices()
091         */
092        int[] getVertexIndices();
093
094        /** Get the vertices for the face.
095         * @return the vertices for the face
096         */
097        List<Vector3D> getVertices();
098
099        /** Return true if the vertices for this face define a convex polygon
100         * with non-zero size.
101         * @return true if the vertices for this face define a convex polygon
102         *      with non-zero size
103         */
104        boolean definesPolygon();
105
106        /** Get the 3D polygon defined by this face.
107         * @return the 3D polygon defined by this face
108         * @throws IllegalArgumentException if the vertices for the face do not
109         *      define a polygon
110         * @see #definesPolygon()
111         */
112        ConvexPolygon3D getPolygon();
113    }
114}