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
andEndPosition
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
andTime
fields of each trackpoint in the lap are made unlessas_is
is set to true.Lap aggregates
TotalTimeSeconds
andDistanceMeters
are adjusted. For Activity laps, performance metrics such asMaximumSpeed
,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
andDistanceMeters
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
, andCalories
are also recalculated for each lap (if they were defined).StartTime
is also adjusted for the second lap.For Course laps,
BeginPosition
andEndPosition
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 containBeginPosition
andEndPosition
which are exclusive to courses. They also containIntensity
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 withif (defined $lap->Calories)
rather thanif ($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()
orsubtract()
methods. See the pod forGeo::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
andTotalTimeSeconds
fields) from the elapsed data contained in each point of the lap's track. The heartrate information is calculated based on theHeartRateBpm
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
EXAMPLES
Coming soon.
AUTHOR
Patrick Joly
VERSION
1.04
SEE ALSO
perl(1).