Google Earth KML Plugin

Introduction

TrackDataPlugIn and TrackKMLPlugIn are DataTurbine PlugIns which format alt/lat/lon DataTurbine channel data into a KML document for viewing in Google Earth. These PlugIns come with the DataTurbine distribution; they are located within the Apache Tomcat directory at:

apache-tomcat-6.0.18/webapps/webTurbine/WEB-INF/classes

This document provides some information on using these PlugIns, as well as how to setup Google Earth for viewing the track data returned from these PlugIns.

TrackDataPlugIn

TrackDataPlugIn fetches the low-level data (altitude, longitude, latitude) from the DataTurbine channels and returns it to TrackKMLPlugIn (for final processing into a KML document).  As such, your DataTurbine source needs to contain alt, lat, and lon channels. The default channel names assumed by TrackDataPlugIn are “Alt”, “Lat”, and “Lon”.  If your DataTurbine Source doesn’t use these exact channel names, you will need to specify your channel names in a TrackDataPlugIn config file, and then on the command line to start TrackDataPlugIn you use the “-f” command line flag to specify this config file’s name.  Here is an example of this file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
#
# This file provides TrackPlugIn the names of the
# alt, lat, lon, id, type, and classification RBNB channel names.
#
# Blank lines or lines that start with '#' will be skipped
  
#
# The left column indicates the type of channel (see codes below).
# The right column provides the specific RBNB channel name this data will be acquired from.
#
# The channel name codes are as follows (these names must be exactly used in the left column):
# alt (altitude channel)
# lat (latitude channel)
# lon (longitude channel)
# id (track id channel)
# type (type channel)
# class (classification channel)
  
alt  GPS_Alt_MSL
lat  Latitude
lon  Longitude

When you launch TrackDataPlugIn, the following items must be included in the classpath: the path to the TrackDataPlugIn classes and also the path to rbnb.jar.  Here is an example:

        java -cp C:\PROGRA~1\RBNB\V3.2B5\apache-tomcat-6.0.18\webapps\webTurbine\WEB-INF\classes;C:\PROGRA~1\RBNB\V3.2B5\bin\rbnb.jar TrackDataPlugIn -f TrackDataConfig.txt -n TrackData

The “-f” flag specifies the name of the config file and the “-n” flag specifies the name that will be registered for your PlugIn with the DataTurbine server (that is, the name that you would use for making data requests).  If you run TrackDataPlugIn with a “-h” flag you can check out the other command line options available.

TrackKMLPlugIn

TrackKMLPlugIn receives raw data (altitude, latitude, longitude) from TrackDataPlugIn and formats this data for output as a KML document.  This PlugIn uses an input config file to specify various options for how the track will look in Google Earth.  This file is specified with the “-f” command line option when launching TrackKMLPlugIn.  Here is a sample config file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
#
# This file specifies GUI options for TrackKMLPlugIn
#
# Blank lines or lines that start with '#' will be skipped
#
#
# Display parameter options
# Parameter Options
#------------------------------------------------------------
# labelBy   id/type/class/alt/latlon/altlatlon/none; any other entry will be treated as the constant label
# sortBy    id/type/class
# iconBy    type/class/dot/square/airplane/none
# colorBy   type/class/red/green/blue/yellow/purple/aqua; any other entry will be treated as the constant color (must be HEX number in format bbggrr)
#
labelBy Foo
sortBy   id
iconBy   airplane
iconScale   1.0
colorBy  red
#
# To add current values as part of the label:
# label_chan    <chan1>=<nickname1>,<chan2>=<nickname2>,etc.
#
# - "chan" specifies a relative channel within the same Source as the track data is fetched from.
# In other words, "chan" cannot be an absolute Source/Channel name.
# - The "nickname" specifies the string that will be displayed in Google Earth with the data value.
#
label_chan  GPS_Alt_MSL=Alt(m)
 

In this sample config file, we specify to use an airplane icon in Google Earth, label the icon “Foo”, and color the track red.  This file also specifies to display the Altitude value along with the aircraft icon in Google Earth.
When you launch TrackKMLPlugIn, the following items must be included in the classpath: the path to the TrackKMLPlugIn classes and also the path to rbnb.jar.  Here is an example:

java -cp C:\PROGRA~1\RBNB\V3.2B5\apache-tomcat-6.0.18\webapps\webTurbine\WEB-INF\classes;C:\PROGRA~1\RBNB\V3.2B5\bin\rbnb.jar TrackKMLPlugIn -C -f TrackKMLConfig.txt -n TrackKML

The “-f” flag specifies the name of the config file and the “-n” flag specifies the name that will be registered for your PlugIn with the DataTurbine server (that is, the name that you would use for making data requests).  If you run TrackKMLPlugIn with a “-h” flag you can check out the other command line options available.

Viewing tracks in Google Earth
========================
The following software needs to be running for a complete end to end solution:

  • DataTurbine server
  • An instance of TrackDataPlugIn and TrackKMLPlugIn
  • Your DataTurbine Source application, which puts alt/lat/lon data into the DataTurbine
  • Apache Tomcat server (comes with the DataTurbine distribution); supports an HTTP interface for fetching data from the DataTurbine
  • Optional: TimeDrive server (comes with the DataTurbine distribution); provides a TiVO-like interface for requesting historical or real-time data from the DataTurbine server
  • Google Earth, to view the KML documents fetched from the DataTurbine

Here are some instructions on getting the system going with Google Earth:

  1. Start DataTurbine server, Apache Tomcat server, your Source application, and instances of the track PlugIns
  2. Start Google Earth and create a “NetworkLink” object (which is used to periodically fetch KML documents via a URL).
    • The URL to include in the NetworkLink will be something like: http://localhost/RBNB/TrackKML/TrackData/Foo?d=500
    • Here, we are using “Foo” for the name of the DataTurbine source.  This URL requests 500 seconds worth of the most recent data (note the “?d=500” munge).
  3. If you want to create an even “slicker” system, instead of using a static URL such as the one above, start an instance of TimeDrive and allow the user to play/step through their data.
    • An instance of the TimeDrive server needs to be started; timedrive.jar is located in the same directory as rbnb.jar.
    • By default, TimeDrive uses port 4000.  If you need to specify a different port, you can use the “-s” command line flag.  If you use a different port, a further tweak needs to be made in the Tomcat “TimeDrive” servlet configuration file, located at “apache-tomcat-6.0.18\webapps\TimeDrive\WEB-INF\web.xml”.
    • An example of launching TimeDrive: java -jar C:\PROGRA~1\RBNB\V3.2B5\bin\timedrive.jar -u localhost -d0 -m 2
    • When using TimeDrive, the URL you specify in the NetworkLink in Google Earth must change to something like: http://localhost/TimeDrive/RBNB/TrackKML/TrackData/Foo; note that we no longer need the time duration munge (“?d=500”) because the user will specify start time and duration for the data request using the TimeDrive web interface.
    • To see the TimeDrive web interface, go to the following URL in a browser: http://localhost/TimeDrive
  4. You can also provide a Google Earth “setup” file for users, which specifies a desired collection of NetworkLinks.  The user simply loads this file into Google Earth (using File->Open).  Here is an example of a simple setup file.  In this case, Google Earth will automatically request a new KML document every 3 seconds.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<?xml version="1.0" encoding="UTF-8"?>
  <Document>
    <Folder>
      <name>Foo</name>
      <description>
      <![CDATA[<a href="http://localhost/TimeDrive">TimeDrive</a>]]>
      </description>
      <open>1</open>
      <NetworkLink>
        <name>Foo</name>
        <visibility>0</visibility>
        <open>0</open>
        <Url>
          <refreshMode>onInterval</refreshMode>
          <refreshInterval>3</refreshInterval>
        </Url>
      </NetworkLink>
    </Folder>
  </Document>
</kml>

The critical channels in the track data source are alt, lat, and lon. The other channels (speed, heading, class, type, and ID), are all optional. The presense of these channels are legacies from the original use of this code (to process Army tactical data). This tactical legacy is most obvious in the “type” and “class” channels. However, you could create a “type” channel and then have the track icon chosen based on this channel’s value (air, ground, surface, etc). Also, whereas the “type”, “class”, and “ID” channel values can still be used by TrackKMLPlugIn (based on the user’s GUI selections), “speed” and “heading” are not currently used at all. Heading may be used at some point in the future, but currently heading is estimated from the last few lat/lon points.

A feature of these PlugIns that may be useful to someone: TrackKMLPlugIn and TrackDataPlugIn can support a data source which includes more than one track. For instance, the “TrackData” source might have a structure such as:

TrackData
–Track1
—-Alt
—-Lat
—-Lon
–Track2
—-Alt
—-Lat
—-Lon
etc.

In a single request, the TrackKML and TrackData PlugIns can fetch data for the multiple tracks and return a single KML which contains a line for each track in the source.

I ran through this procedure and was able to scrawl a big red line over North Africa in Google Earth, which I dub a success.
It was pretty straightforward once the ducks were lined up. Here’s what I did, running everything on localhost:

  1. Start DataTurbine (rbnb.jar):java -jar $RBNB_HOME/bin/rbnb.jar
  2. prepare and run a source program to generate the data channels that the plugins expect. Here are the critical code bits:
    • String[] chanNames = {“Alt”, “Lat”, “Lon”, “TrackID”, “Type”, “Classification”, “Speed”, “Heading”};
    • cmap.PutDataAsFloat64(cmap.GetIndex(“Alt”), satAlt);
    • cmap.PutDataAsFloat64(cmap.GetIndex(“Lat”), satLatLong);
    • cmap.PutDataAsFloat64(cmap.GetIndex(“Lon”), satLatLong);
    • cmap.PutDataAsString(cmap.GetIndex(“TrackID”), “trackid”);
    • cmap.PutDataAsString(cmap.GetIndex(“Type”), “type”);
    • cmap.PutDataAsString(cmap.GetIndex(“Classification”), “classification”);
    • cmap.PutDataAsFloat32(cmap.GetIndex(“Speed”), satSpeed);
  3. Start WebTurbine (which I modified to run on port 8080):cd $RBNB_HOME/bin && sh ./Start_Webserver.sh
  4. Start the plugins in seperate terminal windows to view their output. I scripted this to make it super simple:
    • 1
      2
      3
      4
      5
      6
      7
            
      #!/bin/sh
      RBNBPI="${RBNB_HOME}/apache-tomcat-5.5.12/webapps/webTurbine/WEB-INF/classes"
      RBNBBIN="${RBNB_HOME}/bin"
      java -cp ${RBNBPI}:${RBNBBIN}/rbnb.jar TrackDataPlugIn -d
    • 1
      2
      3
      4
      5
      6
      #!/bin/sh
      RBNBPI="${RBNB_HOME}/apache-tomcat-5.5.12/webapps/webTurbine/WEB-INF/classes"
      RBNBBIN="${RBNB_HOME}/bin"
      java -cp ${RBNBPI}:${RBNBBIN}/rbnb.jar TrackKMLPlugIn -C -d
  5. Point Google earth at these plugins by doing:
    Add -> Network Link…
    paste in the link: http://localhost:8080/RBNB/TrackKML/TrackData/SatSimKML?d=500
  6. Have fun developing the source program to draw cool pictures
Open Source DataTurbine Initiative © 2016 Frontier Theme