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

Class Region

java.lang.Object
org.apache.sis.internal.storage.io.Region
public final class Region extends Object
A sub-area in a n-dimensional hyper-rectangle, optionally with subsampling. The size of the hyper-rectangle is given by the size argument at construction time, where size.length is the number of dimensions and size[i] is the number of values along dimension i. For each dimension, the index ranges from 0 inclusive to size[i] exclusive.

This class assumes that the values are stored in a sequence (array or uncompressed file) where index at dimension 0 varies fastest, followed by index at dimension 1, etc.

This class has no knowledge of data size. The same Region instance can be used for reading byte and float arrays for instance.

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

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    final long
    length
    Total length of the region.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Region(long[] size, long[] regionLower, long[] regionUpper, int[] subsampling)
    Creates a new region.

  • Method Summary

    Modifier and Type
    Method
    Description
    final int
    getDimension()
    Returns the number of dimension.
    final int
    getTargetSize(int dimension)
    Returns the size after reading only the sub-region at the given subsampling in the given dimension.
    void
    setAdditionalByteOffset(int dimension, long skip)
    Sets an additional offset between values at two consecutive indices in the given dimension of the hyper-cube.
    String
    toString()
    Returns a string representation of this region for debugging purpose.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • length

      public final long length
      Total length of the region. This is the product of all values in the size argument given to the constructor.

  • Constructor Details

    • Region

      public Region(long[] size, long[] regionLower, long[] regionUpper, int[] subsampling)
      Creates a new region. It is caller's responsibility to ensure that:
      • all arrays have the same length
      • size[i] > 0 for all i
      • regionLower[i] >= 0 for all i
      • regionLower[i] < regionUpper[i] <= size[i] for all i
      • subsampling[i] > 0 for all i
      • The total length of data to read does not exceed Integer.MAX_VALUE.
      Parameters:
      size - the number of elements along each dimension.
      regionLower - indices of the first value to read or write along each dimension.
      regionUpper - indices after the last value to read or write along each dimension.
      subsampling - subsampling along each dimension. Shall be greater than zero.
      Throws:
      ArithmeticException - if the size of the region to read exceeds Integer.MAX_VALUE, or the total hyper-cube size exceeds Long.MAX_VALUE.

  • Method Details

    • setAdditionalByteOffset

      public void setAdditionalByteOffset(int dimension, long skip)
      Sets an additional offset between values at two consecutive indices in the given dimension of the hyper-cube. The strides are computed automatically at construction time, but this method can be invoked in some rare cases where those values need to be modified (example: for adapting to the layout of netCDF "unlimited" variable).
      Example: in a cube of dimension 10×10×10, the number of values between indices (0,0,1) and (0,0,2) is 100. If the values type is float, invoking setAdditionalByteOffset(1, 12) will increase this value to 103 (computed as 100 + 12/4). HyperRectangleReader will still read only the requested 100 values, but will skip 3 more values when moving from plane 1 to plane 2.
      This method is the only one in this Region class to use a count of bytes instead of a count of sample values.
      Parameters:
      dimension - dimension for which to increase the stride.
      skip - additional number of bytes to skip after we finished reading a block of data in the specified dimension.

    • getDimension

      public final int getDimension()
      Returns the number of dimension.
      Returns:
      the hyper-rectangle dimension.

    • getTargetSize

      public final int getTargetSize(int dimension)
      Returns the size after reading only the sub-region at the given subsampling in the given dimension.
      Parameters:
      dimension - the dimension for which to get the target size.
      Returns:
      expected number of elements in the given dimension.

    • toString

      public String toString()
      Returns a string representation of this region for debugging purpose.
      Overrides:
      toString in class Object
      Returns:
      a string representation of this region.