NAME

GPS::Babel - Perl interface to gpsbabel

VERSION

This document describes GPS::Babel version 0.11

SYNOPSIS

use GPS::Babel;

my $babel = GPS::Babel->new();

# Read an OZIExplorer file into a data structure
my $data  = $babel->read('route.ozi', 'ozi');

# Convert a file automatically choosing input and output
# format based on extension
$babel->convert('points.wpt', 'points.gpx');

# Call gpsbabel directly
$babel->direct(qw(gpsbabel -i saroute,split
    -f in.anr -f in2.anr -o an1,type=road -F out.an1));

DESCRIPTION

From https://gpsbabel.org/:

GPSBabel converts waypoints, tracks, and routes from one format to
another, whether that format is a common mapping format like
Delorme, Streets and Trips, or even a serial upload or download to a
GPS unit such as those from Garmin and Magellan. By flattening the
Tower of Babel that the authors of various programs for manipulating
GPS data have imposed upon us, it returns to us the ability to
freely move our own waypoint data between the programs and hardware
we choose to use.

As I write this gpsbabel supports 96 various GPS related data formats. In addition to file conversion it supports upload and download to a number of serial and USB devices. This module provides a (thin) wrapper around the gpsbabel binary making it easier to use in a perlish way.

GPSBabel supports many options including arbitrary chains of filters, merging data from multiple files and many format specific parameters. This module doesn't attempt to provide an API wrapper around all these options. It does however provide for simple access to the most common operations. For more complex cases a passthrough method (direct) passes its arguments directly to gpsbabel with minimal preprocessing.

GPSBabel is able to describe its built in filters and formats and enumerate the options they accept. This information is available as a perl data structure which may be used to construct a dynamic user interface that reflects the options available from the gpsbabel binary.

Format Guessing

GPS::Babel queries the capabilities of gpsbabel and can use this information to automatically choose input and output formats based on the extensions of filenames. This makes it possible to, for example, create tools that bulk convert a batch of files choosing the correct format for each one.

While this can be convenient there is an important caveat: if more than one format is associated with a particular extension GPS::Babel will fail rather than risking making the wrong guess. Because new formats are being added to gpsbabel all the time it's possible that a format that can be guessed today will become ambiguous tomorrow. That raises the spectre of a program that works now breaking in the future.

Also some formats support a particular extension without explicitly saying so - for example the compegps format supports .wpt files but gpsbabel (currently) reports that the only format explicitly associated with the .wpt extension is xmap. This means that GPS::Babel will confidently guess that the format for a file called something.wpt is xmap even if the file contains compegps data.

In general then you should only use format guessing in applications where the user will have the opportunity to select a format explicitly if an unambiguous guess can't be made. For applications that must run unattended or where the user doesn't have this kind of control you should make the choice of filter explicit by passing in_format and/or out_format options to read, write and convert as appropriate.

INTERFACE

new( { options } )

Create a new GPS::Babel object. Optionally the exename option may be used to specify the full name of the gpsbabel executable

my $babel = GPS::Babel->new({
    exename => 'C:\GPSBabel\gpsbabel.exe'
});

check_exe()

Verify that the name of the gpsbabel executable is known throwing an error if it isn't. This is generally called by other methods but you may call it yourself to cause an error to be thrown early in your program if gpsbabel is not available.

get_info()

Returns a reference to a hash that describes the capabilities of your gpsbabel binary. The format of this hash is probably best explored by running the following script and perusing its output:

#!/usr/bin/perl -w

use strict;
use GPS::Babel;
use Data::Dumper;

$| = 1;

my $babel = GPS::Babel->new();
print Dumper($babel->get_info());

This script is provided in the distribution as scripts/babel_info.pl.

In general the returned hash has the following structure:

$info = {
    version     => $gpsbabel_version,
    banner      => $gpsbabel_banner,
    filters     => {
        # big hash of filters
    },
    formats     => {
        # big hash of formats
    },
    for_ext     => {
        # hash mapping lower case extension name to a list
        # of formats that use that extension
    }
};

The filters, formats and for_ext hashes are only present if you have gpsbabel 1.2.8 or later installed.

banner()

Get the GPSBabel banner string - the same string that is output by the command

$ gpsbabel -V

version()

Get the GPSBabel version number. The version is extracted from the banner string.

print $babel->version(), "\n";

got_ver( $ver )

Return true if the available version of gpsbabel is equal to or greater than the supplied version string. For example:

die "I need gpsbabel 1.3.0 or later\n"
    unless $babel->got_ver('1.3.0');

guess_format( $filename )

Given a filename return the name of the gpsbabel format that handles files of that type. Croaks with a suitable message if the format can't be identified from the extension. If more than one format matches an error listing all of the matching formats will be thrown.

Optionally a format name may be supplied as the second argument in which case an error will be thrown if the installed gpsbabel doesn't support that format.

Format guessing only works with gpsbabel 1.2.8 or later. As mentioned above, the requirement that an extension maps unambiguously to a format means that installing a later version of gpsbabel which adds support for another format that uses the same extension can cause code that used to work to stop working. For this reason format guessing should only be used in interactive programs that give the user the opportunity to specify a format explicitly if such an ambiguity exists.

get_exename()

Get the name of the gpsbabel executable that will be used. This defaults to whatever File::Which::which('gpsbabel') returns. To use a particular gpsbabel binary either pass the path to the constructor using the 'exename' option or call set_exename( $path ).

set_exename( $path )

Set the path and name of the gpsbabel executable to use. The executable doesn't have to be called 'gpsbabel' - although naming any other program is unlikely to have pleasing results...

$babel->set_exename('/sw/bin/gpsbabel');

read( $filename [, { $options } ] )

Read a file in a format supported by gpsbabel into a Geo::Gpx object. The input format is guessed from the filename unless supplied explicitly in the options like this

$data = $babel->read('hotels.wpt', { in_format => 'xmap' });

See Geo::Gpx for documentation on the returned object.

write( $filename, $gpx_data [, { $options }] )

Write GPX data (typically in the form of an instance of Geo::Gpx) to a file in one of the formats gpsbabel supports. $gpx_data must be a reference to an object that exposes a method called xml that returns a GPX document. Geo::Gpx satisfies this requirement.

The format will be guessed from the filename (see caveats above) or may be explicitly specified by passing a hash containing out_format as the third argument:

$babsel->write('points.kml', $my_points, { out_format => 'kml' });

For consistency the data is filtered through gpsbabel even if the desired output format is 'gpx'. If you will only be dealing with GPX files use Geo::Gpx directly.

convert( $infile, $outfile, [, { $options } ] )

Convert a file from one format to another. Both formats must be supported by gpsbabel.

With no options convert attempts to guess the input and output formats using guess_format - see the caveats about that above. To specify the formats explicitly supply as a third argument a hash containing the keys in_format and out_format like this:

$babel->convert('infile.wpt', 'outfile.kml',
    { in_format => 'compegps', out_format => 'kml' });

gpsbabel treats waypoints, tracks and routes as separate channels of information and not all formats support reading and writing all three. convert attempts to convert anything that can be both read by the input format and written by the output format. If the formats have nothing in common an error will be thrown.

direct( @options )

Invoke gpsbabel with the supplied options. The supplied options are passed unmodified to system(), for example:

$babel->direct(qw(-i gpx -f somefile.gpx -o kml -F somefile.kml));

Throws appropriate errors if gpsbabel fails.

DIAGNOSTICS

%s not found

Can't find the gpsbabel executable.

Missing filename

guess_format (or a method that calls it) needs a filename from which to guess the format.

Unknown format "%s"

An explicit format was passed to guess_format that doesn't appear to be supported by the installed gpsbabel.

Filename "%s" has no extension

Can't guess the format of a filename with no extension.

No format handles extension .%s

The installed gpsbabel doesn't contain a format that explicitly supports the named extension. That doesn't necessarily mean that gpsbabel can't handle the file: many file formats use a number of different extensions and many gpsbabel input/output modules don't specify the extensions they support. If in doubt check the gpsbabel documentation and supply the format explicitly.

Multiple formats (%s) handle extension .%s

guess_format couldn't unambiguously guess the appropriate format from the extension. Check the gpsbabel documentation and supply an explicit format.

Must provide input and output filenames

convert needs input and output filenames.

Formats %s and %s have no read/write capabilities in common

Some gpsbabel formats are read only, some are write only, some support only waypoints or only tracks. convert couldn't find enough common ground between input and output formats to be able to convert any data.

%s failed with error %s

A call to gpsbabel failed.

Must provide an input filename

read needs to know the name of the file to read.

Must provide some data to output

write needs data to output. The supplied object must expose a method called xml that returns GPX data. Typically this is achieved by passing a Geo::Gpx.

CONFIGURATION AND ENVIRONMENT

GPS::Babel requires no configuration files or environment variables. With the exception of direct() all calls pass the argument -p '' to gpsbabel to inhibit reading of any inifile. See "/www.gpsbabel.org/htmldoc- 1.3.2/inifile.html" in http: for more details.

DEPENDENCIES

GPS::Babel needs gpsbabel, ideally installed on your PATH and ideally version 1.2.8 or later.

In addition GPS::Babel requires the following Perl modules:

Geo::Gpx (for read, write)
File::Which

INCOMPATIBILITIES

GPS::Babel has only been tested with versions 1.3.0 and later of gpsbabel. It should work with earlier versions but it's advisable to upgrade to the latest version if possible. The gpsbabel developer community is extremely active so it's worth having the latest version installed.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to [email protected], or through the web interface at https://rt.cpan.org.

AUTHOR

Andy Armstrong <[email protected]>

Robert Lipe and numerous contributors did all the work by providing gpsbabel in the first place. This is just a wafer-thin layer on top of all their goodness.

LICENCE AND COPYRIGHT

Copyright (c) 2006, Andy Armstrong <[email protected]>. All rights reserved.

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.