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.01
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, 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_elapsed( $value, force => true/false )

Returns the elapsed distance (in meters) of a point as initially computed when the trackpoint was created. The value is never reset unless force => 1 is specified.

force is needed internally by Geo::TCX::Lap's split() and Geo::TCX::Track's <merge()> methods. Use with caution.

Time()

Returns the Time field of a trackpoint.

time_dt ()
time_datetime ()

Return a DateTime object corresponding to the time of a trackpoint.

time_local( $trackpoint )

Returns the formatted local time of the trackpoint. The local time is always represented based on the locale of the system that calls this method, not that of where the trackpoint was recorded. It is not possible to know in which time zone a trackpoint 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 and 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, 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).

time_epoch()

Returns the epoch time of a point.

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

Returns the elapsed time of a point as initially computed when the trackpoint was created. The value is never reset unless force => 1 is specified.

force is needed internally by Geo::TCX::Lap's constructor, split(), and reverse() methods as well as Geo::TCX::Track's <reverse()>. Use with caution.

time_duration( $datetime or $trackpoint or $string or $integer )

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.01

SEE ALSO

perl(1).