Package org.apache.sis.internal.storage

Class RangeArgument

java.lang.Object

org.apache.sis.internal.storage.RangeArgument

public final class RangeArgument
extends Object

The user-provided ranges argument together with a set of convenience tools.

Since:

0.8

Version:

1.2

Field Summary

Fields

Modifier and Type	Field	Description
private SampleDimension.Builder	builder	A builder for sample dimensions, created when first needed.
private int	first	If a subsampling has been applied, indices of the first and last band to read, together with the interval (stride) between bands.
final boolean	hasAllBands	Whether the selection contains all bands of the resource, not necessarily in order.
private int	interval	If a subsampling has been applied, indices of the first and last band to read, together with the interval (stride) between bands.
private int	last	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[]	packed	The range indices specified by user in high bits, together (in the low bits) with the position in the ranges array where each index was specified.

Constructor Summary

Constructors

Modifier	Constructor	Description
private	RangeArgument(long[] packed, boolean hasAllBands)	Encapsulates the user supplied ranges argument, packed in high bits of packed.

Method Summary

Modifier and Type	Method	Description
SampleDimension.Builder	builder()	Returns a builder for sample dimensions.
int	getFirstSpecified()	Returns the value of the first index specified by the user.
int	getNumBands()	Returns the number of sample dimensions.
int	getPixelStride()	Returns the increment to apply on index for moving to the same band of the next pixel.
int[]	getSelectedBands()	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.
GridExtent	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	isIdentity()	Returns true if user specified all bands in increasing order.
Optional<ColorModel>	select(ColorModel colors)	Returns a color model for the bands specified by the user.
SampleModel	select(SampleModel model, boolean view)	Returns a sample model for the bands specified by the user.
SampleDimension[]	select(List<? extends SampleDimension> sourceBands)	Returns sample dimensions selected by the user.
static RangeArgument	validate(int numSampleDimensions, int[] ranges, Localized listeners)	Validate the ranges argument given to GridCoverageResource.read(GridGeometry, int...).

Methods inherited from class java.lang.Object

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

Field Details

packed

private final long[] packed

The range indices specified by user in high bits, together (in the low bits) with the position in the ranges 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 hasAllBands

Whether the selection contains all bands of the resource, not necessarily in order.

first

private int first

If 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 the insertFoo(…) methods are invoked.

See Also:

• insertBandDimension(GridExtent, int)
• insertSubsampling(int[], int)

last

private int last

If 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 the insertFoo(…) methods are invoked.

See Also:

• insertBandDimension(GridExtent, int)
• insertSubsampling(int[], int)

interval

private int interval

If 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 the insertFoo(…) methods are invoked.

See Also:

• insertBandDimension(GridExtent, int)
• insertSubsampling(int[], int)

builder

private SampleDimension.Builder builder

A builder for sample dimensions, created when first needed.

Constructor Details

RangeArgument

private RangeArgument(long[] packed,
 boolean hasAllBands)

Encapsulates the user supplied ranges argument, packed in high bits of packed.

Method Details

validate

public static RangeArgument validate(int numSampleDimensions,
 int[] ranges,
 Localized listeners)

Validate the ranges argument given to GridCoverageResource.read(GridGeometry, int...). This method verifies that all indices are between 0 and numSampleDimensions and that there is no duplicated index.

Parameters:

numSampleDimensions - number of sample dimensions in the resource. Equal to GridCoverageResource.getSampleDimensions().size().

ranges - the ranges 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()

Returns true if user specified all bands in increasing order. This method always return false if insertSubsampling(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 the ranges array supplied by user, or the number of bands in the source coverage if the ranges 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 the ranges 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 to getSourceIndex(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 i^th 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 to getNumBands() exclusive.

Returns:

index of the i^th band to read from the resource.

getTargetIndex

public int getTargetIndex(int i)

Returns the i^th band position. This is the index in the user supplied ranges array where the getSourceIndex(i) value was specified.

Parameters:

i - index of the range index to get, from 0 inclusive to getNumBands() exclusive.

Returns:

index in user supplied ranges array where was specified the getSourceIndex(i) value.

getSubsampledIndex

public int getSubsampledIndex(int i)

Returns the i^th index of the band to read from the resource, after subsampling has been applied. The subsampling results from calls to insertBandDimension(GridExtent, int) and insertSubsampling(int[], int) methods. If the insertXXX(…) methods have never been invoked, then this method is equivalent to getSourceIndex(int).

Parameters:

i - index of the range index to get, from 0 inclusive to getNumBands() exclusive.

Returns:

index of the i^th 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 the insertXXX(…) 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:

• ComponentSampleModel.getPixelStride()

insertBandDimension

public GridExtent insertBandDimension(GridExtent areaOfInterest,
 int bandDimension)

Returns the given extent with a new dimension added for the bands. The extent in the new dimension will range from the minimum range value to the maximum range value inclusive. This method should be used together with insertSubsampling(int[], int).

Use case

This method is useful for reading a n-dimensional data cube with values stored in a PixelInterleavedSampleModel fashion (except if bandDimension is after all existing areaOfInterest dimensions, in which case data become organized in a BandedSampleModel fashion). This method converts the specified domain (decomposed in areaOfInterest and subsampling 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 with HyperRectangleReader 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 with insertBandDimension(GridExtent, int). See that method for more information.

Invoking this method changes the values returned by following methods:

• isIdentity()
• getSubsampledIndex(int)
• getPixelStride()

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

public SampleDimension[] select(List<? extends SampleDimension> sourceBands)

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

public SampleModel select(SampleModel model,
 boolean view)

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 is true, the sample model returned by this method will expect the same DataBuffer than the one expected by the original model. Bands enumerated in the ranges 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 is false, then this method will "compress" bank indices and bit masks for making them consecutive. For example if the ranges 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 be null.

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:

• SampleModel.createSubsetSampleModel(int[])
• SampleModelFactory.subsetAndCompress(int[])

select

public Optional<ColorModel> select(ColorModel colors)

Returns a color model for the bands specified by the user.

Parameters:

colors - the original color model with all bands. Can be null.

Returns:

the color model for a subset of bands, or empty if the given color model was null.

builder

public SampleDimension.Builder 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.