19. GDAL components

The GDAL library (http://www.gdal.org/) provides very comprehensive support for all kinds of geospatial raster formats. Any of these raster formats can be used to create Map layers for a deegree workspace by using either the GDAL Layer or the GDAL Tile Store.

Hint

If there are alternative options for plugging your raster files into the deegree workspace (e.g. by using the GeoTIFFTileStore for GeoTIFF files), you may want to consider them first. As the GDAL library is not written in Java, it is required to install and connect additional (non-deegree) components in order to use it. Additionally, some technical considerations about GDAL dataset pooling and GDAL memory settings may be necessary to achieve optimal performance.

19.1. Connecting GDAL and deegree

Before you can set up GDAL-based resources, the native GDAL library has to be installed correctly and must be accessible by your deegree webservices installation. Please see http://www.gdal.org/ for general GDAL installation instructions.

Note

Currently, GDAL library version 1.10.1 is supported. Other versions may work as well, but have not been tested.

In order to verify that deegree webservices can use the GDAL library, check the log file of the web container (e.g. catalina.out for Tomcat). If you didn’t configure a GDAL settings file in your workspace yet, you should be able to locate the following lines upon workspace startup:

[13:06:40]  INFO: [GdalSettings] --------------------------------------------------------------------------------
[13:06:40]  INFO: [GdalSettings] GDAL JNI adapter.
[13:06:40]  INFO: [GdalSettings] --------------------------------------------------------------------------------
[13:06:40]  INFO: [GdalSettings] No gdal.xml in workspace. Not initializing GDAL JNI adapter.

If a valid GDAL settings file is present in the active deegree workspace, the corresponding lines should look similar to this:

[13:16:54]  INFO: [GdalSettings] --------------------------------------------------------------------------------
[13:16:54]  INFO: [GdalSettings] GDAL JNI adapter.
[13:16:54]  INFO: [GdalSettings] --------------------------------------------------------------------------------
[13:16:54]  INFO: [GdalSettings] Using 'gdal.xml' from workspace for GDAL settings.
[13:16:54]  INFO: [GdalSettings] Max number of open GDAL datasets: 5
[13:16:54]  INFO: [GdalSettings] GDAL initialized successfully.

In case a the GDAL settings file is present, but the GDAL library cannot be accessed, you will see something like the following:

[13:11:08]  INFO: [GdalSettings] --------------------------------------------------------------------------------
[13:11:08]  INFO: [GdalSettings] GDAL JNI adapter.
[13:11:08]  INFO: [GdalSettings] --------------------------------------------------------------------------------
[13:11:08]  INFO: [GdalSettings] Using 'gdal.xml' from workspace for GDAL settings.
Native library load failed.
java.lang.UnsatisfiedLinkError: no gdaljni in java.library.path
[13:11:08] ERROR: [JsfUtils] Workspace startup failed: org.gdal.gdal.gdalJNI.AllRegister()V(class java.lang.UnsatisfiedLinkError)
java.lang.UnsatisfiedLinkError: org.gdal.gdal.gdalJNI.AllRegister()V
  at org.gdal.gdal.gdalJNI.AllRegister(Native Method)
  at org.gdal.gdal.gdal.AllRegister(gdal.java:499)
  at org.deegree.commons.gdal.GdalSettings.registerOnceQuietly(GdalSettings.java:113)
  at org.deegree.commons.gdal.GdalSettings.registerGdal(GdalSettings.java:97)
  at org.deegree.commons.gdal.GdalSettings.init(GdalSettings.java:92)
  [...]

In this case, ensure that the GDAL library is installed on your system and available via the dynamic library path used by the Java VM. You may need to adapt environment variables (e.g. LD_LIBRARY_PATH on Linux) to achieve this.

19.2. GDAL settings

The GDAL settings file gdal.xml belongs in the main directory of the deegree workspace.

19.2.1. Minimal GDAL settings example

The only mandatory element is OpenDatasets. A minimal valid configuration example looks like this:

GDAL settings (minimal example)

<GDALSettings configVersion="3.4.0"
  xmlns="http://www.deegree.org/gdal" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.deegree.org/gdal http://schemas.deegree.org/commons/gdal/3.4.0/gdal.xsd">
  <OpenDatasets>5</OpenDatasets>
</GDALSettings>

This configuration will register the GDAL JNI adapter and will allow a maximum of five GDAL datasets to be kept open for simultaneous access.

19.2.2. More complex GDAL settings example

GDAL settings (more complex example)

<GDALSettings configVersion="3.4.0"
  xmlns="http://www.deegree.org/gdal" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.deegree.org/gdal http://schemas.deegree.org/commons/gdal/3.4.0/gdal.xsd" />
  <OpenDatasets>10</OpenDatasets>
  <GDALOption name="GDAL_CACHEMAX">1000</GDALOption>
  <GDALOption name="ECW_CACHE_MAXMEM">419430400</GDALOption>
</GDALSettings>

This configuration will register the GDAL JNI adapter with the following settings:

  • A maximum of ten GDAL datasets will be kept open for simultaneous access
  • GDAL option GDAL_CACHEMAX is set to 1000
  • GDAL option ECW_CACHE_MAXMEM is set to 419430400

Hint

A list of general GDAL parameters is available at http://trac.osgeo.org/gdal/wiki/ConfigOptions. Some parameters (such as ECW_CACHE_MAXMEM) are format specific and outlined on the respective pages in the GDAL documentation.

19.2.3. Configuration options

The configuration format for the GDAL settings file is defined by schema file http://schemas.deegree.org/commons/gdal/3.4.0/gdal.xsd. The following table lists the two available configuration options. When specifiying them, their order must be respected.

Option Cardinality Value Description
OpenDatasets 1..1 Integer Number of open datasets / simultaneous file accesses
GDALOption 0..n String Name / value of parameter to pass on to the GDAL library

19.3. GDAL Layer

A GDAL Layer is a map layer that is backed by one or more raster files. The native GDAL library is used to determine some metadata (e.g. bounding box) and to access the actual raster data.

Hint

You may want to refer to the Map layers chapter for general information on using and defining layer resources.

19.3.1. Configuration example

The only custom element in a GDAL Layer definition is File. A valid example looks like this:

GDAL Layers (example)

<GDALLayers configVersion="3.4.0"
  xmlns="http://www.deegree.org/layers/gdal" xmlns:d="http://www.deegree.org/metadata/description"
  xmlns:l="http://www.deegree.org/layers/base" xmlns:s="http://www.deegree.org/metadata/spatial">
  <GDALLayer>
    <l:Name>luchtfoto_2010</l:Name>
    <d:Title>Orthophoto layer served from an ECW file</d:Title>
    <s:CRS>EPSG:28992 EPSG:25831</s:CRS>
    <l:ScaleDenominators min="0" max="10000" />
    <File>/geodata/ecw/2010/Luchtfoto2010_25cm.ecw</File>
  </GDALLayer>
</GDALLayers>

This configuration will create a single layer resource with the following settings:

  • The file defines a single layer only
  • Name of the layer is luchtfoto_2010
  • Layer is offered in coordinate reference systems EPSG:28992 and EPSG:25831
  • File /geodata/ecw/2010/Luchtfoto2010_25cm.ecw will be accessed via GDAL to retrieve metadata and raster data

19.4. GDAL Tile Store

A GDAL tile store defines one or more tile data sets. Each of these tile data sets is based on a single raster file which is accessed using the native GDAL library.

Hint

You may want to refer to the Tile stores chapter for general information on using and defining tile store resources.

19.4.1. Minimal configuration example

A minimal valid configuration example looks like this:

GDAL Tile Store: Minimal configuration

<GDALTileStore configVersion="3.4.0"
  xmlns="http://www.deegree.org/datasource/tile/gdal" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.deegree.org/datasource/tile/gdal http://schemas.deegree.org/datasource/tile/gdal/3.4.0/gdal.xsd">
  <TileDataSet>
    <TileMatrixSetId>utah</TileMatrixSetId>
    <File>../../data/test.tif</File>
  </TileDataSet>
</GDALTileStore>

This configuration will create a GDAL tile store resource with the following settings:

  • Tile store defines a single tile data set
  • Name of the tile data set is test (derived from file name)
  • Tile matrix set is utah
  • File ../../data/test.tif will be accessed via GDAL to retrieve the raster data
  • Output tile format is not set, defaults to image/png

19.4.2. More complex configuration example

A more complex example that uses all available configuration options:

GDAL Tile Store: More complex configuration

<GDALTileStore configVersion="3.4.0"
  xmlns="http://www.deegree.org/datasource/tile/gdal" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.deegree.org/datasource/tile/gdal http://schemas.deegree.org/datasource/tile/gdal/3.4.0/gdal.xsd">  
  <TileDataSet>
    <Identifier>2010</Identifier>
    <TileMatrixSetId>NLDEPSG28992Scale</TileMatrixSetId>
    <File>/geodata/ecw/2010/Luchtfoto2010_25cm.ecw</File>
    <ImageFormat>image/jpeg</ImageFormat>    
  </TileDataSet>
  <TileDataSet>
    <Identifier>2011</Identifier>
    <TileMatrixSetId>NLDEPSG28992Scale</TileMatrixSetId>
    <File>/geodata/ecw/2011/Mozaiek2011.ecw</File>
    <ImageFormat>image/jpeg</ImageFormat>
 </TileDataSet>    
</GDALTileStore>

This configuration will create a GDAL tile store resource with the following settings:

  • Tile store defines two tile data sets with identifiers 2010 and 2011
  • Tile matrix set is NLDEPSG28992Scale
  • Tile data set 2010 is backed by file /geodata/ecw/2010/Luchtfoto2010_25cm.ecw
  • Tile data set 2011 is backed by file /geodata/ecw/2011/Mozaiek2011.ecw
  • Output tile format is image/jpeg

19.4.3. Configuration options

The configuration format for the GDAL tile store is defined by schema file http://schemas.deegree.org/datasource/tile/gdal/3.4.0/gdal.xsd. There’s only a single configuration element, but it may occur several times:

Option Cardinality Value Description
TileDataSet 1..n Complex GDAL-based tile data set

Each TileDataSet element defines a single tile data set:

Option Cardinality Value Description
Identifier 0..1 String Identifier of the tile data set, default: base file name without path and suffix
TileMatrixSetId 1..1 String Reference to the identifier of corresponding tile matrix set
File 1..1 String Raster file that contains the tile data, read using GDAL
ImageFormat 0..1 String Output tile format, default: image/png