BoundaryIOManager3D.java
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.geometry.io.euclidean.threed;
import java.util.Collection;
import java.util.stream.Stream;
import org.apache.commons.geometry.euclidean.threed.BoundarySource3D;
import org.apache.commons.geometry.euclidean.threed.PlaneConvexSubset;
import org.apache.commons.geometry.euclidean.threed.Triangle3D;
import org.apache.commons.geometry.euclidean.threed.mesh.TriangleMesh;
import org.apache.commons.geometry.io.core.BoundaryIOManager;
import org.apache.commons.geometry.io.core.GeometryFormat;
import org.apache.commons.geometry.io.core.input.GeometryInput;
import org.apache.commons.geometry.io.core.output.GeometryOutput;
import org.apache.commons.geometry.io.euclidean.threed.obj.ObjBoundaryReadHandler3D;
import org.apache.commons.geometry.io.euclidean.threed.obj.ObjBoundaryWriteHandler3D;
import org.apache.commons.geometry.io.euclidean.threed.stl.StlBoundaryReadHandler3D;
import org.apache.commons.geometry.io.euclidean.threed.stl.StlBoundaryWriteHandler3D;
import org.apache.commons.geometry.io.euclidean.threed.txt.CsvBoundaryReadHandler3D;
import org.apache.commons.geometry.io.euclidean.threed.txt.CsvBoundaryWriteHandler3D;
import org.apache.commons.geometry.io.euclidean.threed.txt.TextBoundaryReadHandler3D;
import org.apache.commons.geometry.io.euclidean.threed.txt.TextBoundaryWriteHandler3D;
import org.apache.commons.numbers.core.Precision;
/** Class managing IO operations for geometric data formats containing 3D region boundaries.
* IO operation are performed by read and write handlers registered for specific data formats.
*
* <p><strong>Implementation note:</strong>Instances of this class are thread-safe as long as the
* registered handler instances are thread-safe.</p>
* @see BoundaryReadHandler3D
* @see BoundaryWriteHandler3D
* @see <a href="https://en.wikipedia.org/wiki/Boundary_representations">Boundary representations</a>
*/
public class BoundaryIOManager3D extends BoundaryIOManager<
PlaneConvexSubset,
BoundarySource3D,
BoundaryReadHandler3D,
BoundaryWriteHandler3D> {
/** Get a {@link FacetDefinitionReader} for reading facet information from the given input.
* @param in input to read facets from
* @param fmt format of the input; if null, the format is determined implicitly from the
* file extension of the input {@link GeometryInput#getFileName() file name}
* @return facet definition reader
* @throws IllegalArgumentException if no read handler can be found for the input format
* @throws IllegalStateException if a data format error occurs
* @throws java.io.UncheckedIOException if an I/O error occurs
*/
public FacetDefinitionReader facetDefinitionReader(final GeometryInput in, final GeometryFormat fmt) {
return requireReadHandler(in, fmt).facetDefinitionReader(in);
}
/** Return a {@link Stream} providing access to all facets from the given input. The underlying input
* stream is closed when the returned stream is closed. Callers should therefore use the returned stream
* in a try-with-resources statement to ensure that all resources are properly released.
* <pre>
* try (Stream<FacetDefinition> stream = manager.facets(in, fmt)) {
* // access stream content
* }
* </pre>
* <p>The following exceptions may be thrown during stream iteration:</p>
* <ul>
* <li>{@link IllegalStateException} if a data format error occurs</li>
* <li>{@link java.io.UncheckedIOException UncheckedIOException} if an I/O error occurs</li>
* </ul>
* @param in input to read from
* @param fmt format of the input; if null, the format is determined implicitly from the
* file extension of the input {@link GeometryInput#getFileName() file name}
* @return stream providing access to the facets in the input
* @throws IllegalArgumentException if no read handler can be found for the input format
* @throws IllegalStateException if a data format error occurs during stream creation
* @throws java.io.UncheckedIOException if an I/O error occurs during stream creation
*/
public Stream<FacetDefinition> facets(final GeometryInput in, final GeometryFormat fmt) {
return requireReadHandler(in, fmt).facets(in);
}
/** Return a {@link Stream} providing access to all triangles from the given input. The underlying input
* stream is closed when the returned stream is closed. Callers should therefore use the returned stream
* in a try-with-resources statement to ensure that all resources are properly released.
* <pre>
* try (Stream<Triangle3D> stream = manager.triangles(in, fmt, precision)) {
* // access stream content
* }
* </pre>
* <p>The following exceptions may be thrown during stream iteration:</p>
* <ul>
* <li>{@link IllegalArgumentException} if mathematically invalid data is encountered</li>
* <li>{@link IllegalStateException} if a data format error occurs</li>
* <li>{@link java.io.UncheckedIOException UncheckedIOException} if an I/O error occurs</li>
* </ul>
* @param in input to read from
* @param fmt format of the input; if null, the format is determined implicitly from the
* file extension of the input {@link GeometryInput#getFileName() file name}
* @param precision precision context used for floating point comparisons
* @return stream providing access to the triangles in the input
* @throws IllegalArgumentException if no read handler can be found for the input format
* @throws IllegalStateException if a data format error occurs during stream creation
* @throws java.io.UncheckedIOException if an I/O error occurs during stream creation
*/
public Stream<Triangle3D> triangles(final GeometryInput in, final GeometryFormat fmt,
final Precision.DoubleEquivalence precision) {
return boundaries(in, fmt, precision)
.flatMap(p -> p.toTriangles().stream());
}
/** Return a {@link TriangleMesh} containing all triangles from the given input.
* @param in input to read from
* @param fmt format of the input; if null, the format is determined implicitly from the
* file extension of the input {@link GeometryInput#getFileName() file name}
* @param precision precision context used for floating point comparisons
* @return mesh containing all triangles from the input
* @throws IllegalArgumentException if mathematically invalid data is encountered or no read
* handler can be found for the input format
* @throws IllegalStateException if a data format error occurs
* @throws java.io.UncheckedIOException if an I/O error occurs
*/
public TriangleMesh readTriangleMesh(final GeometryInput in, final GeometryFormat fmt,
final Precision.DoubleEquivalence precision) {
return requireReadHandler(in, fmt).readTriangleMesh(in, precision);
}
/** Write all boundaries in the stream to the output.
*
* <p>This method does not explicitly close the {@code boundaries} stream. If callers need to ensure that
* the stream is closed (for example, if the stream is reading from a file), they should use it in a
* try-with-resources statement outside of this method.</p>
* @param boundaries stream containing boundaries to write
* @param out output to write to
* @param fmt format of the output; if null, the format is determined implicitly from the
* file extension of the output {@link GeometryOutput#getFileName() file name}
* @throws IllegalArgumentException if no write handler can be found for the output format
* @throws java.io.UncheckedIOException if an I/O error occurs
*/
public void write(final Stream<? extends PlaneConvexSubset> boundaries, final GeometryOutput out,
final GeometryFormat fmt) {
requireWriteHandler(out, fmt).write(boundaries, out);
}
/** Write all facet in the stream to the output.
*
* <p>This method does not explicitly close the {@code boundaries} stream. If callers need to ensure that
* the stream is closed (for example, if the stream is reading from a file), they should use it in a
* try-with-resources statement outside of this method.</p>
* @param facets stream containing facets to write
* @param out output to write to
* @param fmt format of the output; if null, the format is determined implicitly from the
* file extension of the output {@link GeometryOutput#getFileName() file name}
* @throws IllegalArgumentException if no write handler can be found for the output format
* @throws java.io.UncheckedIOException if an I/O error occurs
*/
public void writeFacets(final Stream<? extends FacetDefinition> facets, final GeometryOutput out,
final GeometryFormat fmt) {
requireWriteHandler(out, fmt).writeFacets(facets, out);
}
/** Write the given facets to the output.
* @param facets facets to write
* @param out output to write to
* @param fmt format of the output; if null, the format is determined implicitly from the
* file extension of the output {@link GeometryOutput#getFileName() file name}
* @throws IllegalArgumentException if no write handler can be found for the output format
* @throws java.io.UncheckedIOException if an I/O error occurs
*/
public void writeFacets(final Collection<? extends FacetDefinition> facets, final GeometryOutput out,
final GeometryFormat fmt) {
requireWriteHandler(out, fmt).writeFacets(facets, out);
}
/** Register default read/write handlers. This method registers a read and write handler
* for each value in {@link GeometryFormat3D}.
*/
public void registerDefaultHandlers() {
// obj
registerReadHandler(new ObjBoundaryReadHandler3D());
registerWriteHandler(new ObjBoundaryWriteHandler3D());
// stl
registerReadHandler(new StlBoundaryReadHandler3D());
registerWriteHandler(new StlBoundaryWriteHandler3D());
// txt
registerReadHandler(new TextBoundaryReadHandler3D());
registerWriteHandler(new TextBoundaryWriteHandler3D());
// csv
registerReadHandler(new CsvBoundaryReadHandler3D());
registerWriteHandler(new CsvBoundaryWriteHandler3D());
}
}