KML and Google Earth Features

KML Reflector

WMS Convenience Wrapper for KML

Overview

Standard WMS requests can be quite long and verbose. For instance like the following:

http://localhost:8080/geoserver/wms?service=WMS&request=GetMap&version=1.1.1&format=application/vnd.google-earth.kml+XML&width=1024&height=1024&srs=EPSG:4326&layers=topp:states&styles=population&bbox=-180,-90,180,90

Typing into a browser can be quite cumbersome and error prone. Not to mention repetitive as many of the parameters do not change. The KML Reflector solves this problem nicely. The reflector concept involves filling in sensible defaults for many of the paramaters of a standard WMS request so the user does not have to. Using the reflector one can shorten the above request to:

http://localhost:8080/geoserver/wms/kml_reflect?layers=topp:states

Using the KML Reflector

To use the KML reflector all one must do is specify wms/kml_reflect? as opposed to wms? in a request. The only mandatory parameter to a kml reflector call is the layers parameter. As stated above the reflector fills in sensible defaults for the rest of the parameters. The following table lists all the defaults used:

The styles parameter is derived by using the default style as configured by GeoServer for each layer specified in the layers parameter.

Any of these defaults can be overridden when specifying the request. For instance if one wanted to specify a particular style to be used:

http://localhost:8080/geoserver/wms/kml_reflect?layers=topp:states&styles=population

Or to specify a particular bounding box:

http://localhost:8080/geoserver/wms/kml_reflect?layers=topp:states&bbox=-124.73,24.96,-66.97,49.37

Custom Descriptions

Controlling the description element (balloon pop-up) of your KML

Overview

When GeoServer generates KML for a vector dataset, it attaches information from the data to each Placemark that is created. By default this is a simple HTML table which displays all the attribute data (metadata in KML terms).

In some cases this is not ideal. For instance if some of the attributes of the dataset are sensitive and not to be made public. In this case it is possible to use the KMATTR parameter in a KML request to turn off attribution.

Specifying KMATTR

Specifying KMATTR in a request easy.. All one must do is append the parameter "kmattr=<true|false>" to a KML request. For example:

http://localhost:8080/geoserver/wms/kml_reflect?layers=topp:states*kmattr=false

Attribution with Templates

An alternative to simply turning attribution off is use a template to customize which attributes are attached to a Placemark. Applying templates to KML Placemarks is described in detail here. There is also an in depth tutorial that hits on many of the powerful things one can do.

Scoring

Introduction

GeoServer can return KML in one of two forms. The first is as a number of Placemark elements. Each Placemark corresponds to a feature in the underlying dataset. This form only applies to vector datasets.

The second form is as an Overlay element. In this form the rendering is done by the GeoServer WMS and only the resulting image is sent to Google Earth. This is the only form available for raster datasets, but can be applied to vector datasets as well.

Both forms are available for vector datasets, which one is used is driven by the size of the dataset. The first (Placemark) form looks nicer but if the dataset is large then the amount of data can cause Google Earth to hang trying to process it all. Having GeoServer render as an Overlay puts less of a strain on Google Earth, but unfortunately does not look as good.

The following shows the same dataset rendered in Placemark form on the left and Overlay form on the right.

KML Scoring

Luckily the user usually does not have to worry about this. GeoServer is smart enough to figure out which form should be used on its own based on the amount of data that is being queried. A threshold value is used for which if the number of features returned is greater then a certain value then the Overlay form is used. Determining this threshold value is called KML Scoring.

By default, GeoServer will use Overlay form if more then 2154 features are being returned to Google Earth. However this value can be controlled by the user via the KMSCORE parameter. The KMSCORE parameter is specified as part of a KML request and is an integer value between 0 and 100. The default value for this parameter is 50. If you have a high powered computer you can likely set this higher and get back more vector data.

GeoServer uses the following formula to calculate the feature threshold value:

number of features = 10^(KMSCORE/15)

The following shows the values of the feature threshold for different values of the KMSORE parameter:

KMSCORE Number of Features 0 Always Raster 10 4 20 21 30 100 40 464 50 2154 60 10000 70 46415 80 215443 90 1000000 99 3981071 100 Always Vector

Specifying KMSCORE

Specifying KMSCORE in a request easy.. All one must do is append the parameter "kmscore=<value>" to a KML request. For example:

http://localhost:8080/geoserver/wms/kml_reflecet?layers=topp:states&kmscore=20

Legend Overlays

KML Legend Overlays

Overview

One of the operations of WMS is GetLegendGraphic which allows a WMS client to obtain a legend graphic from the server for a particular layer. Combining it with KML overlays produces a nice way to produce legends in Google Earth.

Using Legend Overlays

Getting GeoServer to return KML with a legend overlay is easy. All one must do is append the parameter "legend=true" to a KML request. For example:

http://localhost:8080/geoserver/wms/kml_reflect?layers=topp:states&legend=true

Google Earth aggressively caches overlays. Which means if you change a style in GeoServer expecting it to impact the look of your legend overlay chances are it will not until you restart Google Earth.

Super-Overlays

Overview

Super-Overlays are a form of KML in which data is broken up into regions. This allows Google Earth to refresh/request only particular sections of the map when the view area changes. Super overlays are used to efficiently publish large sets of imagery.  GeoServer supports two types of super-overlays, raster super-overlays and vector super-overlays.  In a raster overlay Google Earth recieves a single image file for each region, while in vector overlays it receives information about each feature.  This means that raster overlays require less resources on the client machine running Google Earth, but vector-overlays look much nicer, as well as adding clickable popups with more information about features (see http://geoserver.org/display/GEOSDOC/02+Custom+Descriptions for details on these popups).

With super overlays, regions or tiles form a hierarchy. Each level of the hierarchy corresponds to a particular image resolution. Tiles that are lower in the hierarchy correspond to higher resolution. This allows Google Earth to progressively load higher resolution imagery as a user zooms in on the map.

GeoServer takes all the pain out of Super-Overlay creation, as it automatically creates the proper hierarchy and tiles the data. The only thing to be done is to add your data to GeoServer. It can tile vector data, but it truly shines with large raster data (GeoTiff, ArcGrid, GTOPO30, ImageFiles, and soon MrSID).  For vector data, see the section below on Vector Super-Overlays.

Consider the above tile which is at some level n of our hierarchy. As we zoom in we see higher resolution tiles for the next level n+1 are loaded.

Using Raster Super Overlays

Getting GeoServer to return KML as a raster super overlay is easy. All one must do is append the parameter "superoverlay=true" to a KML request. For example:

http://localhost:8080/geoserver/wms/kml_reflect?layers=nurc:Img_Sample&superoverlay=true

Raster Super Overlays and Tiling

GeoServer implements super overlays in a way that is compatible with the WMS Tiling Client Recommendation. Super overlays are generated in such a way that the regions of tiles of the super overlay are the same tiles that a WMS tiling client would request. The upshot of this is that one can use existing tile caching mechanisms and reap a potentially large performance benefit.

This tutorial walks through the process of setting up super overlays with tile caching.

 Vector Super-Overlays

KML has support for including the feature information directly in the KML document and letting Google Earth to the rendering.  This has lots of great benefits like allowing the user to select features to see HTML descriptions and toggle the display of individual features, as well as better looking rendering when the zoom level doesn't match that of the graphics provided by GeoServer.  For large datasets, however, all of this feature information can take a long time to download and use a lot of client side-resources for Google Earth to render.  For such data sets, vector overlays allow the client to only download part of a dataset when viewing the entire map, and pull more information down as he or she zooms in.

 Using Vector Super-Overlays

GeoServer will automatically do most of the work in generating vector super-overlays.  However, because vector super-overlays work by omitting some of the data, rather than delivering it pre-rendered as raster super-overlays do, you must provide GeoServer a hint as to which features should be shown before others, known as a "regionating strategy."  Regionating strategies can be specified in the request using a GeoServer-specific format option, in the form 'format_options=regionateby:<strategy>;regionateattr:<attribute>".  (more on format_options can be found at http://geoserver.org/display/GEOSDOC/02+Custom+Descriptions).&nbsp; For example, to regionate the topp:states layer that is included in the geoserver installer, using the 'population' attribute, the request would look like

http://localhost:8080/geoserver/wms/kml_reflect?layers=topp:states;regionateattr:population

GeoServer currently supports two regionating strategies: "data" and "sld" .  The "data" strategy uses the attribute given in the request to sort the features, features with higher values of the attribute will appear higher up in the tile hierarchy.  The "sld" strategy uses the style for the request to determine which features to include; features that are not rendered by the style will be omitted from the KML.  (This is the default behavior if no regionating strategy is specified.)  However, using these strategies in a request returns only the individual tiles.

Using GeoWebCache With GeoServer for Vector Super-Overlays

Since GeoServer does not generate a fully browsable hierarchy, you'll need a little help from some software that can combine a set of KML tiles into such a hierarchy.  GeoWebCache does just that, and there is a handy plugin you can use to deploy it within GeoServer.  Just download and install it as described at http://geoserver.org/display/GEOSDOC/GeoWebCache. In order to configure the regionating strategy used by GeoWebCache, go into the normal GeoServer configuration settings, where you'll see options labelled "KML Regionating Attribute" and "KML Regionating Strategy" which specify the values for GeoWebCache to use.  Once these values are set, you can point Google Earth at

http://localhost:8080/geoserver/gwc/service/kml/topp:states.kml.kmz

to see your vector super-overlay (replace topp:states with the name of your layer, of course).  

Under Development Super overlays are still under active development. Please try it out and report any bugs in the issue tracker

Time Visualization

Overview

One of the slickest features of Google Earth is the time slider, which allows you to visualize changes in a dataset over time. As of version 1.5.2 GeoServer makes it very simple to convert existing geospatial data that has a time element in to Google Earth.

Using Time with GeoServer

To use time with GeoServer you need a dataset that has a time or date as one of the elements. To use it in GeoServer you make a 'template' file called time.ftl, and place it in the featureTypes directory. GeoServer will then return the proper values to Google Earth, and the time slider will automatically appear. For more information on setting this up, see the Time Template Tutorial.

Filtering Data

Overview

Though not a specific Google Earth feature, GeoServer has a powerful capability to limit the data returned based on a query passed in by the user. The KML Reflector will pass through any 'FILTER' or 'CQL_FILTER" parameter to GeoServer to constrain the response. Filters are basically a translation of a SQL 'WHERE' statement in to web form, and allow the full power of SQL, though limited to a single table. One can do logical filters, like AND and OR, to make very complex queries, leveraging numerical and string comparisons, geometric operations (bbox, touches, intersects, disjoint), LIKE statements, nulls, and more.

OGC Filters

There is an open standard put out by the Open Geospatial COnsortium called 'Filter Encoding' GeoServer implements the full spec, so read it for the full language with examples.

There simplest filter is very easy to include. It is called the 'featureid' filter, and it lets you grab a single feature by saying its id:

This request will take you to the state of Maryland. The featureids of your data are most easily found by doing WFS requests and examining the resulting GML. KML output will also include the featureids if there is not a template that overrides it.

After the basics using Filters in a URL gets a little out of hand, as one is supposed to include a full XML filter inside the url, like:

So we don't recommend using those. Instead there is CQL, which allows one to specify the same long statement much more succinctly.

CQL Filters

See Common Query Language (CQL) Tutorial (unfinished) for an introduction to CQL queries.

For right here we'll just demonstrate what the above query would be in CQL:

Which is much more compact. That query will get you all the states in the US with square kilometers of land between 100,000 and 150,000:

Placemarks For Raster Output

Adding placemarks when the KMScore decides on raster output

Overview

Normally when a raster image is returned, there is no extra data returned such as the name of the feature. This is normally only returned when KML is returned. But in the example of your viewport zoomed in to a small area of a very large feature, it would normally have to return that whole large feature - which can be slow. With KMSCORE and KMZ output, you can speed this up by returning a raster image instead. But without additional information such as the name of the feature, this is not always useful. 

The KMPLACEMARK format option can be used to provide placemarks in addition to the raster image; one folder for each image and one placemark for each feature polygon. Each placemark will display the name of the polygon, placed in the same location as the polygon's label would be. The placemark's description field may contain non-spatial attribute values as per the feature type's description template.

Specifying KMPLACEMARK

To specify KMPLACEMARK, simply add format options to the request url and specify "kmplacemark:<true|false>". For example:

http://localhost:8080/geoserver/wms?service=WMS&request=GetMap&format=application/vnd.google-earth.kml+XML
&width=1024&height=1024&srs=EPSG:4326&layers=topp:states&styles=population&bbox=-180,-90,180,90
&format_options=kmplacemark:true

If the KMPLACEMARK option is set to false or is not specified, then the behaviour will revert to the default of not adding placemarks.

Note that this can be used with the new KML reflector, but not with the deprecated version. For example, this will work:

http://localhost:8080/geoserver/kml/wms?layers=topp:states&format_options=kmplacemark:true

while this will not:

http://localhost:8080/geoserver/wms/kml_reflect?layers=topp:states&format_options=kmplacemark:true