Package com.irurueta.geometry.io

Class LoaderPLY

java.lang.Object
com.irurueta.geometry.io.Loader
com.irurueta.geometry.io.LoaderPLY
All Implemented Interfaces:
Closeable, AutoCloseable
public class LoaderPLY extends Loader
Loads PLY files. This class is meant to read PLY files using an iterative process to read the file in small pieces of data. Because the file is loaded in small pieces, this class has a low memory impact. Besides parameters such as maxVerticesInChunk or maxStreamPositions can be adjusted in order to increase or reduce memory usage at the expense of performance (the greater the memory usage the better the performance). This class needs random access to file positions, and for that reason it cannot be used with streams. This class is based in the work of: http://w3.impa.br/~diego/software/rply/

  • Field Details

    • BUFFER_SIZE

      public static final int BUFFER_SIZE
      Size of internal buffer where bytes from stream of data read into. This size (8 bytes) is meant to be able to fit any data type.
      See Also:

    • DEFAULT_MAX_VERTICES_IN_CHUNK

      public static final int DEFAULT_MAX_VERTICES_IN_CHUNK
      Constant defining maximum number of vertices to be stored in a single data chunk. By default, this is the maximum values stored in a short 65535. This is so that data chunks can be compatible with technologies such as openGL where vertex indices are short values, and hence only 65535 vertices can be indexed at a time.
      See Also:

    • MIN_MAX_VERTICES_IN_CHUNK

      public static final int MIN_MAX_VERTICES_IN_CHUNK
      Minimum allowed value for maximum vertices in a chunk. At least one vertex must be contained on a data chunk, for that reason this constant is 1.
      See Also:

    • DEFAULT_ALLOW_DUPLICATE_VERTICES_IN_CHUNK

      public static final boolean DEFAULT_ALLOW_DUPLICATE_VERTICES_IN_CHUNK
      Constant defining if by default duplicate vertices are allowed in a data chunk. By allowing duplicate vertices, PLY loading can be speed up a little bit at the expense of getting larger sets of data which will contain redundant vertices. If your environment is memory constrained, this should be disabled. By default, it is disabled.
      See Also:

    • DEFAULT_MAX_STREAM_POSITIONS

      public static final int DEFAULT_MAX_STREAM_POSITIONS
      Constant defining default maximum number of stream positions to be cached. This loader keeps track of a set of stream positions that have been parsed on ASCII mode. By keeping a cache of positions loading times can be largely reduced at the expense of using more memory during loading. By default, this is set to 1000000 positions. This only has effect on ASCII PLY files. For binary PLY files this constant is ignored.
      See Also:

    • MIN_STREAM_POSITIONS

      public static final int MIN_STREAM_POSITIONS
      Constant defining minimum allowed value for maximum stream positions.
      See Also:

    • PROGRESS_DELTA

      public static final float PROGRESS_DELTA
      Constant defining when progress change should be notified. When progress is increased by this value from previous notification, then progress will be notified again.
      See Also:

    • validStream

      private boolean validStream
      Boolean indicating if file is a valid PLY stream of data.

    • validityChecked

      private boolean validityChecked
      Boolean indicating whether validity of file has already been checked.

    • loaderIterator

      private LoaderPLY.LoaderIteratorPLY loaderIterator
      Iterator currently loading provided file.

    • maxVerticesInChunk

      private int maxVerticesInChunk
      Indicates maximum number of vertices to keep in a chunk of data. By default, this is the maximum values stored in a short 65535. This is so that data chunks can be compatible with technologies such as openGL where vertex indices are short values, and hence only 65535 vertices can be indexed at a time.

    • allowDuplicateVerticesInChunk

      private boolean allowDuplicateVerticesInChunk
      Indicates whether duplicate vertices in a chunk are allowed. By allowing duplicate vertices, PLY loading can be speed up a little bit at the expense of getting larger sets of data which will contain redundant vertices. If your environment is memory constrained, this should be disabled. By default, it is disabled.

    • maxStreamPositions

      private long maxStreamPositions
      Maximum number of stream positions to be cached. This loader keeps track of a set of stream positions that have been parsed on ASCII mode. By keeping a cache of positions loading times can be largely reduced at the expense of using more memory during loading. By default, this is set to 1000000 positions. This only has effect on ASCII PLY files. For binary PLY files this setting is ignored.

  • Constructor Details

    • LoaderPLY

      public LoaderPLY()
      Constructor.

    • LoaderPLY

      public LoaderPLY(int maxVerticesInChunk)
      Constructor.
      Parameters:
      maxVerticesInChunk - Indicates maximum number of vertices to keep in a chunk of data.
      Throws:
      IllegalArgumentException - Raised if maximum number of vertices is smaller than MIN_MAX_VERTICES_IN_CHUNK.

    • LoaderPLY

      public LoaderPLY(int maxVerticesInChunk, boolean allowDuplicateVerticesInChunk)
      Constructor.
      Parameters:
      maxVerticesInChunk - Indicates maximum number of vertices to keep in a chunk of data.
      allowDuplicateVerticesInChunk - Indicates whether duplicate vertices in a chunk are allowed.
      Throws:
      IllegalArgumentException - Raised if maximum number of vertices is smaller than MIN_MAX_VERTICES_IN_CHUNK.

    • LoaderPLY

      public LoaderPLY(int maxVerticesInChunk, boolean allowDuplicateVerticesInChunk, long maxStreamPositions)
      Constructor.
      Parameters:
      maxVerticesInChunk - Indicates maximum number of vertices to keep in a chunk of data.
      allowDuplicateVerticesInChunk - Indicates whether duplicate vertices in a chunk are allowed.
      maxStreamPositions - Maximum number of stream positions to be cached.
      Throws:
      IllegalArgumentException - Raised if maximum number of vertices is smaller than MIN_MAX_VERTICES_IN_CHUNK or if maximum stream positions is smaller than MIN_STREAM_POSITIONS.

    • LoaderPLY

      public LoaderPLY(File f) throws IOException
      Constructor.
      Parameters:
      f - file to be loaded.
      Throws:
      IOException - if file does not exist or cannot be loaded.

    • LoaderPLY

      public LoaderPLY(File f, int maxVerticesInChunk) throws IOException
      Constructor.
      Parameters:
      f - file to be loaded.
      maxVerticesInChunk - Indicates maximum number of vertices to keep in a chunk of data.
      Throws:
      IllegalArgumentException - Raised if maximum number of vertices is smaller than MIN_MAX_VERTICES_IN_CHUNK.
      IOException - if file does not exist or cannot be loaded.

    • LoaderPLY

      public LoaderPLY(File f, int maxVerticesInChunk, boolean allowDuplicateVerticesInChunk) throws IOException
      Constructor.
      Parameters:
      f - file to be loaded.
      maxVerticesInChunk - Indicates maximum number of vertices to keep in a chunk of data.
      allowDuplicateVerticesInChunk - Indicates whether duplicate vertices in a chunk are allowed.
      Throws:
      IllegalArgumentException - Raised if maximum number of vertices is smaller than MIN_MAX_VERTICES_IN_CHUNK.
      IOException - if file does not exist or cannot be loaded.

    • LoaderPLY

      public LoaderPLY(File f, int maxVerticesInChunk, boolean allowDuplicateVerticesInChunk, long maxStreamPositions) throws IOException
      Constructor.
      Parameters:
      f - file to be loaded.
      maxVerticesInChunk - Indicates maximum number of vertices to keep in a chunk of data.
      allowDuplicateVerticesInChunk - Indicates whether duplicate vertices in a chunk are allowed.
      maxStreamPositions - Maximum number of stream positions to be cached.
      Throws:
      IllegalArgumentException - Raised if maximum number of vertices is smaller than MIN_MAX_VERTICES_IN_CHUNK or if maximum stream positions is smaller than MIN_STREAM_POSITIONS.
      IOException - if file does not exist or cannot be loaded.

    • LoaderPLY

      public LoaderPLY(LoaderListener listener)
      Constructor.
      Parameters:
      listener - listener to notify start, end and progress events.

    • LoaderPLY

      public LoaderPLY(LoaderListener listener, int maxVerticesInChunk)
      Constructor.
      Parameters:
      listener - listener to notify start, end and progress events.
      maxVerticesInChunk - Indicates maximum number of vertices to keep in a chunk of data.
      Throws:
      IllegalArgumentException - Raised if maximum number of vertices is smaller than MIN_MAX_VERTICES_IN_CHUNK.

    • LoaderPLY

      public LoaderPLY(LoaderListener listener, int maxVerticesInChunk, boolean allowDuplicateVerticesInChunk)
      Constructor.
      Parameters:
      listener - listener to notify start, end and progress events.
      maxVerticesInChunk - Indicates maximum number of vertices to keep in a chunk of data.
      allowDuplicateVerticesInChunk - Indicates whether duplicate vertices in a chunk are allowed.
      Throws:
      IllegalArgumentException - Raised if maximum number of vertices is smaller than MIN_MAX_VERTICES_IN_CHUNK.

    • LoaderPLY

      public LoaderPLY(LoaderListener listener, int maxVerticesInChunk, boolean allowDuplicateVerticesInChunk, long maxStreamPositions)
      Constructor.
      Parameters:
      listener - listener to notify start, end and progress events.
      maxVerticesInChunk - Indicates maximum number of vertices to keep in a chunk of data.
      allowDuplicateVerticesInChunk - Indicates whether duplicate vertices in a chunk are allowed.
      maxStreamPositions - Maximum number of stream positions to be cached.
      Throws:
      IllegalArgumentException - Raised if maximum number of vertices is smaller than MIN_MAX_VERTICES_IN_CHUNK or if maximum stream positions is smaller than MIN_STREAM_POSITIONS.

    • LoaderPLY

      public LoaderPLY(File f, LoaderListener listener) throws IOException
      Constructor.
      Parameters:
      f - file to be loaded.
      listener - listener to notify start, end and progress events.
      Throws:
      IOException - if file does not exist or cannot be loaded.

    • LoaderPLY

      public LoaderPLY(File f, LoaderListener listener, int maxVerticesInChunk) throws IOException
      Constructor.
      Parameters:
      f - file to be loaded.
      listener - listener to notify start, end and progress events.
      maxVerticesInChunk - Indicates maximum number of vertices to keep in a chunk of data.
      Throws:
      IllegalArgumentException - Raised if maximum number of vertices is smaller than MIN_MAX_VERTICES_IN_CHUNK.
      IOException - if file does not exist or cannot be loaded.

    • LoaderPLY

      public LoaderPLY(File f, LoaderListener listener, int maxVerticesInChunk, boolean allowDuplicateVerticesInChunk) throws IOException
      Constructor.
      Parameters:
      f - file to be loaded.
      listener - listener to notify start, end and progress events.
      maxVerticesInChunk - Indicates maximum number of vertices to keep in a chunk of data.
      allowDuplicateVerticesInChunk - Indicates whether duplicate vertices in a chunk are allowed.
      Throws:
      IllegalArgumentException - Raised if maximum number of vertices is smaller than MIN_MAX_VERTICES_IN_CHUNK.
      IOException - if file does not exist or cannot be loaded.

    • LoaderPLY

      public LoaderPLY(File f, LoaderListener listener, int maxVerticesInChunk, boolean allowDuplicateVerticesInChunk, long maxStreamPositions) throws IOException
      Constructor.
      Parameters:
      f - file to be loaded.
      listener - listener to notify start, end and progress events.
      maxVerticesInChunk - Indicates maximum number of vertices to keep in a chunk of data.
      allowDuplicateVerticesInChunk - Indicates whether duplicate vertices in a chunk are allowed.
      maxStreamPositions - Maximum number of stream positions to be cached.
      Throws:
      IllegalArgumentException - Raised if maximum number of vertices is smaller than MIN_MAX_VERTICES_IN_CHUNK or if maximum stream positions is smaller than MIN_STREAM_POSITIONS.
      IOException - if file does not exist or cannot be loaded.

  • Method Details

    • getMaxVerticesInChunk

      public int getMaxVerticesInChunk()
      Returns maximum number of vertices to keep in a chunk of data. By default, this is the maximum values stored in a short is 65535. This is so that data chunks can be compatible with technologies such as openGL where vertex indices are short values, and hence only 65535 vertices can be indexed at a time.
      Returns:
      Maximum number of vertices to keep in a chunk of data.

    • setMaxVerticesInChunk

      public void setMaxVerticesInChunk(int maxVerticesInChunk) throws LockedException
      Sets maximum number of vertices to keep in a chunk of data.
      Parameters:
      maxVerticesInChunk - Indicates maximum number of vertices to keep in a chunk of data.
      Throws:
      IllegalArgumentException - Raised if maximum number of vertices is smaller than MIN_MAX_VERTICES_IN_CHUNK.
      LockedException - Raised if this instance is locked because loading is in progress.

    • areDuplicateVerticesInChunkAllowed

      public boolean areDuplicateVerticesInChunkAllowed()
      Determines whether duplicate vertices in a chunk are allowed. By allowing duplicate vertices, PLY loading can be speed up a little bit at the expense of getting larger sets of data which will contain redundant vertices. If your environment is memory constrained, this should be disabled. By default, it is disabled.
      Returns:
      Determines whether duplicate vertices in a chunk are allowed.

    • setAllowDuplicateVerticesInChunk

      public void setAllowDuplicateVerticesInChunk(boolean allow) throws LockedException
      Sets whether duplicate vertices in a chunk are allowed. By allowing duplicate vertices, PLY loading can be speed up a little bit at the expense of getting larger sets of data which will contain redundant vertices. If your environment is memory constrained, this should be disabled. By default, it is disabled.
      Parameters:
      allow - Indicates whether duplicates will be allowed or not.
      Throws:
      LockedException - Raised if this instance is locked because loading is in progress.

    • getMaxStreamPositions

      public long getMaxStreamPositions()
      Returns maximum number of stream positions to be cached. This loader keeps track of a set of stream positions that have been parsed on ASCII mode. By keeping a cache of positions loading times can be largely reduced at the expense of using more memory during loading. By default, this is set to 1000000 positions. This only has effect on ASCII PLY files. For binary PLY files this setting is ignored.
      Returns:
      maximum number of stream positions to be cached.

    • setMaxStreamPositions

      public void setMaxStreamPositions(long maxStreamPositions) throws LockedException
      Sets maximum number of stream positions to be cached. This loader keeps track of a set of stream positions that have been parsed on ASCII mode. By keeping a cache of positions loading times can be largely reduced at the expense of using more memory during loading. By default, this is set to 1000000 positions. This only has effect on ASCII PLY files. For binary PLY files this setting is ignored.
      Parameters:
      maxStreamPositions - Maximum number of stream positions to be cached.
      Throws:
      IllegalArgumentException - Raised if provided value is lower than DEFAULT_MAX_STREAM_POSITIONS.
      LockedException - Raised if this instance is locked because loading is in progress.

    • isReady

      public boolean isReady()
      Indicates it this loader has enough parameters to start the loading process.
      Specified by:
      isReady in class Loader
      Returns:
      True if ready, false otherwise.

    • getMeshFormat

      public MeshFormat getMeshFormat()
      Returns mesh format supported by this loader, which is PLY_MESH_FORMAT.
      Specified by:
      getMeshFormat in class Loader
      Returns:
      Format supported by this loader, which is PLY_MESH_FORMAT.

    • isValidFile

      public boolean isValidFile() throws LockedException, IOException
      Reads the header of provided file and determines whether file is valid or not.
      Specified by:
      isValidFile in class Loader
      Returns:
      True if file is a valid PLY file, false otherwise.
      Throws:
      LockedException - Raised if this instance is locked because loading is in progress.
      IOException - if an i/O error occurs.

    • load

      public LoaderIterator load() throws LockedException, NotReadyException, IOException, LoaderException
      Starts the loading process. This method reads the file header, checks its validity and prepares an iterator so the loading process can be carried in an iterative process.
      Specified by:
      load in class Loader
      Returns:
      Iterator to load the file in small chunks of data.
      Throws:
      LockedException - Raised if this instance is locked because loading is in progress.
      NotReadyException - raised if this instance is not yet ready because not enough parameters have been set.
      IOException - if an I/O error occurs.
      LoaderException - Raised if file is not a valid PLY or is corrupted.

    • internalSetMaxVerticesInChunk

      private void internalSetMaxVerticesInChunk(int maxVerticesInChunk)
      Internal method to set maximum number of vertices to keep in a chunk of data.
      Parameters:
      maxVerticesInChunk - Indicates maximum number of vertices to keep in a chunk of data.
      Throws:
      IllegalArgumentException - Raised if maximum number of vertices is smaller than MIN_MAX_VERTICES_IN_CHUNK.

    • internalSetAllowDuplicateVerticesInChunk

      private void internalSetAllowDuplicateVerticesInChunk(boolean allow)
      Internal method to set whether duplicate vertices in a chunk are allowed. By allowing duplicate vertices, PLY loading can be speed up a little bit at the expense of getting larger sets of data which will contain redundant vertices. If your environment is memory constrained, this should be disabled. By default, it is disabled.
      Parameters:
      allow - Indicates whether duplicates will be allowed or not.

    • internalSetMaxStreamPositions

      private void internalSetMaxStreamPositions(long maxStreamPositions)
      Internal method to set maximum number of stream positions to be cached. This loader keeps track of a set of stream positions that have been parsed on ASCII mode. By keeping a cache of positions loading times can be largely reduced at the expense of using more memory during loading. By default, this is set to 1000000 positions. This only has effect on ASCII PLY files. For binary PLY files this setting is ignored.
      Parameters:
      maxStreamPositions - Maximum number of stream positions to be cached.
      Throws:
      IllegalArgumentException - Raised if provided value is lower than DEFAULT_MAX_STREAM_POSITIONS.

    • readFromStream

      private void readFromStream() throws LockedException, IOException, LoaderException
      Reads header of provided file and initializes iterator to read data chunks of this file.
      Throws:
      LockedException - Raised if this instance is locked because loading is in progress.
      IOException - if an i/O error occurs.
      LoaderException - Raised if file is not a valid PLY or is corrupted

    • readHeader

      private void readHeader() throws IOException, LoaderException
      Reads the header of provided file.
      Throws:
      IOException - if an I/O error occurs.
      LoaderException - Raised if file is not a valid PLY or is corrupted.

    • wordToDataType

      private DataTypePLY wordToDataType(String word) throws LoaderException
      Converts a word into a data type. If an unsupported word is found then a LoaderException is raised.
      Parameters:
      word - word to be converted.
      Returns:
      DataType obtained from word.
      Throws:
      LoaderException - Raised if file is not a valid PLY or is corrupted (i.e. an unsupported word is found).