Keyhole Markup Language

📃 These are primarily notes, intended to be a collection of useful fragments, that will probably never be complete in any sense.

Note that KML is an open format, and specific apps (such as Google Earth) may not use/support all of it.

KML uses decimal lat-long, and uses WGS84. (always?(verify)) (see also Cartographic_notes)

Applications and associations

KML (Keyhole Markup Language)

MIME: application/vnd.google-earth.kml+xml

KMZ: KML-zipped

MIME:application/vnd.google-earth.kmz
containing a compressed KML file,
...lets you pack in images (icons, etc.) so that the KML does not have to refer to public-server URIs for that

Will open in Google Earth or anything else that has it registered.

Note that Google Maps also takes KML, like:

http://maps.google.com/maps?q=http://example.com/things.kml

Simple example

A simple KML file looks like:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.2">
  <Placemark>
    <name>Portland</name>
    <Point>
      <coordinates>-122.6676358763541,45.52181645404051</coordinates>
    </Point>
  </Placemark>
</kml>

What is stored

KML Features include:

Placemark (basic vector features: points, lines, polygons)
Folder, Document (containers)
- Document (container for features and styles)
- Folder (container for features)
image overlays (ground, screen, photo)
NetworkLink (to remote KML/KMZ files)

Note that Region is regularly used to describe metadata and points of interest within certain boxes.

Lod allows you to specify the (minimum, maximum) screen size of a feature before it should be considered active.

Styles

You can declare colors and/or line widths on icons, labels, lines, polygons, balloons, and lists.

May be ignored unless you need them.

Are usually referenced by their id, within the same document.

Placemarks

should include a <name> and
may include a <description> (HTML must be element-escaped, or in CDATA section)
may include a <LookAt> structure
may include a <styleUrl> to refer to style (usually a #hash based URL to refer to a style declared in the same KML file.
has an element declaring its type: (Point, LineString, etc., see below)
- with option elements depending on the type
- and a <coordinates> element
  - with coordinates in text nodes
  - space-separated coordinates
  - comma-separated per dimensions
    - longitude (≥ −180 and <= 180)
    - latitude (≥ −90 and ≤ 90)
    - altitude (meters) (optional)

Common options:

altitudeMode (string)
- defines interpretation of the third (altitude) coordinate, if used:
- clampToGround (default, ignores altitude)
- relativeToGround: Relative to ground elevation
- absolute: Relative to sea level (regardless of ground elevation)

extrude (boolean, 0 or 1)
- connect point/line/polygon to ground (direction of center of Earth)
- applies when altitudeMode is relativeToGround or absolute

tessellate (boolean, 0 or 1)
- Show very large line segments so they follow the terrain (vertically, rather than poking through mountains, go underground, etc.)
- applies when altitudeMode is clampToGround

Types, options per type

Point

altitudeMode, extrude
Example: <Point><coordinates>-6.1456,-35.1</coordinates></Point>

LineString

Non-closed sequence of coordinates
altitudeMode, extrude, tessellate

LinearRing

Closed line string (a minimal polygon)
altitudeMode, extrude, tessellate,
typically the outer boundary of a Polygon. A LinearRing can also be used as the inner boundary of a Polygon to create holes in the Polygon. A Polygon can contain multiple <LinearRing> elements used as inner boundaries.

Polygon

Similar to LinearRing, with a required main polygon, and contained cutout polygons:
- outerBoundaryIs (LinearRing), required
- innerBoundaryIs (LinearRing), (0 or more)
altitudeMode, extrude, tessellate

MultiGeometry

Can contain one or more Geometry-type (e.g. line, polygon) elements, that should be viewed as a single feature.

(except in cases where polygon innerBoundaries apply?)

Model

Points to a COLLADA resource (see also Cartographic notes)