Home | Docs | Issue Tracker | FAQ | Download | |
Author: | Jeff McKenna |
---|---|
Contact: | jmckenna at gatewaygeomatics.com |
Author: | Yewondwossen Assefa |
Contact: | assefa at dmsolutions.ca |
Last Updated: | 2011-01-14 |
Contents
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:
There are two ways a WMS request can pass an SLD document with a GetMap request to MapServer:
These two methods are both available through MapServer. An example of a request would be:
http://demo.mapserver.org/cgi-bin/wms?SERVICE=wms&VERSION=1.1.1&REQUEST=GetMap
&LAYERS=country_bounds&SLD=http://demo.mapserver.org/ogc-demos/map/sld/sld_line_simple.xml
Test the remote SLD request.
The SLD in the above request follows:
<?xml version="1.0" encoding="UTF-8"?>
<StyledLayerDescriptor version="1.0.0"
xmlns="http://www.opengis.net/sld"
xmlns:ogc="http://www.opengis.net/ogc"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.opengis.net/sld
http://schemas.opengis.net/sld/1.0.0/StyledLayerDescriptor.xsd">
<NamedLayer>
<Name>country_bounds</Name>
<UserStyle>
<Title>xxx</Title>
<FeatureTypeStyle>
<Rule>
<LineSymbolizer>
<Geometry>
<ogc:PropertyName>center-line</ogc:PropertyName>
</Geometry>
<Stroke>
<CssParameter name="stroke">#0000ff</CssParameter>
</Stroke>
</LineSymbolizer>
</Rule>
</FeatureTypeStyle>
</UserStyle>
</NamedLayer>
</StyledLayerDescriptor>
Version 1.1.0 of the same SLD
<?xml version="1.0" encoding="UTF-8"?>
<StyledLayerDescriptor version="1.1.0"
xmlns="http://www.opengis.net/sld"
xmlns:se="http://www.opengis.net/se"
xmlns:ogc="http://www.opengis.net/ogc"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.opengis.net/sld
http://schemas.opengis.net/sld/1.1.0/StyledLayerDescriptor.xsd">
<NamedLayer>
<se:Name>country_bounds</se:Name>
<UserStyle>
<se:Name>xxx</se:Name>
<se:FeatureTypeStyle>
<se:Rule>
<se:LineSymbolizer>
<se:Geometry>
<ogc:PropertyName>center-line</ogc:PropertyName>
</se:Geometry>
<se:Stroke>
<se:SvgParameter name="stroke">#0000ff</se:SvgParameter>
</se:Stroke>
</se:LineSymbolizer>
</se:Rule>
</se: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.
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:
- 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 | Yes | Only available for AGG driver and mapserver version >=5.2 |
Stroke (CssParameter): linejoin and linecap | No | Not supported in MapServer |
Stroke (CssParameter): dasharray | Yes | |
Stroke (CssParameter): dashoffset | No | |
PerperdicularOffset (only in SLD 1.1.0) | Yes | Offset values of the style object will be set |
InitialGap(GraphicStroke SLD 1.1.0) | No | |
Gap (GraphicStroke parameter SLD 1.1.0) | No |
Note that SvgParameter instead of CssParameter are required for SLD 1.1.0.
The following are examples of valid requests using the LineSymbolizer:
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 |
Fill-opacity | Yes | Only available for AGG driver and mapserver version >=5.2 |
PerperdicularOffset | No | SLD 1.1.0 parameter |
Displacement | Yes | SLD 1.1.0 parameter. Sets offsetx/y in MapServer |
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:
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 | Yes | Support added in MapServer 5.4 |
Size | Yes | |
Rotation | Yes | Support added in MapServer 5.4 |
Displacement | Yes | SLD 1.1.0 Paramater. Support added in MapServer 5.4 |
AnchorPoint | No |
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:
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. Only PerperdicularOffset and IsAligned are suported for LinePlacement. |
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:
The following are examples of valid requests using the TextSymbolizer:
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
The following Features are available in SLD 1.0
Features | Supported | Notes |
---|---|---|
Color | Yes | |
Opacity | No | |
Quantity | Yes | |
Label | No |
The following is an example of ColorMap usage for SLD 1.0.
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.
The following Features are available in SLD 1.1
Features | Supported | Notes |
---|---|---|
Categorize | Yes |
The following is an example of and SLD 1.1.0 with a raster symbolizer
<StyledLayerDescriptor version="1.1.0" xsi:schemaLocation="http://www.opengis.net/sld http://schemas.opengis.net/sld/1.1.0/StyledLayerDescriptor.xsd" xmlns="http://www.opengis.net/sld" xmlns:ogc="http://www.opengis.net/ogc" xmlns:se="http://www.opengis.net/se" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<NamedLayer>
<se:Name>landsat</se:Name>
<UserStyle>
<se:Name>xxx</se:Name>
<se:FeatureTypeStyle>
<se:Rule>
<se:RasterSymbolizer>
<se:Opacity>0.7</se:Opacity>
<se:ColorMap>
<se:Categorize fallbackValue="#78c818">
<se:LookupValue>Rasterdata</se:LookupValue>
<se:Value>#ffffff</se:Value>
<se:Threshold>22</se:Threshold>
<se:Value>#00ff00</se:Value>
<se:Threshold>30</se:Threshold>
<se:Value>#00bf3f</se:Value>
<se:Threshold>37</se:Threshold>
<se:Value>#007f7f</se:Value>
<se:Threshold>45</se:Threshold>
<se:Value>#003fbf</se:Value>
<se:Threshold>52</se:Threshold>
<se:Value>#0000ff</se:Value>
<se:Threshold>60</se:Threshold>
<se:Value>#000000</se:Value>
</se:Categorize>
</se:ColorMap>
</se:RasterSymbolizer>
</se:Rule>
</se:FeatureTypeStyle>
</UserStyle>
</NamedLayer>
</StyledLayerDescriptor>
The classes that are created are:
class 1: [pixel] < 22 with color ffffff
class 2: [pixel] >= 22 AND [pixel] < 30 with color 00ff00
class 3: [pixel] >= 30 AND [pixel] < 37 with color 00bf3f
class 4: [pixel] >= 37 AND [pixel] < 45 with color 007f7f
class 5: [pixel] >= 45 AND [pixel] < 52 with color 003fbf
class 6: [pixel] >= 52 AND [pixel] < 60 with color 0000ff
class 7: [pixel] >= 60 with color 000000
Examples using 8 bits and 16 bits rasters can be seen at:
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:
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:
Additional MapScript functions have been added or will be added to complement these functions:
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.
The following is a small script that calls the generateSLD() function to create an SLD for a specific layer in a mapfile:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | <?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");
// force visibilty of the layer
$oLayer->set('status', MS_ON);
// 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 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: