GeoTools : ImageCollection



Module Maintainer:

Daniele Romagnoli


(red star)(red star)(red star)(red star)(red star)

Email Help:


IP Review:


Allows setting up a coverage store on top of a main folder containing several datasets (which can also be organized in subfolders) such as simple images, not georeferenced maps, ...

Background info

The GridCoverageReader will allow to provide access to a main folder containing several simple images (even organized in subfolders) without CRS.
The input of the reader will be that main directory. Since that folder can contain thousands of images, there isn't any preliminar "deep check"/"scan" when initializing the reader. Moreover, files could be added/removed on that folder, even once the reader has been created.

Note that the Coverage reader will not provide any information (such as metadata, properties) about the available images and/or image's properties. The user should know in advance which image he needs to access as well as the image's extent.

Reading an image will be achieved by specifying a "path" by means of a CQL Filter (such as, as an instance PATH='subfolder1/draft3/image2.tif')
The CQL_FILTER will be useful when propagating requests from GeoServer to the reader, as already happens for the ImageMosaic plugin.

Checks on the path should be performed in order to prevent requests to move outside to the input folder.

The Coverage reader could cache image properties (width, height, URL, spi, ...) in a soft value hash map in order to know in advance (for repeated requests) the BBOX of the image, the SPI to be used in order to instantiate an ImageReader... and so on. When asked to take access to a specific image, the reader can check if the image is still available or if it has been changed. This could be achieved by taking note of the lastModified time as well as the last check time.

Development and instructions

Adding dependency to GeoServer

The module lives in unsupported at this location.
It behaves like other plugins (geotiff, arcgrid, imagemosaic, ...). Therefore, in order to add it on GeoServer, you simply needs to add the gt-imagecollectionXXX.jar into GeoServer/WEB-INF/lib.
If you need to include it in the GeoServer build (as an instance for debugging purposes with eclipse), you should add the following entry to the parent's pom, within the dependencyManagement section:


Then, edit the following poms:

  • wcs/pom.xml
  • wms/pom.xml
  • web/core/pom.xml
  • web/app/pom.xml

by adding this dependecy:


Sample usage

Configuring a new store on GeoServer

Setting up a config properties

In case you need to specify a minimal preliminar configuration before setting up a new raster store, you can add a file into the folder you will use as root for the store.
In that properties file you can configure the following parameters:


By default, the plugin will use the folder name as coverage name.

  • coverageName property allows you to specify a different one to be used to configure the coverage.
  • defaultPath can be used to specify a file to be used as reference to setup basic coverage properties (envelope, size, ...)
  • expand is a boolean which allows to specify whether to apply RGB expansion to paletted images. (DEFAULT is TRUE)
  • timeBetweenChecks is the time interval between two consecutive checks on a file. Being the imageCollection a dynamic collection (files can be modified, deleted, ...) there is a periodic check on file existence and file "last modified time" flag. This property represents the time between two checks, in seconds. (DEFAULT is 10 minutes = 600 seconds)
  • maxWidth and maxHeight allow to specify reference values which will be used to represent the maximum extent of the configured coverage. (DEFAULT is 65536 for both values)

Configure the store

In order to configure a new store on top of a folder containing an image collection, you simply needs to navigate to the GeoServer's gui "add store" page and then select the ImageCollection raster data source. Then, select the folder you want to use as root of your image Collection and continue configuring the store as a standard raster store.

Specifying WMS requests

Once you have configured your coverage, you can start sending WMS GetMap requests to access an image available on the collection.

Suppose you have configured an imageCollection store on top of a myCollection folder containing the following datasets.

+-- folder1
|   +-- folderA
|   |    \-- A.TIF
|   +-- B.TIF
|   \-- C.TIF
\-- folder2
    +-- subfolderA
    |    \-- D.TIF
    +-- subfolderB
    |    \-- E.TIF
    \-- F.TIF

In order to send a getMap request to access the E.TIF image contained on myCollection/folder2/subfolderB you simply need to append a CQL_FILTER to the getMap request, like this:

Make sure to always specify a CQL_FILTER=PATH='pathToRequestedImage' since geoserver actually has no way to send a default path to the request (This will require some hardcoding).

Finally, if your image is 1000x1000 pixels and you want to get the area of the image contained within a rectangle (x0,y0 x1,y1) (As an instance, x0=400,y0=400 x1=700,y1=700), make sur to specify a BBOX parameter where Yi are specified with negative coordinates. As instance, for the same example, you need to specify BBOX=400,-700,700,-400. Make sure to respect minX,minY,maxX,maxY syntax.

Moreover, the width and height getMap parameters allow to force the requested image area to fit into the specified size.

Module Status

Gold Star Quality Assurance Check

(red star) IP Check: Need to be achieved.
(red star) Releasable: currently in beginning stages
(red star) Quality Assurance: currently in beginning stages
(red star) Stability: No planned API changes
(red star) Supported: currently in beginning stages

IP Review

IP review is underway - known issue:

Outstanding Issues

Remember that the module maintainer is a volunteer, and if you can help test this module please jump on the developers list and help out. Patches may be attached to the above issues for review by the module maintainer.