SLD

Author:Jeff McKenna Contact:jmckenna atgatewaygeomatics.com Author:Yewondwossen Assefa Contact:assefa at dmsolutions.ca Last Updated:2008/07/18 Revision:$Revision: 8452 $ Date:$Date: 2009-01-23 12:08:00 -0800 (Fri, 23 Jan 2009) $

Contents

• SLD
  • Introduction
  • Server Side Support
  • Client Side Support
  • Named Styles support
  • Other Items Implemented
  • Issues Found During Implementation

Introduction

This document describes the procedures for taking advantage of the Styled Layer Descriptor (SLD) support in WMS GetMap requests with MapServer. SLD support exists for the server side (ability to read an SLD and apply it with a GetMap request) and for the client side (includes sending SLD requests to server and generate SLD files on the fly from MapServer map file). SLD support was added to MapServer in version 4.2.

This document assumes that you are already familiar with the following aspects of MapServer:

• MapServer application development and setting up .map files.
• Familiarity with the WMS specification would be an asset. Links to the MapServer WMS documents are included in the next section.

Links to SLD-related Information

• Styled Layer Descriptor Implementation Specification.
• MapServer WMS Client HowTo.
• MapServer WMS Server HowTo.
• MapServer OGC Web Services Workshop.
• Open GIS Consortium (OGC) home page.

Server Side Support

General Information

There are two ways a WMS request can pass an SLD document with a GetMap request to MapServer:

• SLD parameter pointing to remote SLD (SLD=http://URL_TO_SLD).
• SLD_BODY parameter to send the SLD definition in the URL.

These two methods are both available through MapServer. An example of a request would be:

http://www2.dmsolutions.ca/cgi-bin/mswms_world?SERVICE=WMS&VERSION=1.1.1&Request=GetMap
&LAYERS=WorldGen_Outline&SLD=http://www2.dmsolutions.ca/msapps/world_testdata/tests
/sld_tests/sld_line_simple.xml

Test the remote SLD request.

The SLD in the above request follows:

<StyledLayerDescriptor version="1.0.0">
  <NamedLayer>
    <Name>WorldGen_Outline</Name>
    <UserStyle>
      <Title>xxx</Title>
      <FeatureTypeStyle>
        <Rule>
        <LineSymbolizer>
         <Geometry>
           <PropertyName>center-line</PropertyName>
         </Geometry>
         <Stroke>
           <CssParameter name="stroke">#0000ff</CssParameter>
         </Stroke>
        </LineSymbolizer>
        </Rule>
      </FeatureTypeStyle>
    </UserStyle>
  </NamedLayer>
</StyledLayerDescriptor>

When MapServer gets a valid SLD through a request, it parses this SLD to extract all the styles attached to the NamedLayers, and then it applies these styles to the map before it is returned to the client. When applying the SLD, MapServer compares the <Name> parameter of the NamedLayers in the SLD document to the WMS layer names (WMS layer names are available in a GetCapabilities request).

Note

All the examples given in this document are live uses of valid SLDs and a MapServer installation with SLD support.

Additional WMS features related to SLDs have also been developed:

Table1. Additional WMS Features

Features	Supported	Notes
Method GET : SLD URL	Yes
Method GET : SLD_BODY	Yes	Additional item
Describer Layer	Yes
GetLegendGraphic	Yes
GetStyles	Yes	Uses MapScript to get the SLD

Note

As of MapServer version 4.2.3, the GetLegendGraphic request (see section 12 of the Styled Layer Descriptor Implementation Specification) works as follows: if the RULE keyword is absent from the request, an image containing the entire legend for the specified layer will be returned. This image consists of the layer name and a symbolization graphic and label for each class.

Specific SLD Elements Supported

The following tables give a lot of additional details about SLD support in MapServer.

Table2. Named Layers and User Layers

Features	Supported	Notes
Named Layers	Yes
User Layers	No

Table3. Named Styles and User Styles

Features	Supported	Notes
Named Styles	Yes
User Styles	Yes

Table 4. User Styles

Features	Supported	Notes
Name	No	This was removed at implementation time, since it does not fit with MapServer
Title	No	No use in the MapServer environment
Abstract	No	No use in the MapServer environment
IsDefault	No	Only one style is available per layer
FeatureTypeStyle	Yes	MapServer has a concept of one feature type style per layer (either point, line, polygon, or raster)

Table 5. FeatureTypeStyle

Features	Supported	Notes
Name	No	No use in the MapServer environment
Title	No	No use in the MapServer environment
Abstract	No	No use in the MapServer environment
FeatureTypeName	No	No use in the MapServer environment
SemanticTypeIdentifier	No	Still an experimental element in the SLD specifications
Rule	Yes

Table 6. Rule

Features	Supported	Notes
Name	Yes
Title	Yes
Abstract	No	No use in the MapServer environment
LegendGraphic	Yes
Filter	Yes
ElseFilter	Yes
MinScaleDenominator	Yes
MaxScaleDenominator	Yes
LineSymbolizer	Yes
PolygonSymbolizer	Yes
PointSymbolizer	Yes
TextSymbolizer	Yes
RasterSymbolizer	Yes	Applies for 8-bit rasters

• Filter and ElseFilter

  For each rule containing a filter, there is a class created with the class expression set to reflect that filter. Available filters that can be used are Comparison Filters and Logical Filters (see the Filter Encoding HowTo). The ElseFilter parameters are converted into a class in MapServer and placed at the end of the class list with no expression set. They are used to render elements that did not fit into any other classes.

• MinScaleDenomibator and MaxScaleDenominator are translated in minscale and maxscale in MapServer.

The following are examples of valid requests using the Filters:

• line with one filter: sld 6a / full request 6a

• line with multiple filters: sld 6b / full request 6b

• line with one filter and an else filter: sld 6c / full request 6c

• spatial filter using BBOX: sld 6d/ full request 6d

• The above example enables spatial filtering using the BBOX parameter as a Filter for a selected area (Africa). Note that an ElseFilter will not work with a spatial filter.

Table 7. LineSymbolizer

Features	Supported	Notes
Geometry	No	MapServer uses the data geometry to do the rendering
Stroke: GraphicFill	No	Solid color is used
Stroke: GraphicStroke	Yes	Draws the symbol along the line
Stroke (CssParameter): stroke	Yes	RGB colors are supported
Stroke (CssParameter): width	Yes
Stroke (CssParameter): opacity	No	Not supported in MapServer
Stroke (CssParameter): linejoin and linecap	No	Not supported in MapServer
Stroke (CssParameter): dasharray	Yes
Stroke (CssParameter): dashoffset	No

The following are examples of valid requests using the LineSymbolizer:

• simple line: sld 7a / full request 7a

• line with width: sld 7b / full request 7b

• dashed line: sld 7c / full request 7c

Table 8. PolygonSymbolizer

Features	Supported	Notes
Geometry	No
Stroke	Yes	Strokes are the same as for the LineSymbolizer
Fill	Yes	Was developed to support symbol fill polygons in addition to solid fill

A Fill can be a solid fill or be a Graphic Fill, which is either a well-known Mark symbol (e.g., square, circle, triangle, star, cross, x) or an ExternalGraphic element (e.g., gif, png) available through a URL. When a Mark symbol is used in an SLD, MapServer creates a corresponding symbol in the map file and uses it to render the symbols. When a ExternalGraphic is used, the file is saved locally and a pixmap symbol is created in the mapfile referring to the this file. Note that the Web object IMAGEPATH is used to save the file.

The following are examples of valid requests using the PolygonSymbolizer:

• simple solid fill: sld 8a / full request 8a

• solid fill with outline: sld 8b / full request 8b

• fill with mark symbol: sld 8c / full request 8c

• fill with external symbol: sld 8d/ full request 8d

Table 9. PointSymbolizer

Features	Supported	Notes
Geometry	No
Graphic: Mark symbol	Yes	Well-known names (square, circle, triangle, star, cross, X) are supported
Graphic: ExternalGraphic	Yes	Was developed to support symbol fill polygons in addition to solid fill
Opacity	No	Not supported in MapServer
Size	Yes
Rotation	No	Not supported in MapServer

Note: refer to the PolygonSymbolizer notes for how the Mark and ExternalGraphic symbols are applied in MapServer.

The following are examples of valid requests using the PointSymbolizer:

• filled mark symbol: sld 9a / full request 9a

• default settings (square, size 6, color 128/128/128): sld 9b / full request 9b

• external symbol: sld 9c / full request 9c

Table 10. TextSymbolizer

Features	Supported	Notes
Geometry	No
Label	Yes
Font(font-family)	Yes	Font names used are those available in MapServer font file. If no fonts are available there, default bitmap fonts are used
Font-style (Italic, ...)	Yes
Font-weight	Yes
Font-size	Yes	If true-type fonts are not used, default bitmap sizes are given
LabelPlacement	Yes	PointPlacement is supported. LinePlacement is supported for versions >=5.2.1.
Halo	Yes	Supported (fill converted to outlinecolor, and radius is converted to outlinewidth. Note that outlinewidth is only available for AGG in >=5.2)
Fill	Yes	Only solid color is available

Notes on the TextSymbolizer:

• Font names: when converting Font parameters to MapServer, the following rule is applied to get the font name: FontFamily-FontStyle-FontWeight. For example, if there is an SLD with a Font Family of arial, a Font Style of italic, and a Font weight equal to bold, the resulting MapServer font name is arial-bold-italic. Font Style and Weight are not mandatory and, if not available, they are not used in building the font name. When a Font Style or a Font Weight is set to normal in an SLD, it is also ignored in building the name. For example, if there is an SLD with a Font Family of arial, a Font Style of normal and a Font weight equals to bold, the resulting MapServer font name is arial-bold.
• A TextSymbolizer can be used in MapServer either on an Annotation layer or on a Point, Line, or Polygon layer - in addition to other symbolizers used for these layers.
• PointPacement: a point placement includes AnchorPoint (which is translated to Position in MapServer) Displacement (which is translated to Offset) and Angle (which is translated to Angle).
• Angle setting: by default the angle parameter is set to AUTO. For point features, users can use the PointPlacement to alter the value. For line features, the user can add a LinePlacement: If an ‘empty’ LinePlacement is part of the SLD, the angle will be set to to FOLLOW, If a LinePlacement contains the PerpendicualarOffset parameter, the angle withh be set to 0 and the PerpendicualarOffset will be used to set the offset values in the label object.

The following are examples of valid requests using the TextSymbolizer:

• annotation layer : test for label, font, point placement, color, angle: sld 10a / full request 10a

• annotation layer with text and symbols using 2 symbolizers: sld 10b / full request 10b

• line layer with text using 2 symbolizers: sld 10c / full request 10c

Table 11. RasterSymbolizer

Features	Supported	Notes
Geometry	No
Opacity	Yes
ChannelSelection	No
OverlapBehaviour	No
ColorMap	Yes
ContrastEnhancement	No
ShadedRelief	No
ImageOutline	No

The current support in MapServer includes only ColorMap parameter support. It can be used to classify 8-bit rasters. Inside the ColorMap parameters, the color and quantity parameters are extracted and used to do the classification.

Table 12. ColorMap

Features	Supported	Notes
Color	Yes
Opacity	No
Quantity	Yes
Label	No

The following is an example of ColorMap usage.

If we have following ColorMap in an SLD:

<ColorMap>
  <ColorMapEntry color="#00ff00" quantity="22"/>
  <ColorMapEntry color="#00bf3f" quantity="30"/>
  <ColorMapEntry color="#007f7f" quantity="37"/>
  <ColorMapEntry color="#003fbf" quantity="45"/>
  <ColorMapEntry color="#0000ff" quantity="52"/>
  <ColorMapEntry color="#000000" quantity="60"/>
</ColorMap>

The six classes that are created are:

class 1: [pixel] >= 22 AND [pixel] < 30 with color 00ff00
class 2: [pixel] >= 30 AND [pixel] < 37 with color 00bf3f
class 3: [pixel] >= 37 AND [pixel] < 45 with color 007f7f
class 4: [pixel] >= 45 AND [pixel] < 52 with color 003fbf
class 5: [pixel] >= 52 AND [pixel] < 60 with color 0000ff
class 6: [pixel] = 60 with color 000000

Note that the ColorMapEntry quantity parameters should be in increasing order.

Examples using 8 bits and 16 bits rasters can be seen at:

• example 1
• example 2

Client Side Support

Client side support of the SLD consists of two parts:

• The first part is using MapServer as a WMS client to send a GetMap request with an SLD. This is done using two metadata that can be placed at a layer level in a MapServer mapfile. These two metadata are:

  • wms_sld_url, which takes a valid URL as a value and appends SLD=xxx to the GetMap request.
  • wms_sld_body, which takes a valid SLD string and appends SLD_BODY=xxx to the GetMap request. If the value of wms_sld_body is set to AUTO, MapServer generates an SLD based on the classes found in the layer and send this SLD as the value of the SLD_BODY parameter in the GetMap request.

• The other major item is the generation of an SLD document from MapServer classes. These functions are currently available through MapServer/MapScript interface. Here are the functions available:

  • on a map object: generatesld
  • on a layer object: generatesld

  Additional MapScript functions have been added or will be added to complement these functions:

  • on a map object: applysld
  • on a layer object: applysld

Note

When generating an SLD from MapServer classes, if there is a pixmap symbol you need to have this symbol available through a URL so it can be converted as an ExternalGraphic symbol in the SLD. To do this, you need to define the URL through a web object level metadata called WMS_SLD_SYMBOL_URL in your map file. The SLD generated uses this URL and concatenates the name of the pixmap symbol file to get the value that is generated as the ExternaGraphic URL.

PHP/MapScript Example that Generates an SLD from a Mapfile

The following is a small script that calls the generateSLD() function to create an SLD for a specific layer in a mapfile:

<?php

// define variables
define( "MAPFILE", "D:/ms4w/apps/cadastra/map/cadastra.map" );
define( "MODULE", "php_mapscript.dll" );

// load the mapscript module
if (!extension_loaded("MapScript")) dl(MODULE);

// open map
$oMap = ms_newMapObj( MAPFILE );

// get the parcel layer
$oLayer = $oMap->getLayerByName("parcel");

// generate the sld for that layer
$SLD = $oLayer->generateSLD();

// save sld to a file
$fp = fopen("parcel-sld.xml", "a");
fputs( $fp, $SLD );
fclose($fp);

?>

Named Styles support

Named styles support are introduced in MapServer 5.2. The support is base on MS RFC 39: Support of WMS/SLD Named Styles

MapServer 5.2 introduces the possibility to assign a group to a series of classes defined on a layer object using two new non-mandatory keywords CLASSGROUP (at the layer level) and GROUP at the class level:

LAYER
    ...
    CLASSGROUP "group1"
    ...
    CLASS
        NAME "name1"
        GROUP "group1"
        ...
    END
    CLASS
        NAME "name2"
        GROUP "group2"
        ...
    END
    CLASS
        NAME "name3"
        GROUP "group1"
        ...
    END
    ...

At rendering time, if the CLASSGROUP is defined, only classes that have the same group name would be used. Based on this concept, WMS/SLD support uses the class groups as named styles. Each group of classes is considered equivalent to a named style:

• The GetCapbilities request will output all the styles that are available
• The GetMap request can use the STYLES parameter to specify a named style
• The GetLegendGraphic can use the STYLES parameter to specify a named style

Other Items Implemented

• Support of filled polygons with Mark and ExternalGraphic symbols.
• MapScript functions to parse and apply SLD.
• SLD_BODY request support on client and server side.

Issues Found During Implementation

• Limitation of the FilterEncoding to comparison and logical filters. The spatial filters were not made available since it required major changes in MapServer WMS support.