.. _anchor-configuration-gdal: =============== 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 :ref:`anchor-configuration-layers` for a deegree workspace by using either the :ref:`anchor-configuration-gdal-layer` or the :ref:`anchor-configuration-gdal-tilestore`. .. 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. --------------------------- 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 :ref:`anchor-configuration-gdal-settings` file in your workspace yet, you should be able to locate the following lines upon workspace startup: .. code-block:: text [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 :ref:`anchor-configuration-gdal-settings` file is present in the active deegree workspace, the corresponding lines should look similar to this: .. code-block:: text [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 :ref:`anchor-configuration-gdal-settings` file is present, but the GDAL library cannot be accessed, you will see something like the following: .. code-block:: text [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. .. _anchor-configuration-gdal-settings: ------------- GDAL settings ------------- The GDAL settings file gdal.xml belongs in the main directory of the deegree workspace. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Minimal GDAL settings example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The only mandatory element is OpenDatasets. A minimal valid configuration example looks like this: .. topic:: GDAL settings (minimal example) .. literalinclude:: xml/gdal_minimal.xml :language: xml This configuration will register the GDAL JNI adapter and will allow a maximum of five GDAL datasets to be kept open for simultaneous access. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ More complex GDAL settings example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. topic:: GDAL settings (more complex example) .. literalinclude:: xml/gdal_complex.xml :language: xml 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. ^^^^^^^^^^^^^^^^^^^^^ 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. .. table:: Options for the GDAL settings configuration file +--------------+-------------+---------+----------------------------------------------------------+ | 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 | +--------------+-------------+---------+----------------------------------------------------------+ .. _anchor-configuration-gdal-layer: ---------- 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 :ref:`anchor-configuration-layers` chapter for general information on using and defining layer resources. ^^^^^^^^^^^^^^^^^^^^^ Configuration example ^^^^^^^^^^^^^^^^^^^^^ The only custom element in a GDAL Layer definition is File. A valid example looks like this: .. topic:: GDAL Layers (example) .. literalinclude:: xml/gdal_layers_minimal.xml :language: xml 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 .. _anchor-configuration-gdal-tilestore: --------------- 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 :ref:`anchor-configuration-tilestore` chapter for general information on using and defining tile store resources. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Minimal configuration example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A minimal valid configuration example looks like this: .. topic:: GDAL Tile Store: Minimal configuration .. literalinclude:: xml/gdal_tilestore_minimal.xml :language: xml 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ More complex configuration example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A more complex example that uses all available configuration options: .. topic:: GDAL Tile Store: More complex configuration .. literalinclude:: xml/gdal_tilestore_complex.xml :language: xml 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 ^^^^^^^^^^^^^^^^^^^^^ 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: .. table:: Options for ``TileDataSet`` configuration elements +-----------------+-------------+---------+----------------------------------------------------------------------------------+ | 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 | +-----------------+-------------+---------+----------------------------------------------------------------------------------+