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.stream.Stream;
    20
    21  import org.apache.commons.geometry.euclidean.threed.BoundarySource3D;
    22  import org.apache.commons.geometry.euclidean.threed.PlaneConvexSubset;
    23  import org.apache.commons.geometry.euclidean.threed.mesh.TriangleMesh;
    24  import org.apache.commons.geometry.io.core.BoundaryReadHandler;
    25  import org.apache.commons.geometry.io.core.input.GeometryInput;
    26  import org.apache.commons.numbers.core.Precision;
    27
    28  /** Basic interface for reading 3D geometric boundary representations
    29   * (<a href="https://en.wikipedia.org/wiki/Boundary_representation">B-reps</a>) from a specific data storage
    30   * format. This interface is primarily intended for use with {@link BoundaryIOManager3D}.
    31   *
    32   * <p><strong>Implementation note:</strong> implementations of this interface <em>must</em>
    33   * be thread-safe.</p>
    34   *
    35   * @see <a href="https://en.wikipedia.org/wiki/Boundary_representations">Boundary representations</a>
    36   * @see BoundaryWriteHandler3D
    37   * @see BoundaryIOManager3D
    38   */
    39  public interface BoundaryReadHandler3D extends BoundaryReadHandler<PlaneConvexSubset, BoundarySource3D> {
    40
    41      /** Return a {@link FacetDefinitionReader} for reading raw
    42       * {@link org.apache.commons.geometry.io.euclidean.threed.FacetDefinition facets} from the given
    43       * input stream.
    44       * @param in input stream to read from
    45       * @return facet definition reader instance
    46       * @throws IllegalStateException if a data format error occurs
    47       * @throws java.io.UncheckedIOException if an I/O error occurs
    48       */
    49      FacetDefinitionReader facetDefinitionReader(GeometryInput in);
    50
    51      /** Return a {@link Stream} that can be used to access all facet information from the given input stream.
    52       * The input stream is expected to contain data in the format supported by this handler.
    53       *
    54       * <p>The underlying input stream is closed when the returned stream is closed. Callers should therefore
    55       * use the returned stream in a try-with-resources statement to ensure that all resources are properly released.
    56       * </p>
    57       * <pre>
    58       *  try (Stream&lt;FacetDefinition&gt; stream = handler.facets(in)) {
    59       *      // access stream content
    60       *  }
    61       * </pre>
    62       *
    63       * <p>The following exceptions may be thrown during stream iteration:</p>
    64       * <ul>
    65       *  <li>{@link IllegalArgumentException} if mathematically invalid data is encountered</li>
    66       *  <li>{@link IllegalStateException} if a parsing or syntax error occurs</li>
    67       *  <li>{@link java.io.UncheckedIOException UncheckedIOException} if an I/O error occurs</li>
    68       * </ul>
    69       * @param in input stream to read from; this is <em>not</em> closed when the returned stream is closed
    70       * @return stream providing access to the facet information from the given input stream
    71       * @throws java.io.UncheckedIOException if an I/O error occurs during stream creation
    72       */
    73      Stream<FacetDefinition> facets(GeometryInput in);
    74
    75      /** Read a triangle mesh from the given input. Implementations may throw runtime
    76       * exceptions if mathematically invalid boundaries are encountered.
    77       * @param in input stream to read from
    78       * @param precision precision context used for floating point comparisons
    79       * @return triangle mesh containing the data from the given input stream
    80       * @throws IllegalStateException if a parsing or syntax error occurs
    81       * @throws java.io.UncheckedIOException if an I/O error occurs
    82       */
    83      TriangleMesh readTriangleMesh(GeometryInput in, Precision.DoubleEquivalence precision);
    84  }