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.00
River stage zero No dependents
/ Geo::TCX::Trackpoint

NAME

Geo::TCX::Trackpoint - Class to store and edit TCX trackpoints

SYNOPSIS

use Geo::TCX::Trackpoint;

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::Trackpoint provides a data structure for TCX trackpoints and provides accessor methods to read and edit trackpoint data.

TCX trackpoints are different from GPX trackpoints in that they contain tags such as AltitudeMeters, DistanceMeters, HeartRateBpm, Time, and potentially Cadence, SensorState. Also the coordinates are tagged with longer-form fields as LatitudeDegrees, LongitudeDegrees.

Constructor Methods

new( $xml_str )

Takes an xml string argument containing coordinates contained within the Position xml tag (optional) as recorded by Garmin Edge devices and returns a basic Geo::TCX::Trackpoint object containing only coordinates.

$str_basic = '<Position><LatitudeDegrees>45.304996</LatitudeDegrees><LongitudeDegrees>-72.637243</LongitudeDegrees></Position>';
$tp_basic = Geo::TCX::Trackpoint->new( $str_basic );
Geo::TCX::Trackpoint::Full::new( $xml_str, $previous_pt )

Takes an xml string argument in the form of a Garmin TCX trackpoint, as recorded by Garmin Edge devices, and returns a Geo::TCX::Trackpoint::Full object containing fields that are supplementary to coordinates. See the list of fields in the AUTOLOAD section below.

$str_full = '<Trackpoint><Time>2014-08-11T10:25:26Z</Time><Position><LatitudeDegrees>45.304996</LatitudeDegrees><LongitudeDegrees>-72.637243</LongitudeDegrees></Position><AltitudeMeters>211.082</AltitudeMeters><DistanceMeters>13.030</DistanceMeters><HeartRateBpm><Value>80</Value></HeartRateBpm></Trackpoint>';

$tp_full = Geo::TCX::Trackpoint::Full->new( $str_full );

$previous_pt is optional and if specified will be interpreted as the previous trackpoint and be used to keep track of the distance and time that have elapsed since the latter. See the methods below to access these "elapsed" fields. If no previous trackpoint is provided, the elapsed time will remain undefined and the elapsed distance will set to the DistanceMeters field of the trackpoint.

clone()

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

$clone = $trackpoint->clone;

AUTOLOAD Methods

field( $value )

Methods with respect to certain fields can be autoloaded and return the current or newly set value.

For Basic trackpoints, LatitudeDegrees and LongitudeDegrees are the supported fields.

For Full trackpoints, supported fields are: LatitudeDegrees, LongitudeDegrees, AltitudeMeters, DistanceMeters, Time, HeartRateBpm, Cadence, and SensorState.

Some fields may contain a value of 0. It is safer to check if a field is defined with if (defined $trackpoint->Cadence) rather than if ($trackpoint->Cadence).

Caution should be used if setting a $value as no checks are performed to ensure the value is appropriate or in the proper format.

Object Methods

to_gpx()

Returns a trackpoint as a Geo::Gpx::Point.

to_geocalc()

Returns a trackpoint as a Geo::Calc object.

to_basic()

Returns a trackpoint as a Geo::TCX::Trackpoint object with only position information (i.e coordinates).

distance_to ( $trackpoint )

Calculates and returns the distance to the specified $trackpoint object using the Geo::Calc module.

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 trackpoint by printing them to screen. Returns true.

Object Methods for class Geo::TXC::Trackpoint::Full

distance( $meters, Trackpoint object )

Expects a decimal-number or integer and sets the DistanceMeters field for the trackpoint, returning that value.

If the elapsed-distance information for the point is not already set and another trackpoint object is also provided (e.g. the previous trackpoint), the method will compute and store the distance (in meters) from that previous point. This field is accessible via the distance_elapsed() method.

To simply get the DistanceMeters field, call the AUTOLOAD accessor for it.

distance_elapsed( $value, force => true/false )

Returns the elapsed distance (in meters) of a point as initially computed when the trackpoint was created.

For the moment, the value is never reset unless called with option force => 1 which is not recommended.

time( $DateTime or $time_string, Trackpoint object )

Expects a DateTime object or a $time_string in a format parseable by DateTime::Format::ISO8601's parse_datetime constructor and sets the time-related fields for the trackpoint. Returns a DateTime object corresponding to the time of that point.

If the elapsed-time information for the point is not already set and another trackpoint object is also provided (e.g. the previous trackpoint), the method will compute and store the time (in seconds) since the timestamp of that previous point. This field is accessible via the time_elapsed() method.

The method maybe called without arguments to obtain an instance of a DateTime object corresponding to the time of that point (no reference to DateTime objects are ever kept in trackpoints, they are too voluminous).

To simply get the Time field, call the AUTOLOAD accessor for it.

localtime( $trackpoint )

Returns the formatted local time of the trackpoint (in the locale of the system, not that of the track per se, i.e. it is not possible to know the zone of where the track was recorded at this stage).

time_add( @duration )
time_subtract( @duration )

Perform DateTime math on the timestamps of each lap's starttime and trackpoint by adding the specified time duration.

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, which expect a hash of keys such as years => 3, months => 5, weeks => 1, days => 1, hours => 6, minutes => 15, seconds => 45, nanoseconds => 12000, end_of_month => 'limit'

where only the relevant keys need to be specified i.e. time_add( minutes > 30, seconds > 15).

Return the resulting DateTime object.

time_epoch( $epoch_time )

Sets/gets the time of a point based on an epoch time. Returns the point's epoch time.

time_elapsed( $value, force => true/false )

Returns the elapsed time of a point as initially computed when the trackpoint was created.

For the moment, the value is never reset unless called with option force => 1 which is not recommended.

time_duration( $datetime )

Returns a DateTime::Duration object containing the duration between the timestamps of two trackpoints. Consistent with the documentation for DateTime::Duration the "duration is relative to the object from which $datetime is subtracted". The duration will be positive if the timestamp of $datetime occurs prior to the trackpoint, otherwise it will be negative.

This method accepts four forms for the argument: a DateTime object such as that returned by $pt->time, an ISO8601 string such as that returned by $pt->Time, a Trackpoint object, or an integer than can be interpreted as an epoch time.

These duration objects are useful to pass to time_add() or time_subtract.

EXAMPLES

Coming soon.

AUTHOR

Patrick Joly

VERSION

1.00

SEE ALSO

perl(1).