Class IO3D


  • public final class IO3D
    extends java.lang.Object
    Utility class providing convenient access to 3D IO functionality. The static read and write methods here delegate to a default BoundaryIOManager3D instance. The default configuration should be sufficient for most purposes. If customization is required, consider directly creating and configuring and a BoundaryIOManager3D instance.

    Examples

    The example below reads an OBJ file as a stream of triangles, transforms each triangle, and writes the result as a CSV file. The data formats are inferred from the input and output file extensions.

     GeometryInput input = new FileGeometryInput(Paths.get("orig.obj"));
     GeometryOutput scaledOutput = new FileGeometryOutput(Paths.get("scaled.csv"));
     AffineTransformMatrix3D transform = AffineTransformMatrix3D.createScale(2);
    
     // Use the input triangle stream in a try-with-resources statement to ensure
     // all resources are properly released.
     try (Stream<Triangle3D> stream = IO3D.triangles(input, null, precision)) {
          IO3D.write(stream.map(t -> t.transform(transform)), scaledOutput, null);
     }
     
    See Also:
    BoundaryIOManager3D
    • Constructor Detail

      • IO3D

        private IO3D()
        Utility class; no instantiation.
    • Method Detail

      • facetDefinitionReader

        public static FacetDefinitionReader facetDefinitionReader​(java.nio.file.Path path)
        Get a FacetDefinitionReader for reading facet information from the given file path. The data format is determined by the file extension of the argument.
        Parameters:
        path - path to obtain a reader for
        Returns:
        facet definition reader
        Throws:
        java.lang.IllegalArgumentException - if no handler has been registered with the default manager for the input format
        java.lang.IllegalStateException - if a data format error occurs
        java.io.UncheckedIOException - if an I/O error occurs
        See Also:
        BoundaryIOManager3D.facetDefinitionReader(GeometryInput, GeometryFormat)
      • facetDefinitionReader

        public static FacetDefinitionReader facetDefinitionReader​(java.net.URL url)
        Get a FacetDefinitionReader for reading facet information from the given URL. The data format is determined by the file extension of the argument.
        Parameters:
        url - URL to read from
        Returns:
        facet definition reader
        Throws:
        java.lang.IllegalArgumentException - if no handler has been registered with the default manager for the input format
        java.lang.IllegalStateException - if a data format error occurs
        java.io.UncheckedIOException - if an I/O error occurs
        See Also:
        BoundaryIOManager3D.facetDefinitionReader(GeometryInput, GeometryFormat)
      • facets

        public static java.util.stream.Stream<FacetDefinition> facets​(java.nio.file.Path path)
        Return a Stream providing access to all facets from the given file path. The data format is determined by the file extension of the argument.

        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. Ex:

          try (Stream<FacetDefinition> stream = IO3D.facets(path)) {
              // access stream content
          }
         

        The following exceptions may be thrown during stream iteration:

        • IllegalStateException if a data format error occurs
        • UncheckedIOException if an I/O error occurs
        Parameters:
        path - file path to read from
        Returns:
        stream providing access to the facets in the specified file
        Throws:
        java.lang.IllegalArgumentException - if no handler has been registered with the default manager for the input format
        java.lang.IllegalStateException - if a data format error occurs during stream creation
        java.io.UncheckedIOException - if an I/O error occurs during stream creation
        See Also:
        BoundaryIOManager3D.facets(GeometryInput, GeometryFormat)
      • facets

        public static java.util.stream.Stream<FacetDefinition> facets​(java.net.URL url)
        Return a Stream providing access to all facets from the given URL. he data format is determined by the file extension of the argument.

        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. Ex:

          try (Stream<FacetDefinition> stream = IO3D.facets(url)) {
              // access stream content
          }
         

        The following exceptions may be thrown during stream iteration:

        • IllegalStateException if a data format error occurs
        • UncheckedIOException if an I/O error occurs
        Parameters:
        url - URL to read from
        Returns:
        stream providing access to the facets from the specified URL
        Throws:
        java.lang.IllegalArgumentException - if no handler has been registered with the default manager for the input format
        java.lang.IllegalStateException - if a data format error occurs during stream creation
        java.io.UncheckedIOException - if an I/O error occurs during stream creation
        See Also:
        BoundaryIOManager3D.facets(GeometryInput, GeometryFormat)
      • facets

        public static java.util.stream.Stream<FacetDefinition> facets​(GeometryInput in,
                                                                      GeometryFormat fmt)
        Return a 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.
          try (Stream<FacetDefinition> stream = IO3D.facets(in, fmt)) {
              // access stream content
          }
         

        The following exceptions may be thrown during stream iteration:

        • IllegalStateException if a data format error occurs
        • UncheckedIOException if an I/O error occurs
        Parameters:
        in - input to read from
        fmt - format of the input; if null, the format is determined implicitly from the file extension of the input file name
        Returns:
        stream providing access to the facets in the input
        Throws:
        java.lang.IllegalArgumentException - if no read handler has been registered with the default manager for the input format
        java.lang.IllegalStateException - if a data format error occurs during stream creation
        java.io.UncheckedIOException - if an I/O error occurs during stream creation
        See Also:
        BoundaryIOManager3D.facets(GeometryInput, GeometryFormat)
      • boundaries

        public static java.util.stream.Stream<PlaneConvexSubset> boundaries​(java.nio.file.Path path,
                                                                            org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Return a Stream providing access to all boundaries from the given file path. The data format is determined by the file extension of the argument.

        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. Ex:

          try (Stream<PlaneConvexSubset> stream = IO3D.boundaries(path, precision)) {
              // access stream content
          }
         

        The following exceptions may be thrown during stream iteration:

        • IllegalArgumentException if mathematically invalid data is encountered
        • IllegalStateException if a data format error occurs
        • UncheckedIOException if an I/O error occurs
        Parameters:
        path - file path to read from
        precision - precision context used for floating point comparisons
        Returns:
        stream providing access to the boundaries in the specified file
        Throws:
        java.lang.IllegalArgumentException - if no read handler has been registered with the default manager for the input format
        java.lang.IllegalStateException - if a data format error occurs during stream creation
        java.io.UncheckedIOException - if an I/O error occurs during stream creation
        See Also:
        BoundaryIOManager.boundaries(GeometryInput, GeometryFormat, Precision.DoubleEquivalence)
      • boundaries

        public static java.util.stream.Stream<PlaneConvexSubset> boundaries​(java.net.URL url,
                                                                            org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Return a Stream providing access to all boundaries from the given URL. The data format is determined by the file extension of the argument.

        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. Ex:

          try (Stream<PlaneConvexSubset> stream = IO3D.boundaries(url, precision)) {
              // access stream content
          }
         

        The following exceptions may be thrown during stream iteration:

        • IllegalArgumentException if mathematically invalid data is encountered
        • IllegalStateException if a data format error occurs
        • UncheckedIOException if an I/O error occurs
        Parameters:
        url - URL to read from
        precision - precision context used for floating point comparisons
        Returns:
        stream providing access to the boundaries in the specified URL
        Throws:
        java.lang.IllegalArgumentException - if no read handler has been registered with the default manager for the input format
        java.lang.IllegalStateException - if a data format error occurs during stream creation
        java.io.UncheckedIOException - if an I/O error occurs during stream creation
        See Also:
        BoundaryIOManager.boundaries(GeometryInput, GeometryFormat, Precision.DoubleEquivalence)
      • boundaries

        public static java.util.stream.Stream<PlaneConvexSubset> boundaries​(GeometryInput in,
                                                                            GeometryFormat fmt,
                                                                            org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Return a Stream providing access to all boundaries 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. Ex:
          try (Stream<H> stream = IO3D.boundaries(in, fmt, precision)) {
              // access stream content
          }
          

        The following exceptions may be thrown during stream iteration:

        • IllegalArgumentException if mathematically invalid data is encountered
        • IllegalStateException if a data format error occurs
        • UncheckedIOException if an I/O error occurs
        Parameters:
        in - input to read boundaries from
        fmt - format of the input; if null, the format is determined implicitly from the file extension of the input file name
        precision - precision context used for floating point comparisons
        Returns:
        stream providing access to the boundaries in the input
        Throws:
        java.lang.IllegalArgumentException - if no read handler is registered with the default manager for the input format
        java.lang.IllegalStateException - if a data format error occurs during stream creation
        java.io.UncheckedIOException - if an I/O error occurs during stream creation
        See Also:
        BoundaryIOManager.boundaries(GeometryInput, GeometryFormat, Precision.DoubleEquivalence)
      • triangles

        public static java.util.stream.Stream<Triangle3D> triangles​(java.nio.file.Path path,
                                                                    org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Return a Stream providing access to all triangles from the given file path. The data format is determined by the file extension of the argument.

        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. Ex:

          try (Stream<Triangle3D> stream = IO3D.triangles(path, precision)) {
              // access stream content
          }
         

        The following exceptions may be thrown during stream iteration:

        • IllegalArgumentException if mathematically invalid data is encountered
        • IllegalStateException if a data format error occurs
        • UncheckedIOException if an I/O error occurs
        Parameters:
        path - file path to read from
        precision - precision context used for floating point comparisons
        Returns:
        stream providing access to the triangles in the specified file
        Throws:
        java.lang.IllegalArgumentException - if no read handler is registered with the default manager for the input format
        java.lang.IllegalStateException - if a data format error occurs during stream creation
        java.io.UncheckedIOException - if an I/O error occurs during stream creation
        See Also:
        BoundaryIOManager3D.triangles(GeometryInput, GeometryFormat, Precision.DoubleEquivalence)
      • triangles

        public static java.util.stream.Stream<Triangle3D> triangles​(java.net.URL url,
                                                                    org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Return a Stream providing access to all triangles from the given URL. The data format is determined by the file extension of the argument.

        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. Ex:

          try (Stream<Triangle3D> stream = IO3D.triangles(url, precision)) {
              // access stream content
          }
         

        The following exceptions may be thrown during stream iteration:

        • IllegalArgumentException if mathematically invalid data is encountered
        • IllegalStateException if a data format error occurs
        • UncheckedIOException if an I/O error occurs
        Parameters:
        url - URL to read from
        precision - precision context used for floating point comparisons
        Returns:
        stream providing access to the triangles from the specified URL
        Throws:
        java.lang.IllegalArgumentException - if no read handler is registered with the default manager for the input format
        java.lang.IllegalStateException - if a data format error occurs during stream creation
        java.io.UncheckedIOException - if an I/O error occurs during stream creation
        See Also:
        BoundaryIOManager3D.triangles(GeometryInput, GeometryFormat, Precision.DoubleEquivalence)
      • triangles

        public static java.util.stream.Stream<Triangle3D> triangles​(GeometryInput in,
                                                                    GeometryFormat fmt,
                                                                    org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Return a 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.
          try (Stream<Triangle3D> stream = IO3D.triangles(in, fmt, precision)) {
              // access stream content
          }
         

        The following exceptions may be thrown during stream iteration:

        • IllegalArgumentException if mathematically invalid data is encountered
        • IllegalStateException if a data format error occurs
        • UncheckedIOException if an I/O error occurs
        Parameters:
        in - input to read from
        fmt - format of the input; if null, the format is determined implicitly from the file extension of the input file name
        precision - precision context used for floating point comparisons
        Returns:
        stream providing access to the triangles in the input
        Throws:
        java.lang.IllegalArgumentException - if no read handler is registered with the default manager for the input format
        java.lang.IllegalStateException - if a data format error occurs during stream creation
        java.io.UncheckedIOException - if an I/O error occurs during stream creation
        See Also:
        BoundaryIOManager3D.triangles(GeometryInput, GeometryFormat, Precision.DoubleEquivalence)
      • read

        public static BoundarySource3D read​(java.nio.file.Path path,
                                            org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Return a BoundarySource3D containing all boundaries from the file at the given path. The data format is determined from the file extension. A runtime exception may be thrown if mathematically invalid boundaries are encountered.
        Parameters:
        path - file path to read from
        precision - precision context used for floating point comparisons
        Returns:
        object containing all boundaries from the file at the given path
        Throws:
        java.lang.IllegalArgumentException - if mathematically invalid data is encountered or no read handler is registered with the default manager for the input format
        java.lang.IllegalStateException - if a data format error occurs
        java.io.UncheckedIOException - if an I/O error occurs
        See Also:
        BoundaryIOManager.read(GeometryInput, GeometryFormat, Precision.DoubleEquivalence)
      • read

        public static BoundarySource3D read​(java.net.URL url,
                                            org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Return a BoundarySource3D containing all boundaries from the given URL. The data format is determined from the file extension of the URL path. A runtime exception may be thrown if mathematically invalid boundaries are encountered.
        Parameters:
        url - URL to read from
        precision - precision context used for floating point comparisons
        Returns:
        object containing all boundaries from the given URL
        Throws:
        java.lang.IllegalArgumentException - if mathematically invalid data is encountered or no read handler is registered with the default manager for the input format
        java.lang.IllegalStateException - if a data format error occurs
        java.io.UncheckedIOException - if an I/O error occurs
        See Also:
        BoundaryIOManager.read(GeometryInput, GeometryFormat, Precision.DoubleEquivalence)
      • read

        public static BoundarySource3D read​(GeometryInput in,
                                            GeometryFormat fmt,
                                            org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Return a BoundarySource3D containing all boundaries from the given input. A runtime exception may be thrown if mathematically invalid boundaries are encountered.
        Parameters:
        in - input to read boundaries from
        fmt - format of the input; if null, the format is determined implicitly from the file extension of the input file name
        precision - precision context used for floating point comparisons
        Returns:
        object containing all boundaries from the input
        Throws:
        java.lang.IllegalArgumentException - if mathematically invalid data is encountered or no read handler is registered with the default manager for the input format
        java.lang.IllegalStateException - if a data format error occurs
        java.io.UncheckedIOException - if an I/O error occurs
        See Also:
        BoundaryIOManager.read(GeometryInput, GeometryFormat, Precision.DoubleEquivalence)
      • readTriangleMesh

        public static TriangleMesh readTriangleMesh​(java.nio.file.Path path,
                                                    org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Return a TriangleMesh containing all triangles from the given file path. The data format is determined from the file extension of the path. A runtime exception may be thrown if mathematically invalid boundaries are encountered.
        Parameters:
        path - file path to read from
        precision - precision context used for floating point comparisons
        Returns:
        mesh containing all triangles from the given file path
        Throws:
        java.lang.IllegalArgumentException - if mathematically invalid data is encountered or no read handler is registered with the default manager for the input format
        java.lang.IllegalStateException - if a data format error occurs
        java.io.UncheckedIOException - if an I/O error occurs
        See Also:
        BoundaryIOManager3D.readTriangleMesh(GeometryInput, GeometryFormat, Precision.DoubleEquivalence)
      • readTriangleMesh

        public static TriangleMesh readTriangleMesh​(java.net.URL url,
                                                    org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Return a TriangleMesh containing all triangles from the given URL. The data format is determined from the file extension of the URL path. A runtime exception may be thrown if mathematically invalid boundaries are encountered.
        Parameters:
        url - URL to read from
        precision - precision context used for floating point comparisons
        Returns:
        mesh containing all triangles from the given URL
        Throws:
        java.lang.IllegalArgumentException - if mathematically invalid data is encountered or no read handler is registered with the default manager for the input format
        java.lang.IllegalStateException - if a data format error occurs
        java.io.UncheckedIOException - if an I/O error occurs
        See Also:
        BoundaryIOManager3D.readTriangleMesh(GeometryInput, GeometryFormat, Precision.DoubleEquivalence)
      • readTriangleMesh

        public static TriangleMesh readTriangleMesh​(GeometryInput in,
                                                    GeometryFormat fmt,
                                                    org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Return a TriangleMesh containing all triangles from the given input. A runtime exception may be thrown if mathematically invalid boundaries are encountered.
        Parameters:
        in - input to read from
        fmt - format of the input; if null, the format is determined implicitly from the file extension of the input file name
        precision - precision context used for floating point comparisons
        Returns:
        a mesh containing all triangles from the input
        Throws:
        java.lang.IllegalArgumentException - if mathematically invalid data is encountered or no read handler is registered with the default manager for the input format
        java.lang.IllegalStateException - if a data format error occurs
        java.io.UncheckedIOException - if an I/O error occurs
        See Also:
        BoundaryIOManager3D.readTriangleMesh(GeometryInput, GeometryFormat, Precision.DoubleEquivalence)
      • write

        public static void write​(java.util.stream.Stream<? extends PlaneConvexSubset> boundaries,
                                 java.nio.file.Path path)
        Write all boundaries in the stream to given file path. The data format is determined by the file extension of the target path. If the target path already exists, it is overwritten.

        This method does not explicitly close the boundaries stream. Callers should use the stream in a try-with-resources statement outside of this method if the stream is required to be closed.

        Parameters:
        boundaries - stream containing boundaries to write
        path - file path to write to
        Throws:
        java.lang.IllegalArgumentException - if no write handler is registered with the default manager for the output format
        java.io.UncheckedIOException - if an I/O error occurs
        See Also:
        BoundaryIOManager3D.write(Stream, GeometryOutput, GeometryFormat)
      • write

        public static void write​(java.util.stream.Stream<? extends PlaneConvexSubset> boundaries,
                                 GeometryOutput out,
                                 GeometryFormat fmt)
        Write all boundaries in the stream to the output.

        This method does not explicitly close the boundaries stream. Callers should use the stream in a try-with-resources statement outside of this method if the stream is required to be closed.

        Parameters:
        boundaries - stream containing boundaries to write
        out - output to write to
        fmt - format of the output; if null, the format is determined implicitly from the file extension of the output file name
        Throws:
        java.lang.IllegalArgumentException - if no write handler is registered with the default manager for the output format
        java.io.UncheckedIOException - if an I/O error occurs
        See Also:
        BoundaryIOManager3D.write(Stream, GeometryOutput, GeometryFormat)
      • writeFacets

        public static void writeFacets​(java.util.Collection<? extends FacetDefinition> facets,
                                       java.nio.file.Path path)
        Write the given facets to the file path. The data format is determined by the file extension of the target path. If the target path already exists, it is overwritten.
        Parameters:
        facets - facets to write
        path - path to write to
        Throws:
        java.lang.IllegalArgumentException - if no write handler is registered with the default manager for the output format
        java.io.UncheckedIOException - if an I/O error occurs
        See Also:
        BoundaryIOManager3D.writeFacets(Collection, GeometryOutput, GeometryFormat)
      • writeFacets

        public static void writeFacets​(java.util.stream.Stream<? extends FacetDefinition> facets,
                                       java.nio.file.Path path)
        Write all facets in the stream to the file path. The data format is determined by the file extension of the target path. If the target path already exists, it is overwritten.

        This method does not explicitly close the facets stream. Callers should use the stream in a try-with-resources statement outside of this method if the stream is required to be closed.

        Parameters:
        facets - stream containing facets to write
        path - path to write to
        Throws:
        java.lang.IllegalArgumentException - if no write handler is registered with the default manager for the output format
        java.io.UncheckedIOException - if an I/O error occurs
        See Also:
        BoundaryIOManager3D.writeFacets(Stream, GeometryOutput, GeometryFormat)
      • writeFacets

        public static void writeFacets​(java.util.stream.Stream<? extends FacetDefinition> facets,
                                       GeometryOutput out,
                                       GeometryFormat fmt)
        Write all facets in the stream to the output.

        This method does not explicitly close the facets stream. Callers should use the stream in a try-with-resources statement outside of this method if the stream is required to be closed.

        Parameters:
        facets - stream containing facets to write
        out - output to write to
        fmt - format of the output; if null, the format is determined implicitly from the file extension of the output file name
        Throws:
        java.lang.IllegalArgumentException - if no write handler is registered with the default manager for the output format
        java.io.UncheckedIOException - if an I/O error occurs
        See Also:
        BoundaryIOManager3D.writeFacets(Stream, GeometryOutput, GeometryFormat)