/ 
Geo-Track-Log-0.02
River stage zero No dependents
/ Geo::Track::Log

NAME

Geo::Track::Log - Represent track logs and find a location based on a track log and a date.

SYNOPSIS

use Geo::Track::Log;
my $log = new Geo::Track::Log;

# add a point to a track log.
$log->addPoint( {
              timestamp => '2004-12-25 12:00:00',
              lat => 0.0,
              long=> 0.0,
} );

$log->addPoint( {
              timestamp => '2004-12-25 13:00:00',
              lat => 0.0,
              long=> 1.0,
} );

Get our location at a time
my ($pt, $sPt, $ePt) = $log->whereWasI('2004-12-25 12:30:00');
or (a synonym)
my ($pt, $sPt, $ePt) = $log->interpolate('2004-12-25 12:30:00');
(see DESCRIPTION for more)

Load tracklog from a Garnix format file
$log->loadTrackFromGarnix('file handle');

Load Waypoint from a Garnix format file
$log->loadWayFromGarnix('file handle');

Fix the funky Garnix line format
my $pt = $log->fixGarnixTrackLine ( qq( 44?  3' 33.23" -123?  5'  0.07" 148.0 WGS84 00:50:19-2004/07/12 [1];) )

Load a GPX (GPS XML) format file
$log->loadTrackFromGPX('file handle');

return the earliest point, by time
my $pt = $log->minTimeStamp();

return the latest point, by time
my $pt = $log->maxTimeStamp();

What percent of the way is time $d between the time at points $sPt and $dPt?
my $pct = $self->getPercent($d, $sPt, $ePt);

DESCRIPTION

whereWasI()?

So we were on the equator and the prime meridean at noon on Christmas.
And one degree of longitude (69 statute miles) at 13:00 (1:00pm).  Assuming
we operated at constant velocity, where were we at 12:30?

$pt = the interpolated point in between the start point ($sPt) and end
point ($ePt).  The points on each side of the line are included because
it seemed to make sense.

The midpoint will be calculated based on a straight linear transfer.  A 
line is metaphorically drawn from $sPt to $ePt.  Then the times are compared
with the time passed to whereWasI(), and the program moves proportionally
up the line from start point to end point.

Note: this calculation is not literally correct because it doesn't strictly
do a Great Circle route calculation.  The Great Circle route calculation
(as well as lots of great Great Circle information) is shown here:
http://williams.best.vwh.net/avform.htm#Intermediate

Since I didn't really understand it, I'll leave it at 'patches welcome.'

At the equator the distance from (0,0) to (1,1) is about 97 statute miles.
from (45,0) to (46,1) is about 84 miles, so caveat emptor.

The method 'interpolate' is offered as a synonym for whereWasI(), in case you 
are using someone else's track log."

load track points from a Garnix format file
$log->loadTrackFromGarnix('filename');

Garnix format looks like this:
44?  3' 33.23" -123?  5'  0.07" 148.0 WGS84 00:50:19-2004/07/12 [1];

The '?' should be a degree marker.  The code handles that.

Garnix also has options to use the abbreviations 'deg' 'min' and 'sec' in
place of the symbols.  As well as having a -y flag to output data in 
Waypoint+ format.  The code doesn't handle that.  Sorry.

EXPLICATION

Geo::Track::Log provides a class to represent, manage, and manipulate track
logs.  At the simplest level, a track log is a series of coordinates that 
represent the virtual bread crumbs of a journey.  As a series of points a 
track log needs no special class.  Throw it into an array of hash refs
and off you go.  This structure is easy to extend to handle track point 
level extensions.  

And once you have lat/long geo data there are many attributes you can
add.  Timestamps? altitude? velocity?  Just fields in the hash ref.

And that is what I did while working on the Geo::Track::Animate module.  
But as happens with software in development, the attributes of a track 
log have grown.   First was the need for a name.  But that was easy.  No
need to break the model.  A scalar name and a scalar pointer to an array
of hashrefs containing track point level attributes.

And then I started to throw track logs around.  Take this set of track 
logs and plot them on a map, and then take this other set and aggregate
them into one track log to animate together.

No problem!  Perl is great!  Arrays of hash refs are wonderful!  Life is
good!

And next I wanted to animate multiple track logs and display each one in 
a different color.  But hey, that is just a presentation level requirement,
and so why would it live with the track log?  And so I told myself these
stories while working on the code.

But all the stories came to an end when I wanted to display a descriptive
label on my track logs.  First I assumed I would use the track log name
as my label.  The problem arose that my track logs were stored in individual
files, and my file naming convention is not presentation layer friendly.

I'm a bit of a geek, but even I was offended by an animated map with track
logs labeled 'tk04032004.txt' and 'tk04052004.txt.'  And I wasn't going to 
change my file naming conventions since aside from its' tersness, 
'tk04032004.txt' is a more precise name then 'Tuesday bike commute.'

And all of this is a round about way of getting to the point.  In biology
ontogeny recapitulates philogeny while in software, perhaps especially 
in Perl (which after all is less software than some variation on runic 
majick) every program evolves in its conception of data from the simple
to the complex and on until the program is subsumed into a pure 
representation as data.

When the actual masters like zool and danbri talk, it is nearly pure
ontology, with an afterthought instruction to the data telling it
to instantiate itself and perform.

Long ago I stumbled on one of my mantras of software development.
Simple data leads to complex code, and complex data allows for 
simple code.

The complexity has to live somewhere.

And all of this leads to the basic knowledge that a module called
Geo::Track::Log is just one step along the path of creating an 
ontology of place.

EXPORT

We don't need no steenking exports!  We are OO geeks now.

SEE ALSO

More on Great Circles
http://williams.best.vwh.net/avform.htm#Intermediate

http://www.mappinghacks.com

Geo::Track::Animate
Audio::DSS

AUTHORS

Rich Gibson, E<lt>rgibson@cpan.orgmE<gt>

Schuyler Erle E<lt>schuyler@nocat.netE<gt> GPX support and general help


Thanks to: 
Gene Boggs E<lt>gene@cpan.orgE<gt>

COPYRIGHT AND LICENSE

Copyright 2004 by Rich Gibson

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.