GeoTools : Using Grid Coverage

may want to wait until geoapi interfaces are implemented before adding code examples here. Describing the concepts can start now


The essential property of coverage is to be able to generate a value for any point within its domain. How coverage is represented internally is not a concern. For example consider the following different internal representations of coverage:
1. A coverage may be represented by a set of polygons which exhaustively tile a plane (that is each point on the plane falls in precisely one polygon). The value returned by the coverage for a point is the value of an attribute of the polygon that contains the point.
2. A coverage may be 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.
3. Coverage may be represented by a mathematical function. The value returned by the coverage for a point is just the return value of the function when supplied the coordinates of the point as arguments.
4. Coverage may be represented by combination of these. For example, coverage may be represented by a combination of mathematical functions valid over a set of polynomials.


This interface would represent the basic implementation which provides access to grid coverage data. A GridCoverage implementation may provide the ability to update grid values.


In Geotools, a GridCoverage2D is a grid coverage backed by a J2SE RenderedImage. A rendered image is handled as a matrix of values. However, it raises some issues:

  • Images in floating point formats are very useful for computations, but usually slow to display and not accepted by many image writer plug-ins.
  • Images with integer pixels are much faster to display (usually hardward accelerated) and supported by most image writer plug-ins, but inconvenient for computations purpose.

It is hard to have the advantages of both worlds in same time. Geotools manages two versions of the same image: a floating point version for computations, and an integer versions for display and saving in PNG, JPEG, etc. formats. It sound like a waste of memory, but actually not that much. Remember that Java Advanced Imaging (JAI) images are tiled and the default JAI's TileCache is limited to 16Mb. If the real data are floating points, the integer versions will be computed only for the requested tiles, and conversely.

If we have to live with two versions of the same data (floating point and integer values), Geotools tries to make the switch between those two versions as easy as possible. This is GridCoverage2D.geophysics(boolean) jobs.

  • geophysics(true) returns the floating point version, useful for computation. Note that this version often uses a custom ColorSpace, otherwise the image can't be display as-is (Geotools tries to supports display of floating point images even if their integer counterparts are more suitable for this task).
  • geophysics(false) returns the integer image, useful for fast display and saving to disk. Note that this image uses a standard J2SE ColorSpace, so it should work with most ImageWriter plug-ins.

However, geophysics(boolean) will work only if the user teach it how to convert between floating point and integer values. This is usually done with a linear conversion of the form value * scale + offset. In the "OpenGIS GridCoverage Implementation specification 1.0", this linear relationship was specified through getScale() and getOffset() attributes in the SampleDimension interface. In Geotools implementation, we generalized it to an arbitrary MathTransform1D, in order to support logarithmic conversions like the one used in remote sensing images of oceanographic chlorophylle-a concentrations.

An other difference between OpenGIS specification and Geotools implementation is that Geotools allows specifying scale and offset attributes at a finer grain than OpenGIS. The OpenGIS specification put scale and offset attributes in the SampleDimension interface (as explained in previous paragraph). Geotools put them in one or more Category, which are included in each SampleDimension.

User can specifies scale and offset attributes explicitly (which I recommand if you want an uniform look for all images of the same type, for example all Sea Surface Temperature (SST) images), or user can computes it dynamically. Below is an example of dynamic computation:

Category values = new Category("values", 
                      new Color[] {Color.BLUE, Color.GREEN, Color.RED}, 
                      new NumberRange(1, 255), 
                      new NumberRange(arcGridRaster.getMinValue(), 
Category nan = new Category("nodata", Color.BLACK, 0); 

The first category ("values") means that floating point (geophysics) values range from arcGridRaster.getMinValue() to arcGridRaster.getMaxValue(), and the user allocates them integer values 1 to 255 inclusive. The linear relationship from the integer values to the floating point values (i.e. the above-cited scale and offset attributes) will be computed automatically.

The second category ("nodata") means that the user allocates one slot for "nodata" (user could have many slots if he wants, for example a different slot for data masked by clouds), and this slots will have the integer value 0. Geotools will automatically maps this integer value to NaN in the floating point image.

Note: if the user specifies integer values in a range not greater than 0-255, Geotools will uses a 8-bits IndexColorModel for the integer version of RenderedImage. Otherwise, if the integer values are in a range not greater than 0-65535, then Geotools will uses a 16-bits IndexColorModel.

Grid coverage processing

Cool things like raster filters, resampling and reprojection. See

Coverage Exchange

Support for creation of grid coverages from persistent formats as well as exporting a grid coverage to a persistent formats. For example, it allows for creation of grid coverages from the GeoTIFF Well-known Binary format and exporting to the GeoTIFF file format. Basic implementations only require creation of grid coverages from a file format or resource. The interface given in figure 4 has a discovery mechanism to query the available file formats supported.

See Using Grid Coverage Exchange for more information.