Comprehensive Guide to Styling KML

Points
Lines
Polygon
Labels
Descriptions

Introduction

In GeoServer KML is styled via Styled Layer Descriptor (SLD). This is the same approach used to style regular WMS output formats like rasters. The philosophy is a bit different from how Google Earth is normally styled, and indeed is a bit more like CSS. The style of the map is specified in the SLD file, as a series of rules, and then the data matching those rules is styled appropriately in to KML. One can have multiple SLD files used for the same datasets, and users can even create their own SLD files for the server to render. For those unfamiliar with SLD a good introduction can be found here. The remainder of this guide contains information about how to construct SLD documents in order to impact the look of KML produced by GeoServer.

Basic SLD Creation Wizard

In the FeatureType editor (Config -> Data -> FeatureTypes -> Edit) there is basic SLD creation wizard, reached by hitting the 'Create new SLD' button:

A new screen will appear that allows you to customize how your data will appear on a map. This page may differ slightly depending on what data you use. Just be sure to fill in all the required fields. Click the squares next to 'Text Color,' and 'Color of the lines' to select a color. Decide how wide, in pixels, you want your lines to be and enter that number in the 'Line dimensions' box. Click 'Apply Style' and then 'Finished'

SLD files

The following is a skeleton of a SLD document. It can be used as a base on which to expand upon to create more interesting and complicated styles.

<StyledLayerDescriptor version="1.0.0" 
		xsi:schemaLocation="http://www.opengis.net/sld StyledLayerDescriptor.xsd" 
		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">

	<NamedLayer>
		<Name>Default Line</Name>
		<UserStyle>
			<Title>Skeleton</Title>
			<Abstract>A skeleton style</Abstract>
			<FeatureTypeStyle>
                              <Rule>
                                  <!-- symbolizers go here -->
                               </Rule>
                        </FeatureTypeStyle>
		</UserStyle>
	</NamedLayer>
</StyledLayerDescriptor>

To edit or add new SLD files to GeoServer, go to Config -> Data -> Styles in the web admin.

Points

In SLD styles for points are specified via a PointSymbolizer. An empty PointSymbolizer element will result in a default KML style:

<PointSymbolizer>
</PointSymbolizer>

The two aspects of the resulting point which can be specified via a PointSymbolizer are color and opacity.

Color

The color of a point is specified with a CssParameter element and a fill attribute. The color is specified as a 6 digit hex code.

<PointSymbolizer>
   <Graphic>
     <Mark>
        <Fill>
            <CssParameter name="fill">#ff0000</CssParameter>
        </Fill>
     </Mark>
   </Graphic>
</PointSymbolizer>

Opacity

The opacity of a point is specified with a CssParameter element and a fill-opacity attribute. The opacity is specified as a floating point number between 0 and 1.

<PointSymbolizer>
   <Graphic>
     <Mark>
        <Fill>
            <CssParameter name="fill-opacity">0.5</CssParameter>
        </Fill>
     </Mark>
   </Graphic>
</PointSymbolizer>

Icon

By default a point will be rendered with the icon. A different icon can be specified with the ExternalGraphic element:

<PointSymbolizer>
   <Graphic>
     <ExternalGraphic>
        <OnlineResource xlink:type="simple" xlink:href="http://maps.google.com/mapfiles/kml/pal3/icon55.png"/>
        <Format>image/png</Format>
     </ExternalGraphic>
   </Graphic>
</PointSymbolizer>

In the above example the custom icon is specified as a remote url. It is also possible to specify a relative url:

<PointSymbolizer>
   <Graphic>
     <ExternalGraphic>
        <OnlineResource xlink:type="simple" xlink:href="icon55.png"/>
        <Format>image/png</Format>
     </ExternalGraphic>
   </Graphic>
</PointSymbolizer>

In this case the file icon55.png must be located in the styles directory of the GeoServer data directory.

Lines

In SLD styles for lines are specified via a LineSymbolizer. An empty LineSymbolizer element will result in a default KML style:

<LineSymbolizer>
</LineSymbolizer>

The aspects of the resulting line which can be specified via a LineSymbolizer are color,width, and opacity.

Color

The color of a line is specified with a CssParameter element and a stroke attribute. The color is specified as a 6 digit hex code.

<LineSymbolizer>
   <Stroke>
      <CssParameter name="stroke">#ff0000</CssParameter>
   </Stroke>
</LineSymbolizer>

Width

The width of a line is specified with a CssParameter element and a stroke-width attribute. The color is specified as an integer:

<LineSymbolizer>
   <Stroke>
      <CssParameter name="stroke-width">5</CssParameter>
   </Stroke>
</LineSymbolizer>

Opacity

The opacity of a line is specified with a CssParameter element and a stroke-opacity attribute. The opacity is specified as a floating point number between 0 and 1.

<LineSymbolizer>
   <Stroke>
      <CssParameter name="stroke-opacity">0.5</CssParameter>
   </Stroke>
</LineSymbolizer>

Polygons

In SLD styles for polygons are specified via a PolygonSymbolizer. An empty PolygonSymbolizer element will result in a default KML style:

<PolygonSymbolizer>
</PolygonSymbolizer>

The aspects of the resulting line which can be specified via a PolygonSymbolizer are outline color, outline width, outline opacity, fill color, and fill opacity.

Outline Color

The outline color of a polygon is specified with a CssParameter element and stroke attribute inside of a Stroke element. The color is specified as a 6 digit hex code:

<PolygonSymbolizer>
  <Stroke>
     <CssParameter name="stroke">#0000FF</CssParameter>
  </Stroke>
</PolygonSymbolizer>

Outline Width

The outline width of a polygon is specified with a CssParameter element and stroke-width attribute inside of a Stroke element. The width is specified as an integer.

<PolygonSymbolizer>
  <Stroke>
     <CssParameter name="stroke-width">5</CssParameter>
  </Stroke>
</PolygonSymbolizer>

Outline Opacity

The outline opacity of a polygon is specified with a CssParameter element and stroke attribute inside of a Stroke element. The opacity is specified as a floating point number between 0 and 1.

<PolygonSymbolizer>
  <Stroke>
     <CssParameter name="stroke-opacity">0.5</CssParameter>
  </Stroke>
</PolygonSymbolizer>

Fill Color

The fill color of a polygon is specified with a CssParameter element and fill attribute inside of a Fill element. The color is specified as a 6 digit hex code:

<PolygonSymbolizer>
  <Fill>
     <CssParameter name="fill">#0000FF</CssParameter>
  </Fill>
</PolygonSymbolizer>

Fill Opacity

The fill opacity of a polygon is specified with a CssParameter element and fill-opacity attribute inside of a Fill element. The opacity is specified as a floating point number between 0 and 1.

<PolygonSymbolizer>
  <Fill>
     <CssParameter name="fill-opacity">0.5</CssParameter>
  </Fill>
</PolygonSymbolizer>

Labels

In GeoServer there are two ways to specify a label for a feature/placemark. The first is with a template, the second is with a text symbolizer. The template takes precedence over the symbolizer.

1. Template

Specifying labels via a template involves creating a special template file called title.ftl and placing it into the feature type directory (under the GeoServer data directory) for the dataset to be labeled. For instance to create a template to label the states dataset by state name one would create the file: <datadir>/featureTypes/title.ftl. The content of the file would be:

${STATE_NAME.value} State

A full tutorial on how to use templates to create labels is available here.

2. TextSymbolizer

In SLD labels are specified with the Label element of a TextSymbolizer:

<TextSymbolizer>
  <Label>
    <ogc:PropertyName>STATE_NAME</ogc:PropertyName>
  </Label>
  <Font>
  </Font>
</TextSymbolizer>

Note the "ogc:" prefix on the PropertyName element.

The aspects of the resulting label which can be specified via a TextSymbolizer are color and opacity.

Color

The color of a label is specified with a CssParameter element and fill attribute inside of a Fill element. The color is specified as a 6 digit hex code:

<TextSymbolizer>
  <Label>
    <ogc:PropertyName>STATE_NAME</ogc:PropertyName>
  </Label>
  <Font>
  </Font>
  <Fill>
    <CssParameter name="fill">#000000</CssParameter>
  </Fill>
</TextSymbolizer>

Opacity

The opacity of a label is specified with a CssParameter element and fill-opacity attribute inside of a Fill element. The opacity is specified as a floating point number between 0 and 1:

<TextSymbolizer>
  <Label>
    <ogc:PropertyName>STATE_NAME</ogc:PropertyName>
  </Label>
  <Font>
  </Font>
  <Fill>
    <CssParameter name="fill-opacity">0.5</CssParameter>
  </Fill>
</TextSymbolizer>

Descriptions

In KML each feature/placemark has a description which is a blurb of html which describes the feature. By default GeoServer creates an HTML table which displays all the attributes of the feature.

It is possible to change this behaviour with a template. This involves creating a special template filed called description.ftl and placing it into the feature type directory (under the GeoServer data directory) for the dataset. For instance to create a template to provide a description for the states dataset one would create the file: <datadir>/featureTypes/title.ftl. The content of the file could be:

This is the state of ${STATE_NAME.value}.

A full tutorial on how to use templates to create descriptions is available here.