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
    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 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
    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
    Returns the ith index of the band to read from the resource.
    int
    Returns the ith index of the band to read from the resource, after subsampling has been applied.
    int
    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
    Returns true if user specified all bands in increasing order.
    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.
    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:
    • 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:
    • 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:
    • 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 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 to getNumBands() 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 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 ith 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 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 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:
    • 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:

      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:
    • 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.