| Home | Products | Issue Tracker | Service Providers | FAQ | Twitter | Download

# KML - Keyhole Markup Language

Table of Contents

- KML - Keyhole Markup Language

  - Links to KML-Related Information

  - Data Access / Connection Method

  - Example 1: Displaying a .KML file

  - Example 2: Displaying a .KMZ file

  - Example 3: Displaying a “Superoverlay” KML file

Keyhole Markup Language (KML) is an XML-based language for managing the display of 3D geospatial data. KML is a standard maintained by the Open Geospatial Consoritum (OGC).

## Links to KML-Related Information

- Google’s KML Reference

- OGC’s KML Specification

- KML Validator

- KML Validator (against OGC KML 2.2)

## Data Access / Connection Method

KML access in MapServer is available through OGR. See the OGR driver page for specific driver information. Read support was initially added to GDAL/OGR version 1.5.0. A more complete KML reader was added to GDAL/OGR in version 1.8.0, through the libKML driver (including the ability to read multigeometry, and KMZ files).

The CONNECTION parameter must include the kml or kmz extension, and the DATA parameter should be the name of the layer.

    CONNECTIONTYPE OGR
    CONNECTION "filename.kml"
    DATA "layername"

## Example 1: Displaying a .KML file

### OGRINFO

First you should make sure that your GDAL/OGR build contains the “KML” driver, by using the ‘–formats’ command:

    >ogrinfo --formats
       Loaded OGR Format Drivers:
       ...
       -> "GML" (read/write)
       -> "GPX" (read/write)
       -> "KML" (read/write)
       ...

If you don’t have the driver, you might want to try the FWTools or MS4W packages, which include the driver.

Once you have the KML driver you are ready to try an ogrinfo command on your file to get a list of available layers:

    >ogrinfo myplaces.kml
       INFO: Open of `myplaces.kml'
       using driver `KML' successful.
       1: Layer #0 (Point)

Now use ogrinfo to get information on the structure of the layer:

    >ogrinfo fountains-hotel.kml "Layer #0" -summary
      Had to open data source read-only.
      INFO: Open of `fountains-hotel.kml'
        using driver `KML' successful.

      Layer name: Layer #0
      Geometry: Point
      Feature Count: 1
      Extent: (18.424930, -33.919627) - (18.424930, -33.919627)
      Layer SRS WKT:
      GEOGCS["WGS 84",
          DATUM["WGS_1984",
            SPHEROID["WGS 84",6378137,298.257223563,
              AUTHORITY["EPSG","7030"]],
          AUTHORITY["EPSG","6326"]],
        PRIMEM["Greenwich",0,
          AUTHORITY["EPSG","8901"]],
        UNIT["degree",0.01745329251994328,
          AUTHORITY["EPSG","9122"]],
        AUTHORITY["EPSG","4326"]]
      Name: String (0.0)
      Description: String (0.0)

### Mapfile Example

     LAYER
       NAME "kml_example"
       TYPE POINT
       STATUS DEFAULT
       CONNECTIONTYPE OGR
       CONNECTION "kml/fountains-hotel.kml"
       DATA "Layer #0"
       LABELITEM "NAME"
       CLASS
         NAME "My Places"
         STYLE
           COLOR 250 0 0
           OUTLINECOLOR 255 255 255
           SYMBOL 'circle'
           SIZE 6
         END
       LABEL
         SIZE TINY
         COLOR 0 0 0
         OUTLINECOLOR 255 255 255
         POSITION AUTO
       END
      END
    END

## Example 2: Displaying a .KMZ file

### OGRINFO

First you should make sure that your GDAL/OGR build contains the “LIBKML” driver, by using the ‘–formats’ command:

    >ogrinfo --formats
       Loaded OGR Format Drivers:
       ...
       -> "GML" (read/write)
       -> "GPX" (read/write)
       -> "LIBKML" (read/write)
       -> "KML" (read/write)
       ...

If you don’t have the driver, you might want to try the FWTools or MS4W packages, which include the driver. Or you can follow the compiling notes for libKML and GDAL/OGR.

Once you have the LIBKML driver you are ready to try an ogrinfo command on your file to get a list of available layers:

    >ogrinfo Lunenburg_Municipality.kmz
       INFO: Open of `Lunenburg_Municipality.kmz'
       using driver `LIBKML' successful.
       1: Lunenburg_Municipality

Now use ogrinfo to get information on the structure of the layer:

    >ogrinfo Lunenburg_Municipality.kmz Lunenburg_Municipality -summary
       INFO: Open of `Lunenburg_Municipality.kmz'
          using driver `LIBKML' successful.

       Layer name: Lunenburg_Municipality
       Geometry: Unknown (any)
       Feature Count: 1
       Extent: (-64.946433, 44.133207) - (-64.230281, 44.735125)
       Layer SRS WKT:
       GEOGCS["WGS 84",
           DATUM["WGS_1984",
               SPHEROID["WGS 84",6378137,298.257223563,
                   AUTHORITY["EPSG","7030"]],
               TOWGS84[0,0,0,0,0,0,0],
               AUTHORITY["EPSG","6326"]],
           PRIMEM["Greenwich",0,
               AUTHORITY["EPSG","8901"]],
           UNIT["degree",0.0174532925199433,
               AUTHORITY["EPSG","9108"]],
           AUTHORITY["EPSG","4326"]]
       Name: String (0.0)
       description: String (0.0)
       timestamp: DateTime (0.0)
       begin: DateTime (0.0)
       end: DateTime (0.0)
       altitudeMode: String (0.0)
       tessellate: Integer (0.0)
       extrude: Integer (0.0)
       visibility: Integer (0.0)

### Mapfile Example

    LAYER
      NAME "lunenburg"
      TYPE POLYGON
      STATUS DEFAULT
      CONNECTIONTYPE OGR
      CONNECTION "Lunenburg_Municipality.kmz"
      DATA "Lunenburg_Municipality"
      CLASS
        NAME "Lunenburg"
        STYLE
          COLOR 244 244 16
          OUTLINECOLOR 199 199 199
        END
      END
    END # layer

## Example 3: Displaying a “Superoverlay” KML file

A superoverlay is a KML file that contains tiled data, that is broken up into “regions”; this is an efficient way to display large images. For more background on superoverlays see the Google Developers KML Tutorial.

MapServer can access superoverlays through GDAL.

Note

The following was tested with GDAL 2.0.2-dev on 2016-01-17; several enhancements to GDAL were made when testing this superoverlay (see tickets 6310 and 6311).

### GDALINFO

First you should make sure that your GDAL/OGR build contains the “KMLSUPEROVERLAY” driver, by using the ‘–formats’ command:

    >gdalinfo --formats
       Supported Formats:
       ...
       R -raster- (rwv): R Object Data Store
       MAP -raster- (rov): OziExplorer .MAP
       KMLSUPEROVERLAY -raster- (rwv): Kml Super Overlay
       PDF -raster,vector- (rw+vs): Geospatial PDF
       ...

If you don’t have the driver, you might want to check if your platform has a ready-to-use package/installer (Windows users please see MS4W), which include the driver.

Note

For this example, we will use the remote KML file referenced in the Google Developers Tutorial (http://mw1.google.com/mw-earth-vectordb/kml-samples/mv-doqq.kml). We will also access this remote file directly through vsicurl, which has been available in GDAL since 1.8.0

Now use gdalinfo to get information on the structure of the layer:

    >gdalinfo /vsicurl/http://mw1.google.com/mw-earth-vectordb/kml-samples/mv-doqq.kml

    Driver: KMLSUPEROVERLAY/Kml Super Overlay
    Files: none associated
    Size is 16384, 16384
    Coordinate System is:
    GEOGCS["WGS 84",
        DATUM["WGS_1984",
            SPHEROID["WGS 84",6378137,298.257223563,
                AUTHORITY["EPSG","7030"]],
            AUTHORITY["EPSG","6326"]],
        PRIMEM["Greenwich",0,
            AUTHORITY["EPSG","8901"]],
        UNIT["degree",0.0174532925199433,
            AUTHORITY["EPSG","9122"]],
        AUTHORITY["EPSG","4326"]]
    Origin = (-122.129312658577720,37.439803353779496)
    Pixel Size = (0.000004270647777,-0.000004095141704)
    Metadata:
      DESCRIPTION=The original is a 7008 x 6720 DOQQ of Mountain View in 1991. (Source:
          http://gis.ca.gov/). This is a Region NetworkLink hierarchy of 900+
          GroundOverlays each of 256 x 256 pixels arranged in a hierarchy such
          that more detailed images are loaded and shown as the viewpoint nears.
          Enable the "Boxes" NetworkLink to see a LineString for
          each Region. Tour the "Boxes" to visit each tile. Visit the
          "A" and "B" Placemarks to see multiple levels of
          hierarchy together. Use the slider on various images in the hierarchy
          to see how the resolution varies and of the entire hierarchy to see
          the imagery below. (Find the Google Campus...).

      NAME=SuperOverlay: MV DOQQ
    Image Structure Metadata:
      INTERLEAVE=PIXEL
    Corner Coordinates:
    Upper Left  (-122.1293127,  37.4398034) (122d 7'45.53"W, 37d26'23.29"N)
    Lower Left  (-122.1293127,  37.3727086) (122d 7'45.53"W, 37d22'21.75"N)
    Upper Right (-122.0593424,  37.4398034) (122d 3'33.63"W, 37d26'23.29"N)
    Lower Right (-122.0593424,  37.3727086) (122d 3'33.63"W, 37d22'21.75"N)
    Center      (-122.0943275,  37.4062560) (122d 5'39.58"W, 37d24'22.52"N)
    Band 1 Block=256x256 Type=Byte, ColorInterp=Red
      Overviews: 8192x8192, 4096x4096, 2048x2048, 1024x1024, 512x512, 256x256
      Mask Flags: PER_DATASET ALPHA
      Overviews of mask band: 8192x8192, 4096x4096, 2048x2048, 1024x1024, 512x512, 256x256
    Band 2 Block=256x256 Type=Byte, ColorInterp=Green
      Overviews: 8192x8192, 4096x4096, 2048x2048, 1024x1024, 512x512, 256x256
      Mask Flags: PER_DATASET ALPHA
      Overviews of mask band: 8192x8192, 4096x4096, 2048x2048, 1024x1024, 512x512, 256x256
    Band 3 Block=256x256 Type=Byte, ColorInterp=Blue
      Overviews: 8192x8192, 4096x4096, 2048x2048, 1024x1024, 512x512, 256x256
      Mask Flags: PER_DATASET ALPHA
      Overviews of mask band: 8192x8192, 4096x4096, 2048x2048, 1024x1024, 512x512, 256x256
    Band 4 Block=256x256 Type=Byte, ColorInterp=Alpha
    Overviews: 8192x8192, 4096x4096, 2048x2048, 1024x1024, 512x512, 256x256

### Mapfile Example

Finally, access the superoverlay image through a MapServer layer with TYPE RASTER, as you would other rasters, such as:

    MAP
      NAME "superoverlay"
      STATUS ON
      SIZE 400 300
      EXTENT -122.1293127 37.3727086 -122.0593424 37.4398034
      UNITS DD
      IMAGECOLOR 255 255 255

      LAYER
        NAME "mountain-view-superoverlay"
        TYPE RASTER
        STATUS ON
        DATA "/vsicurl/http://mw1.google.com/mw-earth-vectordb/kml-samples/mv-doqq.kml"
        CLASS
          NAME "Superoverlay"
          STYLE
          END #style
        END #class
      END #layer

    END #Map

### Test Your Mapfile with the shp2img Command

The easiest way to test your superoverlay mapfile is with the MapServer shp2img utility.

    >shp2img -m superoverlay-kml.map -o ttt.png -all_debug 3

    msLoadMap(): 0.000s
    msDrawMap(): rendering using outputformat named png (AGG/PNG).
    msDrawMap(): WMS/WFS set-up and query, 0.000s
    msDrawRasterLayerLow(mountain-view-superoverlay): entering.
    msDrawRasterLayerGDAL(): Entering transform.
    msDrawRasterLayerGDAL(): src=0,0,16384,16384, dst=44,0,312,300
    msDrawRasterLayerGDAL(): source raster PL (-4.888,-27.409) for dst PL (44,0).
    msDrawRasterLayerGDAL(): red,green,blue,alpha bands = 1,2,3,4
    msDrawMap(): Layer 0 (mountain-view-superoverlay), 4.314s
    msDrawMap(): Drawing Label Cache, 0.008s
    msDrawMap() total time: 4.347s
    msSaveImage(ttt.png) total time: 0.090s
    shp2img total time: 4.441s

The following map image should be generated: