Class Region
java.lang.Object
org.apache.sis.internal.storage.io.Region
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
FieldsModifier and TypeFieldDescriptionfinal long
Total length of the region.private long[]
Additional values to add toskips
, 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
ConstructorsConstructorDescriptionRegion
(long[] size, long[] regionLower, long[] regionUpper, int[] subsampling) Creates a new region. -
Method Summary
Modifier and TypeMethodDescription(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.toString()
Returns a string representation of this region for debugging purpose.
-
Field Details
-
targetSize
final int[] targetSizeThe 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 startAtPosition of the first value to read. This position is zero if the value of allregionLower
elements is zero. -
skips
private final long[] skipsNumber of values to skip after having read values.skips[0]
is the number of values to skip after each single value on the same line.skips[1]
is the number of values to skip after having read the last value in a line.skips[2]
is the number of values to skip after having read the last value in a plane.skips[3]
is the number of values to skip after having read the last value in a cube.- etc.
subsampling
argument given at construction time. The length of this array is the hyper-rectangle dimension plus one. -
skipBytes
private long[] skipBytes -
length
public final long lengthTotal length of the region. This is the product of all values in thesize
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 iregionLower[i] >= 0
for all iregionLower[i] < regionUpper[i] <= size[i]
for all isubsampling[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 exceedsInteger.MAX_VALUE
, or the total hyper-cube size exceedsLong.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 isThis method is the only one in thisfloat
, invokingsetAdditionalByteOffset(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.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 theskips
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 thelong
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
Returns a string representation of this region for debugging purpose.
-