Package org.apache.sis.coverage.grid

Class GridCoverage2D

java.lang.Object
org.apache.sis.coverage.BandedCoverage
org.apache.sis.coverage.grid.GridCoverage
org.apache.sis.coverage.grid.GridCoverage2D
public class GridCoverage2D extends GridCoverage
Basic access to grid data values backed by a two-dimensional RenderedImage. 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 SampleDimension.
Since:
1.1
Version:
1.2

  • Field Details

    • BIDIMENSIONAL

      static final int BIDIMENSIONAL
      A constant for identifying code that relying on having 2 dimensions. This is the minimal number of dimension required for this coverage.
      See Also:

    • data

      private final RenderedImage data
      The sample values stored as a RenderedImage.

    • gridToImageX

      private final long gridToImageX
      Offsets to apply for converting grid coverage coordinates to image pixel coordinates. This is RenderedImage.getMinX() − GridExtent.getLow(xDimension) for the x offset and a similar formula for the y offset.

    • gridToImageY

      private final long gridToImageY
      Offsets to apply for converting grid coverage coordinates to image pixel coordinates. This is RenderedImage.getMinX() − GridExtent.getLow(xDimension) for the x offset and a similar formula for the y offset.

    • xDimension

      private final int xDimension
      Indices of extent dimensions corresponding to image x and y coordinates. Typical values are 0 for xDimension and 1 for yDimension, but different values are allowed.

    • yDimension

      private final int yDimension
      Indices of extent dimensions corresponding to image x and y coordinates. Typical values are 0 for xDimension and 1 for yDimension, but different values are allowed.

    • gridGeometry2D

      private final AtomicReference<GridGeometry> gridGeometry2D
      The two-dimensional components of the coordinate reference system and "grid to CRS" transform. This is derived from GridCoverage.gridGeometry when first needed, retaining only the components at dimension indices xDimension and yDimension. The same AtomicReference instance may be shared with GridCoverage.convertedView and GridCoverage.packedView.
      See Also:

  • Constructor Details

    • GridCoverage2D

      private GridCoverage2D(GridCoverage2D source, List<SampleDimension> range, org.opengis.referencing.operation.MathTransform1D[] converters, boolean isConverted)
      Creates a new grid coverage for the conversion of specified source coverage.
      Parameters:
      source - the coverage containing source values.
      range - the sample dimensions to assign to the converted grid coverage.
      converters - conversion from source to converted coverage, one transform per band.
      isConverted - whether this grid coverage is for converted or packed values.

    • GridCoverage2D

      GridCoverage2D(GridCoverage source, GridGeometry domain, GridExtent extent, RenderedImage data)
      Creates a new grid coverage for the resampling of specified source coverage.
      Parameters:
      source - the coverage containing source values.
      domain - the grid extent, CRS and conversion from cell indices to CRS.
      extent - the domain.getExtent() value.
      data - the sample values as a RenderedImage, with one band for each sample dimension.

    • 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 RenderedImage, with one band for each sample dimension.
      Throws:
      IllegalGridGeometryException - if the image size is not consistent with the grid geometry.
      IllegalArgumentException - 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 GridExtent 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 IllegalGridGeometryException 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 RenderedImage, with one band for each sample dimension.
      Throws:
      IllegalGridGeometryException - if the domain does not met the above-documented conditions.
      IllegalArgumentException - if the image number of bands is not the same than the number of sample dimensions.
      ArithmeticException - if the distance between grid location and image location exceeds the long capacity.
      See Also:

  • Method Details

    • unwrapIfSameSize

      private static RenderedImage unwrapIfSameSize(RenderedImage data)
      Returns the wrapped image if the only difference is a translation, or data otherwise.

    • addExtentIfAbsent

      static GridGeometry addExtentIfAbsent(GridGeometry domain, RenderedImage data)
      If the given domain does not have a GridExtent, creates a new grid geometry with an extent computed from the given image. The new grid will start at the same location than the image and will have the same size.
      Parameters:
      domain - the domain to complete. May be null.
      data - user supplied image, or null if missing.
      Returns:
      the potentially completed domain (may be null).

    • addExtentIfAbsent

      static GridGeometry addExtentIfAbsent(GridGeometry domain, Rectangle bounds)
      If the given domain does not have a GridExtent, creates a new grid geometry with an extent computed from the given image bounds. The new grid will start at the same location than the image and will have the same size.

      This method does nothing if the given domain already has an extent; it does not verify that the extent is consistent with image size. This verification should be done by the caller.

      Parameters:
      domain - the domain to complete. May be null.
      bounds - image or raster bounds (cannot be null).
      Returns:
      the potentially completed domain (may be null).

    • createExtent

      private static GridExtent createExtent(int dimension, Rectangle bounds, org.opengis.referencing.crs.CoordinateReferenceSystem crs)
      Creates a grid extent with the low and high coordinates of the given image bounds. The coordinate reference system is used for extracting grid axis names, in particular the DimensionNameType.VERTICAL and DimensionNameType.TIME dimensions. The DimensionNameType.COLUMN and DimensionNameType.ROW dimensions can not be inferred from CRS analysis; they are added from knowledge that we have an image.
      Parameters:
      dimension - number of dimensions.
      bounds - bounds of the image for which to create a grid extent.
      crs - coordinate reference system, or null if none.

    • verifyImageSize

      private static void verifyImageSize(GridExtent extent, RenderedImage data, int[] imageAxes)
      Verifies that the domain is consistent with image size. We do not verify image location; it can be anywhere.

    • defaultIfAbsent

      static List<? extends SampleDimension> defaultIfAbsent(List<? extends SampleDimension> range, RenderedImage data, int numBands)
      If the sample dimensions are null, creates default sample dimensions with default names. The default names are "gray", "red, green, blue" or "cyan, magenta, yellow" if the color model is identified as such, or numbers if the color model is not recognized.
      Parameters:
      range - the list of sample dimensions, potentially null.
      data - the image for which to build sample dimensions, or null.
      numBands - the number of bands in the given image, or 0 if none.
      Returns:
      the given list of sample dimensions if it was non-null, or a default list otherwise.

    • verifyBandCount

      private static void verifyBandCount(List<? extends SampleDimension> range, RenderedImage data)
      Verifies that the number of bands in the image is equal to the number of sample dimensions. The number of bands is fetched from the sample model, which in theory shall never be null. However, this class has a little bit of tolerance to missing sample model. It may happen when the image is used only as a matrix storage.

    • getBandType

      final DataType getBandType()
      Returns the constant identifying the primitive type used for storing sample values.
      Overrides:
      getBandType in class GridCoverage

    • 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.
      Overrides:
      createConvertedValues in class GridCoverage
      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 GridCoverage
      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 sliceExtent argument specifies the area of interest and may be null for requesting the whole image. The coordinates given by RenderedImage.getMinX() and getMinY() will be the image location relative to the location specified in sliceExtent low coordinates (see super-class javadoc for more discussion). The image width and height will be the sliceExtent 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 GridCoverage
      Parameters:
      sliceExtent - area of interest, or null for the whole image.
      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.
      DisjointExtentException - if the given extent does not intersect this grid coverage.
      CannotEvaluateException - if this method cannot produce the rendered image for another reason.
      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.
      Overrides:
      appendDataLayout in class GridCoverage
      Parameters:
      root - root of the tree where to add a branch.
      vocabulary - localized resources for vocabulary.
      column - the single column where to write texts.