README

Waddle是一个PHP库，用于解析GPS活动（例如运动手表）并计算各种指标。它支持解析.TCX、.GPX、.PWX和.CSV文件。

安装

通过Composer

{
    "require": {
        "kyoden/waddle": "dev-master"
    }
}

通过Zip文件

从本存储库下载Waddle的zip文件并将其放置到您的项目中。然后您需要包含您希望使用的文件，除非您正在使用自动加载器。

示例用法

<?php
$parser = new \Waddle\Parser\TCXParser();
$activity = $parser->parse('/path/to/activity.tcx');

这将解析.tcx文件并将活动加载到$activity变量中，然后可以使用该变量来计算指标

<?php
$parser = new \Waddle\Parser\TCXParser();
$activity = $parser->parse('/path/to/activity.tcx');

// Get some key metrics
$totalDistance = $activity->getTotalDistance(); # In metres, e.g. 1000
$totalDuration = $activity->getTotalDuration(); # In seconds, e.g. 255
$totalCalories = $activity->getTotalCalories(); # e.g. 100

// Convert those metrics into more human-readable values
$totalDistanceInMiles = \Waddle\Converter::convertMetresToMiles($totalDistance); # e.g. 0.62
$totalDurationInHoursMinutesSeconds = \Waddle\Converter::convertSecondsToHumanReadable($totalDuration); # e.g. 00:04:15

可用的解析器

$parser = new \Waddle\Parser\TCXParser();
$parser = new \Waddle\Parser\GPXParser();
$parser = new \Waddle\Parser\PWXParser();
$parser = new \Waddle\Parser\CSVParser();

所有解析器只有一个需要调用的parse()方法，传递相关文件的路径，如前面的示例所示。此parse()方法返回活动类的实例（或者在失败时抛出异常）。然后可以使用此活动对象根据文件内容计算所有不同的指标。

可用的活动指标/数据

$activity->getType() - 这返回活动的类型，例如“跑步”或“骑行”

$activity->getStartTime($format) - 这返回活动的开始时间。变量$format应包含一个有效的数据格式

$activity->getTotalDistance() - 这返回活动的总距离，单位为米。

$activity->getTotalDuration() - 这返回活动的总持续时间，单位为秒。

$activity->getAvgHeartRage() - 这返回活动的平均心率，单位为bpm。

$activity->getMaxHeartRage() - 这返回活动的最大心率，单位为bpm。

$activity->getCadence() - 这返回活动的平均踏频，单位为ppm。

$activity->getAveragePacePerMile() - 这返回活动每英里的平均配速，格式为"hh:mm:ss"。

$activity->getAveragePacePerKilometre() - 这返回活动每公里的平均配速，格式为"hh:mm:ss"。

$activity->getAverageSpeedInMPH() - 这返回活动的平均速度，单位为每小时英里。

$activity->getAverageSpeedInKPH() - 这返回活动的平均速度，单位为每小时公里。

$activity->getTotalCalories() - 这返回活动中燃烧的总卡路里（如果文件中指定了此信息）。

$activity->getMaxSpeedInMPH() - 这返回活动的最大速度，单位为每小时英里。

$activity->getMaxSpeedInKPH() - 这返回活动的最大速度，单位为每小时公里。

$activity->getTotalAscentDescent() - 这返回一个数组，包含上升和下降的总距离，单位为米。

$activity->getSplits($distance) - 这返回活动分割的数组。未来 - 未来这将分割成迷你活动对象，这样就可以对单独的分割计算指标。

解析器之间的差异

某些文件格式包含比其他格式更多的信息。例如，标准.TCX或.PWX文件在顶部包含摘要信息，包括活动的总持续时间、总距离等。而.CSV和.GPX等格式则没有，因此这些信息由解析器计算。因此，您可能会在解析器的结果之间发现一些差异。

在格式之间转换指标

默认情况下，某些指标使用不便于理解的度量单位进行计算，例如总距离以米为单位，而您可能更希望使用更便于理解的单位，如英里或千米。

您可以使用转换器类在格式之间进行转换

\Waddle\Converter::convertMetresPerSecondToMilesPerHour($val) - 将每秒米值转换为每小时英里。

\Waddle\Converter::convertMetresPerSecondToKilometresPerHour($val) - 将每秒米值转换为每小时千米。

\Waddle\Converter::convertMetresToKilometres($val) - 将米值转换为千米。

\Waddle\Converter::convertMetresToMiles($val) - 将米值转换为英里。

\Waddle\Converter::convertMetresToFeet($val) - 将米值转换为英尺。

\Waddle\Converter::convertMilesToMetres($val) - 将英里值转换为米。

\Waddle\Converter::convertKilometresToMetres($val) - 将千米值转换为米。

\Waddle\Converter::convertHoursMinutesSecondsToDecimal($h, $m, $s) - 将小时、分钟和秒的值转换为十进制小时值。例如，2小时、45分钟和0秒将转换为十进制“2.75”小时。

\Waddle\Converter::convertSecondsToHumanReadable($val) - 将秒值转换为“hh:mm:ss”格式。

\Waddle\Converter::convertHumanReadableToSeconds($val) - 将“hh:mm:ss”格式的字符串转换为秒。

附加功能 - 计算器

除了活动类中可用的计算外，还有额外的计算器类可供使用，以计算GPS活动文件中未包含的数据，如消耗的卡路里。

卡路里计算器

卡路里计算器类使用MET（代谢当量）分数来计算消耗的卡路里数量，基于活动的强度和个人的体重。

需要注意的是，卡路里计算在不同系统之间可能会有很大的差异，因此只能用作粗略估计，因为有许多因素会影响个人燃烧卡路里的速度。

可用方法

\Waddle\Calculators\CalorieCalculator::calculateMETFromMPH($avgSpeed) - 根据平均速度（每小时英里）计算跑步活动的粗略MET分数。

\Waddle\Calculators\CalorieCalculator::calculateMETFromKPH($avgSpeed) - 根据平均速度（每小时千米）计算跑步活动的粗略MET分数。

\Waddle\Calculators\CalorieCalculator::calculateCaloriesBurned(float $mets, float $weightInKG, float $timeInHours) - 根据活动的MET分数、个人的体重（千克）和活动持续时间（十进制时间）计算粗略的卡路里消耗量。

示例

// Get the average speed in MPH
$averageSpeedInMPH = $activity->getAverageSpeedInMPH();

// Calculate the MET score
$metScore = \Waddle\Calculators\CalorieCalculator::calculateMETFromMPH($averageSpeedInMPH);

// Get the weight of the person in KG
$weightInKG = 75;

// Get the duration and convert to hours decimal
$durationInHumanReadable = \Waddle\Converter::convertSecondsToHumanReadable($activity->getTotalDuration());
$durationSplit = explode(":", $durationInHumanReadable);
$durationInDecimalHours = \Waddle\Converter::convertHoursMinutesSecondsToDecimal($durationSplit[0], $durationSplit[1], $durationSplit[2]);

// Calculate the calories burned
$caloriesBurned = \Waddle\Calculators\CalorieCalculator::calculateCaloriesBurned($metScore , $weightInKG, $durationInDecimalHours );

帮助

如果您需要关于Waddle的帮助，只需提出一个描述问题的issue。