Class TiledGridCoverage.AOI

Object
AOI
Direct Known Subclasses:
Tiled­Grid­Coverage​.Snapshot, Tiled­Grid­Coverage​.Tile­Iterator
Enclosing class:
Tiled­Grid­Coverage
protected abstract static class TiledGridCoverage.AOI extends Object
An Area Of Interest (AOI) describing a tile area or sub-area to read in response to a user's request. AOI can be a mutable iterator over all the tiles to read (Tiled­Grid­Coverage​.Tile­Iterator) or an immutable snapshot of the iterator position as an instant (Tiled­Grid­Coverage​.Snapshot).
Since:
1.7

  • Method Details

    • getTileCoordinatesInResource

      public final long[] getTileCoordinatesInResource()
      Returns the current AOI position in the tile matrix of the original resource. This method assumes that the upper-left corner of tile (0,0) in the resource starts at cell coordinates (0,0) of the resource.
      Returns:
      current AOI tile coordinates in original coverage resource.

    • getTileIndexInResource

      public final int getTileIndexInResource()
      Returns the current AOI position as an index in the vector of tiles of the original resource. Tiles are assumed stored in a row-major fashion. with the first tiles starting at index 0.
      Returns:
      current AOI tile index in original coverage resource.

    • getTileIndexInResultArray

      public final int getTileIndexInResultArray()
      Returns the current AOI position as an index in the array of tiles to be returned by Tiled­Grid­Coverage​.read­Tiles(…). If this AOI is an iterator, the initial position is zero and is incremented by 1 in each call to Tiled­Grid­Coverage​.Tile­Iterator​.next().
      Returns:
      current AOI tile index in the result array of tiles.
      See Also:

    • getCachedTile

      public Raster getCachedTile()
      Returns the cached tile for current AOI position. This method returns the value given in a call to the cache(Raster) during a previous iteration when the iterator was at the same position, if that raster has not yet been garbage collected.
      Returns:
      cached tile at current AOI position, or null if none.
      See Also:

    • cache

      public Raster cache(Raster tile)
      Stores the given raster in the cache for the current AOI position. If a raster is already in the cache and has the same size and equal sample model, then the given raster is ignored and the existing raster is returned on the assumption that it has the same content.
      Parameters:
      tile - the raster to cache.
      Returns:
      the cached raster. Should be the given raster instance, unless this method is invoked during two concurrent reads of the same tile.
      See Also:

    • createRaster

      public WritableRaster createRaster()
      Creates an initially empty raster for the tile at the current AOI position. The sample model is Tiled­Grid­Coverage​.model and the minimum x and y position are set to the pixel coordinates in two dimensions of the AOI.

      The raster is not filled with Tiled­Grid­Coverage​.fill­Values. Filling, if needed, should be done by the caller.

      If some resource's listeners have registered an interest for tile read events, and if these listeners have not yet been notified about the reading of the specified tile, then a Tile­Read­Event is sent to these listeners. This policy is based on the fact that this method is typically invoked before a tile is read.

      Returns:
      a newly created, initially empty raster.
      See Also:

    • moveRaster

      public Raster moveRaster(Raster tile)
      Returns the given raster relocated at the current AOI position. This method does not need to be invoked for tiles created by create­Raster(), but may need to be invoked for tiles created by a method external to this class, such as Image­Reader​.read­Tile­Raster(int, int, int). If the given raster is already at the current AOI position, then this method returns that raster directly.
      Parameters:
      tile - the raster to move at the current AOI position.
      Returns:
      the relocated raster (may be raster itself).
      See Also:

    • getTileLocation

      public Point getTileLocation()
      Creates the coordinates of the upper-left corner of the tile at the current AOI position. This is the (min­X, min­Y) values of the tile created by create­Raster().
      Returns:
      coordinates of the upper-left pixel of the tile at the current iterator position.
      See Also:

    • getUncroppedTileLocation

      public Optional<Point> getUncroppedTileLocation()
      Returns the location (relative to the cropped tile) of the upper-left corner of the uncropped tile. This value is present under the following conditions:
      • Reading an image made of a single potentially huge tile, and
      • the huge tile is cropped for avoiding to read that tile in whole.
      This value is empty for tiled images, because this class usually reads tiles fully (without cropping) on the assumption that they are reasonably small.

      This value can be added to the coordinates of a point for converting from uncropped tile coordinates to cropped tile coordinates. See get­Region­Inside­Tile(boolean) for a code snippet.

      Returns:
      the location (relative to the cropped tile) of the upper-left corner of the uncropped tile.

    • getRegionInsideTile

      public Rectangle getRegionInsideTile(boolean subsampled)
      Returns the coordinates of the pixels to read relative to the current tile's upper-left corner. The upper-left corner of the uncropped tile is assumed to have the coordinates (0,0). Therefore, the (x, y) location computed by this method is usually (0,0) and the rectangle size is usually the tile size, but those values may be different if the enclosing Tiled­Grid­Coverage contains only one (potentially large) tile. The rectangle may also be smaller when reading tiles on the last row or column of the tile matrix.

      Subsampling

      If the subsampled argument is false, then this method returns coordinates relative to the tile in the originating Tiled­Grid­Coverage­Resource, i.e. without subsampling. If subsampled is true, then this method returns coordinates relative to the raster, i.e. with subsampling.

      Conversion to raster space

      Because this rectangle is relative to the uncropped tile, the raster origin needs to be added to the rectangle location for obtaining coordinates in the raster space. Furthermore, in the special case where the region to read is made of one potentially huge tile, Tiled­Grid­Coverage may have cropped the tile. In the latter case, the rectangle location also needs to be shifted by subtracting the get­Uncropped­Tile­Location() value. Generally, the code can be as below: 
      WritableRaster tile = iterator.createRaster();
Rectangle validArea = iterator.getRegionInsideTile(true);
if (validArea != null) {
    // Conversion from relative to absolute tile's coordinates.
    validArea.translate(tile.getMinX(), tile.getMinY());

    // Conversion to coordinates to read in the underlying resource.
    Rectangle sourceArea = iterator.imageToResource(validArea, false);

    // Conversion from uncropped coordinates to cropped coordinates.
    iterator.getUncroppedTileLocation().ifPresent((p) -> sourceArea.translate(p.x, p.y));
}
      Parameters:
      subsampled - whether to return coordinates with subsampling applied.
      Returns:
      pixel to read inside the tile, or null if the region is empty.
      Throws:
      Arithmetic­Exception - if the tile coordinates overflow 32-bits integer capacity.
      See Also:

    • getRegionInsideTile

      public boolean getRegionInsideTile(long[] lower, long[] upper, long[] subsampling, boolean subsampled)
      Returns the clipped coordinates of the cells to read relative to the tile's upper-left corner. The upper-left corner of the uncropped tile is assumed to have the coordinates (0,0,0,…). Therefore, the lower bounds computed by this method are usually (0,0,0,…) and the upper bounds (before subsampling) are usually the tile size, but those values may be different if the enclosing Tiled­Grid­Coverage contains only one tile. The bounds may also be smaller when reading tiles on the last row or column of the tile matrix.

      The Tiled­Grid­Coverage subsampling is provided for convenience, but is constant for all tiles regardless the subregion to read. The same values can be obtained by Tiled­Grid­Coverage​.get­Subsampling(int).

      This method is a generalization of get­Region­Inside­Tile(boolean) to any number of dimensions. See that method for a discussion about the subsampled argument and a code snippet. The given arrays can be of any length, but that length must be the same for all arguments. If the given arrays are longer than necessary, the result is truncated to the arrays length. If the given arrays are longer than necessary, the extraneous array elements are unchanged.

      Parameters:
      lower - a pre-allocated array where to store relative coordinates of the first pixel.
      upper - a pre-allocated array where to store relative coordinates after the last pixel.
      subsampling - a pre-allocated array where to store subsampling, or null if not needed.
      subsampled - whether to return coordinates with subsampling applied.
      Returns:
      true on success, or false if the tile is empty.
      Throws:
      Array­Index­Out­Of­Bounds­Exception - if the given arrays are not of the same length.