view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

# SYNOPSIS

    my ($gpx, $waypoints, $tracks);

    # From a filename, an open file, or an XML string:

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

    my $waypoints = $gpx->waypoints();
    my $tracks    = $gpx->tracks();

# DESCRIPTION

`Geo::Gpx` supports the parsing and generation of GPX data.

## Constructor

- new( input => ($fname | $fh) or xml => $xml \[, work\_dir => $working\_directory \] )

    Create and return a new `Geo::Gpx` instance based on a \*.gpx file (_$fname_), an open filehandle (_$fh_), or an XML string (_$xml_). GPX 1.0 and 1.1 are supported.

    The optional `work_dir` (or `wd` for short) specifies where to save any working files, such as with the save() method. It can be supplied as a relative path or as an absolute path. If `work_dir` is omitted, it is set based on the path of the _$fn...

- clone()

    Returns a deep copy of a `Geo::Gpx` instance.

        $clone = $self->clone;

## Methods

- waypoints( $int or name => $name )

    Without arguments, returns the array reference of waypoints.

    With an argument, returns a reference to the waypoint whose `name` field is an exact match with _$name_. If an integer is specified instead of the `name` key/value pair, returns the waypoint at position _$int_ in the array reference (1-indexed wi...

    Returns `undef` if no corresponding waypoints are found such that this method can be used to check if a specific point exists (i.e. no exception is raised if _$name_ or _$int_ do not exist) .

- waypoints\_add( $point or \\%point \[, $point or \\%point, … \] )

    Add one or more waypoints. Each waypoint must be either a [Geo::Gpx::Point](https://metacpan.org/pod/Geo%3A%3AGpx%3A%3APoint) or a hash reference with fields that can be parsed by [Geo::Gpx::Point](https://metacpan.org/pod/Geo%3A%3AGpx%3A%3APoint...

        %point = ( lat => 54.786989, lon => -2.344214, ele => 512, name => 'My house' );
        $gpx->waypoints_add( \%point );

          or

        $pt = Geo::Gpx::Point->new( %point );
        $gpx->waypoints_add( $pt );

- waypoints\_search( $field => $regex )

    returns an array of waypoints whose _$field_ (e.g. `name`, `desc`, …) matches _$regex_. By default, the regex is case-sensitive; specify `qr/(?i:search_string_here)/` to ignore case.

- waypoints\_clip( $name | $regex | LIST )
- way\_clip( )

    Sends the coordinates of the waypoint(s) whose name is either `$name` or matches `$regex` to the clipboard (all points found are sent to the clipboard) and returns an array of points found. By default, the regex is case-sensitive; specify `qr/(?i...

    Alternatively, an array of `Geo::GXP::Points` can be provided. `way_clip()` is a short-hand for this method (convenient when used interactively in the debugger).

    This method is only supported on unix-based systems that have the `xclip` utility installed (see DEPENDENCIES).

- waypoints\_delete\_all()

    delete all waypoints. Returns true.

- waypoint\_delete( $name )

    delete the waypoint whose `name` field is an exact match for _$name_ (case sensitively). Returns true if successful, `undef` if the name cannot be found.

- waypoint\_rename( $name, $new\_name )

    rename the waypoint whose `name` field is an exact match for _$name_ (case sensitively) to _$new\_name_. Returns the point's new name if successful, `undef` otherwise.

- waypoints\_merge( $gpx, $regex )

    Merge waypoints with those contained in the [Geo::Gpx](https://metacpan.org/pod/Geo%3A%3AGpx) instance provide as argument. Waypoints are compared based on their respective `name` fields, which must exist in _$gpx_ (if names are missing in the cu...

    A _$regex_ may be provided to limit the merge to a subset of waypoints from _$gpx_.

    Returns the number of points successfully merged (i.e. the difference in `$gps->waypoints_count` before and after the merge).

- waypoint\_closest\_to( $point or $tcx\_trackpoint )
- trackpoint\_closest\_to( … )
- routepoint\_closest\_to( … )
- point\_closest\_to( … )

    From any [Geo::Gpx::Point](https://metacpan.org/pod/Geo%3A%3AGpx%3A%3APoint) or [Geo::TCX::Trackpoint](https://metacpan.org/pod/Geo%3A%3ATCX%3A%3ATrackpoint) object, return the [Geo::Gpx::Point](https://metacpan.org/pod/Geo%3A%3AGpx%3A%3APoint) t...

- waypoints\_print()

    print the list of waypoints to screen, along with their names and descriptions if defined. Returns true.

- waypoints\_count()

    returns the number of waypoints in the object.

- routes( integer or name => 'name' )

    Returns the array reference of routes when called without argument. Optionally accepts a single integer referring to the route number from routes aref (1-indexed with negative integers also counting from the end of the array) or a key value pair ...

- routes\_add( $route or $points\_aref \[, name => $route\_name )

    Add a route to a `Geo::Gpx` object. The _$route_ is expected to be an existing route (i.e. a hash ref). Returns true. A new route can also be created based an array reference(s) of [Geo::Gpx::Point](https://metacpan.org/pod/Geo%3A%3AGpx%3A%3APoin...

    `name` and all other meta fields supported by routes can be provided and will overwrite any existing fields in _$route_.

- routes\_delete\_all()

    delete all routes. Returns true.

- routes\_count()

    returns the number of routes in the object.

- tracks( integer or name => 'name' )