Luciad Developer Platform

This guide discusses the WMS samples included with the OGC Web Server Suite.

Configuring the server’s capabilities

Description of the default configuration format

The TLcdWMSCapabilitiesXMLDecoder configures the server’s capabilities through an XML file. A sample XML file is shown in program Program: Configuration of the data repository.

Program: Configuration of the data repository

<WMS_Capabilities_config version="1.0">
  <Service>
    <Name>OGC:WMS</Name>
    <Title>Luciad Web Map Service</Title>
    <Abstract>OpenGIS compliant Web Map Service implementation powered by Luciad</Abstract>
    <KeywordList>
      <Keyword>USA</Keyword>
      <Keyword>Washington DC</Keyword>
    </KeywordList>
    <OnlineResource xmlns:xlink="http://www.w3.org/1999/xlink"
                    xlink:type="simple" xlink:href="http://www.luciad.com"/>
  </Service>
  <Output>
    <Format>image/jpeg</Format>
    <Format>image/png</Format>
    <FeatureInfoFormat>text/plain</FeatureInfoFormat>
    <LegendGraphicFormat>image/png</LegendGraphicFormat>
    <DescribeLayerFormat>application/vnd.ogc.wms_xml</DescribeLayerFormat>
  </Output>
  <MapData>
    <Folder>webapps/LuciadLightspeedOGC</Folder>
  </MapData>
  <Root>
    <Title>Web Map Service Layers</Title>
    <Layer namevisible = "false">
      <Name>Usa</Name>
      <Title>Usa layer</Title>
      <Layer namevisible = "true">
        <Name>Usa_states</Name>
        <Title>States</Title>
        <File>Data/Shp/Usa/states.shp</File>
        <Abstract>States of the USA</Abstract>
        <PaintStyle mode="outlined_filled">
          <FillStyle color="#F4EABE" opacity="1" pattern="filled"/>
          <LineStyle color="#400000" opacity="1" width="1"/>
        </PaintStyle>
        <Label foreground="#6D470B" filled="true" background="#EFA945" framed="true"
	       withPin="true" fontname="Arial" fontsize="12" fontstyle="bold_italic" >
          <Feature name="STATE_NAME"/>
          <Feature name="STATE_ABBR"/>
        </Label>
      </Layer>
      <Layer namevisible = "true">
        <Name>Usa_cities</Name>
        <Title>Cities</Title>
        <File>Data/Shp/Usa/city_125.shp</File>
        <Abstract>Cities of the USA</Abstract>
        <PaintStyle>
          <PointStyle color="#F70909" size="6" shape="filled_circle"/>
        </PaintStyle>
      </Layer>
    </Layer>
    <Layer namevisible = "true" opaque = "true">
      <Name>Washington_DC_raster</Name>
      <Title>Raster</Title>
      <File>Data/Rst/wash_spot_small.rst</File>
      <Abstract>Raster data for Washington DC</Abstract>
      <MinScaleDenominator>5000</MinScaleDenominator>
      <MaxScaleDenominator>1000000</MaxScaleDenominator>
      <Dimension name="ExampleDimension" units="Unit" unitSymbol ="Symbol" default="1"
                 nearestValue="true" multipleValues="false" current="false">1,2,3</Dimension>
    </Layer>
  </Root>
</WMS_Capabilities_config>

The root element of the XML document is WMS_Capabilities_config. It contains an attribute specifying the version number of the configuration file.

The rest of the xml file consists of three parts: the first part contains a description of the Web Map Service, the second part contains the result image types and the third part containing a definition of the different layers and a description of how the data in those layers should be rendered.

Description of the Web Map Service

The Web Map Service is described in the Service element. It contains the following elements:

Name: the name of the service. This element is required and must have as contents 'WMS' or 'OGC:WMS'.
Title: the title of the service. This element is required. It should be brief yet descriptive, to identify this server in a menu with other servers.
Abstract: a descriptive narrative providing more information about the service.
LayerLimit: a positive integer indicating the maximum number of layers a client is permitted to include in a single request. If this element is absent, the server imposes no limit.
MaxWidth, MaxHeight: positive integers indicating the maximum width and height values that a client is permitted to include in a single request. If either element is absent, the server imposes no limit on the corresponding parameter.
KeywordList: a list of keywords or keyword phrases describing the server to help catalog searching. Each keyword or keyword phrase must be placed in a Keyword element.
OnlineResource: this element may be used to refer to the website of the service provider.

Enumeration of the possible output formats

The Output element enumerates all the possible output formats for the GetMap, the GetFeatureInfo, the GetLegendGraphic and the DescribeLayer requests^[1]. The output formats for a GetMap request are described in Format elements, for a GetFeatureInfo request in FeatureInfoFormat elements, for a GetLegendGraphic request in LegendGraphicFormat elements and for a DescribeLayer request in DescribeLayerFormat elements. The formats are specified as MIME types.

Note that each listed output format must have a corresponding encoder implementation, as described in Configure a WMS server. For example, if the MIME type image/png is listed as an output format for the GetMap request, a corresponding ILcdGXYViewEncoder must be available in the WMS.

Description of the layers

The map produced by the Luciad WMS server includes different layers of geographic information. As defined by the OpenGIS WMS specification, a single root layer encloses any number of additional layers, which may be hierarchically nested according to the user’s preferences. For each of these layers, the user determines how the objects in the layer should be rendered. Depending on the type of objects in a layer, the user is able to specify other properties of the renderer.

The layer description starts with the MapData element that contains the folder that is used as base directory for all the relative paths in the layer descriptions.

The hierarchical structure of the layers is reflected in the nested structure of the XML file. All the layers are enclosed within the Root element. A layer is described by a name, a title and possibly an abstract. The name is a single unique word, used in requests to refer to a layer, the title is a short description for the user’s benefit and the abstract is a longer description of the layer. A set of optional attributes can be defined to further determine the behavior of the layer:

namevisible: specifies whether the layer is published in the capabilities sent to the client. Setting its value to true indicates that the layer is published in the capabilities and therefore also can be used in requests. The default value is false.
queryable: specifies whether a layer accepts GetFeatureInfo requests. Setting its value to true indicates that the layer accepts GetFeatureInfo requests. The default value is false.
opaque: indicates whether a layer contains opaque data. Setting its value to true indicates that the layer represents an area-filling coverage. Note that this property is only meant to inform the client: for example, if it is true, the client is advised to place such a layer at the bottom of a stack of maps.
noSubsets: specifies whether a layer accepts client requests for subsets of the full bounding box of the data. Setting its value to true indicates that the layer only accepts requests for the entire bounding box. The default value is false.
fixedWidth: specifies whether a layer can accept client requests for an arbitrary width. Setting its value to a nonzero value indicates a fixed width; 0 indicates that the WMS can produce maps of arbitrary width. The default value is 0.
fixedHeight: specifies whether a layer can accept client requests for an arbitrary height. Setting its value to a nonzero value indicates a fixed height; 0 indicates that the WMS can produce maps of arbitrary height. The default value is 0.

Each of these attributes can be inherited or replaced by sublayers.

The root layer is the top layer in the hierarchy and should contain one or more layers. Every other layer can contain other layers or can contain actual data. A 'data layer' has a File element with the path to the file containing the data. This path must be relative to the base directory defined in the MapData element. The file to be loaded can be of any format, as long as there is a model decoder available that can decode it.

Many data file types include rendering information. Files in the ESRI Shape format do not contain this information and if data should be retrieved from such a file, this additional rendering information can be provided using a PaintStyle element in the layer description. This element can contain a PointStyle, a LineStyle and/or a FillStyle element.

A PointStyle element describes the icon to be used for painting points. This element can have different attributes:

imagesrc: the path of the file that contains the image to be used as icon. This path must be relative to the classpath, for example relative to the WEB-INF/classes directory. If this attribute is provided, the following attributes are not taken into account.
shape: this attribute specifies a predefined icon. This can be circle, filled_circle, rectangle, filled_rectangle, cross or cross_rectangle.
color: the HTML code of the color for the predefined icon.
size: the size of the predefined icon, in number of pixels.

For polygons and polylines, a LineStyle element can be provided. Its possible attributes are:

color: the HTML code of the color.
opacity: the opacity to be used, which is a number between 0 (transparent) and 1 (opaque).
width: the width of a line, in number of pixels.

For polygons, besides a LineStyle, a FillStyle element can be defined with the same attributes as the LineStyle. To specify in which mode the polygon should be painted, the PaintStyle element has an attribute mode. The different painting modes are:

polygon
filled
outlined_filled

The Luciad WMS server can label shapes with one or more of the features. How the labels are painted is defined in the Label element. Its attributes are:

foreground: the color of the label text.
filled: true if the labels should have a filled background, false otherwise.
background: the fill color of the label frame.
framed: true if the labels should be surrounded with a frame, false otherwise.
withPin: true if a pin should be drawn from the shape to the label, false otherwise.
fontname: the name of the label font.
fontsize: the size of the label font.
fontstyle: the label font style can be bold, italic or bold_italic.

The Label element contains the feature names of the features whose values have to be added to the label. These feature names are attributes of the Feature element.

Graphical editor

The samples contain a graphical editor for editing the default configuration format. You can start the WMS Server Configuration Editor from the LuciadFusion launcher (start.jar). Select and run the wms.server.config.editor sample. A screenshot of this editor is shown in Figure 1, “Sample WMS Configuration Editor”. The main panel contains three different tabs, which are each used to edit a different part of the configuration file.

The Layers tab shows a tree view of the available layers. By using the control buttons below the tree, layers can be added, removed or reordered. When a layer in the tree is selected, its properties are displayed in the right panel, ready for editing.

The Map data tab is used to configure the main data folder and the available output formats.

The Service metadata tab is used to set some general information about the WMS server itself. In the bottom of the main panel, a text area presents tooltip information and debug messages.

Figure 1. Sample WMS Configuration Editor

Extending the default configuration format

The WMS Server API allows the user developing a custom configuration format by writing their own implementation of ILcdWMSCapabilitiesDecoder. The decoder for the default configuration format is available as sample in the package samples.wms.server.config.xml. The user can start from this sample to develop a custom format. The decoder is built using the general XML decoder framework that is located in the package com.luciad.format.xml in LuciadLightspeed . More information about the usage of this framework can be found in the LuciadLightspeed Developer’s Guide.

1. Note that the GetLegendGraphic and DescribeLayer requests are only available for an SLD-enabled WMS.

The WMS server samples