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
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    final long
    Total length of the region.
    private long[]
    Additional values to add to skips, but in bytes instead of as a number of values.
    private final long[]
    Number of values to skip after having read values.
    (package private) final long
    Position of the first value to read.
    (package private) final int[]
    The size after reading only the sub-region at the given subsampling.
  • 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
    (package private) final int
    Number of dimensions for which we can collapse the read operations in a single operation because their data are contiguous.
    final int
    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.
    (package private) final long
    offset(long sampleSize)
    Returns the offset in bytes where reading should start.
    void
    setAdditionalByteOffset(int dimension, long skip)
    Sets an additional offset between values at two consecutive indices in the given dimension of the hyper-cube.
    (package private) final long
    stride(int dimension, int base, int sampleSize)
    Computes stride in number of bytes for the given dimension.
    (package private) final int
    targetLength(int dimension)
    Returns the total number of values to be read from the sub-region while applying the subsampling.
    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

    • targetSize

      final int[] targetSize
      The size after reading only the sub-region at the given subsampling. The length of this array is the hyper-rectangle dimension.
      See Also:
    • startAt

      final long startAt
      Position of the first value to read. This position is zero if the value of all regionLower elements is zero.
    • skips

      private final long[] skips
      Number of values to skip after having read values.
      1. skips[0] is the number of values to skip after each single value on the same line.
      2. skips[1] is the number of values to skip after having read the last value in a line.
      3. skips[2] is the number of values to skip after having read the last value in a plane.
      4. skips[3] is the number of values to skip after having read the last value in a cube.
      5. etc.
      Values are determined by the subsampling argument given at construction time. The length of this array is the hyper-rectangle dimension plus one.
    • skipBytes

      private long[] skipBytes
      Additional values to add to skips, but in bytes instead of as a number of values. This is the only field in this Region class to be expressed in byte units. This offset is rarely provided.
    • 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.
    • contiguousDataDimension

      final int contiguousDataDimension()
      Number of dimensions for which we can collapse the read operations in a single operation because their data are contiguous. This is the index of the first non-zero element in the skips array.
    • offset

      final long offset(long sampleSize)
      Returns the offset in bytes where reading should start. Offset is relative to the first sample value of the hyper-cube.
      Parameters:
      sampleSize - size of sample values, in bytes.
      Returns:
      offset in bytes relative to the first sample value.
    • stride

      final long stride(int dimension, int base, int sampleSize)
      Computes stride in number of bytes for the given dimension. Caller must provide a base stride value, which is the stride that we would have in absence of subregion and additional bytes to skip. This method adds to that given base the number of bytes to skip.
      Parameters:
      dimension - the dimension for which to compute the stride.
      base - stride that we would have in absence of subregion and bytes to skip.
      sampleSize - size of sample values, in bytes.
      Returns:
      stride in bytes.
      Throws:
      ArithmeticException - if the number of bytes exceed the long capacity.
    • targetLength

      final int targetLength(int dimension)
      Returns the total number of values to be read from the sub-region while applying the subsampling. This method takes in account only the given number of dimensions.
    • 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.