View source for Keyhole Markup language

{{stub}}

== Introduction ==

According to [http://en.wikipedia.org/wiki/Keyhole_Markup_Language Wikipedia] (retrieved April 10, 2011), {{quotation|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 [http://www.opengeospatial.org/ogc Open Geospatial Consortium] (OGC) standards. OGC is {{quotation|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]]

End-users of programs such as Google Earth are not exposed to XML coding since the pro version of the software allows defining placemarks as well as virtual tours through a GUI interface.

Below, we show a basic example of the XML code that just defines a placemark with coordinates and a description
<source lang="XML">
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.2">
<Placemark>
<name>Faclab Unige</name>
<description>Fablab de l'université de Genève sur le site de Batelle</description>
<Point>
<coordinates>6.139765530824662,46.176638424281556,0</coordinates>
</Point>
</Placemark>
</kml>
</source>

== Creating exhibits with and for Google Earth ==

While KML defines placemarks, views on placemarks, virtuals tours, etc. it is usually distributed withing a ".kmz file, which is a zip file. The *.kmz includes a kml file plus various multimedia assets.

Google Earth Pro, i.e. the desktop version (not the browser version) allows editing *kmz files.

=== Overview ===

The main functionalities are in the "Add" menu, also available as icons on the menu bar.

* Folders: Create a new folder (start with this). You can move the folder from the Temporary Places to "My Places".
* Placemark: Create a new placemark. To do so, first position your view in a good angle and height. Then, add the placemark.
* Polygon: Allows inserting a colored polygone, e.g. to mark an area
* Model: Allows uploading a [[Collada]] 3D model.
* Tour: Create a tour, i.e. follow a user's navigation path. First click on the tour icon, then use the buttons that appear to record and complete the recording.

[[image:google-earth-places-context-menu.png|thumb|600px|none|Google Earth Pro - Places panel and context menu]]

Each item (e.g. placemark, model or picture) can be edited and repositioned.

Saving a folder as a KMZ file and using it:
* Right-click on the item (e.g. a folder) -> Save Place as.
* To use the file, open it in a browser or directly in Google Earth.

=== Adding models ===

Google Earth can display 3D models in [[Collada]] format.

To create collada files, you could use any sort of [[3D modeling]] or [[Computer-aided design and manufacturing|CAD]] tool. Most formats can be converted to Collada. 

To add a model, use the model icon (or Add->model). Then fill in the properties window. To re-edit properties, right-click on the item in the places panel

Within the properties popup, you can
* Add a description
* Define the camera view. The easiest way is to change the view using the Google Earth control, then press the <code>Shnaphot current view</code> button in the View tab of the properties popup.
* Change the altitude. By default, the model sits on the ground. You may want to slightly embed it if the ground is uneven, but requires knowing the altitude from the sea floor.

You also can directly manipulate the model (open the properties popup first)
* change its size by dragging the green edges of the model
* Rotate around the Z-Axis, drag the green lozenge
* Change its place, drag the green cross
* You cannot rotate the model around other axis, i.e. if your model does not sit correctly, you will have to roted the original model (e.g. 90 degrees around the X-axis) and then re-import the rotated model.

[[file:google-earth-adding-models.png|none|thumb|800px|Adding and positioning a Collada (*.dae) model in Google Earth Pro (Jan 2020).]]

Within the KML file, the placement XML code of the model could then look like the fragment below, and, as explained below, you then can edit the doc.kml file in the exported *kmz archive to add things that the authoring interface does not allow doing.<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2" xmlns:kml="http://www.opengis.net/kml/2.2" xmlns:atom="http://www.w3.org/2005/Atom">
<Document>

<source lang="XML">
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2" xmlns:gx="http://www.google.com/kml/ext/2.2" xmlns:kml="http://www.opengis.net/kml/2.2" xmlns:atom="http://www.w3.org/2005/Atom">
<Document>
......
 <Folder>
  <name>UniGE</name>
  .............
  <Placemark id="OpenAirTemple">
   <name>Open Air Temple</name>
   <description><![CDATA[This was made (as a test with) TinkerCAD Code<a href="https://www.tinkercad.com/codeblocks/7JpQZDXcLjG-rotated-matrix-of-simple-towers">https://www.tinkercad.com/codeblocks/7JpQZDXcLjG-rotated-matrix-of-simple-towers</a>Blocks]]></description>
   <LookAt>
    <longitude>6.138808314750876</longitude>
    <latitude>46.19514246054897</latitude>
    <altitude>0</altitude>
    <heading>0.0005688108686985107</heading>
    <tilt>60.00112631496884</tilt>
    <range>144.7967905032639</range>
    <gx:altitudeMode>relativeToSeaFloor</gx:altitudeMode>
   </LookAt>
   <styleUrl>#m_ylw-pushpin</styleUrl>
   <Model id="model_2">
    <altitudeMode>relativeToGround</altitudeMode>
    <Location>
     <longitude>6.138624480121518</longitude>
     <latitude>46.19521277632689</latitude>
     <altitude>8</altitude>
    </Location>
    <Orientation>
     <heading>219.1029213043479</heading>
     <tilt>0</tilt>
     <roll>0</roll>
    </Orientation>
    <Scale>
     <x>0.1646009085056746</x>
     <y>0.1645994077651669</y>
     <z>0.1646001581354208</z>
    </Scale>
    <Link>
     <href>files/Rotated Matrix of simple towers 270.dae</href>
    </Link>
    <ResourceMap>
    </ResourceMap>
   </Model>
  </Placemark>
...............
</source>

=== Creating a tour ===

[[file:google-earth-save-tour.png|thumb|200px|right|Save a tour in Google Earth]]
[[file:google-earth-start-stop-tour.png|thumb|100px|right|Start or stop a tour in Google Earth]]
A tour is just another item in a places folder. To create a tour:
* Either use the Add Menu or click directly on the "Record a tour" icon in the Menu bar
* Position yourself at some starting point
* Click the red button in the tour control widget that will appear(bottom left of the scene) 
* Now navigate, e.g. by clicking on your various places or manually by using the Google Earth controls (navigation widgets on top right, mouse, keyboard, etc.)
* Click the red button again once you are done with your tour.
* You now will see a new widget where you can play the tour and also register it with the "save" icon.
* You then can position the "tour" item somewhere in the beginning of a places folder

Warning: One you placed a tour inside a places folder and after using the tour you cannot add other objects. Move the tour to another folder to do so.

== Using Sketchup to create kmz files ==

As of Jan 2020, the free (online version) of [[Google Sketchup tutorial|Sketchup]] no longer allows creating *.kmz files. You either should acquire a commercial version or else directly use Google Earth Pro, as explained above.

In Sketchup Pro, you can place a Sketchup model in the right place with very little work.

; Requirements
* Google Earth must be installed on your Computer

; Procedure for Version 8 (no longer available)

* 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)

[[File:Sketchup-add-location.png|600px|thumbnail|none|Sketchup Add Location]]

[[image:gs-google-earth-layer.jpg|600px|thumbnail|none|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. 

'''KMZ architecture'''
* At its root, a doc.kml defines what is shown to the user
* All the rest is optional, i.e. the "files" subdirectory created by default by Google Earth can be either empty or includes various multimedia resources used by doc.kml. This implies that a kml file can assess resources via http:

Examples
* [http://tecfa.unige.ch/guides/KML/Sightseeing%20Tour.kmz Sightseeing Tour.kmz] only includes [http://tecfa.unige.ch/guides/KML/doc-renamed-of-sightseeing-tour.kml doc-renamed-of-sightseeing-tour.kml]
* [http://tecfa.unige.ch/guides/KML/UniGE.kmz UniGE.kmz] includes a picture plus a *.dae 3D model

=== 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 Pictures or Colladas file plus assets representing 3D models. For example, Sketchup creates a ''models'' directory with a Collada model and a texture subdirectory.

=== KML software ===
As of Jan 2020, the only KML editing software seems to be Google Earth Professional, see above for an introduction. 
* KML Builder (win) was a free KML editor that [http://www.northgates.ca/kmleditor/ no longer seem to work] as of Jan 2020.

* [http://www.kmlvalidator.com/home.htm KML Validator] (dead online service)

== Editing KML files ==

Most often KML is used with Google Earth, inside a KMZ file. KMZ is a zip archive that will include a KML file plus all the assets it uses. Assets also can be references with URL.

=== Extract a KML file from a KMZ archive ===

If you never experienced an XML format before, you might read [[Editing XML tutorial]].

The '''easiest way''' to see a KML file is the following: ''In Google Earth, you can right-click a Feature in the Places panel and copy it. To view the corresponding KML for the copied object, open your favorite text editor and paste the selection into it.'' ([https://developers.google.com/kml/documentation/kmlreference?csw=1 KML reference guide]).

Otherwise, you can extract the KML file from a KMZ archive. Get a useful zip program like 7-zip or learn how to deal with *.zip files using Windows Explorer

* Launch the zip program
* Open the kmz file
* Drag doc.kml to the desktop (if you use a zip utility that allows this)
* Open this doc.kml file with a [[text editor]] or an [[XML editor]] (do '''not''' use Windows notepad !) and edit
* Put it back into the zip archive once you are done.

You now can enhance the experience, for example:
* Change Model coordinates and orientation. 
** In Google Earth, the coordinates can be found at bottom right of the window. That being said, it may be easier to set camera views from the google Earth properties window (see above).
* Add Viewpoints (Scenes) to the tour.

=== KML Documentation ===

The [http://code.google.com/apis/kml/documentation/kmlreference.html KML reference guide] is well done

First things you may need to fix:
* [http://code.google.com/apis/kml/documentation/kmlreference.html#location Location and Orientation]
* [http://code.google.com/apis/kml/documentation/kmlreference.html#lookat <LookAt>]
* [http://code.google.com/apis/kml/documentation/kmlreference.html#camera <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.

==== Webster university with a virtual swimming pool ====

Below is a simple example exported from sketchup (enhancing WUG with a swimming pool)
<source lang="XML">
<?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>

</source>

Same example improved:
* Added viewpoints. Played with 5 digits of the longitude.
* Added description
* To do: The model should be adjusted from sea level (cannot use negative numbers from the ground)

Live example: [http://tecfa.unige.ch/guides/te/cosc2010/gs-interface-google-earth-demo.kmz gs-interface-google-earth-demo.kmz]

<source lang="XML">
<?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>

</source>

==== Uni Mail and Uni Pignon ====

Here is a simple tour of Uni Mail and Uni Pignon with some extra thrown in. 

[http://tecfa.unige.ch/guides/KML/UniGE.kmz UniGE.kmz]

Since the code is rather lengthy you can examine it in [[Keyhole Markup language/Uni Pignon - Mail KML example]].

To Do: Create a more streamlined tour !

== Links ==

; At Google

* [http://code.google.com/apis/kml/documentation/ KML Documentation Introduction]
** [http://code.google.com/apis/kml/documentation/kml_tut.html KML Tutorial]
** [http://code.google.com/apis/kml/documentation/kmlreference.html KML Reference]

; Other introductions

* [http://en.wikipedia.org/wiki/Keyhole_Markup_Language Keyhole Markup Language]

; Websites

* [https://sites.google.com/site/kmltouring/home KMLtouring]. A website that explains how to use Google Earth, including tour creation, adding pictures and polygones, editing KML, code examples, etc.

* [http://www.gearthblog.com/ Google Earth Blog]

; Examples

* [http://www.northeastern.edu/neuhome/aboutnortheastern/maps.html Northeastern University]

[[Category: 3D]]
[[Category: XML]]