NAME

VERSION

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

    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.

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

DEPENDENCIES

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

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

INCOMPATIBILITIES

BUGS AND LIMITATIONS

Please report any bugs or feature requests to "bug-gps-babel@rt.cpan.org", or through the web interface at <http://rt.cpan.org>.

AUTHOR

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

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

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.