deegree 3 WMS configuration concepts

Contents

Service configuration
GetFeatureInfo configuration
Further workspace configuration

This page describes a technical concept for the WMS layer configuration in deegree 3. It's aligned with the concepts for datastore configuration. The primary goal of the design is to be as easy as possible, allow for all possible combinations of layer nesting while minimizing the chances of mis-configurations.

If you want to know more about the deegree 3 mapService, read the deegree3/MapService page.

If you want to know how to set up a deegree 3 mapService by yourself, take a look at deegree3/HowToSetupWMS.

If you prefer to use a preconfigured war file demo, read WMS: Get it up and running in 5 minutes.

1. Service configuration

The deegree 3 web services are configured in the folder WEB-INF/workspace/. This section focuses on the WMS specific settings done in WEB-INF/workspace/services/wms.xml. Other parts of the configuration are described in the deegree3/WorkspaceConfiguration.

1.1. Types of Layers

There are two different approaches for inserting layers into a deegree 3 WMS: a static and a dynamic approach. It is possible to mix these two approaches within a single WMS configuration.

dynamic: all data from a specified data directory is loaded automatically. Read more on DynamicLayers below.
static: every single layer has to be explicitly specified in the configuration. Read on here.

The deegree 3 mapService configuration for staticaly inserted layers differentiates three types of layers (requestable, unrequestable, logical). Two of these types will actually be visible in the WMS' capabilities response, while the other one is 'invisible' to the outside. Every layer can be coupled with at most one datastore. This concept enables a maximum level of flexibility when it comes to combining several datastores to one nested visible WMS layer, and a minimum of redundancy when it comes to constraints like scale and bbox. Read more about the underlying concepts for datastore configuration.

1.1.1. RequestableLayer

A requestable layer is a layer that can be requested through the WMS interface, and is thus required to have a name. Requestable layers are the "standard" layers in a deegree mapService configuration file. Besides the requirement of having a name, a requestable layer, in case that it's not a group layer, should have a dataStore Id. This could be a FeatureStoreId for example. There are several additional possibilities of configuring a layer in the wms.xml configuration file. Here are some examples given and explained.

Here is an example snippet defining a layer with dimension TIME, based on a shape file:

<RequestableLayer>
  <Name>WeatherStations</Name>
  <Title>Weatherstations in Utah County</Title>
  <Dimension isTime="true">
    <Property>TIMESTAMP</Property>
    <DefaultValue>2009-01-01T00:00:00Z</DefaultValue>
    <MultipleValues>true</MultipleValues>
    <NearestValue>true</NearestValue>
    <Current>true</Current>
    <Extent>2009-01-01T00:00:00Z/2009-01-07T00:00:00Z/P1D</Extent>
  </Dimension>
  <FeatureStoreId>utah_weather</FeatureStoreId>
  <DirectStyle>
    <File>../styles/utah_weather.xml</File>
  </DirectStyle>
</RequestableLayer>

Here is an example snipped defining a layer with dimension ELEVATION, based on a raster coverage tiff file:

<RequestableLayer>
  <Name>DEM30</Name>
  <Title>DEM 30m Raster of Utah</Title>
  <Dimension isElevation="true">
    <Property>ELEV</Property>
    <DefaultValue>0/3500</DefaultValue>
    <MultipleValues>true</MultipleValues>
    <NearestValue>true</NearestValue>
    <Extent>0/3500</Extent>
  </Dimension>
  <CoverageStoreId>utah_dem30</CoverageStoreId>
  <DirectStyle>
    <File>../styles/utah_dem30.xml</File>
  </DirectStyle>
</RequestableLayer>

Here is an example layer definition utilizing a RemoteWMSStore and defining its own LegendGraphic showing the original LegendURL in the WMS Capabilities document:

<RequestableLayer queryable="true">
  <Name>roads</Name>
  <Title>Roads</Title>
  <Abstract>Roads of some cities</Abstract>
  <RemoteWMSStoreId>roads</RemoteWMSStoreId>
  <DirectStyle>
    <File>../styles/somestyle.xml</File>
    <LegendGraphicFile outputGetLegendGraphicUrl="false">http://www.someurl.org/legends/defaultlegend.png</LegendGraphicFile>
  </DirectStyle>
</RequestableLayer>

1.1.2. UnrequestableLayer

An unrequestable layer is a layer that is visible in the WMS capabilities, but is not requestable. Therefore, an unrequestable layer may not have a <name> element. Unrequestable layers are usually used for categories or the root layer, as most people will not want all WMS layers to be requestable at once. Our CITE WMS configuration uses a structure like this:

<UnrequestableLayer>
    <Title>deegree 3 utahDemo</Title>
    <CRS>EPSG:4326 CRS:84 EPSG:26912</CRS>
    <RequestableLayer>
    ...
    </RequestableLayer>
    <RequestableLayer>
    ...
    </RequestableLayer>
    <RequestableLayer>
    ...
    </RequestableLayer>
</UnrequestableLayer>

1.1.3. LogicalLayer

The logical layer is a layer, which is not visible to the OGC frontend, i.e. it does not show up in the WMS capabilities document. It can be used to combine different datastores into one requestable layer like this:

<RequestableLayer>
    <Name>ElevationContours</Name>
    <Title>Elevationcontours in Utah</Title>
    <LogicalLayer>
        <FeatureStoreId>utah_contours500ft</FeatureStoreId>
        <SLDStyle>
            <File>../styles/utah_contours.xml</File>
            <NamedLayer>ElevationContours</NamedLayer>
            <Name>ElevationContours</Name>
            <UserStyle>default:ElevationContours</UserStyle>
            <UserStyle>ElevationContoursSimple</UserStyle>
        </SLDStyle>
    </LogicalLayer>
    <LogicalLayer>
        <FeatureStoreId>utah_contours1000ft</FeatureStoreId>
        <SLDStyle>
            <File>../styles/utah_contours.xml</File>
            <NamedLayer>ElevationContours</NamedLayer>
            <Name>ElevationContours</Name>
            <UserStyle>default:ElevationContours</UserStyle>
            <UserStyle>ElevationContoursSimple</UserStyle>
        </SLDStyle>
    </LogicalLayer>
</RequestableLayer>

1.1.4. DynamicLayer

There is another layer type that can be configured. Strictly speaking, it is not a layer, but rather a configuration option that instructs the service to construct a layer tree by itself. All dynamically created layers are handled as requestable layers.

There are different kinds of dynamic layers:

<ShapefileDirectory> : based on shape files on the file system. Here, a directory needs to be specified as entry point.
<PostGIS> : based on data stored in a PostgreSQL/PostGIS database. Here, a db connection needs to be specified.

1.1.4.1. Styling for dynamic layers

The files containing the style definitions need to be located in the same folder as the data.
The files containing the style definitions need to be named exactly like the respective data source, with file ending sld (myData.sld).
The style definitions may consist of both SLD and SE elements.

1.1.4.2. DynamicLayer for shape files

A complete deegree 3 mapService configuration making use of dynamic layers based on shape files may look like this:

<?xml version="1.0" encoding="UTF-8"?>
<deegreeWMS
  configVersion="3.0.0"
  xmlns="http://www.deegree.org/services/wms"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:dgws="http://www.deegree.org/webservices"
  xsi:schemaLocation="http://www.deegree.org/services/wms http://schemas.deegree.org/services/wms/3.0.0/wms_configuration.xsd">

  <ServiceConfiguration>
    <DefaultLayerOptions>
      <FeatureInfoRadius>10</FeatureInfoRadius>
    </DefaultLayerOptions>

    <UnrequestableLayer>
      <Title>deegree 3 utahDemo</Title>
      <CRS>EPSG:4326 CRS:84 EPSG:26912</CRS>

      <DynamicLayer>
        <ShapefileDirectory>../data/data/utah/vector/busroutes</ShapefileDirectory>
      </DynamicLayer>

    </UnrequestableLayer>
  </ServiceConfiguration>
</deegreeWMS>

and will result in a dynamically loaded layer tree based on the file system. The layer tree will then be constructed like this:

If a subnode of the specified directory again is a directory, it is scanned recursively, and a category layer is inserted for each folder.
If a subnode is a datastore definition (like shape files), a new layer is inserted in the respective category layer.

The mechanism is able to parse .prj files (containing WKT CRS definitions or just plain EPSG codes) to set the correct CRS for the data source, and able to automatically parse .sld files for symbolizing. New files can be added at runtime. An RTree index is generated automatically when the file is loaded the first time, and stored to disk.

1.1.4.3. DynamicLayer for data stored in DB

People with special requirements may want to use a dynamic configuration based on tables in a data base. Information about how this is currently implemented can be found at deegree3/DynamicLayerPostGIS.

A complete deegree 3 mapService configuration making use of dynamic layers based on data in a PostGIS database may look like this:

<?xml version="1.0" encoding="UTF-8"?>
<deegreeWMS
  configVersion="3.0.0"
  xmlns="http://www.deegree.org/services/wms"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:dgws="http://www.deegree.org/webservices"
  xsi:schemaLocation="http://www.deegree.org/services/wms http://schemas.deegree.org/services/wms/3.0.0/wms_configuration.xsd">

  <ServiceConfiguration>
    <RequestableLayer>
      <Name>root</Name>
      <Title>Root Layer</Title>
      <CRS>EPSG:4326 EPSG:26912 EPSG:25832 AUTO:42001 AUTO:42002</CRS>
      <DynamicLayer>
        <PostGIS>conn</PostGIS>
      </DynamicLayer>
    </RequestableLayer>
  </ServiceConfiguration>
</deegreeWMS>

1.2. Special Layer

1.2.1. Statistics Layer

The statistics layer is simply one single layer with special content on access statistics:

This layer provides a graphical analysis of the regions especially interesting to the users of this mapService.
- The bounding boxes for each GetMap request are put together into one single image to visualise the most interesting areas (for the users of the maps).
- The layer is not available in the online demo. Please test this in your local installation by activating it in the configuration file (workspace/services/wms.xml)

1.3. Data source types

Currently we have two types of data sources, one for vector data (feature store)

```
<FeatureStoreId>someFeatureFileBaseName</FeatureStoreId>
```

and one for coverage data (coverage store)

```
<CoverageStoreId>someCoverageFileBaseName</CoverageStoreId>
```

deegree 3.1 adds a third data source, the remote WMS store:

<RemoteWMSStoreId>someCoverageFileBaseName</RemoteWMSStoreId>

The RemoteWMSStoreId must obviously point to a remote OWS store for WMS (there is currently no way to use a remote WCS or WFS).

The IDs given here are the file base names of the corresponding data sources (without the file ending ".xml", hence base name). Within the workspace, the data sources are placed in the folder datasources/coverage, datasources/feature or datasources/remoteows respectively. Read more in the deegree3/WorkspaceConfiguration.

A full example for coverage data looks like this:

<RequestableLayer>
  <Name>DEM90</Name>
  <Title>DEM 90m Raster of Utah</Title>
  <CoverageStoreId>utah_dem</CoverageStoreId>
  <DirectStyle>
    <File>../styles/utah_dem.xml</File>
  </DirectStyle>
  <DirectStyle>
    <File>../styles/yet_another_style.xml</File>
  </DirectStyle>
</RequestableLayer>

1.4. Example configurations

For complete examples how things are configured please refer to the ready to run examples:

deegree utahDemo: documentation and download
deegree inspireNode documentation and download

The following xml can be used for as a snippet template for certain configuration option and to know the order of element. You must adapt the examples to your environment.

congfig version 3.1

<wms:deegreeWMS xmlns:wms="http://www.deegree.org/services/wms" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:dgws="http://www.deegree.org/webservices" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" configVersion="3.1.0" xsi:schemaLocation="http://www.deegree.org/services/wms http://schemas.deegree.org/services/wms/3.1.0/wms_configuration.xsd">
  
<wms:SupportedVersions>
    <wms:Version>1.1.1</wms:Version>
    <wms:Version>1.3.0</wms:Version>
  </wms:SupportedVersions>
  <wms:MetadataStoreId>09844e51-e5cd-52c3-737d-b3a61366d028</wms:MetadataStoreId>
  <wms:MetadataURLTemplate>http://deegree3-demo.deegree.org:80/csw-workspace/services?service=CSW&amp;request=GetRecordById&amp;version=2.0.2&amp;id=${metadataSetId}</wms:MetadataURLTemplate>

  <wms:ServiceConfiguration>
    <wms:DefaultLayerOptions>
      <wms:AntiAliasing>BOTH</wms:AntiAliasing>
      <wms:MaxFeatures>100000</wms:MaxFeatures>
      <wms:FeatureInfoRadius>10</wms:FeatureInfoRadius>
    </wms:DefaultLayerOptions>

    <wms:UnrequestableLayer queryable="false">
      <wms:Title>Root Layer</wms:Title>
      <wms:Abstract>Root Layer</wms:Abstract>
        <wms:CRS>EPSG:25832 EPSG:31467 EPSG:4326 EPSG:4258 EPSG:3034 EPSG:3042 EPSG:3043 EPSG:3044</wms:CRS>

      <!-- Feature store based layer, no style; will be drawn in default style (black lines, grey fills) -->      
      <wms:RequestableLayer>
        <wms:Name>layer1</wms:Name>
        <wms:Title>Layer One</wms:Title>
        <wms:FeatureStoreId>fs_layerone</wms:FeatureStoreId>
      </wms:RequestableLayer>
      
      <!-- Feature store based layer referencing SE FeatureTypeStyle -->      
      <wms:RequestableLayer>
        <wms:Name>layer2</wms:Name>
        <wms:Title>Layer Two</wms:Title>
        <wms:FeatureStoreId>fs_layer2</wms:FeatureStoreId>
        <wms:DirectStyle>
        <wms:File>../styles/se_layerstyle.xml</wms:File>
        <wms:Name>default</wms:Name>
        </wms:DirectStyle>
      </wms:RequestableLayer>
   
      <!-- Feature store based layer referencing SLD Style; will be drawn as defined in SLD Request -->     
      <!-- Specific Style in SLD  must be identified here by NamedLayer and UserStyle -->     
      <wms:RequestableLayer>
        <wms:Name>layer3</wms:Name>
        <wms:Title>Layer Three</wms:Title>
        <wms:FeatureStoreId>fs_layer3</wms:FeatureStoreId>
        <wms:SLDStyle>
          <wms:File>../styles/sld_layerstyle.xml</wms:File>
          <wms:NamedLayer>Darstellung</wms:NamedLayer>
          <wms:Name>default</wms:Name>
          <wms:UserStyle>default1</wms:UserStyle>
        </wms:SLDStyle>
      </wms:RequestableLayer>
      
      <!-- RemoteWMSStore examle (cascading WMS) -->     
      <wms:RequestableLayer>
        <wms:Name>layer3</wms:Name>
        <wms:Title>Layer Three</wms:Title>
        <wms:RemoteWMSStoreId>rs_layer3</wms:RemoteWMSStoreId>
      </wms:RequestableLayer>
      
      <!-- CoverageStore example for raster data sources. (raster data, aerial images, ...)
           usage of SLD/SE 1.1.0 is possible also if 'real' raster data is to be drawn; 
           see SLDStyle, DirctStyle, 
           GetFeatureInfo is disabled for this example, but could be allowed for raster data
          -->     
      <wms:RequestableLayer queryable="false">
        <wms:Name>layer_cs</wms:Name>
        <wms:Title>Layer Coverage store</wms:Title>
        <wms:CoverageStoreId>cs_layer</wms:CoverageStoreId>
      </wms:RequestableLayer>
      
      
      <!-- Example with extensive configuration options -->     
      <wms:RequestableLayer queryable="true">
        <wms:Name>layer_cs</wms:Name>
        <wms:Title>Layer Coverage store</wms:Title>
        <wms:Abstract>wms:Abstract</wms:Abstract>
        <wms:MetadataSetId>wms:MetadataSetId</wms:MetadataSetId>
        <wms:Keywords>
          <wms:Keyword>Environment</wms:Keyword>
          <wms:Keyword>Nature</wms:Keyword>
        </wms:Keywords>
        <wms:BoundingBox crs="EPSG:4326">
            <wms:LowerCorner>8.14860937 53.22404236</wms:LowerCorner>
            <wms:UpperCorner>10.37847614 54.1418763</wms:UpperCorner>
        </wms:BoundingBox>
        <wms:CRS>EPSG:25832 EPSG:31468 EPSG:4326</wms:CRS>
        <wms:ScaleDenominators min="0.0"  max="10000000"/>
        <wms:FeatureStoreId>fs_layer2</wms:FeatureStoreId>
        <wms:DirectStyle>
        <wms:File>../styles/se_layerstyle.xml</wms:File>
        <wms:Name>default</wms:Name>
        </wms:DirectStyle>
        <wms:DirectStyle>
        <wms:File>../styles/se_layerstyle.xml</wms:File>
        <wms:Name>colorful</wms:Name>
        <!-- Choose either LegendConfigurationFile if your configured a special SLD/SE to 
             be used for creating the legend graphic or -->
        <!-- <wms:LegendConfigurationFile>wms:LegendConfigurationFile</wms:LegendConfigurationFile> -->
        <!-- wms:LegendGraphicFile for an already existing image file 
             outputGetLegendGraphicUrl will handle if original url or GetLegendGraphic request url will 
             be declared in LegendURL or GetCapabilities response -->
        <wms:LegendGraphicFile outputGetLegendGraphicUrl="true">http://www.deegree.org/deegree/images/deegree/logo-deegree.png</wms:LegendGraphicFile>
        </wms:DirectStyle>
        <wms:LayerOptions>
          <wms:AntiAliasing>BOTH</wms:AntiAliasing>
          <wms:MaxFeatures>100000</wms:MaxFeatures>
          <wms:FeatureInfoRadius>10</wms:FeatureInfoRadius>
        </wms:LayerOptions>
      </wms:RequestableLayer>
      
      <!-- Multiple sources for one layer as Logical layers (not itself requestable as layer -->
      <wms:RequestableLayer>
        <wms:Name>mylogicallayer</wms:Name>
        <wms:Title>This layer consists of more then 1 datasource</wms:Title>
        <wms:LogicalLayer queryable="true">
          <wms:ScaleDenominators min="50000" max="10000000" />
          <wms:FeatureStoreId>aerialimageboxes</wms:FeatureStoreId>
          <wms:DirectStyle>
          <wms:File>../styles/se_layerstyle.xml</wms:File>
          <wms:Name>default</wms:Name>
          </wms:DirectStyle>
        </wms:LogicalLayer>
        <wms:LogicalLayer queryable="false">
          <wms:ScaleDenominators min="0.00001" max="50000" />
          <wms:CoverageStoreId>cs_aerialimage</wms:CoverageStoreId>
        </wms:LogicalLayer>
      </wms:RequestableLayer>
      
      
      <!-- Multiple layers ordered with hierachy each requestable with getMap -->
      <wms:RequestableLayer>
        <wms:Name>hierachylayer</wms:Name>
        <wms:Title>This layer consists of more then 1 requestable layers</wms:Title>
        <wms:RequestableLayer>
          <wms:Name>aerialimagebox</wms:Name>
          <wms:Title>aerialimagebox</wms:Title>
          <wms:ScaleDenominators min="50000" max="10000000" />
          <wms:FeatureStoreId>aerialimageboxes</wms:FeatureStoreId>
        </wms:RequestableLayer>
        <wms:RequestableLayer>
          <wms:Name>aerialimage</wms:Name>
          <wms:Title>aerial image</wms:Title>
          <wms:ScaleDenominators min="0.00001" max="50000" />
          <wms:CoverageStoreId>cs_aerialimage</wms:CoverageStoreId>
        </wms:RequestableLayer>
      </wms:RequestableLayer>
            
    </wms:UnrequestableLayer>
    
  </wms:ServiceConfiguration>
  <wms:FeatureInfoFormats>

    <wms:GetFeatureInfoFormat>
      <wms:File>html.gfi</wms:File>
      <wms:Format>text/html</wms:Format>
    </wms:GetFeatureInfoFormat>
   <!-- 
    <wms:GetFeatureInfoFormat>
      <wms:XSLTFile>featureinfo2html.xsl</wms:XSLTFile>
      <wms:Format>text/html</wms:Format>
    </wms:GetFeatureInfoFormat>
     -->
  </wms:FeatureInfoFormats>

</wms:deegreeWMS>

1.5. Review

Some may wonder why there is the limitation of at most one datastore for any layer. This plays together with the concept that datastores should be constraint-less, as detailed in the concepts for datastore configuration. Another motivation is that is has been reported that deegree users sometimes wonder why they see no data in their freshly configured deegree 2 WMS. This may be due to a number of reasons: scale constraints, bbox constraints, wrong SRS etc. If it would be possible for datastores to have scale constraints in deegree 3, and layers to have multiple datastores, there is virtually any number of places where it might go wrong. Even if a layer has only one datastore, it might not be shown due to the layers scale constraints, the data stores scale constraints, the layer bbox, the datastore bbox etc. This duplication of concepts can be avoided with the proposed configuration concept.

The concept also allows for a minimal configuration. A configuration of a shape file layer without a style is as simple as this:

<RequestableLayer>
  <Name>cite:Autos</Name>
  <Title>cite:Autos</Title>
  <FeatureStoreId>autos</FeatureStoreId>
</RequestableLayer>

and results in a layer that has the correct bounding box in the capabilities.

2. GetFeatureInfo configuration

This section describes the configuration concept of text/html output format for deegree mapServices. The configuration file is located at WEB-INF/workspace/services/html.gfi. If you create this file please make sure it is UTF-8 encoded.

The special deegree 3 syntax does not need complex XSLT scripting. In the following simple configuration example you find a default template where you have the choice to rewrite feature type names, property names or values.

<?template start>
<html>
  <head>
    <title>Feature info of deegree3 mapService</title>
    <meta http-equiv='Content-Type' content='text/html; charset=utf-8'>
    <link href="styles.css" rel="stylesheet" type="text/css" />
  </head>
  <body>
    <h2>deegree3 WMS feature info</h2>
    <table>
      <?feature *:feature>
    </table>
  </body>
</html>

<?template feature>
<tr>
      <td colspan="2" style="border: solid white 0px;">&nbsp;</td>
</tr>
<tr style="background-color: #99BBE8;">
      <td colspan="2" style="border: solid black 1px;"><?name:map ftname></td>
</tr>
<?property not(besitz):property>

<?template property>
<tr>
  <td <?even:evencolor><?odd:oddcolor> valign="top"><strong><?name:map propname></strong></td>
  <td <?even:evencolor><?odd:oddcolor>><?value:map value></td>
</tr>

<?template oddcolor>style="background-color: #99BBE8;"
<?template evencolor>style="background-color: white;"

<?map ftname>

kastanien=Kastanien

<?map propname>
art=Art
umf=Umfang (m)

<?map value>

true=yes
false=no

To remove the specified property names from the text/html result set, write:

<?property not(besitz,otherpropertyname):property>

If nothing is to be excluded, use:

<?property *:property>

3. Further workspace configuration

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

CategoryDeegree3