Tour Tutorial

About

How to create a tour. We will create a KML that will reproduce the tour sample in the KML Reference with the edition of simplekml.GxSoundCue.

Creating the Code

First import simplekml and create a KML object:

import simplekml
kml = simplekml.Kml(open=1) # the document will be open in the table of contents

Next create a point feature and style it (note, we change the scale of the icon, this is going to be changed later during the tour:

pnt = kml.newpoint(name="New Zealand's Southern Alps", coords=[(170.144,-43.605)])
pnt.style.iconstyle.scale = 1.0

Now for the important part, creating the tour:

tour = kml.newgxtour(name="Play me!")

Once we have a tour we can create a playlist which will be contained inside of the tour:

playlist = tour.newgxplaylist()

A playlist is a collection of tour primitives (which are basically different events that happen during the tour), whose order is very important. The order that the tour primitives are added to the playlist is the order in which they play. There are five different tour primitives - simplekml.GxAnimatedUpdate, simplekml.GxFlyTo, simplekml.GxSoundCue, simplekml.GxTourControl and simplekml.GxWait. In the following code snippet we will create all of the tour primitives and add them to the playlist:

soundcue = playlist.newgxsoundcue()
soundcue.href = "http://code.google.com/p/simplekml/source/browse/samples/drum_roll_1.wav"
soundcue.gxdelayedstart = 2

animatedupdate = playlist.newgxanimatedupdate(gxduration=6.5)
animatedupdate.update.change = '<IconStyle targetId="{0}"><scale>10.0</scale></IconStyle>'.format(pnt.style.iconstyle.id)

flyto = playlist.newgxflyto(gxduration=4.1)
flyto.camera.longitude = 170.157
flyto.camera.latitude = -43.671
flyto.camera.altitude = 9700
flyto.camera.heading = -6.333
flyto.camera.tilt = 33.5
flyto.camera.roll = 0

wait = playlist.newgxwait(gxduration=2.4)

The order in which we added the tour primitives to the playlist is important. If the simplekml.GxSoundCue was added after the simplekml.GxFlyTo, then Google Earth would wait for the simplekml.GxFlyTo to finish before playling the simplekml.GxSoundCue, but if the simplekml.GxSoundCue is added first it will play at the same time as the simplekml.GxFlyTo. It is best to have a look at the touring section of the KML Reference to familiarise yourself with what exactly is going on with tours. In this example the simplekml.GxSoundCue is delayed from playing by 2 second so the sound with stop playling at about the same time as the whole tour (the sound clip is about 4 seconds long).

Note

According the the KML Reference a tour needs either a simplekml.GxFlyTo or simplekml.GxWait to hold a tour open. If you just have an simplekml.GxAnimatedUpdate the tour plays for zero seconds in Google Earth. So, if you only want a simplekml.GxAnimated make sure you add a simplekml.GxWait tour primitive to the end of the tour with the same duration as the class:simplekml.GxAnimated.

And finally we save the kml:

kml.save("tut_tours.kml")

Complete Code Example

Here is the complete code:

import simplekml

kml = simplekml.Kml(name='9_tours', open=1)

pnt = kml.newpoint(name="New Zealand's Southern Alps", coords=[(170.144,-43.605)])
pnt.style.iconstyle.scale = 1.0

tour = kml.newgxtour(name="Play me!")
playlist = tour.newgxplaylist()

soundcue = playlist.newgxsoundcue()
soundcue.href = "http://code.google.com/p/simplekml/source/browse/samples/drum_roll_1.wav"
soundcue.gxdelayedstart = 2

animatedupdate = playlist.newgxanimatedupdate(gxduration=6.5)
animatedupdate.update.change = '<IconStyle targetId="{0}"><scale>10.0</scale></IconStyle>'.format(pnt.style.iconstyle.id)

flyto = playlist.newgxflyto(gxduration=4.1)
flyto.camera.longitude = 170.157
flyto.camera.latitude = -43.671
flyto.camera.altitude = 9700
flyto.camera.heading = -6.333
flyto.camera.tilt = 33.5
flyto.camera.roll = 0

wait = playlist.newgxwait(gxduration=2.4)

kml.save("tut_tours.kml")