README

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

安装

通过Composer

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

通过ZIP文件

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

示例用法

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

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

<?php
$parser = new \Waddle\Parsers\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\Parsers\TCXParser();
$parser = new \Waddle\Parsers\GPXParser();
$parser = new \Waddle\Parsers\PWXParser();
$parser = new \Waddle\Parsers\CSVParser();

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

可用的活动指标/数据

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

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

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

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

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

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

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

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

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

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

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

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

$activity->getSplits($type) - 这返回活动分段的数组。变量$type应包含"m"（英里）或"k"（公里）。活动将分成1英里/公里的点。 未来 - 未来这将成为迷你活动对象，以便可以对单个分段计算指标。

解析器之间的差异

某些文件格式包含比其他格式更多的信息。例如，标准.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的任何帮助，请提出一个描述问题的工单。