Overview
KML (Keyhole Markup Language), an XML schema originally developed for Google Earth to describe shapes on a map has been supported by VE since version 6.0 was released and hasn't changed much since VE 6.2. The common questions this series will address are "Which KML features does VE support?" and "How do I use these features?" for developers with no KML experience.
KML Quickstart
If you haven't already, take a look at the Interactive SDK (http://dev.live.com/virtualearth/sdk/ ) and MSDN (http://msdn.microsoft.com/en-us/library/bb429606.aspx ) on to see how to load a feed into VE. I had trouble loading KML locally (GeoRSS was okay) using any browser even with a website setup through IIS. I found that uploading my KML file to SkyDrive and referencing the URL worked. Finally, you'll need to open the google KML documentation page (http://code.google.com/apis/kml/documentation/kmlreference.html) to follow along.
Here is a sample KML loader taken from the SDK with a few modifications:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title></title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<script src="http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.2"></script>
<script type="text/javascript">
var map = null;
function GetMap()
{
map = new VEMap('myMap');
map.LoadMap(new VELatLong(46.3081, -122.1928), 12);
}
function AddMyLayer(type)
{
var l = new VEShapeLayer();
var veLayerSpec = new VEShapeSourceSpecification(type, document.getElementById('txtSource').value, l);
map.ImportShapeLayerData(veLayerSpec, onFeedLoad);
}
function onFeedLoad(feed)
{
alert('RSS or Collection loaded. There are ' + feed.GetShapeCount() + ' items in this list.');
}
</script>
</head>
<body onload="GetMap();">
<div id='myMap' style="position:relative; width:600px; height:400px;"></div>
<p>
For this version, the GeoRSS feed needs to be on the same domain as this computer.
Right-click
<a href="http://dev.live.com/virtualearth/sdk/georsstest.xml">
georsstest.xml</a>,
save the file into the same folder as this Web page,
such as <code>C:\Inetpub\wwwroot</code>,
and then click the <b>Load RSS</b> button below.
<p>
<INPUT id="txtSource" type="text" value="http://vuygfa.bay.livefilestore.com/y1pfy2O5bvHiI9WjTOqfVLfq-Jx8UzgI1erd_YsaIQsDosJx-4SEYXj3jf-JH2MUndQzrsmTvlaTt5RUXl80e__sw/KML_Samples2.kml" name="txtSource">
<INPUT id="loadFeed" type="button" value="Load RSS" onclick="AddMyLayer(VEDataType.ImportXML);">
</body>
</html>
The following KML file was loaded into VE:
<kml xmlns="http://www.opengis.net/kml/2.2">
<Placemark>
<name>Pushpin Title</name>
<description>Pushpin Description</description>
<LineString>
<coordinates> -112.2550785337791,36.07954952145647,2357
-112.2549277039738,36.08117083492122,2357
-112.2552505069063,36.08260761307279,2357
-112.2564540158376,36.08395660588506,2357
-112.2580238976449,36.08511401044813,2357
-112.2595218489022,36.08584355239394,2357
-112.2608216347552,36.08612634548589,2357
-112.262073428656,36.08626019085147,2357
-112.2633204928495,36.08621519860091,2357
-112.2644963846444,36.08627897945274,2357
-112.2656969554589,36.08649599090644,2357 </coordinates>
</LineString>
</Placemark>
</kml>
So far all of this is pretty much the same as loading a GeoRSS feed. Note that the <placemark> tags are required to describe every shape placed on the map. The line is also drawn right on the ground due to the <AltitudeMode> being set to RelativeToGround (refer to google KML documentation) by default.
You can color the line and specify its line width by creating them within a <style> tag, and then referencing the <style> id in your shape. e.g:
<Style id="globeIcon">
<LineStyle>
<width>10</width>
<color>7fff00ff</color>
</LineStyle>
</Style>
<Placemark>
.....
<styleUrl>#globeIcon</styleUrl>
</Placemark>
Let's add some 3D features to our polyline now. If you wish to keep your shape off the ground, you can set the <altitudeMode> tag to absolute (in our example, it must be within the <LineString> tag)
<LineString>
......
<altitudeMode>Absolute</altitudeMode>
</LineString>
For some odd reason, the <width> tag is ignored when going into absolute <altitudeMode>. Also, the altitude in which the shape hovers from cannot be changed (since the <altitude> tag is currently ignored).
Finally, we can add lines that go into the ground by setting the <Extrude> tag boolean to 1
<LineString>
......
<extrude>1</extrude>
<altitudeMode>Absolute</altitudeMode>
</LineString>
So far these features are the only one I have found that stands out from GeoRSS formats. There are still KML features I have yet to attempt but the list below is what I have found working/not working. You can reference the KML file used in these examples here: http://vuygfa.bay.livefilestore.com/y1pfy2O5bvHiI9WjTOqfVLfq-Jx8UzgI1erd_YsaIQsDosJx-4SEYXj3jf-JH2MUndQzrsmTvlaTt5RUXl80e__sw/KML_Samples2.kml.
Summary
The following tags have been discovered to work in VE 6.2
- Kml
- Placemark
- Name
- Description
- Extrude
- Coordinates
- Width
- Color
- StyleUrl
- LineStyle, IconStyle, PolyStyle
- Icon (2D only)
- LineString, Point, Polygon
- AltitudeMode (except doesn't factor in Altitude)
The following tags have been discovered not working (can be specified, but values will be ignored) in VE 6.2
- Visibility
- Altitude
- Tessellate
- Altitude (and conversely, AltitudeMode will always ignore this tag)
- LookAt (and all underlying tags that rely on camera manipulation)