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.
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.
The GDAL settings file gdal.xml belongs in the main directory of the deegree workspace.
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.
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:
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.
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 |
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.
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:
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.
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:
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:
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 |