Package org.geotools.coverage.grid

Class GridCoverage2D

  • All Implemented Interfaces:
    Serializable, PropertySource, Coverage, GridCoverage
    Direct Known Subclasses:
    Interpolator2D
    public class GridCoverage2D
extends AbstractGridCoverage
    Basic access to grid data values backed by a two-dimensional rendered image. Each band in an image is represented as a sample dimension.

    Grid coverages are usually two-dimensional. However, their envelope may have more than two dimensions. For example, a remote sensing image may be valid only over some time range (the time of satellite pass over the observed area). Envelopes for such grid coverage can have three dimensions: the two usual ones (horizontal extent along x and y), and a third one for start time and end time (time extent along t). However, the grid range for all extra-dimension must have a size not greater than 1. In other words, a GridCoverage2D can be a slice in a 3 dimensional grid coverage. Each slice can have an arbitrary width and height (like any two-dimensional images), but only 1 voxel depth (a "voxel" is a three-dimensional pixel).

    Serialization note:
    Because it is serializable, GridCoverage2D can be included as method argument or as return type in Remote Method Invocation (RMI). However, the pixel data are not sent during serialization. Instead, the image data are transmitted "on-demand" using socket communications. This mechanism is implemented using JAI SerializableRenderedImage class. While serialization (usually on server side) should work on J2SE 1.4 and above, deserialization (usually on client side) of GridCoverage2D instances requires J2SE 1.5.

    Serialization warning:
    Deserialization of the SerializableRenderedImage class is inherently insecure which makes deserialization of GridCoverage2D instances insecure. This feature should only be used in cases where it can be guaranteed that the GridCoverage2D instances being deserialized come from trusted sources.

    Since:
    2.1
    Author:
    Martin Desruisseaux (IRD)
    See Also:
    Serialized Form

    • Field Detail

      • image

        protected final transient PlanarImage image
        The raster data.

      • gridGeometry

        protected final GridGeometry2D gridGeometry
        The grid geometry.

    • Constructor Detail

      • GridCoverage2D

        public GridCoverage2D​(CharSequence name,
                      GridCoverage2D coverage)
        Constructs a new grid coverage with the same parameter than the specified coverage. This constructor is useful when creating a coverage with identical data, but in which some method has been overridden in order to process data differently (e.g. interpolating them).
        Parameters:
        name - The name for this coverage, or null for the same than coverage.
        coverage - The source grid coverage.

      • GridCoverage2D

        protected GridCoverage2D​(CharSequence name,
                         PlanarImage image,
                         GridGeometry2D gridGeometry,
                         GridSampleDimension[] bands,
                         GridCoverage[] sources,
                         Map<?,​?> properties,
                         Hints hints)
                  throws IllegalArgumentException
        Constructs a grid coverage with the specified grid geometry and sample dimensions. The envelope (including the coordinate reference system) is inferred from the grid geometry.

        This constructor accepts an optional set of properties. Keys are String objects (CaselessStringKey are accepted as well), while values may be any Object.

        Parameters:
        name - The grid coverage name.
        image - The image.
        gridGeometry - The grid geometry (must contains an envelope with its coordinate reference system and a "grid to CRS" transform).
        bands - Sample dimensions for each image band, or null for default sample dimensions. If non-null, then this array's length must matches the number of bands in image.
        sources - The sources for this grid coverage, or null if none.
        properties - The set of properties for this coverage, or null none.
        hints - An optional set of hints, or null if none.
        Throws:
        IllegalArgumentException - If the number of bands differs from the number of sample dimensions.
        Since:
        2.5

    • Method Detail

      • getGridGeometry

        public GridGeometry2D getGridGeometry()
        Returns information for the grid coverage geometry. Grid geometry includes the valid range of grid coordinates and the georeferencing.
        Returns:
        The information for the grid coverage geometry.

      • getEnvelope

        public Bounds getEnvelope()
        Returns the bounding box for the coverage domain in coordinate reference system coordinates. The returned envelope have at least two dimensions. It may have more dimensions if the coverage has some extent in other dimensions (for example a depth, or a start and end time).
        Specified by:
        getEnvelope in interface Coverage
        Overrides:
        getEnvelope in class AbstractCoverage
        Returns:
        The bounding box for the coverage domain in coordinate system coordinates.

      • getEnvelope2D

        public ReferencedEnvelope getEnvelope2D()
        Returns the two-dimensional bounding box for the coverage domain in coordinate reference system coordinates. If the coverage envelope has more than two dimensions, only the dimensions used in the underlying rendered image are returned.
        Returns:
        The two-dimensional bounding box.

      • getCoordinateReferenceSystem2D

        public CoordinateReferenceSystem getCoordinateReferenceSystem2D()
        Returns the two-dimensional part of this grid coverage CRS. If the complete CRS is two-dimensional, then this method returns the same CRS. Otherwise it returns a CRS for the two first axis having a length greater than 1 in the grid range. Note that those axis are garanteed to appears in the same order than in the complete CRS.
        Returns:
        The two-dimensional part of the grid coverage CRS.
        See Also:
        AbstractCoverage.getCoordinateReferenceSystem()

      • getNumSampleDimensions

        public int getNumSampleDimensions()
        Returns the number of bands in the grid coverage.
        Returns:
        The number of sample dimensions in the coverage.

      • getSampleDimension

        public GridSampleDimension getSampleDimension​(int index)
        Retrieve sample dimension information for the coverage. For a grid coverage, a sample dimension is a band. The sample dimension information include such things as description, data type of the value (bit, byte, integer...), the no data values, minimum and maximum values and a color table if one is associated with the dimension. A coverage must have at least one sample dimension.
        Parameters:
        index - Index for sample dimension to retrieve. Indices are numbered 0 to (n-1).
        Returns:
        Sample dimension information for the coverage.

      • getSampleDimensions

        public GridSampleDimension[] getSampleDimensions()
        Returns all sample dimensions for this grid coverage.
        Returns:
        All sample dimensions.

      • getInterpolation

        public Interpolation getInterpolation()
        Returns the interpolation used for all evaluate(...) methods. The default implementation returns InterpolationNearest.
        Returns:
        The interpolation.

      • evaluate

        public byte[] evaluate​(Position coord,
                       byte[] dest)
                throws CannotEvaluateException
        Returns a sequence of byte values for a given location (world coordinates).
        Specified by:
        evaluate in interface Coverage
        Overrides:
        evaluate in class AbstractCoverage
        Parameters:
        coord - World coordinates of the location to evaluate.
        dest - An array in which to store values, or null.
        Returns:
        An array containing values.
        Throws:
        CannotEvaluateException - if the values can't be computed at the specified coordinate. More specifically, PointOutsideCoverageException is thrown if the evaluation failed because the input point has invalid coordinates.

      • evaluate

        public int[] evaluate​(Point2D coord,
                      int[] dest)
               throws CannotEvaluateException
        Returns a sequence of integer values for a given location (world coordinates).
        Parameters:
        coord - World coordinates of the location to evaluate.
        dest - An array in which to store values, or null.
        Returns:
        An array containing values.
        Throws:
        CannotEvaluateException - if the values can't be computed at the specified coordinate. More specifically, PointOutsideCoverageException is thrown if the evaluation failed because the input point has invalid coordinates.

      • evaluate

        public float[] evaluate​(Point2D coord,
                        float[] dest)
                 throws CannotEvaluateException
        Returns a sequence of float values for a given location (world coordinates).
        Parameters:
        coord - World coordinates of the location to evaluate.
        dest - An array in which to store values, or null.
        Returns:
        An array containing values.
        Throws:
        CannotEvaluateException - if the values can't be computed at the specified coordinate. More specifically, PointOutsideCoverageException is thrown if the evaluation failed because the input point has invalid coordinates.

      • evaluate

        public double[] evaluate​(Point2D coord,
                         double[] dest)
                  throws CannotEvaluateException
        Returns a sequence of double values for a given location (world coordinates).
        Parameters:
        coord - World coordinates of the location to evaluate.
        dest - An array in which to store values, or null.
        Returns:
        An array containing values.
        Throws:
        CannotEvaluateException - if the values can't be computed at the specified coordinate. More specifically, PointOutsideCoverageException is thrown if the evaluation failed because the input point has invalid coordinates.

      • evaluate

        public int[] evaluate​(GridCoordinates2D coord,
                      int[] dest)
        Return sample dimension (band) values as an array of integers for the given grid location. The range of valid grid coordinates can be retrieved as in this example: 
        
 GridEnvelope2D gridBounds = coverage.getGridGeometry2D().getGridRange();
        Parameters:
        coord - grid (ie. pixel) coordinates
        dest - an optionally pre-allocated array; if non-null, its length should be equal to the number of bands (sample dimensions)
        Returns:
        band values for the given grid (pixel) location
        Throws:
        PointOutsideCoverageException - if the supplied coords are outside the grid bounds

      • evaluate

        public float[] evaluate​(GridCoordinates2D coord,
                        float[] dest)
        Return sample dimension (band) values as an array of floats for the given grid location. The range of valid grid coordinates can be retrieved as in this example: 
        
 GridEnvelope2D gridBounds = coverage.getGridGeometry2D().getGridRange();
        Parameters:
        coord - grid (ie. pixel) coordinates
        dest - an optionally pre-allocated array; if non-null, its length should be equal to the number of bands (sample dimensions)
        Returns:
        band values for the given grid (pixel) location
        Throws:
        PointOutsideCoverageException - if the supplied coords are outside the grid bounds

      • evaluate

        public double[] evaluate​(GridCoordinates2D coord,
                         double[] dest)
        Return sample dimension (band) values as an array of doubles for the given grid location. The range of valid grid coordinates can be retrieved as in this example: 
        
 GridEnvelope2D gridBounds = coverage.getGridGeometry2D().getGridRange();
        Parameters:
        coord - grid (ie. pixel) coordinates
        dest - an optionally pre-allocated array; if non-null, its length should be equal to the number of bands (sample dimensions)
        Returns:
        band values for the given grid (pixel) location
        Throws:
        PointOutsideCoverageException - if the supplied coords are outside the grid bounds

      • getDebugString

        public String getDebugString​(Position coord)
        Returns a debug string for the specified coordinate. This method produces a string with pixel coordinates and pixel values for all bands (with geophysics values or category name in parenthesis). Example for a 1-banded image: 
        (1171,1566)=[196 (29.6 °C)]
        Parameters:
        coord - The coordinate point where to evaluate.
        Returns:
        A string with pixel coordinates and pixel values at the specified location, or null if coord is outside coverage.

      • getOptimalDataBlockSizes

        public int[] getOptimalDataBlockSizes()
        Returns the optimal size to use for each dimension when accessing grid values. The default implementation returns the image's tiles size.
        Returns:
        The optimal size to use for each dimension when accessing grid values, or null if none.

      • getRenderedImage

        public RenderedImage getRenderedImage()
        Returns grid data as a rendered image.
        Returns:
        The grid data as a rendered image.

      • getRenderableImage

        public RenderableImage getRenderableImage​(int xAxis,
                                          int yAxis)
        Returns 2D view of this grid coverage as a renderable image. This method allows interoperability with Java2D.
        Specified by:
        getRenderableImage in interface Coverage
        Overrides:
        getRenderableImage in class AbstractCoverage
        Parameters:
        xAxis - Dimension to use for x axis.
        yAxis - Dimension to use for y axis.
        Returns:
        A 2D view of this grid coverage as a renderable image.

      • show

        public void show​(String title,
                 int xAxis,
                 int yAxis)
        {inheritDoc}
        Overrides:
        show in class AbstractCoverage
        Parameters:
        title - The window title, or null for default value.
        xAxis - Dimension to use for the x display axis.
        yAxis - Dimension to use for the y display axis.

      • show

        public void show​(String title)
        {inheritDoc}
        Overrides:
        show in class AbstractCoverage
        Parameters:
        title - The window title, or null for default value.

      • prefetch

        public void prefetch​(Rectangle2D area)
        Hints that the given area may be needed in the near future. Some implementations may spawn a thread or threads to compute the tiles while others may ignore the hint.
        Parameters:
        area - A rectangle indicating which geographic area to prefetch. This area's coordinates must be expressed according the grid coverage's coordinate reference system, as given by AbstractCoverage.getCoordinateReferenceSystem().

      • dispose

        public boolean dispose​(boolean force)
        Provides a hint that a coverage will no longer be accessed from a reference in user space. This method disposes the image only if at least one of the following conditions is true (otherwise this method do nothing):

        • force is true, or
        • The underlying image has no sinks.

        This safety check helps to prevent the disposal of an image that still used in a JAI operation chain. It doesn't prevent the disposal in every cases however. When unsure about whatever a coverage is still in use or not, it is safer to not invoke this method and rely on the garbage collector instead.

        Overrides:
        dispose in class AbstractCoverage
        Parameters:
        force - true for forcing an inconditionnal disposal, or false for performing a conservative disposal. The recommanded value is false.
        Returns:
        true if this method disposed at least some resources, or false if this method vetoed against the disposal.
        Since:
        2.4
        See Also:
        PlanarImage.dispose()

      • toString

        public String toString()
        Returns a string representation of this grid coverage. This is mostly for debugging purpose and may change in any future version.
        Overrides:
        toString in class AbstractCoverage