Class GridCoverage

java.lang.Object
org.apache.sis.coverage.BandedCoverage
org.apache.sis.coverage.grid.GridCoverage
Direct Known Subclasses:
BufferedGridCoverage, ConcatenatedGridCoverage, DerivedGridCoverage, GridCoverage2D, TiledGridCoverage

public abstract class GridCoverage extends BandedCoverage
Base class of coverages with domains defined as a set of grid points. The essential property of coverage is to be able to generate a value for any point within its domain. Since a grid coverage is represented by a grid of values, the value returned by the coverage for a point is that of the grid value whose location is nearest the point.
Since:
1.0
Version:
1.3
  • Field Details

    • gridGeometry

      protected final GridGeometry gridGeometry
      The grid extent, coordinate reference system (CRS) and conversion from cell indices to CRS.
      See Also:
    • sampleDimensions

      private final SampleDimension[] sampleDimensions
      List of sample dimension (band) information for the grid coverage. Information include such things as description, the no data values, minimum and maximum values, etc. A coverage must have at least one sample dimension. The content of this array shall never be modified.
      See Also:
    • packedView

      private transient GridCoverage packedView
      View over this grid coverage after conversion of sample values, or null if not yet created. May be this if we determined that there is no conversion or the conversion is identity.
      See Also:
    • convertedView

      private transient GridCoverage convertedView
      View over this grid coverage after conversion of sample values, or null if not yet created. May be this if we determined that there is no conversion or the conversion is identity.
      See Also:
  • Constructor Details

    • GridCoverage

      protected GridCoverage(GridGeometry domain, List<? extends SampleDimension> ranges)
      Constructs a grid coverage using the specified grid geometry and sample dimensions. The grid geometry defines the "domain" (inputs) of the coverage function, and the sample dimensions define the "range" (output) of that function.
      Parameters:
      domain - the grid extent, CRS and conversion from cell indices to CRS.
      ranges - sample dimensions for each image band.
      Throws:
      NullPointerException - if an argument is null or if the list contains a null element.
      IllegalArgumentException - if the range list is empty.
    • GridCoverage

      GridCoverage(GridCoverage source, GridGeometry domain)
      Constructs a new grid coverage with the same sample dimensions than the given source.
      Parameters:
      source - the source from which to copy the sample dimensions.
      domain - the grid extent, CRS and conversion from cell indices to CRS.
  • Method Details

    • getCoordinateReferenceSystem

      public org.opengis.referencing.crs.CoordinateReferenceSystem getCoordinateReferenceSystem()
      Returns the coordinate reference system to which the values in grid domain are referenced. This is the target coordinate reference system of the gridToCRS math transform.

      The default implementation delegates to GridGeometry.getCoordinateReferenceSystem().

      Specified by:
      getCoordinateReferenceSystem in class BandedCoverage
      Returns:
      the "real world" CRS of this coverage.
      Throws:
      IncompleteGridGeometryException - if the grid geometry has no CRS.
    • getEnvelope

      public Optional<org.opengis.geometry.Envelope> getEnvelope()
      Returns the bounding box for the coverage domain in CRS coordinates. The envelope encompasses all cell surfaces, from the left border of leftmost cell to the right border of the rightmost cell and similarly along other axes.

      The default implementation delegates to GridGeometry.getEnvelope().

      Specified by:
      getEnvelope in class BandedCoverage
      Returns:
      the bounding box for the coverage domain in CRS coordinates.
      Since:
      1.2
    • getGridGeometry

      public GridGeometry getGridGeometry()
      Returns information about the domain of this grid coverage. Information includes the grid extent, CRS and conversion from cell indices to CRS. GridGeometry can also provide derived information like bounding box and resolution.
      Returns:
      grid extent, CRS and conversion from cell indices to CRS.
      See Also:
    • getSampleDimensions

      public List<SampleDimension> getSampleDimensions()
      Returns information about the range of this grid coverage. Information include names, sample value ranges, fill values and transfer functions for all bands in this grid coverage. The length of the returned list should be equal to the number of bands in the rendered image.
      Specified by:
      getSampleDimensions in class BandedCoverage
      Returns:
      names, value ranges, fill values and transfer functions for all bands in this grid coverage.
      See Also:
    • getRanges

      private NumberRange<?>[] getRanges()
      Returns the range of values in each sample dimension, or null if none.
    • getBandType

      DataType getBandType()
      Returns the data type identifying the primitive type used for storing sample values in each band. We assume no packed sample model (e.g. no packing of 4 byte ARGB values in a single 32-bits integer). If the sample model is packed, the value returned by this method should be as if the image has been converted to a banded sample model.
    • forConvertedValues

      public GridCoverage forConvertedValues(boolean converted)
      Returns a grid coverage that contains real values or sample values, depending if converted is true or false respectively. If there is no transfer function defined by the sample dimensions, then this method returns this. In all cases, the returned grid coverage r has the following properties:
      • The list returned by r.getSampleDimensions() is equal to the list returned by this.getSampleDimensions() with each element e replaced by e.forConvertedValues(converted).
      • The RenderedImage produced by r.render(extent) is equivalent to the image returned by this.render(extent) with all sample values converted using the transfer function if converted is true, or the inverse of transfer function if converted is false.
      The default implementation delegates to createConvertedValues(boolean) when first needed, then caches the result for future invocations.
      Parameters:
      converted - true for a coverage containing converted values, or false for a coverage containing packed values.
      Returns:
      a coverage containing converted or packed values, depending on converted argument value. May be this but never null.
      Throws:
      CannotEvaluateException - if an error occurred while conversion the values.
      See Also:
    • createConvertedValues

      protected GridCoverage createConvertedValues(boolean converted)
      Creates the grid coverage instance for the converted or packed values. This method is invoked by forConvertedValues(boolean) when first needed. Then the result returned by this method is cached for future invocations of forConvertedValues(converted).

      Subclasses can override this method for customizing the converted coverages while leverage the caching done by forConvertedValues(boolean).

      Parameters:
      converted - true for a coverage containing converted values, or false for a coverage containing packed values.
      Returns:
      a new coverage containing converted or packed values, depending on converted argument value. May be this but never null.
      Throws:
      CannotEvaluateException - if an error occurred while conversion the values.
      Since:
      1.3
    • convert

      final RenderedImage convert(RenderedImage source, DataType bandType, org.opengis.referencing.operation.MathTransform1D[] converters, ImageProcessor processor)
      Creates a new image of the given data type which will compute values using the given converters.
      Parameters:
      source - the image for which to convert sample values.
      bandType - the type of data in the bands resulting from conversion of given image.
      converters - the transfer functions to apply on each band of the source image.
      processor - the processor to use for creating the tiles of converted values.
      Returns:
      the image which compute converted values from the given source.
    • evaluator

      public GridCoverage.Evaluator evaluator()
      Creates a new function for computing or interpolating sample values at given locations. That function accepts DirectPosition in arbitrary Coordinate Reference System; conversions to grid indices are applied as needed.

      Multi-threading

      Evaluators are not thread-safe. For computing sample values concurrently, a new Evaluator instance should be created for each thread by invoking this method multiply times.
      Specified by:
      evaluator in class BandedCoverage
      Returns:
      a new function for computing or interpolating sample values.
      Since:
      1.1
    • render

      public abstract RenderedImage render(GridExtent sliceExtent)
      Returns a two-dimensional slice of grid data as a rendered image. The given sliceExtent argument specifies the coordinates of the slice in all dimensions that are not in the two-dimensional image. For example if this grid coverage has (x,y,z,t) dimensions and we want to render an image of data in the (x,y) dimensions, then the given sliceExtent shall contain the (z,t) coordinates of the desired slice. Those coordinates are specified in a grid extent where low coordinate = high coordinate in the z and t dimensions. The two dimensions of the data to be shown (x and y in our example) shall be the only dimensions having a size greater than 1 cell.

      If the sliceExtent argument is null, then the default value is getGridGeometry().getExtent(). This means that gridExtent is optional for two-dimensional grid coverages or grid coverages where all dimensions except two have a size of 1 cell. If the grid extent contains more than 2 dimensions with a size greater than one cell, then a SubspaceNotSpecifiedException is thrown.

      How to compute a slice extent from a slice point in "real world" coordinates

      The sliceExtent is specified to this method as grid indices. If the z and t values are not grid indices but are relative to some Coordinate Reference System (CRS) instead, then the slice extent can be computed as below. First, a slice point containing the z and t coordinates should be constructed as a DirectPosition in one of the following ways:
      • The slicePoint has a CRS with two dimensions less than this grid coverage CRS.
      • The slicePoint has the same CRS than this grid coverage, but the two coordinates to exclude are set to Double.NaN.
      Then:
      sliceExtent = getGridGeometry().derive().slice(slicePoint).getIntersection();
      If the slicePoint CRS is different than this grid coverage CRS (except for the number of dimensions), a coordinate transformation will be applied as needed.

      Characteristics of the returned image

      Image dimensions x and y map to the first and second dimension respectively of the two-dimensional sliceExtent subspace. The coordinates given by RenderedImage.getMinX() and getMinY() will be the image location relative to the location specified in sliceExtent low coordinates. For example, in the case of image minimum X coordinate:
      • A value of 0 means that the image left border is exactly where requested by sliceExtent.getLow(xDimension).
      • A positive value means that the returned image is shifted to the right compared to specified extent. This implies that the image has less data than requested on left side. It may happen if the specified extent is partially outside grid coverage extent.
      • A negative value means that the returned image is shifted to the left compared to specified extent. This implies that the image has more data than requested on left side. It may happen if the image is tiled, the specified sliceExtent covers many tiles, and expanding the specified extent is necessary for returning an integer amount of tiles.
      Similar discussion applies to the minimum Y coordinate. The image width and height will be the sliceExtent sizes if this method can honor exactly the request, or otherwise may be adjusted for the same reasons than x and y location discussed above.

      Implementations should return a view as much as possible, without copying sample values. GridCoverage subclasses can use the ImageRenderer class as a helper tool for that purpose. This method does not mandate any behavior regarding tiling (size of tiles, their numbering system, etc.). Some implementations may defer data loading until a tile is requested.

      Parameters:
      sliceExtent - a subspace of this grid coverage extent where all dimensions except two have a size of 1 cell. May be null if this grid coverage has only two dimensions with a size greater than 1 cell.
      Returns:
      the grid slice as a rendered image. Image location is relative to sliceExtent.
      Throws:
      org.opengis.geometry.MismatchedDimensionException - if the given extent does not have the same number of dimensions than this coverage.
      SubspaceNotSpecifiedException - if the given argument is not sufficient for reducing the grid to a two-dimensional slice.
      DisjointExtentException - if the given extent does not intersect this grid coverage.
      CannotEvaluateException - if this method cannot produce the rendered image for another reason.
    • toString

      public String toString()
      Returns a string representation of this grid coverage for debugging purpose. The returned string is implementation dependent and may change in any future version. Current implementation is equivalent to the following, where <default flags> is the same set of flags than GridGeometry.toString().
      Overrides:
      toString in class Object
      Returns:
      a string representation of this grid coverage for debugging purpose.
    • toTree

      @Debug public TreeTable toTree(Locale locale, int bitmask)
      Returns a tree representation of some elements of this grid coverage. The tree representation is for debugging purpose only and may change in any future SIS version.
      Parameters:
      locale - the locale to use for textual labels.
      bitmask - combination of GridGeometry flags.
      Returns:
      a tree representation of the specified elements.
      See Also:
    • appendDataLayout

      @Debug void appendDataLayout(TreeTable.Node root, Vocabulary vocabulary, TableColumn<CharSequence> column)
      Appends a "data layout" branch (if it exists) to the tree representation of this coverage. That branch will be inserted between "coverage domain" and "sample dimensions" branches. The default implementation does nothing.
      Parameters:
      root - root of the tree where to add a branch.
      vocabulary - localized resources for vocabulary.
      column - the single column where to write texts.