NAME

Geo::Gpx - Create and parse GPX files.

VERSION

This document describes Geo::Gpx version 0.22

SYNOPSIS

# Version 0.10 compatibility
use Geo::Gpx;
my $gpx = Geo::Gpx->new( @waypoints );
my $xml = $gpx->xml;

# New API, generate GPX
my $gpx = Geo::Gpx->new();
$gpx->waypoints(\@wpt);
my $xml = $gpx->xml('1.0');

# Parse GPX
my $gpx = Geo::Gpx->new( xml => $xml );
my $waypoints = $gpx->waypoints();
my $tracks = $gpx->tracks();

# Parse GPX from open file
my $gpx = Geo::Gpx->new( input => $fh );
my $waypoints = $gpx->waypoints();
my $tracks = $gpx->tracks();

DESCRIPTION

The original goal of this module was to produce GPX/XML files which were parseable by both GPX Spinner and EasyGPS. As of version 0.13 it has been extended to support general parsing and generation of GPX data. GPX 1.0 and 1.1 are supported.

INTERFACE

new( { args } )

The original purpose of Geo::Gpx was to allow an array of Geo::Cache objects to be converted into a GPX file. This behaviour is maintained by this release:

use Geo::Gpx;
my $gpx = Geo::Gpx->new( @waypoints );
my $xml = $gpx->xml;

New applications can use Geo::Gpx to parse a GPX file:

my $gpx = Geo::Gpx->new( xml => $gpx_document );

or from an open filehandle:

my $gpx = Geo::Gpx->new( input => $fh );

or can create an empty container to which waypoints, routes and tracks can then be added:

my $gpx = Geo::Gpx->new();
$gpx->waypoints( \@wpt );

bounds( [ $iterator ] )

Compute the bounding box of all the points in a Geo::Gpx returning the result as a hash reference. For example:

my $gpx = Geo::Gpx->new( xml => $some_xml );
my $bounds = $gpx->bounds();

returns a structure like this:

$bounds = {
    minlat  => 57.120939,
    minlon  => -2.9839832,
    maxlat  => 57.781729,
    maxlon  => -1.230902
};

$iterator defaults to $self->iterate_points.

name( [ $newname ] )

Accessor for the <name> element of a GPX. To get the name:

my $name = $gpx->name();

and to set it:

$gpx->name('My big adventure');

desc( [ $newdesc ] )

Accessor for the <desc> element of a GPX. To get the the description:

my $desc = $gpx->desc();

and to set it:

$gpx->desc('Got lost, wandered around for ages, got cold, got hungry.');

author( [ $newauthor ] )

Accessor for the author structure of a GPX. The author information is stored in a hash that reflects the structure of a GPX 1.1 document:

my $author = $gpx->author();
$author = {
    'link' => {
        'text' => 'Hexten',
        'href' => 'http://hexten.net/'
    },
    'email' => {
        'domain' => 'hexten.net',
        'id' => 'andy'
    },
    'name' => 'Andy Armstrong'
},

When setting the author data a similar structure must be supplied:

$gpx->author({
    name => 'Me!'
});

The bizarre encoding of email addresses as id and domain is a feature of GPX.

time( [ $newtime ] )

Accessor for the <time> element of a GPX. The time is converted to a Unix epoch time when a GPX document is parsed and formatted appropriately when a GPX is generated

print $gpx->time();

prints

1164488503

$gpx->time(1164488503);

keywords( [ $newkeywords ] )

Access for the <keywords> element of a GPX. Keywords are stored as an array reference:

$gpx->keywords(['bleak', 'cold', 'scary']);
my $k = $gpx->keywords();
print join(', ', @{$k}), "\n";

prints

bleak, cold, scary

copyright( [ $newcopyright ] )

Access for the <copyright> element of a GPX.

$gpx->copyright('(c) You Know Who');
print $gpx->copyright(), "\n";

prints

You Know Who

link

Accessor for the <link> element of a GPX. Links are stored in a hash like this:

$link = {
    'text' => 'Hexten',
    'href' => 'http://hexten.net/'
};

For example:

$gpx->link({ href => 'http://google.com/', text => 'Google' });

waypoints( [ $newwaypoints ] )

Accessor for the waypoints array of a GPX. Each waypoint is a hash (which may also be a Geo::Cache instance in legacy mode):

my $wpt = {
    # All standard GPX fields
    lat           => 54.786989,
    lon           => -2.344214,
    ele           => 512,
    time          => 1164488503,
    magvar        => 0,
    geoidheight   => 0,
    name          => 'My house & home',
    cmt           => 'Where I live',
    desc          => '<<Chez moi>>',
    src           => 'Testing',
    link          => {
        href => 'http://hexten.net/',
        text => 'Hexten',
        type => 'Blah'
    },
    sym           => 'pin',
    type          => 'unknown',
    fix           => 'dgps',
    sat           => 3,
    hdop          => 10,
    vdop          => 10,
    pdop          => 10,
    ageofdgpsdata => 45,
    dgpsid        => 247
};

All fields apart from lat and lon are optional. See the GPX specification for an explanation of the fields. The waypoints array is an anonymous array of such points:

$gpx->waypoints([ { lat => 57.0, lon => -2 }, { lat => 57.2, lon => -2.1 } ]);

routes( [ $newroutes ] )

Accessor for the routes array. The routes array is an array of hashes like this:

my $routes = [
    {
        'name' => 'Route 1'
        'points' => [
            {
                'lat' => '54.3286193447719',
                'name' => 'WPT1',
                'lon' => '-2.38972155527137'
            },
            {
                'lat' => '54.6634365629388',
                'name' => 'WPT2',
                'lon' => '-2.55373552512617'
            },
            {
                'lat' => '54.7289259665049',
                'name' => 'WPT3',
                'lon' => '-3.05196861273443'
            }
        ],
    },
    {
        'name' => 'Route 2'
        'points' => [
            {
                'lat' => '54.4165154835049',
                'name' => 'WPT4',
                'lon' => '-2.56153453279676'
            },
            {
                'lat' => '54.6670126167344',
                'name' => 'WPT5',
                'lon' => '-2.69526089464403'
            }
        ],
    }
];

$gpx->routes($routes);

Each of the points in a route may have any of the atttibutes that are legal for a waypoint.

tracks( [ $newtracks ] )

Accessor for the tracks array. The tracks array is an array of hashes like this:

my $tracks = [
    {
        'name' => 'Track 1',
        'segments' => [
            {
                'points' => [
                    {
                        'lat' => '54.5182217145253',
                        'lon' => '-2.62191579018834'
                    },
                    {
                        'lat' => '54.1507759448355',
                        'lon' => '-3.05774931478646'
                    },
                    {
                        'lat' => '54.6016296784874',
                        'lon' => '-3.40418920968631'
                    }
                ]
            },
            {
                'points' => [
                    {
                        'lat' => '54.6862790450185',
                        'lon' => '-3.68760108982739'
                    }
                ]
            }
        ]
    },
    {
        'name' => 'Track 2',
        'segments' => [
            {
                'points' => [
                    {
                        'lat' => '54.9927807628549',
                        'lon' => '-4.04712811256436'
                    },
                    {
                        'lat' => '55.1148395198045',
                        'lon' => '-4.33623533555793'
                    },
                    {
                        'lat' => '54.6214174046189',
                        'lon' => '-4.26293674042878'
                    },
                    {
                        'lat' => '55.0540816059084',
                        'lon' => '-4.42261020671926'
                    },
                    {
                        'lat' => '55.4451622411372',
                        'lon' => '-4.32873765338'
                    }
                ]
            }
        ]
    }
];

version( [ $newversion ] )

Accessor for the schema version of a GPX document. Versions 1.0 and 1.1 are supported.

print $gpx->version();

prints

1.0

add_waypoint( waypoint ... )

Add one or more waypoints. Each waypoint must be a reference to a hash. Each waypoint must include the keys lat and lon and may include others:

my $wpt = {
    lat           => 54.786989,
    lon           => -2.344214,
    ele           => 512,
    time          => 1164488503,
    magvar        => 0,
    geoidheight   => 0,
    name          => 'My house & home',
    cmt           => 'Where I live',
    desc          => '<<Chez moi>>',
    src           => 'Testing',
    link          => {
        href => 'http://hexten.net/',
        text => 'Hexten',
        type => 'Blah'
    },
    sym           => 'pin',
    type          => 'unknown',
    fix           => 'dgps',
    sat           => 3,
    hdop          => 10,
    vdop          => 10,
    pdop          => 10,
    ageofdgpsdata => 45,
    dgpsid        => 247
};

$gpx->add_waypoint( $wpt );

iterate_points()

Get an iterator that visits all the points in a Geo::Gpx. For example

my $iter = $gpx->iterate_points();
while (my $pt = $iter->()) {
    print "Point: ", join(', ', $pt->{lat}, $pt->{lon}), "\n";
}

iterate_waypoints()

Get an iterator that visits all the waypoints in a Geo::Gpx.

iterate_routepoints()

Get an iterator that visits all the routepoints in a Geo::Gpx.

iterate_trackpoints()

Get an iterator that visits all the trackpoints in a Geo::Gpx.

xml( [ $version ] )

Generate GPX XML.

my $gpx10 = $gpx->xml('1.0');
my $gpx11 = $gpx->xml('1.1');

If the version is omitted it defaults to the value of the version attibute. Parsing a GPX document sets the version. If the version attribute is unset defaults to 1.0.

Geo::Gpx version 0.10 used Geo::Cache to render each of the points. Geo::Cache generates a number of hardwired values to suit the original application of that module which aren't appropriate for general purpose GPX manipulation. Legacy mode is triggered by passing a list of Geo::Cache points to the constructor; this should probably be avoided for new applications.

TO_JSON

For compatability with JSON modules. Converts this object to a hash with keys that correspond to the above methods. Generated ala:

my %json = map {$_ => $self->$_}
  qw(name desc author keywords copyright
     time link waypoints tracks routes version );
$json{bounds} = $self->bounds( $iter );

With one difference: the keys will only be set if they are defined.

gpx

Synonym for xml(). Provided for compatibility with version 0.10.

loc

Provided for compatibility with version 0.10.

gpsdrive

Provided for compatibility with version 0.10.

DIAGNOSTICS

Invalid arguments: Invalid arguments passed to new().
Undefined accessor method: %s: The various accessor methods are implemented as an AUTOLOAD handler. This error is thrown if an attempt is made to call an accessor other than name, desc, author, time, keywords, copyright, link, waypoints, tracks, routes or version.

DEPENDENCIES

Date::Format Date::Parse HTML::Entities Scalar::Util Time::Local XML::Descent

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-geo-gpx@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Originally by Rich Bowen <rbowen@rcbowen.com>.

This version by Andy Armstrong <andy@hexten.net>.

LICENCE AND COPYRIGHT

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

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

To install Geo::Gpx, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Geo::Gpx

CPAN shell

perl -MCPAN -e shell
install Geo::Gpx

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

INTERFACE

DIAGNOSTICS

DEPENDENCIES

INCOMPATIBILITIES

SEE ALSO

BUGS AND LIMITATIONS

AUTHOR

LICENCE AND COPYRIGHT

DISCLAIMER OF WARRANTY

Module Install Instructions