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.examples.io.threed;
    18
    19  import java.io.File;
    20  import java.io.InputStream;
    21  import java.io.OutputStream;
    22
    23  import org.apache.commons.geometry.core.precision.DoublePrecisionContext;
    24  import org.apache.commons.geometry.euclidean.threed.BoundarySource3D;
    25
    26  /** Utility class containing constants and static convenience methods related to 3D model
    27   * input and output.
    28   */
    29  public final class ModelIO {
    30
    31      /** String representing the OBJ file format.
    32       * @see <a href="https://en.wikipedia.org/wiki/Wavefront_.obj_file">Wavefront .obj file</a>
    33       */
    34      public static final String OBJ = "obj";
    35
    36      /** Singleton handler registry. */
    37      private static final ModelIOHandlerRegistry HANDLER_REGISTRY = new DefaultModelIOHandlerRegistry();
    38
    39      /** Utility class; no instantiation. */
    40      private ModelIO() {}
    41
    42      /** Get the {@link ModelIOHandlerRegistry} singleton instance.
    43       * @return the {@link ModelIOHandlerRegistry} singleton instance
    44       */
    45      public static ModelIOHandlerRegistry getModelIOHandlerRegistry() {
    46          return HANDLER_REGISTRY;
    47      }
    48
    49      /** Read a 3D model from the given file, using the file extension as the model type. The call is delegated
    50       * to the {@link ModelIOHandlerRegistry} singleton.
    51       * @param in file to read
    52       * @param precision precision context to use in model construction
    53       * @return a 3D model represented as a boundary source
    54       * @throws java.io.UncheckedIOException if an IO operation fails
    55       * @throws IllegalArgumentException if the file does not have a file extension or the
    56       *      file extension does not indicate a supported model type
    57       * @see #getModelIOHandlerRegistry()
    58       * @see ModelIOHandlerRegistry#read(File, DoublePrecisionContext)
    59       */
    60      public static BoundarySource3D read(final File in, final DoublePrecisionContext precision) {
    61          return HANDLER_REGISTRY.read(in, precision);
    62      }
    63
    64      /** Read a 3D model of the given type from the file. The call is delegated to the {@link ModelIOHandlerRegistry}
    65       * singleton.
    66       * @param type model input type
    67       * @param in input file
    68       * @param precision precision context to use in model construction
    69       * @return a 3D model represented as a boundary source
    70       * @throws java.io.UncheckedIOException if an IO operation fails
    71       * @throws IllegalArgumentException if the model input type is not supported
    72       * @see #getModelIOHandlerRegistry()
    73       * @see ModelIOHandler#read(String, File, DoublePrecisionContext)
    74       */
    75      public static BoundarySource3D read(final String type, final File in, final DoublePrecisionContext precision) {
    76          return HANDLER_REGISTRY.read(type, in, precision);
    77      }
    78
    79      /** Read a 3D model of the given type from the input stream. The call is delegated to the
    80       * {@link ModelIOHandlerRegistry} singleton.
    81       * @param type model input type
    82       * @param in input stream to read from
    83       * @param precision precision context to use in model construction
    84       * @return a 3D model represented as a boundary source
    85       * @throws java.io.UncheckedIOException if an IO operation fails
    86       * @throws IllegalArgumentException if the model input type is not supported
    87       * @see #getModelIOHandlerRegistry()
    88       * @see ModelIOHandler#read(String, InputStream, DoublePrecisionContext)
    89       */
    90      public static BoundarySource3D read(final String type, final InputStream in,
    91              final DoublePrecisionContext precision) {
    92          return HANDLER_REGISTRY.read(type, in, precision);
    93      }
    94
    95      /** Write the model to the file. The file type is determined by the file extension of the target file.
    96       * The call is delegated to the {@link ModelIOHandlerRegistry} singleton.
    97       * @param model model to write
    98       * @param out output file
    99       * @throws java.io.UncheckedIOException if an IO operation fails
    100      * @throws IllegalArgumentException if the file does not have a file extension or the
    101      *      file extension does not indicate a supported model type
    102      * @see #getModelIOHandlerRegistry()
    103      * @see ModelIOHandlerRegistry#write(BoundarySource3D, File)
    104      */
    105     public static void write(final BoundarySource3D model, final File out) {
    106         HANDLER_REGISTRY.write(model, out);
    107     }
    108
    109     /** Write the model to the file using the specified file type. The call is delegated to the
    110      * {@link ModelIOHandlerRegistry} singleton.
    111      * @param model model to write
    112      * @param type model file type
    113      * @param out output file
    114      * @throws java.io.UncheckedIOException if an IO operation fails
    115      * @throws IllegalArgumentException if the file type is not supported
    116      * @see #getModelIOHandlerRegistry()
    117      * @see ModelIOHandler#write(BoundarySource3D, String, File)
    118      */
    119     public static void write(final BoundarySource3D model, final String type, final File out) {
    120         HANDLER_REGISTRY.write(model, type, out);
    121     }
    122
    123     /** Write the model to the output stream using the specific file type. The call is delegated to the
    124      * {@link ModelIOHandlerRegistry} singleton.
    125      * @param model model to write
    126      * @param type model file type
    127      * @param out output stream
    128      * @throws java.io.UncheckedIOException if an IO operation fails
    129      * @throws IllegalArgumentException if the file type is not supported
    130      * @see #getModelIOHandlerRegistry()
    131      * @see ModelIOHandler#write(BoundarySource3D, String, OutputStream)
    132      */
    133     public static void write(final BoundarySource3D model, final String type, final OutputStream out) {
    134         HANDLER_REGISTRY.write(model, type, out);
    135     }
    136 }