Coverage store configuration (workspace/datasources/coverage)

Contents

Basics
Schema location
Configuration details
Tips for source data
Further workspace configuration

First ideas on the configuration concept for datasources and datastores are described in the deegree3/DatastoreConfigurationConcepts.

1. Basics

Coverage store configurations are defined independant of the application using it.
Each coverage store configuration may be used by multiple deegree 3 applications.
Each coverage store configuration has its own configuration file.
Each configuration file contains exactly one coverage store configuration.
Coverage store configuration files are located in the datasources/coverage/ directory of the deegree workspace. See the workspace directory layout for details.
The name of the configuration file (without the file ending) determins the identifier for this coverage store configuration.
Configuration files need to refer to a specific schema version.

2. Schema location

The schemas for defining deegree 3 coverage store datasources may be found at http://schemas.deegree.org/datasource/coverage/. Each kind of coverage store has its own schema definition. It is mandatory to refer to a specific version of the schemas, as the schema may change over time.

3. Configuration details

Current Version raster: 3.0.0
Current Version pyramid: 3.1.0

For raster data there are three different possible configurations. One is for <Raster> and one is for <MultiResolutionRaster>. The third possibility is for <Pyramid>. If you are not sure which one to use, you probably want the <Raster> configuration.
A <MultiResolutionRaster> wraps single raster elements and adds a resolution for each raster. This means, depending on the resolution of the map a different raster source is used.
A <Pyramid> is used for deegree's support for raster pyramids. For this, it is required that the raster pyramid must be a GeoTIFF, containing the extent and coordinate system of the data. Overlays must be multiples of 2.

3.1. Raster

Attributes

configVersion

mandatory

needs to match the version of the referenced schema.

originLocation

optional

default value: center

possible values: center, outer.

center = ?
outer = ?

readWorldFiles

optional

default value: true

possible values: true, false.

true = world files will be read.
false = world files will be ignored.

nodata

optional

no default value

possible values: the decimal number reflecting missing values.

Elements and their attributes
(elements marked with "choice": one of these elements may be provided.)

StorageCRS

optional, but recommended

EPSG code (e.g. "EPSG:31466") of the raster data

RasterFile

choice

relative path to a single raster file

RasterDirectory

choice

relative path to a directory of raster files

attribute: recursive.

possible values: true, false.
true = raster files in subdirectories will be read as well.
false = raster files in subdirectories will be ignored.

url

choice

a full URL to the raster file

3.1.1. RasterFile example

<Raster xmlns="http://www.deegree.org/datasource/coverage/raster" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.deegree.org/datasource/coverage/raster http://schemas.deegree.org/datasource/coverage/raster/3.0.0/raster.xsd" configVersion="3.0.0" originLocation="outer">
    <StorageCRS>EPSG:26912</StorageCRS>
    <RasterFile>../../../data/utah/raster/dem.tiff</RasterFile>
</Raster>

3.1.2. RasterDirectory example

<Raster xmlns="http://www.deegree.org/datasource/coverage/raster" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.deegree.org/datasource/coverage/raster http://schemas.deegree.org/datasource/coverage/raster/3.0.0/raster.xsd" configVersion="3.0.0" originLocation="outer">
    <StorageCRS>EPSG:26912</StorageCRS>
    <RasterDirectory>../../../data/utah/raster/Satellite_Provo/</RasterDirectory>
</Raster>

3.2. MultiResolutionRaster

Attributes

configVersion

mandatory

needs to match the version of the referenced schema.

originLocation

optional

default value: center

possible values: center, outer.

center = ?
outer = ?

readWorldFiles

optional

default value: true

possible values: true, false.

true = world files will be read.
false = world files will be ignored.

nodata

optional

no default value

possible values: the decimal number reflecting missing values.

Elements and their attributes

StorageCRS

optional, but recommended

EPSG code (e.g. "EPSG:31466") of the raster data

Resolution

mandatory, unbounded

element: Raster

see Raster description above
additional attribute: res
- possible values: decimal value of the resolution for this Raster element

3.2.1. MultiResolutionRaster example

<MultiResolutionRaster xmlns="http://www.deegree.org/datasource/coverage/raster" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.deegree.org/datasource/coverage/raster http://schemas.deegree.org/datasource/coverage/raster/3.0.0/raster.xsd" configVersion="3.0.0" originLocation="outer">
    <StorageCRS>EPSG:26912</StorageCRS>
    <Resolution>
      <Raster configVersion="3.0.0" originLocation="outer" res="1.0">
        <StorageCRS>EPSG:26912</StorageCRS>
        <RasterFile>../../../data/utah/raster/dem.tiff</RasterFile>
      </Raster>
    </Resolution>
    <Resolution>
      <Raster configVersion="3.0.0" res="2.0">
        <StorageCRS>EPSG:26912</StorageCRS>
        <RasterDirectory>../../../data/utah/raster/Satellite_Provo/</RasterDirectory>
      </Raster>
    </Resolution>
</MultiResolutionRaster>

3.3. Raster Pyramids (since 3.1)

Attributes

configVersion
: mandatory
: needs to match the version of the referenced schema.

Elements and their attributes

PyramidFile
: mandatory
: path to the GeoTiff file.
CRS
: optional
: overrides the CRS in the geotiff

3.3.1. Raster Pyramid example

deegree GeoTIFF RasterPyramid has the following prerequisit regarding image file:

must:

GeoTIFF as BIGTIFF
RGB + Alpha
CRS info must be contained
tiled

should:

overview where each overview must consists of 1/2 resolution

<Pyramid xmlns="http://www.deegree.org/datasource/coverage/pyramid" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.deegree.org/datasource/coverage/pyramid http://schemas.deegree.org/datasource/coverage/raster/3.1.0/pyramid.xsd" configVersion="3.1.0">
      <PyramidFile>data/example.tif</PyramidFile>
      <CRS>EPSG:4326</CRS>
</Pyramid>

3.4. JVM Parameter in case of memory cache size limit

You may need to set an JAVA_OPT system property to limit the maximum disk cache size.

Property declaration with example size of 1 GB:

-Ddeegree.raster.cache.disksize=1024m

4. Tips for source data

Here are some quick tip´s for using GDAL to preprocess source data to be used with deegree RasterPyramid. All GDAL utilities are listed here.

Installers can for example be found with FWTools for Windows and Linux. After downloading and installing, you can find FWTools entries to launch an FWTools Shell and OpenEV under an FWTools program group in the Start->All Programs menu. Alternatively or OSGeo4W will contain GDAL for Windows. The following description is based on FWTools.

The OpenEV entry launch the OpenEV application.
The FWTools shell launchs a DOS shell (cmd.exe) with the environment pre-initialized to use all the FWTools commands. Please run setfw.bat in the FWTools install directory to setup the environment appropriately.

4.1. gdal_info

Lists information about a raster dataset. detailed info´s
Please check the following things:

Please check before processing:

is the CRS defined (if not, you must define it either in the next step (e.g. in case only one file is to be processed) or in the end in case source file are noumerous as arial image directories )
are there 3 (rgb) or 4 (rgb +alpha) bands or is there only 1 band with a color table (then you have to translate it to 3 or 4 bands in the next step)

gdalinfo datasetname

4.2. gdal_translate

Can be used to convert raster data between different formats or to perform operations like subsettings, resampling, rescaling pixels, ... in the process. detailed info´s.

deegree RasterPyramid requires rgb files and CRS information in EPSG notion. If your data only lacks CRS declaration you can also add it with gdal_translate after your created your final single bigTIFF.

- expand {gray|rgb|rgba}: expose a dataset with 1 band with a color table as a dataset with 3 (RGB) or 4 (RGBA) bands. The 'gray' value enables to expand a dataset with a color table that only contains gray levels to a gray indexed dataset.

-a_srs {srs_def:}: override/set the projection for the output file. The srs_def may be any of the usual GDAL/OGR forms, complete WKT, PROJ.4, EPSG:n or a file containing the WKT.

gdal_translate [-...] input-file output-file

gdal_translate -a_srs EPSG:12345 -expand rgb input.tif output.tif

4.3. gdal_buildvrt

Builds a VRT (Virtual Dataset) from a list of datasets. detailed info´s

- resolution {highest|lowest|average|user}: enables the user to control the way the output resolution is computed. average is the default. user is new in GDAL 1.7.0 and must be used in combination with the -tr option to specify the target resolution.

- tr xres yres: set target resolution. The values must be expressed in georeferenced units. Both must be positive values.

- addalpha: Adds an alpha mask band to the VRT when the source raster have none. The alpha band is filled on-the-fly with the value 0 in areas without any source raster, and with value 255 in areas with source raster. RGBA viewer will render the areas without source rasters as transparent and areas with source rasters as opaque.

gdalbuiltvrt [-...] [-...] output-file input-files

gdalbuildvrt -addalpha -resolution highest combined.vrt *.tif

4.4. gdal_warp

Image mosaicing, reprojection and warping utility. detailed info´s

- co: {NAME=VALUE} all Options for GeoTiff you can find here

- dstalpha: Create an output alpha band to identify nodata (unset/transparent) pixels.
!!!THIS OPTION IS NOT COMPATIBLE WITH gdal_buildvrt -addalpha !!!

gdalwarp [-...] [-...] input-file output-file

gdalwarp -co TILED=YES -co BIGTIFF=YES -co COMPRESS=DEFLATE combined.vrt merged.tif

4.5. gdal_addo

Build or rebuild overview images for most supported file formats with one over several downsampling algorithms. You can choose different resampling algorithms for the overview levels. If the file has existing overview levels at a level selected, those levels will be recomputed and rewritten in place. detailed info´s

-r {nearest,average,gauss,cubic,average_mp,average_magphase,mode}: resampling algorithm

The Example create overviews, embedded in the supplied TIFF file.

gdaladdo [-...] filename levels

gdaladdo -r gauss merged.tif 2 4 8 16 32 64 128 256 512

5. Further workspace configuration

For other parts of the workspace configuration please consult the following pages:

CategoryDeegree3 CategoryWorkspaceConfiguration