COIN78 - XML Lesson 12: KML - Keyhole Markup Language
Google Earth
Google Earth is a virtual globe that lets you fly anywhere on Earth to view satellite imagery, maps, terrain, 3D buildings, from galaxies in outer space to the canyons of the ocean. You can explore rich geographical content, save your toured places, and share with others. It was originally called Earth Viewer, and was created by Keyhole, Inc, a company acquired by Google in 2004. It maps the Earth by the superimposition of images obtained from satellite imagery, aerial photography and GIS 3D globe. (Wikipedia)
Google Earth is currently available for use on personal computers running Microsoft Windows 2000, XP, Vista, Mac OS X 10.3.9 and above, Linux (released on June 12, 2006), and FreeBSD. Google Earth is also available as a browser plugin (released on June 2, 2008) for Firefox 3[4], Safari 3, IE6 and IE7. It was also made available on the iPhone OS on October 27, 2008, as a free download from the App Store. (Wikipedia)
Before continuing go to the Google Earth Tutorials and view the videos that show how to use Google Earth. Next, read the user guide for detailed information on how to use Google Earth. It is essential to do these things before continuing. Once you are familiar with Google Earth download it and try it out.
KML
Keyhole Markup Language (KML) is an XML-based language schema for expressing geographic annotation and visualization on existing or future Web-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. (Wikipedia)
The KML file specifies a set of features (placemarks, images, polygons, 3D models, textual descriptions, etc.) for display in Google Earth, Maps and Mobile, or any other 3D earth browser (geobrowser) implementing the KML encoding. Each place always has a longitude and a latitude. Other data can make the view more specific, such as tilt, heading, altitude, which together define a "camera view".(Wikipedia)
The simplest kind of KML documents are those that can be authored directly in Google Earth—that is, you don't need to edit or create any KML in a text editor. Placemarks, ground overlays, paths, and polygons can all be authored directly in Google Earth. KML files have either a .kml file extension or a .kmz file extension (for compressed and zipped KML files).
Take a tour of the Google KML tutorial to see how it is used and look at the KML reference guide to view the KML elements.
Tip: To see the KML "code" for a feature in Google Earth, you can simply right-click the feature in the 3D Viewer of Google Earth and select Copy. Then Paste the contents of the clipboard into any text or XML editor. The visual feature displayed in Google Earth is converted into its KML text equivalent.
Placemarks
A Placemark is one of the most commonly used features in Google Earth. It marks a position on the Earth's surface, using a yellow pushpin as the icon. The simplest Placemark includes only a <Point> element, which specifies the location of the Placemark. You can specify a name and a custom icon for the Placemark, and you can also add other geometry elements to it.
The KML code for the simple placemark looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Placemark>
<name>Simple placemark</name>
<description>Attached to the ground. Intelligently places itself
at the height of the underlying terrain.</description>
<Point>
<coordinates>-122.0822035425683,37.42228990140251,0</coordinates>
</Point>
</Placemark>
</kml>
The structure of this file breaks down as follows:
- An XML header. This is line 1 in every KML file. No spaces or other characters can appear before this line.
- A KML namespace declaration. This is line 2 in every KML 2.2 file.
- A Placemark object that contains the following elements:
- A name that is used as the label for the Placemark
- A description that appears in the "balloon" attached to the Placemark
- A Point that specifies the position of the Placemark on the Earth's surface (longitude, latitude, and optional altitude)
What users commonly think of as a "placemark" in Google Earth is actually a <Placemark> element with a <Point> child in KML. A Point Placemark is the only way to draw an icon and label in the 3D Viewer of Google Earth. By default, the icon is the familiar yellow pushpin. In KML, a <Placemark> can contain one or more geometry elements, such as a LineString, Polygon, or Model. But only a <Placemark> with a Point can have an icon and label. The Point is used to place the icon, but there is no graphical representation of the Point itself.
Tip: To find out what the latitude and longitude coordinates of a location are click on the location of interest in the 3D Viewer of Google Earth and then select Add>Placemark. The Add Placemark popup window will come up and the coordinates will be listed in it. This comes in handy when creating a map in Google Maps because you can just copy and paste them into Google Maps.
Descriptive HTML in Placemarks
Auto-Markup in Google Earth (Release 4.0 and later)
Google Earth 4.0 has an auto-markup feature that automatically converts text such as www.google.com into active hyperlinks that the user can click. Text inside the <description> tag, the <Snippet> tag, and the <text> element of <BalloonStyle> are all automatically transformed into standard HTTP hyperlinks. You don't need to add the <a href= ...> tags yourself.
Using the CDATA Element
If you want to write standard HTML inside a <description> tag, you can put it inside a CDATA tag. If you don't, the angle brackets need to be written as entity references to prevent Google Earth from parsing the HTML incorrectly (for example, the symbol > is written as > and the symbol < is written as <). This is a standard feature of XML and is not unique to Google Earth.
The following is an example that uses CDATA where HTML is written:
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
<Placemark>
<name>CDATA example</name>
<description>
<![CDATA[
<h1>CDATA Tags are useful!</h1>
<p><font color="red">Text is <i>more readable</i> and
<b>easier to write</b> when you can avoid using entity
references.</font></p>
]]>
</description>
<Point>
<coordinates>102.595626,14.996729</coordinates>
</Point>
</Placemark>
</Document>
</kml>
Ground Overlays
Ground overlays enable you to "drape" an image onto the Earth's terrain. The <Icon> element contains the link to the .jpg file with the overlay image. Here is an example ground overlay which shows Mount Etna erupting in 2001:
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Folder>
<name>Ground Overlays</name>
<description>Examples of ground overlays</description>
<GroundOverlay>
<name>Large-scale overlay on terrain</name>
<description>Overlay shows Mount Etna erupting
on July 13th, 2001.</description>
<Icon>
<href>http://code.google.com/apis/kml/documentation/etna.jpg</href>
</Icon>
<LatLonBox>
<north>37.91904192681665</north>
<south>37.46543388598137</south>
<east>15.35832653742206</east>
<west>14.60128369746704</west>
<rotation>-0.1556640799496235</rotation>
</LatLonBox>
</GroundOverlay>
</Folder>
</kml>
The positioning of a ground overlay is controlled by the <LatLonBox> tag. Bounding values are given for the north and south latitudes, and east and west longitudes. In addition, rotation values are given for images whose y-axis doesn't coincide with grid north. This example uses a JPEG image for the overlay. Google Earth also supports BMP, GIF, TIFF, TGA, and PNG formats.
More...
To see how to do Paths and Polygons visit the Google KML tutorial. The examples above are taken from there as well. To get the most out of this make sure you load the KML Samples into Google Earth so that you can follow along. The tutorial shows you how to do this. Note, to navigate to the feature in Google Earth double click on it in the Places panel.
To create your own KML try using the KML Interactive Sampler that Google provides. It provides example KML code for placemarks, polygons, balloons, and photo overlays, to name just a few. You can modify the KML and then view it on Google Earth. You can even create tours.
The Google Earth Files web site has a variety of examples of KML files from deforestation, oil spills, and disappearing forests. To see them in Google Earth click on the Open Google Earth file link. All of the KML files will be copied into the Temporary Places in Google Earth. If you would like to save it then it is a good idea to save it as a Network Link. This means that you will not be copying the files to your computer, rather, you will point to the url where the original files are stored. To see how to do this visit the Google Earth Library site.
Google Earth Gallery is a repository of tours that users have created and shared. After you create a tour you may upload and share it with others.
Google Earth from HTML
Now that we have seen how to use KML files and Google Earth we will look at how to bring up Google Earth from HTML code. All of this is done using javascript. This requires the Google Earth Plugin. If it is not already installed you will automatically be prompted to install it when you try to bring up the Hello World page below.
The html code that will bring up Google Earth using the Google Earth plugin is shown in the box. A <div> tag is created where Google Earth will be shown. When the page is being loaded a javascript function is called to establish the connection to that <div> tag followed by any other initializations. In this case the navigation control is set up to be shown. Click here to see the Hello World html rendering. Notice the comment that says that you must use your own API key. Follow the link and use the URL of the host where you will be uploading your html file when generating the key.
<html>
<head>
<title>Hello, Google Earth</title>
<!-- *** Replace the key below below with your own API key, available at
http://code.google.com/apis/maps/signup.html *** -->
<script type="text/javascript" src="http://www.google.com/jsapi?key=ABCDEFG"> </script>
<script type="text/javascript">
google.load("earth", "1");
var ge = null;
function init() {
google.earth.createInstance("map3d", initCallback, failureCallback);
}
function initCallback(pluginInstance) {
ge = pluginInstance;
ge.getWindow().setVisibility(true); // required!
ge.getNavigationControl().setVisibility(ge.VISIBILITY_AUTO);
}
function failureCallback(errorCode) {
alert("Failure loading the Google Earth Plugin: " + errorCode);
}
</script>
</head>
<body onload="init()">
<h3>Hello, Earth!</h3>
<div id="map3d_container" style="border: 1px solid silver; height: 500px;">
<div id="map3d" style="height: 100%;"></div>
</div>
</body>
</html>
This next example calls a function that takes KML as a parameter. It is important to note that each KML line is enclosed in quotation marks followed by the concatenation symbol, +. Notice that it is outside of the quotation marks. The last line will not have the + because there will be nothing else to concatenate. After the KML has been parsed the resulting object is appended to the getFeatures javascript object. The subsequent javascript will display Google Earth at the Pentagon with a polygon drawn around it's edges. Click here to see it.
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Hello, Google Earth</title>
<!-- *** Replace the key below below with your own API key, available at
http://code.google.com/apis/maps/signup.html *** -->
<script type="text/javascript" src="http://www.google.com/jsapi?key=ABCDEFG"> </script>
<script type="text/javascript">
google.load("earth", "1");
var ge = null;
function init() {
google.earth.createInstance("map3d", initCallback, failureCallback);
}
function initCallback(pluginInstance) {
ge = pluginInstance;
ge.getWindow().setVisibility(true); // required!
// add a navigation control
ge.getNavigationControl().setVisibility(ge.VISIBILITY_AUTO);
// add some layers
ge.getLayerRoot().enableLayerById(ge.LAYER_BORDERS, true);
ge.getLayerRoot().enableLayerById(ge.LAYER_ROADS, true);
// Sample KML taken from
// http://code.google.com/apis/kml/documentation/kml_tut.html#polygons
var pentagon = ge.parseKml(
'<?xml version="1.0" encoding="UTF-8"?>' +
'<kml xmlns="http://www.opengis.net/kml/2.2">' +
' <Placemark>' +
' <name>The Pentagon</name>' +
' <Polygon>' +
' <extrude>1</extrude>' +
' <altitudeMode>relativeToGround</altitudeMode>' +
' <outerBoundaryIs>' +
' <LinearRing>' +
' <coordinates>' +
' -77.05788457660967,38.87253259892824,100 ' +
' -77.05465973756702,38.87291016281703,100 ' +
' -77.05315536854791,38.87053267794386,100 ' +
' -77.05552622493516,38.868757801256,100 ' +
' -77.05844056290393,38.86996206506943,100 ' +
' -77.05788457660967,38.87253259892824,100' +
' </coordinates>' +
' </LinearRing>' +
' </outerBoundaryIs>' +
' <innerBoundaryIs>' +
' <LinearRing>' +
' <coordinates>' +
' -77.05668055019126,38.87154239798456,100 ' +
' -77.05542625960818,38.87167890344077,100 ' +
' -77.05485125901024,38.87076535397792,100 ' +
' -77.05577677433152,38.87008686581446,100 ' +
' -77.05691162017543,38.87054446963351,100 ' +
' -77.05668055019126,38.87154239798456,100' +
' </coordinates>' +
' </LinearRing>' +
' </innerBoundaryIs>' +
' </Polygon>' +
' </Placemark>' +
'</kml>');
ge.getFeatures().appendChild(pentagon);
// Fly to the Pentagon
var la = ge.createLookAt('');
la.set(38.867, -77.0565, 500, ge.ALTITUDE_RELATIVE_TO_GROUND, 0, 45, 900);
ge.getView().setAbstractView(la);
document.getElementById('installed-plugin-version').innerHTML =
ge.getPluginVersion().toString();
}
function failureCallback(errorCode) {
alert("Failure loading the Google Earth Plugin: " + errorCode);
}
</script>
</head>
<body onload="init()">
<h3>Hello Pentagon!</h3>
<div id="map3d_container" style="border: 1px solid silver; height: 500px; width: 500px;">
<div id="map3d" style="height: 100%;"></div>
</div>
</body>
</html>
