Package org.apache.sis.internal.storage
Class RangeArgument
java.lang.Object
org.apache.sis.internal.storage.RangeArgument
The user-provided
ranges
argument together with a set of convenience tools.- Since:
- 0.8
- Version:
- 1.2
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate SampleDimension.Builder
A builder for sample dimensions, created when first needed.private int
If a subsampling has been applied, indices of the first and last band to read, together with the interval (stride) between bands.final boolean
Whether the selection contains all bands of the resource, not necessarily in order.private int
If a subsampling has been applied, indices of the first and last band to read, together with the interval (stride) between bands.private int
If a subsampling has been applied, indices of the first and last band to read, together with the interval (stride) between bands.private final long[]
The range indices specified by user in high bits, together (in the low bits) with the position in theranges
array where each index was specified. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
RangeArgument
(long[] packed, boolean hasAllBands) Encapsulates the user suppliedranges
argument, packed in high bits ofpacked
. -
Method Summary
Modifier and TypeMethodDescriptionbuilder()
Returns a builder for sample dimensions.int
Returns the value of the first index specified by the user.int
Returns the number of sample dimensions.int
Returns the increment to apply on index for moving to the same band of the next pixel.int[]
Returns the indices of bands selected by the user.int
getSourceIndex
(int i) Returns the ith index of the band to read from the resource.int
getSubsampledIndex
(int i) Returns the ith index of the band to read from the resource, after subsampling has been applied.int
getTargetIndex
(int i) Returns the ith band position.insertBandDimension
(GridExtent areaOfInterest, int bandDimension) Returns the given extent with a new dimension added for the bands.int[]
insertSubsampling
(int[] subsampling, int bandDimension) Returns the given subsampling with a new dimension added for the bands.boolean
Returnstrue
if user specified all bands in increasing order.select
(ColorModel colors) Returns a color model for the bands specified by the user.select
(SampleModel model, boolean view) Returns a sample model for the bands specified by the user.select
(List<? extends SampleDimension> sourceBands) Returns sample dimensions selected by the user.static RangeArgument
Validate theranges
argument given toGridCoverageResource.read(GridGeometry, int...)
.
-
Field Details
-
packed
private final long[] packedThe range indices specified by user in high bits, together (in the low bits) with the position in theranges
array where each index was specified. This packing is used for making easier to sort this array in increasing order of user-specified range index. -
hasAllBands
public final boolean hasAllBandsWhether the selection contains all bands of the resource, not necessarily in order. -
first
private int firstIf a subsampling has been applied, indices of the first and last band to read, together with the interval (stride) between bands. Those information are computed only when theinsertFoo(…)
methods are invoked.- See Also:
-
last
private int lastIf a subsampling has been applied, indices of the first and last band to read, together with the interval (stride) between bands. Those information are computed only when theinsertFoo(…)
methods are invoked.- See Also:
-
interval
private int intervalIf a subsampling has been applied, indices of the first and last band to read, together with the interval (stride) between bands. Those information are computed only when theinsertFoo(…)
methods are invoked.- See Also:
-
builder
A builder for sample dimensions, created when first needed.
-
-
Constructor Details
-
RangeArgument
private RangeArgument(long[] packed, boolean hasAllBands) Encapsulates the user suppliedranges
argument, packed in high bits ofpacked
.
-
-
Method Details
-
validate
Validate theranges
argument given toGridCoverageResource.read(GridGeometry, int...)
. This method verifies that all indices are between 0 andnumSampleDimensions
and that there is no duplicated index.- Parameters:
numSampleDimensions
- number of sample dimensions in the resource. Equal toGridCoverageResource.getSampleDimensions().size()
.ranges
- theranges
argument given by the user. May be null or empty.listeners
- source of locale to use if an exception must be thrown.- Returns:
- the
ranges
argument encapsulated with a set of convenience tools. - Throws:
IllegalArgumentException
- if a range index is invalid.
-
isIdentity
public boolean isIdentity()Returnstrue
if user specified all bands in increasing order. This method always returnfalse
ifinsertSubsampling(int[], int)
has been invoked.- Returns:
- whether user specified all bands in increasing order without subsampling inserted.
-
getNumBands
public int getNumBands()Returns the number of sample dimensions. This is the length of theranges
array supplied by user, or the number of bands in the source coverage if theranges
array was null or empty.- Returns:
- the number of sample dimensions selected by user.
-
getSelectedBands
public int[] getSelectedBands()Returns the indices of bands selected by the user. This is a copy of theranges
argument specified by the user, in same order. Note that this is not necessarily increasing order.- Returns:
- a copy of the
ranges
argument specified by the user.
-
getFirstSpecified
public int getFirstSpecified()Returns the value of the first index specified by the user. This is not necessarily equal togetSourceIndex(0)
if the user specified the bands out of order.- Returns:
- index of the first value in the user-specified
ranges
array.
-
getSourceIndex
public int getSourceIndex(int i) Returns the ith index of the band to read from the resource. Indices are returned in strictly increasing order.- Parameters:
i
- index of the range index to get, from 0 inclusive togetNumBands()
exclusive.- Returns:
- index of the ith band to read from the resource.
-
getTargetIndex
public int getTargetIndex(int i) Returns the ith band position. This is the index in the user suppliedranges
array where thegetSourceIndex(i)
value was specified.- Parameters:
i
- index of the range index to get, from 0 inclusive togetNumBands()
exclusive.- Returns:
- index in user supplied
ranges
array where was specified thegetSourceIndex(i)
value.
-
getSubsampledIndex
public int getSubsampledIndex(int i) Returns the ith index of the band to read from the resource, after subsampling has been applied. The subsampling results from calls toinsertBandDimension(GridExtent, int)
andinsertSubsampling(int[], int)
methods. If theinsertXXX(…)
methods have never been invoked, then this method is equivalent togetSourceIndex(int)
.- Parameters:
i
- index of the range index to get, from 0 inclusive togetNumBands()
exclusive.- Returns:
- index of the ith band to read from the resource, after subsampling.
-
getPixelStride
public int getPixelStride()Returns the increment to apply on index for moving to the same band of the next pixel. If theinsertXXX(…)
methods have never been invoked, then this method returns 1.- Returns:
- the increment to apply on index for moving to the next pixel in the same band.
- See Also:
-
insertBandDimension
Returns the given extent with a new dimension added for the bands. The extent in the new dimension will range from the minimumrange
value to the maximumrange
value inclusive. This method should be used together withinsertSubsampling(int[], int)
.Use case
This method is useful for reading a n-dimensional data cube with values stored in aPixelInterleavedSampleModel
fashion (except ifbandDimension
is after all existingareaOfInterest
dimensions, in which case data become organized in aBandedSampleModel
fashion). This method converts the specified domain (decomposed inareaOfInterest
andsubsampling
parameters) into a larger domain encompassing band dimension as if it was an ordinary space or time dimension. It makes possible to use this domain withHyperRectangleReader
for example.- Parameters:
areaOfInterest
- the extent to which to add a new dimension for bands.bandDimension
- index of the band dimension.- Returns:
- a new extent with the same values than the given extent plus one dimension for bands.
-
insertSubsampling
public int[] insertSubsampling(int[] subsampling, int bandDimension) Returns the given subsampling with a new dimension added for the bands. The subsampling in the new dimension will be the greatest common divisor of the difference between all user-specified values. This method should be used together withinsertBandDimension(GridExtent, int)
. See that method for more information.Invoking this method changes the values returned by following methods:
- Parameters:
subsampling
- the subsampling to which to add a new dimension for bands.bandDimension
- index of the band dimension.- Returns:
- a new subsampling array with the same values than the given array plus one dimension for bands.
-
select
Returns sample dimensions selected by the user. This is a convenience method for situations where sample dimensions are already in memory and there is no advantage to read them in "physical" order.- Parameters:
sourceBands
- bands in the source coverage.- Returns:
- bands selected by user, in user-specified order.
-
select
Returns a sample model for the bands specified by the user. The model created by this method can be a "view" or can be "compressed":- If
view
istrue
, the sample model returned by this method will expect the sameDataBuffer
than the one expected by the originalmodel
. Bands enumerated in theranges
argument will be used and other bands will be ignored. This mode is efficient if the data are already in memory and we want to avoid copying them. An inconvenient is that all bands, including the ignored ones, are retained in memory. - If
view
isfalse
, then this method will "compress" bank indices and bit masks for making them consecutive. For example if theranges
argument specifies that the bands to read are {1, 3, 4, 6, …}, then "compressed" sample model will use bands {0, 1, 2, 3, …}. This mode is efficient if the data are not yet in memory and the reader is capable to skip the bands to ignore. In such case, this mode save memory.
- Parameters:
model
- the original sample model with all bands. Can benull
.view
- whether the band subset shall be a view over the full band set.- Returns:
- the sample model for a subset of bands, or
null
if the given sample model was null. - Throws:
RasterFormatException
- if the given sample model is not recognized.IllegalArgumentException
- if an error occurred when constructing the new sample model.- See Also:
- If
-
select
Returns a color model for the bands specified by the user.- Parameters:
colors
- the original color model with all bands. Can benull
.- Returns:
- the color model for a subset of bands, or empty if the given color model was null.
-
builder
Returns a builder for sample dimensions. This method recycles the same builder on every calls. If the builder has been returned by a previous call to this method, then it is cleared before to be returned again.- Returns:
- a recycled builder for sample dimensions.
-