/ 
Gpx-Addons-Filter-0.04
River stage zero No dependents
/ Gpx::Addons::Filter

NAME

Gpx::Addons::Filter - filter Geo::Gpx-data based on time-boundaries

VERSION

Version 0.03

SYNOPSIS

The core-function of this module is filter_trk which returns all track-segments of a Geo::Gpx-datastructure, with timestamps in a given time-period.

use Geo::Gpx;
use Gpx::Addons::Filter;

# ... open the filehandle $fh
my $gpx = Geo::Gpx->new( input => $fh );  # see documentation of Geo::Gpx for details
my $all_tracks = $gpx->tracks();

my $selected_tracks = filter_trk($all_tracks, $first_second, $last_second);

# create a new gpx-object and fill it with the selcted tracks
my $new_gpx = Geo::Gpx->new();
$new_gpx->tracks( $selected_tracks );

To include waypoints into the export an additional function filter_wp is provided.

my $bounds = $new_gpx->bounds();            # calculate the boundin-box of the selected tracks
my $all_wp = $gpx->waypoins();              # export all waypoints from the original GPX-file
my $sel_wp = filter_wp($all_wp, $bounds);   # select all waypoints within this box
$new_gpx->waypoints( $sel_wp );             # add these wayponts to the new gpx-object

EXPORT

  • flter_trk

  • filter_wp

FUNCTIONS

filter_trk

This function takes 3 arguments:

  1. Reference to a data-structure (tracks) from Geo::Gpx

  2. The first second of the time-frame we want to export (UNIX-Time)

  3. The last second of the time-frame we want to export (UNIX-Time)

It returns a reference to an array containing all the selected segments. This pointer can be used by the waypoints-method of Geo::Gpx to add them to a new GPX-datastructure. See the examples in SYNOPSIS.

Selection-Logic

Segments are never split. If at least one trackpoints creation-time is within the given time-frame, the whole segment is returned. Points with a creation-time equal to one of the frame-boundarys are considered to be inside of the time-frame. Tracks without any segment are not returned.

If the second parameter (first-second) is undef, all segments up to the last-second will be returned.

If the third parameter (last-second) is undef, all segments after the first-second will be returned.

If second and third parameter are undef, all segments will be returned (quiete useless).

Returnvalues and Warnings

Returns the arraypointer on success (empty if no segments have matched).

The function checks if the timestamp of the last-point in a segment is larger than the one of the fist point. A warning is printed that this segment will be completely ignored. Beside of this, the function assumes, that the trackpoints in the array are in chronological order. As of this version there is no checking, if track-points in the middle of the segment are larger or small than the end-points.

filter_wp

This function takes 3 arguments:

  1. Reference to a data-structure (waypoints) from Geo::Gpx

  2. Reference to a bounding-box as created by Geo::Gpx

  3. Tolerance (number) for inclusion of nearby-waypoints (see function within_bounds)

It returns a pointer to an array containing all waypoints, which are on or within these bounds.

This pointer can be used by the waypoints-method of Geo::Gpx to add them to a new GPX-datastructure. See the examples in SYNOPSIS.

within_bounds

This is a helper-function for filter_wp. It returns 1 if a waypoint is on or within the bounds, undef if outside

Expected Parameters

waypoint

Pointer to the waypoint-hash.

mandatory

box

Pointer to the bounding-box-hash

mandatory

tolerance

Tolerance of waypoints (expands the box slightly so that points near the birder still get included ).

optional, number

first_and_last_second_of

Gets one day as string in ISO-Format (yyyy-mm-dd) and returns the first and last second of this day in UNIX-time. Returns undef on error.

TODO: Evaluate TZ-Problem

AUTHOR

Ingo LANTSCHNER, <perl [at] lantschner.name>

BUGS

Please report any bugs or feature requests to bug-gpx-addons-filter at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Gpx-Addons-Filter. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Gpx::Addons::Filter

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2009 Ingo LANTSCHNER, all rights reserved.

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