/ 
Geo-TCX-1.06
River stage zero No dependents
/ Geo::TCX::Lap

NAME

Geo::TCX::Lap - Extract and edit info from Lap data

SYNOPSIS

use Geo::TCX::Lap;

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.

A sub-class of Geo::TCX::Track, it enables extracting and editing lap information associated with tracks contained in Garmin TCX files. Laps are a more specific form of a Track in that may contain additional information such as lap aggregates (e.g. TotalTimeSeconds, DistanceMeters, …), performance metrics (e.g. MaximumSpeed, AverageHeartRateBpm, …), and other useful fields.

The are two types of Geo::TCX::Lap: Activity and Courses.

Activity

Activity laps are tracks recorded by the Garmin from one of the activity types ('Biking', 'Running', 'MultiSport', 'Other') and saved in what is often refered to ashistory files.

Course

Course laps typically originate from history files that are converted to a course either by a Garmin device or some other software for the purpose of navigation or training. They contain course-specific fields such as BeginPosition and EndPosition and some lap aggregagates but do not contain the performance-metrics or other fields that acivity laps contain.

See the AUTOLOAD section for a list of all supported fields for each type of lap.

Some methods and accessors are applicable only to one type. This is specified in the documentation for each.

Constructor Methods (class)

new( $xml_string, $lapno )

parses and xml string in the form of the lap portion from a Garmin Activity or Course and returns a Geo::TCX::Lap object.

No examples are provided as this constructor is typically called by instances of Geo::TCX. The latter then provides various methods to access lap data and info. The $lapno (lap number) is optional.

Constructor Methods (object)

merge( $lap, as_is => boolean )

Returns a new Geo::TCX::Lap merged with the lap specified in $lap.

$merged = $lap1->merge( $lap2 );

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

Lap aggregates TotalTimeSeconds and DistanceMeters are adjusted. For Activity laps, performance metrics such as MaximumSpeed, AverageHeartRateBpm, …, are also adjusted. For Course laps, EndPosition is also adjusted.

Unlike the merge_laps() method in Geo::TCX, the laps do not need to originate from the same *.tcx file, hence there is also no requirement that they be consecutive laps as is the case in the former.

split( # )

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

($lap1, $lap2) = $merged->split( 45 );

Lap aggregates TotalTimeSeconds and DistanceMeters are recalculated, some small measurement error is to be expected due to the amount of time the device was an auto-pause.

For Activity laps, the performance metrics MaximumSpeed, MaximumHeartRateBpm, AverageHeartRateBpm, Cadence, and Calories are also recalculated for each lap (if they were defined). StartTime is also adjusted for the second lap.

For Course laps, BeginPosition and EndPosition are also adjusted.

Will raise exception unless called in list context.

reverse( # )

This method is allowed only for Courses and returns a clone of the lap object with the order of the trackpoints reversed.

$reversed = $lap->reverse;

When reversing a course, the time and distance information is set at 0 at the first trackpoint. Therefore, the lap aggregates (DistanceMeters, TotalTimeSeconds) may be smaller by a few seconds and meters compared to the original lap due to loss of elapsed time and distance information from the original lap's first point.

AUTOLOAD Methods

field( $value )

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

Possible fields for Activity laps consist of: AverageHeartRateBpm, Cadence, Calories, DistanceMeters, Intensity, MaximumHeartRateBpm, MaximumSpeed, TotalTimeSeconds, TriggerMethod, StartTime.

Course laps contain aggregates such as DistanceMeters, TotalTimeSeconds but not much else. They also contain BeginPosition and EndPosition which are exclusive to courses. They also contain Intensity which almost always equal to 'Active'.

Some fields may contain a value of 0, Calories being one example. It is safer to check if a field is defined with if (defined $lap->Calories) rather than if ($lap->Calories).

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

is_activity()
is_course()

True if the given lap is of the type indicated by the method, false otherwise.

time_add( @duration )
time_subtract( @duration )

Perform DateTime math on the timestamps of each trackpoint in the lap 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().

distancemeters()
totaltimeseconds()
maximumspeed()
maximumheartratebpm()
averageheartratebpm()
cadence()

Calculate and return the distance meters, totaltimeseconds, maximum speed (notionally corresponding to a lap's DistanceMeters and TotalTimeSeconds fields) from the elapsed data contained in each point of the lap's track. The heartrate information is calculated based on the HeartRateBpm field of the trackpoints. The cadence is computed from the average cadence of all the trackpoints' Cadence fields.

The methods do not (yet) reset the fields of the lap yet. The two values may differ due to rounding, the fact that the Garmin recorded the aggregate field with miliseconds and some additional distance the garmin may have recorded between laps, etc. Any difference should be insignificant in relation to the measurement error introduced by the device itself.

xml_string()

returns a string containing the XML representation of object, useful for subsequent saving into an *.tcx file. The string is equivalent to the string argument expected by new().

Overloaded Methods

+

can concatenate two laps by issuing $lap = $lap1 + $lap2 on two Lap objects.

EXAMPLES

Coming soon.

AUTHOR

Patrick Joly

VERSION

1.06

SEE ALSO

perl(1).