/ 
GPS-Point-Filter-0.02
River stage zero No dependents
/ GPS::Point::Filter

NAME

GPS::Point::Filter - Algorithm to filter extraneous GPS points

SYNOPSIS

use GPS::Point::Filter;
my $gpf=GPS::Point::Filter->new;
$gpf->addCallback(sample=>\&GPS::Point::Filter::callback_sample);
my $status=$gpf->addPoint($point);

DESCRIPTION

GPS::Point::Filter uses a single pass linear algorithm to filter extraneous GPS points from a GPS feed. The filter uses three tests to determine whether to trigger a callback or not.

The most common use for this type of algorithm is to intelligently reduce the number of points before transmission over a limited bandwidth network. The filter properties will need to be tuned for particular networks and implementations.

USAGE

use GPS::Point::Filter;
my $gpf=GPS::Point::Filter->new;
$gpf->addCallback(sample=>\&GPS::Point::Filter::callback_sample);
my $point=GPS::Point->new(time    => time,
                          lat     => 39,
                          lon     => -77,
                          speed   => 25,
                          heading => 135);
my $status=$gpf->addPoint($point);
printf "%s\n", $status if $status;

CONSTRUCTOR

new

my $gpf=GPS::Point::Filter->new(
                                separation => 2000,  #meters
                                interlude  => 1200,  #seconds
                                deviation  => 500,   #meters
                               );

initialize

METHODS (Properties)

interlude

Sets or returns the filter interlude property. The interlude is defined as the period of time in seconds for which the previous filter point is still valid or not stale. The filter will trigger a callback if the GPS sample point does not move when the interlude is exceeded.

$gpf->interlude(1200); #default is 1200 seconds

separation

Sets or returns the filter separation property. The separation is defined as the distance in meters between the previous filter point and the sample point. The filter will trigger a callback when then separation is exceeded.

$gpf->separation(2000); #default is 2000 meters

deviation

Sets or returns the filter deviation property. The deviation is defined as the distance in meters between the constant velocity predicted location of the previous filter point and the sample point. The filter will trigger a callback when then deviation is exceeded.

$gpf->deviation(500); #default is 500 meters

METHODS

addCallback

Add a sub reference to the callback hash and returns the $gpf object.

$gpf->addCallback(label=>sub{print shift->latlon."\n"});
$gpf->addCallback(label=>\&mysub);
sub mysub {
  my $point=shift;#GPS::Point (new point)
  my $gpf=shift;  #GPS::Point::Filter with state info and previous point
  printf "Lat: %s, Lon: %s\n", $point->latlon;
}

deleteCallback

my $sub=$gpf->deleteCallback("label");

addPoint

Adds a point to the filter to be tested and returns a short staus string. If the point is "extraneous", then the filter will not trigger a callback.

my $point=GPS::Point->new(
                          lat     =>  39.000, #decimal degrees
                          lon     => -77.000, #decimal degrees
                          speed   =>  50.0,   #meters/second
                          heading =>  45.0,   #degrees clockwise from North
                          );
my $status=$gpf->addPoint($point);
if ($status) {print "added"} else {print "filtered"}

point

Sets or returns the GPS point stored in the GPS::Point::Filter object.

my $point=$gpf->point;

This point is set to the previous filter point when the callback is triggered. But, is updated just after the execute is complete.

count

Sets or returns the count of number of points that have been filtered since the previous filter point;

$gpf->count;

status

Sets or returns the status of the previous filter point.

METHODS (Internal)

callback

Returns the callback hash of sub references.

my $callback=$gpf->callback; #{label=>sub{}}
my %callback=$gpf->callback; #(label=>sub{})

Note: Callbacks are executed sorted by key.

execute

Executes all sub references in the callback hash sorted by key.

The $point and the $gpf objects are passed to the sub routine as the first two arguments.

$gpf->execute;

Functions (Convenience)

callback_sample

A very simple callback example.

GPS::Point::Filter::callback_sample_string($point);

To register

$gpf->addCallback(sample=>\&GPS::Point::Filter::callback_sample);

callback_sample_string

Returns a formated string given a GPS::Point

my $string=GPS::Point::Filter::callback_sample_string($point);

TODO

I would like to implement a Kalman Filter in order to filter point data instead of the current interlude, separation, and deviation properties.

Add count of points filtered since previous point

Add status to gpf object

BUGS

Please report bugs to GEO-PERL list

SUPPORT

Please Try the GEO-PERL list

AUTHOR

Michael R. Davis
CPAN ID: MRDVT
domain=>michaelrdavis,tld=>com,account=>perl

COPYRIGHT

This program is free software licensed under the...

The BSD License

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

GSP::Point, GPS::Point::Filter, Net::GSPD, Geo::Forward, Geo::Inverse