Page 3 of 3
KML in Google Earth
Google Earth is better at supporting KML than Maps - it has more facilities and more extensions. There are many ways to load KML into Google Earth but it is also worth knowing that if you select any displayed graphic on a Google Earth display, right click and select copy then a KML representation of the object is loaded to the clipboard. If you paste the KML into a text editor you can veiw it and modify it for use in your own code. This is a good way to learn about KML.
The easiest way to display a KML file is to simply load the KML file into Google Earth. If you have Earth installed on your machine than simply double clicking on the KML file will open it in Google Earth and display the contents of the file. You can also use the File,Open command and navigate to the KML file. KML files, once loaded can be saved as part of MyPlaces.
If you want to load the KML file using the API then there are three basic ways of doing the job. The first is very similar to the Google Maps API way. You first have to ensure that the KML file is publicly accessible via a URL. If this is the case you can create a NetworkLink object and load it into the Google Earth object for display.
Assuming that the Google Earth object is loaded and initialised then you can display the demo1.kml file given at the start of the article as follows.
First create the link object:
var link = ge.createLink('');
Next create the NetworkLink object and initialise it to the URL using the Link object:
var networkLink = ge.createNetworkLink('');
networkLink.set(link, true, true);
The set method is used to initialise the link and to make it visible and make the map "fly" to the location.
Finally add the NetworkLink object to the map:
If you run this short code segment then you will see the map pan to the new location and you will see a default marker.
So far we haven't done anything we couldn't have achieved using Google Maps - the KML file is loaded from a URL and you can't modify it. If you use either the fetchKML method then you can do the same job but now you can manipulate the resulting KML objects.
The fetchKml method accepts three parameters - the Google Earth object, the url as a string and a call back function that accepts the resulting kmlObject as its first parameter. For example to load the demo1.kml file you would use something like:
Where getKML is a function that is called when the KML has been loaded into the kmlObject. For example to load the kmlObject into the map you would use:
Notice that this doesn't zoom and pan the map to the new location but if you use the mouse to move to the location you will see the default marker in place. Also notice that if the URL is incorrect or if there is any problem with the KML file the kmlObject is null.
The final KML load method, parseKML, is perhaps the most versatile as it can parse KML presented to it as a string. This means you can obtain the KML from any source you care to problem - a local file say, a URL or generated using code.
For example, if we store the text of the previous KML example in a variable:
var KML = '<?xml version="1.0"
' <Placemark>' +
' <Point>' +
' <coordinates>' +
' -1.5,55 ' +
' </coordinates>' +
' </Point>' +
' </Placemark>' +
The strange way of entering the string literal is used to preserve some of the formatting within the program - line breaks and spaces are mostly ignored in KML.
To create the kmlObject from the string we use:
var kmlObject = ge.parseKml(KML);
As long as everything worked and kmlObject isn't null we can display it on the map in the usual way:
Once again the map doesn't automatically pan to the new location but if you do the job manually you will see the marker.
Working with the KML DOM
The main reason for wanting to load the KML into a kmlObject is to manipulate it before displaying it.
The kmlObject can be thought of as a sort of map equivalent of the DOM - Document Object Model. Indeed the same idea applies to the map object itself. What happens is that as the KML is parsed objects are created with the same structure as the nested tags. Each tag gives rise to an object in the DOM and they are nested within each other in the same way that the tags are. That is if <tag2> is nested within <tag1> e.g.
the object that represents tag2 is a child of the object that represents tag1. Sometimes tags at the lowest level of the hierarchy are converted into properties of the object that corresponds to the tag that contains them - see the example below.
The biggest problem you have in any given situation is working out what object in the Google Earth API correspond to which tags. You also have to realise that the structure of a KML file can be far more complicated than the one we have been using so far - in particular there can be multiple features like placemarkers and you have to write code which navigates its way through the DOM tree to find what you are looking at.
A simple example will help get you started. In the case of the sample file demo1.kml that was loaded into the kmlObject variable there is only only feature i.e. the single placemarker. Thus the kmlObject isn't a collection of features it is a an instance of the KmlPlacemark object. The KmlPlacemark object has getGeometry and setGeometry methods that can be use to manipulate its child objects - which correspond to the tags nested within it.
In this case the only child object is a kmlPoint object which was created to correspond to the point tag. This has get and set Latitude and Longitude methods and we don't need to dig any deeper because the co-ordinate tags have been converted into properties of the kmlPoint object.
So putting all this together. To set the latitude and longitude of the placemark to 0,0 we would use:
and to discover the current values we would use:
Notice that the connection between the kmlObject and the map is live in the sense that if you change the details of the object after it has been added to the map then the display is updated.
In a more complicated case the kmlObject may contain lots of placemark objects and other objects and you would have to navigate the DOM to find the placemark you needed to modify or add to.
If you would like to be informed about new articles on I Programmer you can either follow us on Twitter, on Facebook , on Digg or you can subscribe to our weekly newsletter.