Geo::Lookup::ByTime 0.0.2

Geo::Lookup::ByTime is a Perl module to lookup location by time.

SYNOPSIS

use Geo::Lookup::ByTime;

$lookup = Geo::Lookup::ByTime->new( @points );
my $pt = $lookup->nearest( $tm );

Given a set of timestamped locations guess the location at a particular time. This is a useful operation for, e.g., adding location information to pictures based on their timestamp and a GPS trace that covers the same time period.

INTERFACE

new( [ points ] )

Create a new object optionally supplying a list of points. The points may be supplied as an array or as a reference to an array. Each point may be a reference to a hash containing at least the keys lat, lon and time or a reference to an object that supports accessor methods called latitude, longitude and time.

If a coderef is supplied it is assumed to be an iterator that may be called repeatedly to yield a set of points.

add_points( [ points ] )

Add points. The specification for what constitutes a point is the same as for new.

nearest( $time [ , $max_dist ] )

Return a hash indicating the estimated position at the specified time. The returned hash has lat, lon and time keys like this:

my $best = {
lat => 54.29344,
lon => -2.02393,
time => $time
};

Returns undef if the position cant be computed. By default a position will be calculated for any point that lies within the range of time covered by the reference points. Optionally $max_dist may be specified in which case undef will be returned if the closest real point is more than that many metres away from the computed point.
If the requested time coincides exactly with the timestamp of one of the points the returned point will be at the same location as the matching point. If the time falls between the timestamps of two points the returned point will be linearly interpolated from those two points.

In an array context returns a list containing the synthetic point at the specified time (i.e. the value that would be returned in scalar context), the closest real point and the distance between the two in metres

my ($best, $nearest, $dist) = $lookup->nearest( $tm );

get_points()

Return a reference to an array containing all the points in ascending time order.

time_range()

Return as a two element list the time range from earliest to latest of the points in the index. Returns undef if the index is empty.

hav_distance($pt, ...)

Exportable function. Computes the Haversine distance in metres along the line described by the points passed in. Points must be references to hashes with keys lat and lon.