Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


Table of Contents


Children Display


As quoted from the Javadoc, GridCoverageReader interface is intended to

The current implementation status of the GridCoveargeReader normally associates a single reader with a single coverage (e.g., TIFF, GTOPO30, and so on). The intention of this proposal is to break the 1-1 association and allow GridCoverageReader to expose multiple covearges in an efficient way, in order to properly deal with sources storing multiple coverages with different structures and features (e.g., not mosaics, which can deal with multiple coverages having some degree of uniformity).

The current GridCoverageReader interface already allows to expose multiple coverages, but in an inefficient and thread unsafe way, as it is intended to read GridCoverages from the input stream in a sequential order .Currently, there is no efficient nor thread safe way to deal with multiple coverages stored in the same file.   In order to access different coverages, once you have opened a reader, you need the reader is open, one needs to check if more coverages are available by checking hasMoreGridCoverages and then skip to the desired coverage. You can check , and get the name of the current coverage through the getCurrentSubname method.  Thus, there are two issues:

  • Need to open a new reader for each different coverage read, which is rather inefficient as normally the opening of a reader requires parsing the raster data header, or gathering network or database connections, something that is better done only once instead 
  • Need to linearly scan the contents of the reader to reach the desired coverage, with no form of random access, hampering the usage of the current API in storages that contain a large amount of coverages
The idea is to deprecate this methods in favor of methods which allow explicitly specifying the coverage to be accessed


, thus allowing random access to the various coverages and their descriptive information from a single reader instance. In order to preserve backwards compatibility the methods to get the coverage metadata will be maintained, and new methods taking the coverage name as an extra parameter will be added to allow clients selection of a specific coverage provided by the reader.
Finally, a simple observation of the code using reader will show that nowadays pretty much all code casts reader to AbstractGridCoverage2DReader in order to gain access to more meta information about coverages, in particular the grid coverage locacation and grid structure. In order to promote programming against interfaces a new GridCoverage2DReader interface will be created sporting the same common methods AbstractGridCoverage2DReader provides, along with variants that take the coverage name as a parameter.

Additional notes on base implementation changes:

Base class implementing GridCoverageReader is AbstractGridCoverage2DReader.

Currently there is 1:1 relationship between an AbstractGridCoverage2DReader instance and a coverage. Suppose you are working against a NetCDF file which contains several measurements like AirTemperature, AirPressure (with elevation and time) which are 4D datasets. We can think about 2 different coverages.

We also propose to deprecate AbstractGridCoverage2DReader in favor of a new AbstractGridCoverageReader which preserves current methods for simpler readers (which allow to access single coverages) but which allows to get geospatial context (like GridEnvelope, GridRange, GridToWorld transformation, CoordinateReferenceSystem) and read access capabilities by coverage name. Current geospatial context getter method won't be changed to grant backward compatibility.

This work will also be made to prepare The implementation of AbstractGridCoverage2DReader will be changed so that implementors of the current API won't be affected by the change, but allowing new multi-coverage readers to get full benefit from the new API

An outlook into the future

This work is meant as a stepping stone to allow a smooth transition between old style coverage APIs (based on current GridCoverageReader which doesn't have proper logic to deal with time/elevation domains) and new coverage-api currently living on unsupported/coverage-experiment, and loosely based on the DataAccess paradigm, as well as the WCS protocol, which allows for

  • proper geospatial dimensions management (time domain, vertical domain, custom domains) 1 without having to deal with lists of strings
  • a single coverageAccess to deal with multiple underlying coverage sources
The idea is that bridges will be built so that implementations using the new coverage API can be wrapped in the GridCoverage2DReader one, and that similarly old implementations can be wrapped into the new one, allowing for a period of transition between the two programming styles.


This proposal is under construction.


Code Block
/** Sample code usage */
public void testMultipleCoverageReader() {
    AbstractGridCoverageReader reader = ...; // Creating a reader
    String coverageName = "temperature"reader.listSubnames()[1]; // Specifying the coverageName to be accessed

    e..g, "temperature"

    // Getting selected coverage properties    
    final GeneralEnvelope envelope = reader.getOriginalEnvelope(coverageName);
    final GridEnvelope gridRange = reader.getOriginalGridRange(coverageName);  
    // Reading that coverage
    GridCoverage2D coverage = (GridCoverage2D), null);