Module org.apache.sis.feature
Package org.apache.sis.coverage.grid

Class GridCoverage2D

Object
BandedCoverage
GridCoverage
GridCoverage2D
public class GridCoverage2D extends GridCoverage
Basic access to grid data values backed by a two-dimensional Rendered­Image. While images are two-dimensional, the coverage envelope may have more dimensions. In other words the rendered image can be a two-dimensional slice in a n-dimensional space. The only restriction is that the grid extent has a size equals to 1 in all dimensions except two of them.

Example

A remote sensing image may be valid only over some time range (the temporal period of the satellite passing over observed area). Envelopes for such grid coverage can have three dimensions: the two usual ones (horizontal extent along x and y), and a third dimension for start time and end time (temporal extent along t). This "two-dimensional" grid coverage can have any number of columns along x axis and any number of rows along y axis, but only one plan along t axis. This single plan can have a lower bound (the start time) and an upper bound (the end time).

Image size and location

The image width and height must be equal to the grid extent size in the two dimensions of the slice. However, the image origin (minimal x and y values) does not need to be equal to the grid extent low values; a translation will be applied as needed.

Image bands

Each band in an image is represented as a Sample­Dimension.
Since:
1.1

  • Constructor Details

    • GridCoverage2D

      public GridCoverage2D(GridCoverage source, RenderedImage data)
      Constructs a grid coverage using the same domain and range than the given coverage, but different data. This constructor can be used when new data have been computed by an image processing operation, but each pixel of the result have the same coordinates and the same units of measurement than in the source coverage.
      Parameters:
      source - the coverage from which to copy grid geometry and sample dimensions.
      data - the sample values as a Rendered­Image, with one band for each sample dimension.
      Throws:
      Illegal­Grid­Geometry­Exception - if the image size is not consistent with the grid geometry.
      Illegal­Argument­Exception - if the image number of bands is not the same than the number of sample dimensions.
      Since:
      1.2

    • GridCoverage2D

      public GridCoverage2D(GridGeometry domain, List<? extends SampleDimension> range, RenderedImage data)
      Constructs a grid coverage using the specified domain, range and data. If the given domain does not have an extent, then a default Grid­Extent will be computed from given image. Otherwise the image width and height must be equal to the grid extent size in the two dimensions of the slice.

      The image origin (minimal x and y values) can be anywhere; it does not need to be the same as the grid extent low values. Translations will be applied automatically when needed.

      This constructor throws an Illegal­Grid­Geometry­Exception if one of the following errors is detected in the domain argument:

      • The given domain has less than two dimensions.
      • The given domain has more than two dimensions having an extent size greater than 1.
      • The extent size along x and y axes is not equal to the image width and height.
      Parameters:
      domain - the grid extent (may be absent), CRS and conversion from cell indices. If null a default grid geometry will be created with no CRS and identity conversion.
      range - sample dimensions for each image band. The size of this list must be equal to the number of bands. If null, default sample dimensions will be created with no transfer function.
      data - the sample values as a Rendered­Image, with one band for each sample dimension.
      Throws:
      Illegal­Grid­Geometry­Exception - if the domain does not met the above-documented conditions.
      Illegal­Argument­Exception - if the image number of bands is not the same than the number of sample dimensions.
      Arithmetic­Exception - if the distance between grid location and image location exceeds the long capacity.
      See Also:

  • Method Details

    • getGridGeometry2D

      public GridGeometry getGridGeometry2D()
      Returns the two-dimensional part of this grid geometry. If the complete geometry is already two-dimensional, then this method returns the same geometry. Otherwise it returns a geometry for the two first axes having a size greater than 1 in the grid envelope. Note that those axes are guaranteed to appear in the same order than in the complete geometry.
      Returns:
      the two-dimensional part of the grid geometry.
      See Also:

    • createConvertedValues

      protected GridCoverage createConvertedValues(boolean converted)
      Creates a grid coverage that contains real values or sample values, depending if converted is true or false respectively. This method is invoked by the default implementation of Grid­Coverage​.for­Converted­Values(boolean) when first needed.
      Overrides:
      create­Converted­Values in class Grid­Coverage
      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.

    • evaluator

      public GridCoverage.Evaluator evaluator()
      Creates a new function for computing or interpolating sample values at given locations.

      Multi-threading

      Evaluators are not thread-safe. For computing sample values concurrently, a new Evaluator instance should be created for each thread.
      Overrides:
      evaluator in class Grid­Coverage
      Returns:
      a new function for computing or interpolating sample values.
      Since:
      1.1

    • render

      public RenderedImage render(GridExtent sliceExtent) throws CannotEvaluateException
      Returns a grid data region as a rendered image. The slice­Extent argument specifies the area of interest and may be null for requesting the whole image. The coordinates given by Rendered­Image​.get­Min­X() and get­Min­Y() will be the image location relative to the location specified in slice­Extent low coordinates (see super-class javadoc for more discussion). The image width and height will be the slice­Extent sizes if this method can honor exactly the request, but this method is free to return a smaller or larger image if doing so reduce the amount of data to create or copy. This implementation returns a view as much as possible, without copying sample values.
      Specified by:
      render in class Grid­Coverage
      Parameters:
      slice­Extent - area of interest, or null for the whole image.
      Returns:
      the grid slice as a rendered image. Image location is relative to slice­Extent.
      Throws:
      Mismatched­Dimension­Exception - if the given extent does not have the same number of dimensions than this coverage.
      Disjoint­Extent­Exception - if the given extent does not intersect this grid coverage.
      Cannot­Evaluate­Exception - if this method cannot produce the rendered image for another reason.
      See Also: