Package org.apache.sis.internal.storage.io

Class HyperRectangleReader

java.lang.Object
org.apache.sis.internal.storage.io.HyperRectangleReader
public class HyperRectangleReader extends Object
Helper methods for reading a rectangular area, a cube or a hyper-cube from a channel. The data can be stored in an existing array, or a new array can be created. This class does not handle compression; it is rather designed for efficient reading of uncompressed data. It tries to read the largest possible contiguous blocks of data with single ReadableByteChannel.read(ByteBuffer) and ByteBuffer.get(byte[], int, int) method calls.

This reader supports subsampling in any dimension. However, subsampling in the first dimension (the one with fastest varying index) is generally not efficient because it forces a large amount of seek operations. This class makes no special case for making that specific subsampling faster. It is generally not worth because subsampling in the first dimension is a special case anyway. It is the "dimension" of bands in an image using the pixel interleaved sample model, so the caller often needs to process subsampling in the first dimension in a different way than other dimensions anyway.

Since:
0.7
Version:
1.2
Author:
Johann Sorel (Geomatys), Martin Desruisseaux (Geomatys)

  • Constructor Details

    • HyperRectangleReader

      public HyperRectangleReader(byte dataType, ChannelDataInput input) throws DataStoreContentException
      Creates a new reader for the given input.
      Parameters:
      dataType - the type of elements to read, as one of the constants defined in Numbers.
      input - the channel from which to read the values, together with a buffer for transferring data.
      Throws:
      DataStoreContentException - if the given dataType is not one of the supported values.

    • HyperRectangleReader

      public HyperRectangleReader(String filename, Buffer data) throws IOException
      Creates a new reader for the data in an existing buffer. The data will be read from the current buffer position to the buffer limit.
      Parameters:
      filename - a data source name, for error messages or debugging purpose.
      data - a buffer containing the data to read.
      Throws:
      IOException - should never happen.

  • Method Details

    • filename

      public final String filename()
      Returns a file identifier for error messages or debugging purpose.
      Returns:
      the file identifier.

    • sampleSize

      public final int sampleSize()
      Returns the number of bytes in each value to be read.
      Returns:
      number of bytes per value.

    • getOrigin

      public final long getOrigin()
      Returns the input position of the first sample (ignoring sub-area and subsampling). Default value is 0.
      Returns:
      the input position of the first sample (ignoring sub-area and subsampling).

    • setOrigin

      public final void setOrigin(long p)
      Sets the input position of the first sample (ignoring sub-area and subsampling).
      Parameters:
      p - the new input position of the first sample (ignoring sub-area and subsampling).

    • read

      public final Object read(Region region) throws IOException
      Reads data in the given region. It is caller's responsibility to ensure that the Region object has been created with a size argument equals to this hyper-rectangle size.
      Parameters:
      region - the sub-area to read and the subsampling to use.
      Returns:
      the data in an array of primitive type.
      Throws:
      IOException - if an error occurred while transferring data from the channel.
      ArithmeticException - if the region to read is too large or too far from origin.

    • readAsBuffer

      public final Buffer readAsBuffer(Region region, int capacity) throws IOException
      Reads data in the given region as a buffer. This method performs the same work than read(Region) except that the array is wrapped in a heap buffer. The capacity argument is the minimal length of the array to allocate. The actual length of data read will be the limit of the returned buffer.
      Parameters:
      region - the sub-area to read and the subsampling to use.
      capacity - minimal length of the array to allocate, or 0 for automatic.
      Returns:
      the data in a buffer backed by an array on the heap.
      Throws:
      IOException - if an error occurred while transferring data from the channel.
      ArithmeticException - if the region to read is too large or too far from origin.