Yamar at 05:54, 9 December 2007

2007-12-09T05:54:18Z

New page

== KML Code overview ==

The KML export code is shown in full below (at least a snapshot of it
at one point in time, namely near December 2007).

This is written up below in sections in hope that people may learn
from it (note that the KML plugin does more complex things than most plugins).

== Header Section ==

This section of code simply imports a bunch of other needed modules,
declares the version, etc.

# Copyright (C) 2007 Wes Hardaker
# License: GNU GPLv2. See the COPYING file for details.
package GeoDB::Export::Kml;

use strict;
use GeoDB::Export;
use GeoDB::Utils;
use GeoDB::Export::Density;
use IO::File;
use QWizard;

our $VERSION = "0.95";

Here we specify that we're a child class of two other modules, the
''GeoDB::Export'' and ''GeoDB::Export::Density'' modules. Since we're
an export plugin, we must inherit from the first. The second is a
second code file that contains the actual KML density calculating bits
(and eventually it should be a generic density system that could be
used to output things other than KML, but right now it isn't).

In perl, the @ISA variable is what defines your parent classes:

our @ISA = qw(GeoDB::Export GeoDB::Export::Density);

=== KML Option Definitions ===

The following is an array of keyword/human-string pairs we use just a
bit later.

our @altitudeValues =
(relativeToGround => 'relative to the ground',
absolute => 'absolute height above sea level');

The GEOOPTIONS array is a geoqo special variable that is looked for by
code much higher up. This is where we declare all the options to the
given plugin. The KML plugin has more than it's fair share of options
(more than any other) so this section is pretty long. The array
contains a list of perl hashes, where each hash contains keyword/value
pairs describing information about the option.

These options are used by many other parts of the geoqo code. They
automatically turn into the [[GUI]] help screen, they automatically
get used by the ''-d help:export/kml'' help output, the defaults are
all set by things above, the command line parsing (eg: ''-e
kml:dataname=blah:file.kml'') is all handled elsewhere based on the
data in this array. All good geoqo plugins should use this special
array name to declare their options to take advantage of these
features. (even the [http://www.geoqo.org/usage.html geoqo manual
page] takes information from this!)

our @GEOOPTIONS =
(

The first option is a label that is printed to user:

{ name => 'bogus',
type => 'label',
text => 'Basic Settings:',
},

This second one is a normal text box in the GUI that just needs a name
(and it's indented slightly. It's default value, if the user doesn't
pick one, is ''Export from GeoQO'':

{ name => 'dataname',
text => 'Name to call the results:',
default => 'Export from GeoQO',
indent => 1,
},

These three are ''checkbox'' options and the resulting value stored in
the ''dowaypoints'', etc... option variables and will be a 1 or a 0
based on ifit's checked or not. The ''refresh_on_change'' token is
needed to make the gui screen redraw after the user changes the value
(we'll see why in a second).

{ name => 'dowaypoints',
text => 'Include waypoint/geocache markers:',
type => 'checkbox',
refresh_on_change => 1,
default => 1,
},
{ name => 'dodensity',
text => 'Create a density map:',
type => 'checkbox',
refresh_on_change => 1,
default => 1,
},
{ name => 'dojail',
text => 'Show .1 mile radius circles',
type => 'checkbox',
refresh_on_change => 1,
default => 0,
},

This just puts a blank line for a separator:

"",

And we start a new section with a new label. Here note that the
''doif'' section tests the results of the ''dowaypoints'' variable
above. If it's set, then this widget is shown. If not, then it's
hidden (and the ''refresh_on_change'' mentioned above forces this to
hide and unhide when the user clicks on the checkbox or not). All of
the following options make use of this feature.

We'll show a bunch of options in a row now, and you can see the
general point by simply studying them for a bit. Note that the second
option is also a menu when shown in the GUI:

These all relate to saving each waypoint in the output file.

{ name => 'bogus',
type => 'label',
text => 'Configuration of the Waypoints:',
doif => sub {qwparam('dowaypoints') eq '1'},
},
{ name => 'waypointstyle',
type => 'menu',
text => 'Waypoint Style',
labels => ['geoqo' => 'Unique icons per difficulty and waypoint type',
'pushpin' => 'A single pushpin at each waypoint',
],
default => 'geoqo',
indent => 1,
doif => sub {qwparam('dowaypoints') eq '1'},
},
{ name => 'waypointheight',
text => 'Waypoint Altitude',
default => 150,
indent => 1,
helpdesc => '(0 means on the ground)',
doif => sub {qwparam('dowaypoints') eq '1'},
},
{ name => 'waypointmode',
text => 'Altitude mode',
type => 'menu',
labels => \@altitudeValues,
default => 'relativeToGround',
doif => sub {qwparam('dowaypoints') eq '1'},
indent => 1,
},
{ name => 'waypointextrude',
type => 'checkbox',
text => 'Draw a line to the ground:',
indent => 1,
default => 1,
doif => sub {qwparam('dowaypoints') eq '1'},
},
{ name => 'includedescriptions',
type => 'checkbox',
text => 'Include cache descriptions in output:',
indent => 1,
default => 1,
doif => sub {qwparam('dowaypoints') eq '1'},
},

Then we move on to the options relating to density plots.

"",
{ name => 'bogus',
type => 'label',
text => 'Configuration of the density grid:',
doif => sub {qwparam('dodensity') eq '1'},
},
{ name => 'squareratio',
default => '1',
type => 'checkbox',
text => 'Use a square grid',
indent => 1,
refresh_on_change => 1,
doif => sub {qwparam('dodensity') eq '1'},
},
{ name => 'size',
default => 200,
indent => 1,
title => 'Number of squares on a side of the density plot',
help => 'Creates a plot where there are SIZE by SIZE squares of colored rectangles',
doif => sub {qwparam('squareratio') eq '1' && qwparam('dodensity') eq '1'},
},
{ name => 'width',
indent => 1,
title => 'Width in squares of the rectangular density plot',
help => 'Normally equal to the size value but can be set independently. It specifies the width (in squares) of the density plot.',
doif => sub {qwparam('squareratio') ne '1' && qwparam('dodensity') eq '1'},
},
{ name => 'height',
indent => 1,
title => 'Height in squares of the rectangular density plot',
help => 'Normally equal to the size value but can be set independently. It specifies the height (in squares) of the density plot.',
doif => sub {qwparam('squareratio') ne '1' && qwparam('dodensity') eq '1'},
},
{ name => 'spread',
title => 'Spreading Distance',
indent => 1,
help => 'Sets the spread that determines the number of neighboring squares that a given cache will effect. EG, a spread of 5 will affect a circle of density squares in a radius of 5. This generally should be a low value of probably not more than 5 or so.',
default => 5,
doif => sub {qwparam('dodensity') eq '1'},
},
{ name => 'doempty',
title => 'Include empty squares in the density plot:',
help => 'If set to 1, even empty squares will be colored (red). Otherwise the empty squares are removed from the plot leaving the plane ground underneath.',
indent => 1,
type => 'checkbox',
default => 0,
doif => sub {qwparam('dodensity') eq '1'},
},

"",
{ name => 'bogus',
type => 'label',
text => 'Configuration Parameters for shape style:',
doif => sub {qwparam('dodensity') eq '1'},
},
{ name => 'altitude',
title => 'Altitude of density plot squares',
indent => 1,
help => 'The altitude to set the density plot squares at.',
default => 1000,
doif => sub {qwparam('dodensity') eq '1'},
},
{ name => 'densitymode',
text => 'Altitude mode:',
type => 'menu',
labels => \@altitudeValues,
default => 'relativeToGround',
doif => sub {qwparam('dodensity') eq '1'},
indent => 1,
},
{ name => 'extrude',
title => 'Extrude the density plot to the ground:',
help => 'Whether or not to extrude the density plot squares down to the ground.',
type => 'checkbox',
indent => 1,
default => 0,
doif => sub {qwparam('dodensity') eq '1'},
},
{ name => 'opaque',
title => 'Opaqueness of the density squares:',
helpdesc => '(0-100; 0 being completely see-through)',
help => 'The opacity of the density squares. Must be between 0 and 100, with 0 being completely see-through (and thus completely useless).',
indent => 1,
default => 20,
doif => sub {qwparam('dodensity') eq '1'},
},
{ name => 'linewidth',
title => 'Line width:',
help => 'The width of the border lines to draw (0-4). 0 means don\'t draw borders on the squares.',
indent => 1,
default => 0,
doif => sub {qwparam('dodensity') eq '1'},
},

These options relate to doing a 528 foot circle around each cache
(which I refer to as a "jail" since it prevents other caches from
being placed near it):

"",
{ name => 'bagus',
type => 'label',
text => 'Configure .1 mile radius circles:',
doif => sub {qwparam('dojail') eq '1'},
},
{ name => 'jailaltitude',
text => 'Altitude of the circles:',
default => '100',
doif => sub {qwparam('dojail') eq '1'},
indent => 1,
},
{ name => 'jailmode',
text => 'Altitude mode:',
type => 'menu',
labels => \@altitudeValues,
default => 'relativeToGround',
doif => sub {qwparam('dojail') eq '1'},
indent => 1,
},

And finally, some extra options that let you limit the input data by a
square boundary:

"",
{ name => 'bogus',
type => 'label',
text => 'Limit the input data:',
},
{ name => 'limitdata',
default => '1',
type => 'checkbox',
indent => 1,
text => 'Use all the data from the search set',
refresh_on_change => 1,
},
{ name => 'nmax',
title => 'Maximum North coordinate:',
indent => 1,
help => 'The maximum north coordinate value to created the grid over. Normally this is automatically set by the maximum value found in the data, but can be overridden',
doif => sub {qwparam('limitdata') ne '1'},
},
{ name => 'nmin',
title => 'Minimum North coordinate:',
indent => 1,
help => 'The minimum north coordinate value to created the grid over. Normally this is automatically set by the minimum value found in the data, but can be overridden',
doif => sub {qwparam('limitdata') ne '1'},
},
{ name => 'wmax',
title => 'Maximum West coordinate:',
indent => 1,
help => 'The maximum west coordinate value to created the grid over. Normally this is automatically set by the maximum value found in the data, but can be overridden',
doif => sub {qwparam('limitdata') ne '1'},
},
{ name => 'wmin',
title => 'Minimum West coordinate:',
indent => 1,
help => 'The minimum west coordinate value to created the grid over. Normally this is automatically set by the minimum value found in the data, but can be overridden',
doif => sub {qwparam('limitdata') ne '1'},
}
);

Whew. Done.

=== The Actual KML Export Magic ===

First a simple subroutine called _x() which just replaces >, <
and & with legal values in XML (> becomes &gt;):

sub _x {
return GeoDB::Export::_add_basic_entity(@_);
}

Here's the actual function that gets called by geoqo when someone
wants to export to KML. The GUI screen showing all of the options
above may have already been called at this point, or command line
option processing may have been. Either way, the function only needs
to assume that it's all been dealt with.

Every export module needs to implement the ''export_it'' function.
The function passed 3 arguments: A ''self'' reference to the KML
export object, a file name to put the results in, and a GeoQO [[set]]
that is the waypoint data it should be exporting.

sub export_it {
my ($self, $file, $set) = @_;

Open the file and set the ''$fh'' variable as the filehandle to write to:

GEODEBUG(1,"writing file: $file\n");
my $fh = new IO::File ">$file";

Print the starting XML header to the file:

print $fh "<?xml version=\"1.0\" encoding=\"utf-8\"?>
<kml xmlns=\"http://earth.google.com/kml/2.2\">
<Document>

The next line shows the use of the ''dataname'' option variable,
which was one of the first in the ''GEOOPTIONS'' variable above
describing the options that can be passed.

<name>$self->{'options'}{'dataname'}</name>
<open>1</open>
<description>This file was created using GeoQO, which is available from http://www.geoqo.org/</description>
";

We set up some basic variables that remember the possible icons
(shapes), difficulty levels (diffs):

# these match dist/makeicons
my @shapes = ('micro', 'small', 'regular', 'large', 'nosize', 'multi',
'virtual', 'unknown', 'solved', 'webcam', 'event', 'earth');
my @diffs = (qw(1 1.5 2 2.5 3 3.5 4 4.5 5));

my %shapes;

If the style they selected in the ''waypointstyle'' option was
''geoqo'' (the default) then they want a different icon per cache type
and difficulty level combination. We need to output all the style
definitions into the KML file, so we do that next and it goes near the
top of the KML file.

It does this by writing a section of KML for each difficulty for each
shape. These link to icons stored on the geoqo website:

# define the styles needed
if ($self->{'options'}{'waypointstyle'} eq 'geoqo') {
foreach my $shape (@shapes) {
$shapes{$shape} = 1; # cache for later check if we can do it
foreach my $diff (@diffs) {
$diff =~ s/\.//;
print $fh " <Style id=\"$shape$diff\">
<IconStyle>
<Icon>
<href>http://www.geoqo.org/images/icons/geocaches-$shape-$diff.png</href>
</Icon>
</IconStyle>
</Style>
";
}
}
}

Now that we have the styles created, we have to create the top level
folder structure in the KML language:

print $fh "<Folder>
<name>$self->{'options'}{'dataname'}</name>
<description>$self->{'options'}{'dataname'}</description>\n";

Now we just process a bunch of options above into local variables;
this is not strictly necessary, but it's a bit faster to refer to
local variables a bunch of times than repeatedly look into the
$self->{'options'}{'....'} structure for each look up if we're going
to do it a lot:

# remember options
my $geoqostyle = 0;
$geoqostyle = 1 if ($self->{'options'}{'waypointstyle'} eq 'geoqo');
my $doextrude = "";
my $doextrude = "\n <extrude>1</extrude>"
if ($self->{'options'}{'waypointextrude'});
my $height = $self->{'options'}{'waypointheight'};
my $mode = $self->{'options'}{'waypointmode'};

my $dodescriptions = $self->{'options'}{'includedescriptions'};

=== Waypoint Creation ===

We only export the waypoints themselves if the ''dowaypoints''
option (checkbox) was set:

# nopoints is historic...
if ($self->{'options'}{'dowaypoints'} && !$self->{'options'}{'nopoints'}) {

If so, then we need to create a sub-folder within the KML file and
name it appropriately:

print $fh " <Folder>
<name>$self->{'options'}{'dataname'}: Waypoints</name>\n";

This starts setting up the progress bar and sets the maximum number
that we're going to call it. In this case, we're going to set it to
the number of waypoint points in the set. Note that not all the GUI
backends support progress bars (EG, Tk doesn't which means windows
users won't see it):

my $count = 0;
my $next = 0;
$self->setup_progress($set->num(), "Creating Waypoints");

The GeoDB::Set object that we were passed which is full of waypoints
has a nice ''foreach'' function that can be called. You pass it a
reference to another function (in this case, a function declared right
inside the argument list). Basically, all the code starting with the
''sub {'' and beyond gets called once per waypoint. The subroutine is
passed a GeoDB::Waypoint object as the option.

This bit of code prints each waypoint one at a time as the subroutine
defined gets called multiple times. The $_[0] statement refers to the
GeoDB::Waypoint object. All the waypoint data in one of these objects
is stored in the $object->{'data'} hash. EG, the latitude is stored
in: $object->{'data'}{'lat'}

$set->foreach(sub {
$next = $self->set_progress($count++)
if ($count >= $next);
my $style = ($geoqostyle) ? get_tomtom_style($_[0])
: "#khStyle652";
my $c=$_[0]{'data'};
my $type = ($c->{'subtype'} ? "$c->{'type'}|$c->{'subtype'}" : $c->{'type'});

my $description = "";
if ($dodescriptions) {
$description = "<description><![CDATA[";
if ($c->{'groundspeak_short_description_html'} eq 'True') {
$description .=
$c->{'groundspeak_short_description'};
} else {
$description .=
"<pre>" .
_x($c->{'groundspeak_short_description'}) .
"</pre><br />";
}

if ($c->{'groundspeak_long_description_html'} eq 'True') {
$description .=
$c->{'groundspeak_long_description'}
} else {
$description .=
"<pre>" .
_x($c->{'groundspeak_long_description'}) .
"</pre>";
}
$description .= "]]></description>";
}

print $fh "
<Placemark>
<name>" . _x($c->{'ident'} . ": " . $c->{'urlname'}) . "</name>$description
<styleUrl>$style</styleUrl>
<Point>$doextrude
<tessellate>0</tessellate>
<altitudeMode>$mode</altitudeMode>
<coordinates>" . _x($c->{'lon'}) . "," . _x($c->{'lat'}) . ",$height</coordinates>
</Point>
</Placemark>
";
});

That was a lot of code just to print out each waypoint description,
but you'll note a lot of it was deciding whether to print description
information and formatting the output.

Then we stop the progress update so the progress bar window goes away:

$self->stop_progress();

And close off the waypoint folder:

print $fh "</Folder>\n";
}

=== 528 Foot Circle Creation ("jails") ===

Next we do the 528 foot circles, but only if requested via the dojail option:

# create jails around the cache
if ($self->{'options'}{'dojail'}) {

And we place them in their own folder too, just like the waypoints above:

print $fh " <Folder>
<name>$self->{'options'}{'dataname'}: Waypoint .1 Mile Boundaries</name>\n";

First, we need to calculate a ring of points. We basically just store
a ring of latitude, longitude points inside two arrays (distringx and
distringy). The ''cos'' and ''sin'' functions are used to plot the
circumference of a circle in 16 points. Then we multiply it by the
radius distance, which is .001428 between each lat/lon. This actually
works for latitude but for the longitude it'll be right at the equator
but very very wrong at the poles. This needs to be accounted for in
the future...

# calculate a ring
my (@distringx, @distringy);
my $ringcount = 16;
my $radiusdist = .001428; # right for lat, wrong for long
for (my $i = 0; $i < $ringcount; $i++) {
push @distringx, cos(2 * 3.1415 * $i / $ringcount) * $radiusdist;
push @distringy, sin(2 * 3.1415 * $i / $ringcount) * $radiusdist;
}
push @distringx, cos(0) * $radiusdist;
push @distringy, sin(0) * $radiusdist;

More options to just remember in variables for later:

my $altitude = $self->{'options'}{'jailaltitude'};
my $mode = $self->{'options'}{'jailmode'};

This color is transparent (80), no blue (00), no green (00) and
maximum red (ff):

my $color = "800000ff";
my $linewidth = 1;
my $extrude = 1;

Again we start a progress bar (but it's so fast usually you won't see it):

my $count = 0;
my $next = 0;
$self->setup_progress($set->num(), "Creating Jail Circles");

Now, we use the same foreach method mentioned above.

$set->foreach(sub {

These update the progress bar:

$count++;
$next = $self->set_progress($count++)
if ($count >= $next);

Now we create a variable reference to the waypoint data in the 'data' hash:
(not really necessary, but...)

my $c=$_[0]{'data'};

And print a Polygon KML object for each cache:

print $fh "
<Placemark id=\"jail$count\">
<name>GeoJail$count</name>
<Style>
<PolyStyle>
<color>$color</color>
</PolyStyle>
<LineStyle>
<width>$linewidth</width>
<color>$color</color>
</LineStyle>
</Style>
<Polygon id=\"poly$count\">
<extrude>$extrude</extrude>
<tessellate>0</tessellate>
<altitudeMode>$mode</altitudeMode>
<outerBoundaryIs>
<LinearRing>
<coordinates>
";

Here we print coordinates for the ring in the real wold by taking the
lat/lon of the waypoint and then add in the circle difference at each
point that we calculated above. Sometimes the circle point will be
negative, sometimes positive. IE, the points this prints out will
rotate around the waypoint point at a fixed distance (528 feet) at
each point from the starting lat/lon location of the waypoint.

for (my $i = 0; $i <= $ringcount; $i++) {
print $fh ($c->{'lon'}+$distringy[$i]) . "," .
($c->{'lat'}+$distringx[$i]) . "," .
$altitude, " ";
}

Then print the closing part of the waypoint circle KML code:

print $fh "
</coordinates>
</LinearRing>
</outerBoundaryIs>
</Polygon>
</Placemark>
";
});

And stop the progress bar again, and close the circle:

$self->stop_progress();

print $fh "</Folder>\n";
}

=== Density Plot Function Invocation ===

Now, we actually print the density plot. The get_density_map function
is actually defined inside the GeoDB::Export::Density module instead.
We'll include it below and explain it as well. In the meantime, just
know that it prints out a bunch more KML polygons to represent the
density clouds:

# nodensity is historic
$self->get_density_map($set, $fh)
if ($self->{'options'}{'dodensity'} && !$self->{'options'}{'nodensity'});

And then we close the whole thing off.

The remaining code in this section are some functions that calculate a
icon name from the geocache information. Traditionals are put into
icons according to size, the rest are put into icons according to
cache type. The icon name also has the difficulty level in it, so a
small icon at difficulty 2 becomes small2. The decimal is dropped, so
a small at 2.5 becomes small25.

print $fh "</Folder>
</Document>
</kml>
";
}

my %containers =
(
'Micro' => 'micro',
'Small' => 'small',
'Regular' => 'regular',
'Not chosen' => 'nosize',
'Other' => 'nosize',
'Large' => 'large',
);

my %types =
(
'Multi-cache' => 'multi',
'Unknown Cache' => 'unknown',
'Virtual Cache' => 'virtual',
'Webcam Cache' => 'webcam',
'Event Cache' => 'event',
'Earthcache' => 'earth',
# XXX!!! need letterbox!
# 'Letterbox Hybrid' => 'letter',
);

sub get_tomtom_style {
# this matches the code in scripts/devices/tomtom too
my $cache = $_[0];

# XXX: infield vs solved...

# traditionals break down by size
if ($_[0]{'data'}{'subtype'} eq 'Traditional Cache') {
if (exists($containers{$_[0]{data}{groundspeak_container}})) {
my $diff = $_[0]{data}{groundspeak_difficulty};
$diff =~ s/\.//;
return "#$containers{$_[0]{data}{groundspeak_container}}$diff";
}
} else {
if (exists($types{$_[0]{data}{subtype}})) {
return "#$types{$_[0]{data}{subtype}}$_[0]{data}{groundspeak_difficulty}";
}
# the rest get icons for the type
}
return "#khStyle652";
}

=== Density Plot Code ===

This is actually from the GeoDB::Export::Density code file:

.

Breakdown of the KML Plugin - Revision history

Yamar at 06:50, 9 December 2007

Yamar at 05:54, 9 December 2007