[FrontPage] [TitleIndex] [WordIndex

RasterTreeBuilder - Generating image pyramids from georeferenced image collections

1. General Information

First of all, please make sure to read the chapter on General Information for all deegreeTools.

2. Description

The main utility program coming with deegree WCS is the RasterTreeBuilder. It is located in org.deegree.tools.raster package and offers several configuration parameters to optimize data structure for fast access to coverage source(s)*.

The basic idea is that especially for large coverages in most cases a GetCoverage request targets just a small subset of the coverage's spatial extent with a high resolution or a large subset with a low resolution. So it will be useful to have a mechanism that avoids reading and processing data that is not required.

The deegree approach to solve this problem is similar to mechanisms used by several other software packages handling large amounts of raster data:

  1. In step of a pre-processing, the original, large data sources will first be resampled into several levels of lower resolution.
  2. After that each resolution level will be splitted into tiles each having a moderate size.

The optimal size strongly depends on the desired use of a WCS. E.g. if a WCS shall be used for online image visualization within a standard web browser a GetCoverage request hardly will use WIDTH and HEIGHT exceeding 800x800px. So an optimal size of a tile will be ~500x500px guaranteeing no more than nine tiles are needed to create the result to a GetCoverage request and in many cases even less tiles are needed.

3. Library Dependancies

4. Usage

To resample and tile one or more source images the RasterTreeBuilder application needs definition of several parameters passed via commandline options. For each phase of the program – input, processing, output – there are several parameters needed.

An image file passed to the RTB must have a world file assigned to it by having the same name but with extension *.tfw, *.wld, *.jgw, *.jpgw, *.gfw, *.gifw, *.pgw or *.pngw. GeoTIFF files are also accepted.

4.1. Input

There are three alternative ways/parameters to define which input files shall be used for creating a raster tree:












4.2. Processing











4.3. Output




4.4. Misc.

-h or -?

5. Examples

If you followed the preparations, you can use the RasterTreeBuilder with the following command:

You simply need to add the input parameters.

Otherwise you need to add the list of libraries to the classpath.

Example 1
Creating a coverage with 5 levels out of a source directory on a Windows platform

Example 2
Creating a coverage with 4 Levels out of a dBase file on LINUX platform

If you like to tile big images (like the Blue Marble Mosaic with 176 MB as PNG (24 bit color depth)), you need to do some preprocessing first in order not to exceed the 2 GB RAM Limit of Java.

6. Calculation of one Coverage – Inside the RTB

To use the parameters correctly you should understand how RTB works and how the number of resolution levels and tile size is coupled.

Imagine a source image of 4000x4000px with a spatial resolution of 1x1m per pixel. Use '-noOfLevel 3' to force the creation of three resolution levels having 1m (base level of the pyramid), 2m and 4m (peak of the pyramid) spatial resolution. For each level, one tiling step will be performed on the hightest resolution level (1m). At the first tiling step, an image is splitted into four smaller images.

In our example in a first step, the source image is splitted in tiles each having 2000x2000px size; in the second step each of this files is splitted into four tiles each 1000x1000px and in the last, third step each of this tiles is splitted again into four tiles each 500x500px size (as stated above, this is a good size for normal visualization use cases). So you will receive 4³ = 64 tiles in total for the hightest resolution level.

For the second highest resolution level the original image will be resampled to a spatial resolution of 2m (double the highest resolution). After this, two tiling steps will be performed . We will receive 4² = 16 tiles of 500x500px size for the second hightest resolution level.

To create the third level the image will be resampled again to a resolution of 4m. Just one tiling step will be performed resulting in four tiles of 500x500px size. The result is a tiled and pyramidal datastructure.

RTB will create a deegree CoverageDescription as XML document and a sub directory for each source image and resolution level within the defined output directory. Shapefiles containing the location of the tiles (used as an index) as described above will also be created.

7. Referencing the new generated converage to the wcs_configuration.xml

Once you have run the RasterTreeBuilder successfully you need to link the wcs_configuration.xml file to the coverage decription file. Within the <wcs:ContentMetadata> you need to add a new <CoverageOfferingBrief...> increasing the gml:id="ID000001" by one. Change the <name> and <lonLatEnvelope> to the one used in the coverage description. Finally set the (absolute/relativ) path to the coverage description in <deegree:Configuration>.

Afterwards restart the tomcat and the coverage should be served.

Look for other deegreeTools.

2018-04-20 12:04