KMLMapServer turns your UMN MapServer installation in a flexible KML vector and raster data server. Dynamically serve your MapServer data straight into Google Earth.
The goal of this project is to add KML output capabilities to any running MapServer installation. It will run out-of-the-box with zero or minimal configuration. Basically you just install this package somewhere under you web server root and it will work without any configuration. Configuration, if needed, is done through metadata in the MapServer’s mapfile, so you don’t have any other configuration files to worry about.
This project comes from a simple idea: while we already have quite a few running MapServer installations, most of them are related to mountain hiking and trekking. A 3-dimensional view of the territory can bring a significative advantage while planning your holidays in the mountains. So we decided to start this project, in order to display our paths and tracks data in a 3D view using Google Earth.
In order to add KML server capabilities to you MapServer installation, you should have:
- a running UMN MapServer CGI, possibly configured as WFS server if you want to serve raster layers too
- PHP5 with php_mapscript
How it works
The layer server
KMLMapServer was designed with OGC webservices in mind, when possible, the parameter names and meaning are the same as in WFS OGC service, and you normally call KMLMapServer with CGI-style parameters passed on the URL.
A typical call would be:
In this example the layers “roads” and “rivers” from mapfile /maps/mapfile.map are sent to the browser.
Note that you don’t need to specify the layer name(s), you can also get a KML with all the layers in the mapfile, in this case the layers will be served as a folder of Network Links.
The icon server
The icon server is an independent package that creates PNG images of the symbols used for point layers.
It is called through the same endpoint of the main service, the request type is “icon”.
See the image for some example symbols how they appear in the table of contents (click to enlarge).
- KML and KMZ (compressed) output
- Simple cache system to reduce server load with big vector data layers
- Independent symbol server for POINT layers icons
- Customizable Balloons (tooltips) in Google Earth with attribute substitution template
- Limited support to MapServer’s classes and styles for thematic mapping
- Limited support to ogc filter encoding for single vector layer requests
- Raster support through WMS network links
Known issues, limitations
- Styles and classes:
- only one style for each class is parsed, if you have multiple styles in one class, the values of the last one are used
- only color, outlinecolor, backgroundcolor, symbol, size and width are parsed
- Filled polygons:
- filled polygons fail to wrap on the mountains (this seems a Google Earth bug), a define(‘TREAT_POLY_AS_LINE’, true) control this behaviour
- polygons boundaryes do not clamp to ground correctly (this also seems a Google Earth bug), define(‘TREAT_POLY_AS_LINE’, true) convert them in line strings
Most of KMLMapServer features should work without any additional configuration.
Configuration is done through CGI-style values passed on the query string and with special metadata in the mapfile
|request||string||no||kml kmz icon||request type (OGC WFS like)|
|map||string||yes||path to mapfile|
|typename||string (can be a CSV list)||no||layer(s) to be served, if empty all layers are served as network links|
|filter||string||no||well formed XML OGC filter, is active only when a single layer is requested|
|bbox||string||no||standard bbox (not yet implemented)|
|encoding||string||no||mapfile and attributes encoding, default to ISO-8859-1|
KMLMapServer re-use most of existing OGC metadata taken from the LAYER section of the mafile, and define a few of its own.
None of them are required, but if you want to serve rasters you already need them in order to have a working WMS MapServer installation.
Note for rasters: add EPSG:4326 to WMS_SRS metadata on all mapfile layers, otherwise WMS will not work with Google Earth.
|RESULT_FIELDS||The column from which to take the name for the feature||Vector||Defaults to the first column, the name is displayed in Google Earth Balloons and table of contents|
|DESCRIPTION_TEMPLATE||Custom description template||Vector||If present, this is used to build the description string. Parameters surrounded by “%” char are substituted with real values from the corresponding field for the feature|
|BALLOON_TEMPLATE||Custom balloon (tooltip) template||Vector||If present, this is used to build the tooltip. HTML formatting is possible, $[name] ans $[description] are substituted.|
|Layer description||All||All those metadata are searched (in this order) to get a layer description|
|KML_CACHE||Cache life||Vector||Number of seconds after which the cache will expire for a particular layer, if empty or not exists, the cache will be disabled for that layer. Defaults to 0 (cache disabled)|
|KML_SKIP||Skip this layer||All||Do not serve this layer, default to false|
Additional services such as installation, configuration, testing, trouble-shooting and assistance are available at highly competitive price.
Feel free to contact us about KMLMapServer: go to contact page.