Keyhole Markup language

Draft

Introduction

According to Wikipedia (retrieved April 10, 2011), “Keyhole Markup Language (KML) is an XML schema for expressing geographic annotation and visualization within Internet-based, two-dimensional maps and three-dimensional Earth browsers. KML was developed for use with Google Earth, which was originally named Keyhole Earth Viewer. It was created by Keyhole, Inc, which was acquired by Google in 2004. The name "Keyhole" is an homage to the KH reconnaissance satellites, the original eye-in-the-sky military reconnaissance system first launched in 1976. KML is an international standard of the Open Geospatial Consortium.”

KML version 2.2 is one of the many Open Geospatial Consortium (OGC) standards. OGC is “is an international industry consortium of 420 companies, government agencies and universities participating in a consensus process to develop publicly available interface standards. OGC® Standards support interoperable solutions that "geo-enable" the Web, wireless and location-based services and mainstream IT.” (retrieved April 10 2011).

See also: Google Sketchup tutorial

Using sketchup for most of the work

You can place a Sketchup model in the right place with very little work.

Requirements

• Google Earth must be installed on your Computer

Procedure

• Open Menu Window->Model Info
• Select Geo-Location and click on the Add location button
• Search the right location (e.g. enter an address) and then grab when you are happy
• Sketchup now added a layer to your model (that you later can delete if you like)

Google Earth layers in Sketchup

Now do the following adjustements

• Rotate
• Scale

The export as Google Earth model

• File->Export Model
• Select 3Model
• Select Export type = Google Earth (kmz)

Open in Google Earth, clicking on the file should do. Else use File->Open

If the position and the view isn't right, adjust what you can do in Sketchup, then do some KML surgery (see below)

KMZ format and software

Google Earth files are Zip 2.0 archives that use the *.kmz extensions. At its root, the doc.kml specifying contents for display.

KML in Google KMZ files

A KMZ archive includes at least:

• A doc.kml file that defining the features for display in a a 3D Earth browser like Google Earth
• Subdirectories that includes assets, typically a Collada file representing a 3D model. For example, Sketchup creates a models directory with a Collada model and a texture subdirectory.

KML software

• kmleditor/ (win). A free KML editor (needs installation of Microsoft .Net 4

• KML Validator (online service)

Important tags

If you never experience an XML format before, you might read Editing XML tutorial.

Get a useful zip program like z-zip or learn how to deal with *.zip files using Windows Explorer

• Open the zip program
• Open the kmz file
• Drag doc.kml to the desktop (if you use a zip utility open)
• Open this doc.kml file with a text editor or an XML editor (do not use Windows notepad !)

You now can enhance the experience

• Change Model coordinates and orientation.
  • In Google Earth, display location with menu View->Scale Legend
• Add Viewpoints (Scenes) to the tour.

KML Documentation

The KML reference guide is well done

First things you may need to fix:

• Location and Orientation
• <LookAt>
• <Camera>

KMZ/KMZ by example

Important tip

When in Google Earth, click right on an item in the places panel to the left. Then copy. Then paste into a text editor. It will give you the *.kml.

Below is a simple example exported from sketchup (enhancing WUG with a swimming pool)

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2">

  <Folder>
    <name>gs-interface-google-earth-demo</name>
    <description>Created with &lt;a href="http://sketchup.google.com"&gt;Google SketchUp&lt;/a&gt;</description>
    <visibility>1</visibility>
    <LookAt>
      <heading>317.4387945958</heading>
      <tilt>70.27179262714</tilt>
      <latitude>46.25706768089</latitude>
      <longitude>6.151697277086</longitude>
      <range>52.92320526358</range>
      <altitude>22.58315454372</altitude>
    </LookAt>
    <Folder>
      <name>Tour</name>
      <Placemark>
        <name>Scene 1</name>
        <visibility>1</visibility>
        <LookAt>
          <heading>317.4387945958</heading>
          <tilt>70.27179262714</tilt>
          <latitude>46.25706768089</latitude>
          <longitude>6.151697277086</longitude>
          <range>52.92320526358</range>
          <altitude>22.58315454372</altitude>
        </LookAt>
      </Placemark>
    </Folder>
    <Placemark>
      <name>Model</name>
      <description></description>
      <Style id="default"/>
      <Model>
        <altitudeMode>relativeToGround</altitudeMode>
        <Location>
          <latitude>46.257066</latitude>
          <longitude>6.151696</longitude>
          <altitude>0</altitude>
        </Location>
        <Orientation>
          <heading>357.941140275</heading>
          <tilt>0</tilt>
          <roll>0</roll>
        </Orientation>
        <Scale>
          <x>1</x>
          <y>1</y>
          <z>1</z>
        </Scale>
        <Link>
          <href>models/untitled.dae</href>
        </Link>
      </Model>
    </Placemark>
  </Folder>

</kml>

Same example improved:

• Added viewpoints. Played with 5 digits of the longitude.
• Added description
• Can't put the model into the ground. Why not ?

Live example: gs-interface-google-earth-demo.kmz

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2">

  <Folder>
    <name>gs-interface-google-earth-demo</name>
    <description>WUG enhanced with a swimming pool and some palm trees</description>
    <visibility>1</visibility>
    <LookAt>
      <heading>317.4387945958</heading>
      <tilt>70.27179262714</tilt>
      <latitude>46.25706768089</latitude>
      <longitude>6.151697277086</longitude>
      <range>52.92320526358</range>
      <altitude>22.58315454372</altitude>
    </LookAt>
    <Folder>
      <name>Tour</name>
      <Placemark>
        <name>Scene 1</name>
        <visibility>1</visibility>
        <LookAt>
          <heading>317.4387945958</heading>
          <tilt>70.27179262714</tilt>
          <latitude>46.25706768089</latitude>
          <longitude>6.151697277086</longitude>
          <range>52.92320526358</range>
          <altitude>22.58315454372</altitude>
        </LookAt>
      </Placemark>
	  <Placemark>
        <name>Scene 2</name>
        <visibility>1</visibility>
        <LookAt>
          <heading>317.4387945900</heading>
          <tilt>70.27179262714</tilt>
          <latitude>46.25706768089</latitude>
          <longitude>6.151697277086</longitude>
          <range>20</range>
          <altitude>10</altitude>
        </LookAt>
      </Placemark>
      <Placemark>
        <name>In the pool</name>
        <visibility>1</visibility>
        <LookAt>
          <heading>180</heading>
          <tilt>70.27179262714</tilt>
          <!-- play with five digits. Plus to go east, plus to go south  -->
          <latitude>46.25699</latitude>
          <longitude>6.15175</longitude>
          <range>5</range>
          <altitude>5</altitude>
        </LookAt>
      </Placemark>
    </Folder>
    <Placemark>
      <name>Model</name>
      <description>Swimming Pool</description>
      <Style id="default"/>
      <Model>
	    <!-- this is interpreted as above land if not on sea ... won't take neg values pff -->
        <gx:altitudeMode>relativeToSeaFloor</gx:altitudeMode>
        <Location>
          <latitude>46.257066</latitude>
          <longitude>6.151697277086</longitude>
          <altitude>0</altitude>
        </Location>
        <Orientation>
          <heading>357.941140275</heading>
          <tilt>0</tilt>
          <roll>0</roll>
        </Orientation>
        <Scale>
          <x>1</x>
          <y>1</y>
          <z>1</z>
        </Scale>
        <Link>
          <href>models/untitled.dae</href>
        </Link>
      </Model>
    </Placemark>
  </Folder>

</kml>

Links

At Google

• KML Documentation Introduction
  • KML Tutorial
  • KML Reference

Other introductions

• Keyhole Markup Language

Websites

• Google Earth Blog

Examples

• Northeastern University