Usage of the DataTurbine KML plugin

This is the text of an email from John Wilson describing the kml plugin. This will be refined and annotated as this plugin is experimented with.
 
TrackDataPlugIn
===============
This fetches the low-level data channels (corresponding to altitude, longitude, latitude, etc) and returns the data to TrackKMLPlugIn.  Your track data source needs to have at least an alt, lat, and lon channel. The default channel names are "Alt", "Lat", and "Lon".  If your RBNB Source doesn't use these channel names, you will need to specify your channel names in a TrackDataPlugIn config file, using the "-f" command line flag.  As an example of this file, you can consult the default config file, located in your RBNB installation at the following (very long!) path:

    apache-tomcat-5.5.12\webapps\webTurbine\
        WEB-INF\classes\TrackResources\TrackConfig.txt

An example of how to launch this PlugIn:

    java -cp <RBNBPI>;<RBNBBIN>\rbnb.jar
        TrackDataPlugIn -f .\TrackDataConfig.txt

where <RBNBPI> is the path to where TrackDataPlugIn is found, and
<RBNBBIN> is the path to where rbnb.jar is found.

If you run TrackDataPlugIn with a "-h" flag you can check out the other command line options available.  Several of these have to do with the type of data compression being used - we use either a Douglas-Peuker algorithm (the default) or a simple decimation algorithm.

TrackKMLPlugIn
==============
Creates a KML-formatted version of the alt/lat/lon data returned from TrackDataPlugIn.  This PlugIn also has an input config file (which can be specified using the "-f" command line flag).  The default config file is available at:

    apache-tomcat-5.5.12\webapps\webTurbine\
        WEB-INF\classes\TrackResources\KMLConfig.txt

The top entries in this file (labelBy, sortBy, iconBy, iconScale, and colorBy) are used to initialize the PlugIn GUI options.  The options further on in the config file will be used less commonly.

An example of how to launch this PlugIn:

    java -cp <RBNBPI>;<RBNBBIN>\rbnb.jar
        TrackKMLPlugIn -C -f .\TrackKMLConfig.txt

where <RBNBPI> is the path to where TrackKMLPlugIn is found, and <RBNBBIN> is the path to where rbnb.jar is found.  You probably want to use the "-C" option as I have shown above.

If you run TrackKMLPlugIn with a "-h" flag you can check out the other command line options available.

Fetching data
=============
1. Start Tomcat, RBNB Server, and your PlugIns

2. Start Google Earth and include the following type of URL in a NetworkLink:

http://localhost/RBNB/TrackKML/TrackData/<RBNB_Source_Name>?d=500

This URL assumes that Tomcat is running on port 80.  This URL will fetch a track of the most recent 500 seconds worth of data.

3. Is you want to create an even slicker system, instead of just 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 in the same directory as rbnb.jar); if you have port 4000 available on the local machine, you can start TimeDrive by simply executing:

    java -jar timedrive.jar

The TimeDrive GUI would be available at:

    http://localhost/TimeDrive

Set the desired time and data duration (called "Interval" in TimeDrive) and then in your Google Earth NetworkLink you can use a URL such as:

http://localhost/TimeDrive/RBNB/TrackKML/TrackData/<RBNB_Source_Name>

Notice that I have taken off the duration munge ("?d=500") from this URL because TimeDrive will now specify the time and duration to use.

When you bring up the TimeDrive interface in a web browser, or when you first request for data through TimeDrive in Google Earth, you will be prompted for a unique username/pw; this isn't an account - it is simply to uniquely identify yourself (so that multiple users can go through one instance of TimeDrive and yet each specify different times in TimeDrive).  To get rid of this username/pw prompting, run TimeDrive using either the "-m 1" or "-m 2" command line flags.

Legacy channels and multiple tracks per source

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.

TrackKML Screen-Shot

This is a very nice example of use of the DataTurbine KML plugin to track a flight tracing a turbine in the air.
http://dataturbine.org/content/dataturbine-kml-screen-shot

- Larry -

Log of Successful Run - Tips & Tricks

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:
    • #!/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

    • #!/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

- Larry -