In Part 1, we went through how to create your placemarks, and how to record your Google Earth tour. In this second part, we’ll dive into editing the KML file directly. KML is a type of XML, so if you’ve never worked with this before, you will want to go through a tutorial, or read The KML Handbook.
In this article, you will learn about some of the important tags that make up a KML document, and how to add in ScreenOverlays, audio files, and videos to your tour. I’ll also go over some best practices for working with KML files and Google Earth.
Organizing your audio, image, and video files
Be consistent with the naming of your mp3 audio files. I simply named mine “pollution 1.mp3″, “pollution 2.mp3″, etc. and placed them in a folder named “files”, but you may choose something more descriptive like “narrations”. Your folder structure should look something like:
- pollution.kml (the file containing all the placemarks and tour data)
- pollution 1.mp3
- pollution 2.mp3
That’s it. I’ve stored any photos or videos on the webserver; I wasn’t able to bundle these with the KML file. Initially I had stored the MP3 files separate from the KML, and just referenced their URL (ie: http://www.example.com/pollution 1.mp3) but it turns out that Macintosh computers were unable to play these files if they were just referenced by URL. Audio files need to be bundled with the KML file if you want them to play on Mac.
If you don’t have your own webserver, you can just as easily store you images on a site such as imgur or flickr (note: I haven’t used these sites for storing images for Google Earth tours. I do not know if there are hotlinking restrictions)
Working with KML in a sane way
Your KML file contains all of the placemarks you defined in Part 1, as well as the Google Earth tour data. It’s all written in XML, so if you’ve never worked with this, it can be a bit intimidating. I will assume you have a basic understanding of XML tags, if not, here is a tutorial to get you started.
We’ll be using a text editor to modify the KML file. I used Aptana Studio for this — nothing fancy, and it’s free.
Now, the key to creating quality work is quick feedback. When we first started making these tours, the only way we could see the changes we made was to remove the KML from Google Earth, and then load it back up again. This really adds up when you’re making a lot of changes, so the the first thing I did was to find a simple way of reloading the file: the Revert feature. Once you’ve made changes to your KML file, switch over to Google Earth, right click your file, and click Revert. It will say “Do you want to reload…” click Yes. Doing this will reload the file, and any changes you’ve made will now be visible. This is the quickest way to load your changes into Google Earth.
Another tip for creating quality work is continual improvement. This is where a version control system like SVN or git comes in handy. These tools help you keep track of all the changes you make along the way, and allow you to roll back to a previous revision if you make a big mistake editing the KML.
Learn more about git with Pragmatic Version Control Using Git — I’ve read this, and recommend it.
Editing the KML file
You’ll see a bunch of different KML tags in the file. For a full description of what these mean, check out “Touring in KML“. What follows below is a brief description of some of these tags:
Below is the markup for a placemark. All of this code was generated by Google Earth when we defined these placemarks in Part 1… everything except the contents of the <description> tag. Inside this tag, you can put any HTML you want, as long as it is enclosed in the <![CDATA[ any kind of html in here ]]> tag. Below, we’ve added the code for a flash movie, and a description. Apologies for some of the text being cut off — for the full source download, there are links at the bottom of the page.
Google Earth will set the id of each placemark, but you can name this anything you want — in fact it’ll help you later on to name it something descriptive.
<Placemark id="alang"> <name>Alang Shipbreaking Yards</name> <description><![CDATA[ <div> <object data="http://cbc.ca/video/swf/UberPlayer.swf" type="application/x-shockwave-flash" width="460" height="311"> <param name="allowFullScreen" value="true"> <param name="allowScriptAccess" value="always"> <param name="autoPlay" value="true"> <param name="bgcolor" value="#000000"> <param name="flashvars" value="state=embed&clipId=1443535498"> <param name="menu" value="true"> <param name="RSI" value="cbc-production"> <param name="salign" value="tl"> <param name="scale" value="noscale"> <a href="http://cbc.ca/oneocean/video.html?clipID=1443535498" rel="video"> <img alt="Environmentalist and scientist Dr. David Suzuki shares his thoughts on how poorly people have treated the ocean." src="http://staging.oneoceanonline.org/ocean_explorer/tours/video-screenshots/pollution-1429704442.jpg" width="460" height="256" /> </a> </object> </div> <div> <p> Environmentalist and scientist Dr. David Suzuki shares his thoughts on how poorly people have treated the ocean. From taking too much out, as population growth and advances in technology have led to overfishing, to putting too much in, as human garbage is filling the ocean. </p> </div> ]]></description> <LookAt> <longitude>72.18995231957163</longitude> <latitude>21.4025518645366</latitude> <altitude>0</altitude> <range>2772.760523150278</range> <tilt>0</tilt> <heading>-0.006678966784949207</heading> <altitudeMode>relativeToGround</altitudeMode> <gx:altitudeMode>relativeToSeaFloor</gx:altitudeMode> </LookAt> <styleUrl>#oe_placemark</styleUrl> <Point> <coordinates>72.18995231957163,21.4025518645366,0</coordinates> </Point> </Placemark>
In part 1, you made a folder called Overlays. You should see it in your KML file now, and this is where you should put your ScreenOverlays. Have a look below at an example of the Overlays folder with one ScreenOverlay within.
- ScreenOverlay id – just a descriptive identifier for this overlay.
- color – 00ffffff – the important part is the 00 at the beginning. This defines how transparent the image should be (00 is fully transparent, ff is opaque). We want our images to start out transparent, and slowly fade in (because it looks cool)
- Icon href - the URL to the image.
- overlayXY, screenXY – notice the units are set to fraction, and the values are 0.5. This places the image in the exact middle of the screen.
- size – the width and height of the image.
<Folder> <name>Overlays</name> <ScreenOverlay id="01-sea-lion"> <name>Sea Lions</name> <color>00ffffff</color> <Icon> <href>http://cbc.ca/oneocean/ocean_explorer/tours/Images/Pollution/01-sea-lion.jpg</href> </Icon> <overlayXY x="0.5" y="0.5" xunits="fraction" yunits="fraction"/> <screenXY x="0.5" y="0.5" xunits="fraction" yunits="fraction"/> <rotationXY x="0" y="0" xunits="fraction" yunits="fraction"/> <size x="400" y="300" xunits="pixels" yunits="pixels"/> </ScreenOverlay> </Folder>
A FlyTo directs the camera where to go during the tour. You’ll see tens or hundreds of these tags throughout the file, depending on how long your tour is.
<gx:FlyTo> <gx:duration>0.2171179598519757</gx:duration> <gx:flyToMode>smooth</gx:flyToMode> <Camera> <longitude>-160.3462684213953</longitude> <latitude>-12.76946560319076</latitude> <altitude>23729071.04085288</altitude> <heading>-14.49228981377314</heading> <tilt>0</tilt> <roll>0</roll> <altitudeMode>absolute</altitudeMode> </Camera> </gx:FlyTo>
This tag tells the camera to wait at the current point for a number of seconds. Usually you’re waiting for a narration to finish, or waiting while an image is displayed on the screen.
Putting in your own tags
My first scan through the KML, I will put in comments to help me remember where the camera is located at that point in the tour. Go through the code and look for <gx:Wait> tags with larger values (ie: 2 seconds and up). Remember that when you recorded the tour, you waited at each placemark for a little while – by finding this <gx:Wait> tag, you’ve located the point at which the camera arrives at the first placemark. There may also be a <gx:AnimatedUpdate> here, which usually means that a placemark balloon is being displayed.
<!-- Depart-for: "name of destination" --> <!-- Arrive-at: "name of destination" -->
To begin playing an audio file, use the code below. I like to add a comment describing the file.
<!-- Narrate: pollution 3 - "This Northern right whale, already an endangered species, is trapped in a floating " --> <gx:SoundCue> <href>files/pollution 3.mp3</href> </gx:SoundCue>
Showing a placemark description balloon
In the code below, we show the alang placemark’s description, pause the tour and wait for the user to press play, then hide the description. The pause gives the user time to read the description, or watch the video. Note that there is a one second <gx:Wait> at the end to give the balloon a bit of time to fully close before moving on with the tour.
<!-- Show balloon, pause, then hide balloon --> <!-- Show: Balloon --> <gx:AnimatedUpdate> <Update> <targetHref></targetHref> <Change><Placemark targetId="alang"><gx:balloonVisibility>1</gx:balloonVisibility></Placemark></Change> </Update> </gx:AnimatedUpdate> <!-- Pause --> <gx:TourControl></gx:TourControl> <!-- Hide: Balloon --> <gx:AnimatedUpdate> <Update> <targetHref></targetHref> <Change><Placemark targetId="alang"><gx:balloonVisibility>0</gx:balloonVisibility></Placemark></Change> </Update> </gx:AnimatedUpdate> <gx:Wait><gx:duration>1</gx:duration></gx:Wait>
Showing a screen overlay
Here we are fading in the 09-leatherback overlay, waiting for 20 seconds, and then fading it out. Read my comments within my code for a description of what each tag is doing.
<!-- Show: Overlay: 09-leatherback --> <gx:AnimatedUpdate> <!-- make sure overlay is hidden --> <Update> <targetHref></targetHref> <Change><ScreenOverlay targetId="09-leatherback"><visibility>1</visibility><color>00ffffff</color></ScreenOverlay></Change> </Update> </gx:AnimatedUpdate> <gx:AnimatedUpdate> <!-- fade the overlay into visibility over 2 seconds --> <gx:duration>2</gx:duration> <Update> <targetHref></targetHref> <Change><ScreenOverlay targetId="09-leatherback"><visibility>1</visibility><color>ffffffff</color></ScreenOverlay></Change> </Update> </gx:AnimatedUpdate> <gx:Wait><gx:duration>20</gx:duration></gx:Wait> <!-- keep the overlay on the screen for 20 seconds --> <gx:AnimatedUpdate> <!-- fade the overlay out over 2 seconds --> <gx:duration>2</gx:duration> <Update> <targetHref></targetHref> <Change><ScreenOverlay targetId="07-garbage"><visibility>1</visibility><color>00ffffff</color></ScreenOverlay></Change> </Update> </gx:AnimatedUpdate>
Testing as you go
As you make changes, you’ll want to test that everything looks fine in Google Earth — use the Revert feature (described earlier) to load your changes. Getting your wait durations to be just right can be time consuming, so make sure you give these plenty of time: it’s simpler to trim it down than to figure out how much you need to lengthen a wait.
Packing it up
Once we’re satisfied with our tour, it’s time to pack it up as a KMZ file. Now, this is just a ZIP file that contains your KML and audio files… nothing fancy. To make a KMZ file:
- Right click in your project’s folder (ie: where your KML file is located)
- Click New | Compressed (zipped) Folder
- A ZIP file will be created.
- Name this file the same as your KML file (eg: pollution.zip)
- Drag your KML file and your files folder (containing your audio files) into this ZIP file.
- Rename the ZIP file so it ends in .kmz (eg: change pollution.zip to pollution.kmz)
Now you’ve got a KMZ file you can distribute to anyone, and they’ll be able to see your tour!