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.io.euclidean.threed;
18  
19  import java.util.Collection;
20  import java.util.Objects;
21  
22  import org.apache.commons.geometry.euclidean.threed.ConvexPolygon3D;
23  import org.apache.commons.geometry.euclidean.threed.Planes;
24  import org.apache.commons.geometry.euclidean.threed.Vector3D;
25  import org.apache.commons.numbers.core.Precision;
26  
27  /** Class containing static methods that operate on {@link FacetDefinition} instances.
28   */
29  public final class FacetDefinitions {
30  
31      /** Utility class; no instantiation. */
32      private FacetDefinitions() {}
33  
34      /** Construct a {@link ConvexPolygon3D} from the given facet vertices and optional normal.
35       * If the normal is non-null, this method attempts to honor it by making the
36       * polygon point in a similar (but not necessarily equal) direction, reversing the
37       * order of vertices if needed.
38       * @param vertices facet vertices
39       * @param normal facet normal; may be null
40       * @param precision precision context used for floating point comparisons
41       * @return convex polygon constructed from the vertices and normal
42       * @throws IllegalArgumentException if a valid convex polygon cannot be constructed
43       */
44      public static ConvexPolygon3D toPolygon(final Collection<Vector3D> vertices, final Vector3D normal,
45              final Precision.DoubleEquivalence precision) {
46          final ConvexPolygon3D polygon = Planes.convexPolygonFromVertices(vertices, precision);
47  
48          // ensure that the polygon normal matches whatever normal was defined, if any
49          if (normal != null &&
50                  normal.dot(polygon.getPlane().getNormal()) < 0) {
51              return polygon.reverse();
52          }
53          return polygon;
54      }
55  
56      /** Construct a {@link ConvexPolygon3D} from the vertices of the given facet. This method
57       * attempts to honor any normal defined for the facet by making the polygon point in a similar
58       * (but not necessarily equal) direction by reversing the order of vertices if needed.
59       * @param facet facet to convert to a polygon instance
60       * @param precision precision context used for floating point comparisons
61       * @return convex polygon constructed from the facet
62       * @throws NullPointerException if either argument is null
63       * @throws IllegalArgumentException if a valid convex polygon cannot be constructed
64       */
65      public static ConvexPolygon3D toPolygon(final FacetDefinition facet, final Precision.DoubleEquivalence precision) {
66          Objects.requireNonNull(facet, "Facet cannot be null");
67          Objects.requireNonNull(precision, "Precision context cannot be null");
68          return toPolygon(facet.getVertices(), facet.getNormal(), precision);
69      }
70  }