The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Geo-TCX-1.06-TRIAL
River stage zero No dependents
/ Geo::TCX::Track

NAME

Geo::TCX::Track - Class to store and edit a TCX track and its trackpoints

SYNOPSIS

  use Geo::TCX::Track;

DESCRIPTION

This package is mainly used by the Geo::TCX module and serves little purpose on its own. The interface is documented mostly for the purpose of code maintainance.

Geo::TCX::Track provides a data structure for tracks in TCX files as well as methods to store, edit and obtain information from its trackpoints.

Constructor Methods (class)

new( xml_string )

takes an xml_string in the form recorded by Garmin devices (and its TCX format) and returns a track object composed of various Geo::TCX::Trackpoint objects.

The string argument is expected to be flat i.e. no line breaks as per the example below.

  $xml_string = '<Track><Trackpoint><Time>2014-08-11T10:25:23Z</Time><Position><LatitudeDegrees>45.305054</LatitudeDegrees><LongitudeDegrees>-72.637287</LongitudeDegrees></Position><AltitudeMeters>210.963</AltitudeMeters><DistanceMeters>5.704</DistanceMeters><HeartRateBpm><Value>75</Value></HeartRateBpm></Trackpoint></Track>';

  $t = Geo::TCX::Track->new( $xml_string );

Constructor Methods (object)

merge( $track, as_is => boolean, speed => value )

Returns a new merged with the track specified in $track.

  $merged = $track1->merge( $track2 );

Adjustments for the DistanceMeters and Time fields of each trackpoint in the track are made unless as_is is set to true.

If a value is passed to field speed, that value will be used to ajust the time elapsed between the first point of the $track and the last point of the track to be merged with. Otherwise the speed will be estimated based on the total distance and time elapsed of all the trackpoints in the $track. speed has not effect if as_is is true.

split( # )

Returns a 2-element array of Geo::TCX::Track objects with the first consisting of the track up to and including point number # and the second consisting of the all trackpoints after that point.

  ($track1, $track2) = $merged->split( 45 );

Will raise exception unless called in list context.

reverse()

Returns a clone of a track with the order of the trackpoints reversed.

  $reversed = $track->reverse;
clone()

Returns a deep copy of a Geo::TCX::Track instance.

  $c = $track->clone;

Object Methods

trackpoint( # )

returns the trackpoint object corresponding to trackpoint number # for the track.

# is 1-indexed but -1, -2, …, still refer to the last, second to last, …, points respectively.

trackpoints( qw/ # # ... / )

returns an array of Geo::TCX::Trackpoint objects for the number of points specified in list if specified, or all trackpoints if called without arguments.

distance_add( $meters )
distance_subtract( $meters )
distance_net()

Add or subtract to the DistanceMeters field of all points in a Track. Does not impact any other fields of trackpoints. Return true.

distance_net is equivalent to $t->distance_subtract( $t->trackpoint(1)->DistanceMeters - $t->trackpoint(1)->distance_elapsed ).

time_add( @duration )
time_subtract( @duration )

Perform DateTime math on the timestamps of each trackpoint in the track by adding or subtracting the specified duration. Return true.

The duration can be provided as an actual DateTime::Duration object or an array of arguments as per the syntax of DateTime's add() or subtract() methods. See the pod for Geo::TCX::Trackpoint->time_add().

point_closest_to( $point or $trackpoint )

Takes any Geo::Gpx::Point or Geo::TCX::Trackpoint and returns the trackpoint that is closest to it on the track.

If called in list context, returns a three element array consisting of the trackpoint, the distance from the coordinate to the trackpoint (in meters), and the point number of that trackpoint in the track.

xml_string( # )

returns a string containing the XML representation of the object, equivalent to the string argument expected by new().

summ()

For debugging purposes, summarizes the fields of the track by printing them to screen. Returns true.

Overloaded Methods

+

merge two tracks by calling $track = $track1 + $track2.

EXAMPLES

Coming soon.

AUTHOR

Patrick Joly

VERSION

1.06

SEE ALSO

perl(1).