mmerlijn/php-fit-file-analysis

此包的最新版本（v3.2.5）没有可用的许可证信息。

用于分析由Garmin GPS设备创建的FIT文件的PHP类

维护者

详细信息

github.com/mmerlijn/php-fit-file-analysis

主页

源代码

资助包维护！
adriangibbons

安装: 4

依赖: 0

建议: 0

安全: 0

星标: 0

关注者: 0

分支: 49

v3.2.5 2022-06-22 12:35 UTC

Requires (Dev)

Unknown License aa2dac2d21ed55f85b17dee0351c56c30a93b8c4

garminFit

This package is auto-updated.

Last update: 2024-09-22 17:34:24 UTC

README

Build Status Packagist Packagist Coverage Status

phpFITFileAnalysis

一个用于分析由Garmin GPS设备创建的FIT文件的PHP类（>= v5.4）。

实时演示（右键单击并在新标签页中打开）

演示截图

Mountain Biking Power Analysis Quadrant Analysis Swim

如果您有任何问题或需要支持，请先阅读本页的全部内容和常见问题（FAQ）。

什么是FIT文件？

FIT或灵活可互操作数据传输是一种用于GPS轨迹和路线的文件格式。它被较新的Garmin健身GPS设备使用，包括Edge和Forerunner系列，这些系列在自行车手和跑者中很受欢迎。

访问Wiki中的FAQ页面获取更多信息。

我如何使用phpFITFileAnalysis与我的PHP驱动的网站？

这里有几个选择

更现代的方法：在composer.json文件中添加包adriangibbons/php-fit-file-analysis

{
    "require": {
        "adriangibbons/php-fit-file-analysis": "^3.2.0"
    }
}

从命令行运行composer update。

composer.json文件应自动加载phpFITFileAnalysis类，因此只要你在PHP文件中包含自动加载文件，你应该可以用以下方式实例化类

<?php
    require __DIR__ . '/vendor/autoload.php';  // this file is in the project's root folder
    $pFFA = new adriangibbons\phpFITFileAnalysis('fit_files/my_fit_file.fit');
?>

更手动的方法：从GitHub下载ZIP文件，并将/src目录中的PHP类文件放在合适的位置（例如classes/）。已经做出了有意识的努力，将所有内容都保持在单个文件中。

然后，在您想要使用它的PHP页面上包含文件，并实例化类的对象

<?php
    include('classes/phpFITFileAnalysis.php');
    $pFFA = new adriangibbons\phpFITFileAnalysis('fit_files/my_fit_file.fit');
?>

请注意，创建实例时唯一必需的参数是您想要加载的FIT文件的路径。

还有更多的可选参数可以提供。这些将在本页下方更详细地描述。

对象将自动加载FIT文件并遍历其内容。它将把找到的任何数据存储在数组中，这些数组可以通过公共数据变量访问。

访问数据

由类读取的数据存储在关联数组中，可以通过公共数据变量访问

$pFFA->data_mesgs

数组索引是消息和它们包含的字段名称。例如

// Contains an array of all heart_rate data read from the file, indexed by timestamp
$pFFA->data_mesgs['record']['heart_rate']
// Contains an integer identifying the number of laps
$pFFA->data_mesgs['session']['num_laps']

好的，但我怎么知道我的文件中有哪些消息和字段？您可以通过迭代$pFFA->data_mesgs数组，或者查看可以输出到网页的调试信息

// Option 1. Iterate through the $pFFA->data_mesgs array
foreach ($pFFA->data_mesgs as $mesg_key => $mesg) {  // Iterate the array and output the messages
    echo "<strong>Found Message: $mesg_key</strong><br>";
    foreach ($mesg as $field_key => $field) {  // Iterate each message and output the fields
        echo " - Found Field: $mesg_key -> $field_key<br>";
    }
    echo "<br>";
}

// Option 2. Show the debug information
$pFFA->showDebugInfo();  // Quite a lot of info...

有什么真实世界的例子吗？

// Get Max and Avg Speed
echo "Maximum Speed: ".max($pFFA->data_mesgs['record']['speed'])."<br>";
echo "Average Speed: ".( array_sum($pFFA->data_mesgs['record']['speed']) / count($pFFA->data_mesgs['record']['speed']) )."<br>";

// Put HR data into a JavaScript array for use in a Chart
echo "var chartData = [";
    foreach ($pFFA->data_mesgs['record']['heart_rate'] as $timestamp => $hr_value) {
        echo "[$timestamp,$hr_value],";
    }
echo "];";

枚举数据 FIT协议使用枚举数据类型。在FIT SDK中确定了这些值后，它们被包含在类中作为私有变量：$enum_data。

有一个公共函数，可以返回给定消息类型的枚举值。例如

// Access data stored within the private class variable $enum_data
// $pFFA->enumData($type, $value)
// e.g.
echo $pFFA->enumData('sport', 2));  // returns 'cycling'
echo $pFFA->enumData('manufacturer', $this->data_mesgs['device_info']['manufacturer']);  // returns 'Garmin';
echo $pFFA->manufacturer();  // Short-hand for above

此外，公共函数提供了一种简化的方式来访问常用枚举数据

  • manufacturer()
  • product()
  • sport()

可选参数

当实例化phpFITFileAnalysis对象时，可以传递五个可选参数作为关联数组。这些是

  • fix_data
  • data_every_second
  • units
  • pace
  • garmin_timestamps
  • overwrite_with_dev_data

例如

$options = [
    'fix_data'                => ['cadence', 'distance'],
    'data_every_second'       => true
    'units'                   => 'statute',
    'pace'                    => true,
    'garmin_timestamps'       => true,
    'overwrite_with_dev_data' => false
];
$pFFA = new adriangibbons\phpFITFileAnalysis('my_fit_file.fit', $options);

以下将更详细地描述可选参数。

“修复”数据

FIT文件已观察到某些数据点缺失的情况，例如一个传感器（如踏频/足部传感器）缺失数据，而其他传感器（如心率）在同一瞬间收集了信息。原因未知，通常只有相对少量的数据点缺失。修复此问题可能是多余的，因为每个数据都使用时间戳进行索引。然而，对于您的项目来说，确保每种类型的数据具有相同数量的数据点可能很重要。

识别的值： 'all', 'cadence', 'distance', 'heart_rate', 'lat_lon', 'power', 'speed'

**示例：**

$options = ['fix_data' => ['all']];  // fix cadence, distance, heart_rate, lat_lon, power, and speed data
$options = ['fix_data' => ['cadence', 'distance']];  // fix cadence and distance data only
$options = ['fix_data' => ['lat_lon']];  // fix position data only

如果未提供 fix_data 数组，则不会执行数据“修复”。

FIT文件可能包含以下内容

如上图所示，最易缺失数据点的数据类型是：position_lat，position_long，altitude，heart_rate，cadence，distance，speed和power。

除了踏频信息外，缺失的数据点通过插入插值值进行“修复”。

对于踏频，插入零值，因为在此时间点很可能没有收集到数据，因为没有运动。

缺失数据点的插值

// Do not use code, just for demonstration purposes
var_dump($pFFA->data_mesgs['record']['temperature']);  // ['100'=>22, '101'=>22, '102'=>23, '103'=>23, '104'=>23];
var_dump($pFFA->data_mesgs['record']['distance']);  // ['100'=>3.62, '101'=>4.01, '104'=>10.88];

如您在上面的简单示例中看到的，温度数据已记录在每个五个时间戳（100，101，102，103和104）上。然而，在时间戳102和103上没有记录距离信息。

如果 fix_data 包含 'distance'，则该类将尝试在距离数组中插入索引102和103的数据。值使用101（4.01）和104（10.88）之间的线性插值确定。

结果将是

var_dump($pFFA->data_mesgs['record']['distance']);  // ['100'=>3.62, '101'=>4.01, '102'=>6.30, '103'=>8.59, '104'=>10.88];

每秒数据

一些Garmin的健身设备提供智能记录或每秒记录的选择。

智能记录记录健身设备更改方向、速度、心率或海拔的关键点。此记录类型记录的轨迹点较少，可能在时间戳之间有大于一秒的间隔。

您可以通过设置选项来强制时间戳为规律的一秒间隔

$options = ['data_every_second' => true];

缺失的时间戳将根据上述 fix_data 选项进行插值。

如果未指定与 data_every_second 一起的 fix_data 选项，则假定 'fix_data' => ['all']。

请注意，您可能在使用 fix_data 选项时会遇到性能下降。性能提升将被探索——很可能是 interpolateMissingData() 函数不是最优的。

设置单位

默认情况下，假设以下表中的 公制 单位。

您可以选择请求 英制 或 原始 单位而不是公制。原始单位是创建FIT文件的设备使用的单位，并且是FIT标准的本地单位（即，不会对从文件中读取的值进行转换）。

要选择所需的单位，请使用以下之一

$options = ['units' => 'statute'];
$options = ['units' => 'raw'];
$options = ['units' => 'metric'];  // explicit but not necessary, same as default

配速

如果用户需要，可以提供配速而不是速度。根据请求的单位，配速将以公里/分钟（min/km）的形式适用于公制单位；或以英里/分钟（min/mi）的形式适用于英制。

要选择配速，请使用以下选项

$options = ['pace' => true];

配速值将是小数分钟。要获取秒数，您可能希望执行如下操作

foreach ($pFFA->data_mesgs['record']['speed'] as $key => $value) {
    $min = floor($value);
    $sec = round(60 * ($value - $min));
    echo "pace: $min min $sec sec<br>";
}

请注意，如果请求 '原始' 单位，则此参数对速度数据没有影响，因为它未从文件中读取的原始数据中进行更改。

时间戳

Unix时间是从 UTC 00:00:00 Jan 01 1970以来的秒数，然而FIT标准指定时间戳（即date_time和local_date_time类型的字段）代表从 UTC 00:00:00 Dec 31 1989以来的秒数。

FIT和Unix时间戳之间的差异（以秒为单位）是631,065,600

$date_FIT = new DateTime('1989-12-31 00:00:00', new DateTimeZone('UTC'));
$date_UNIX = new DateTime('1970-01-01 00:00:00', new DateTimeZone('UTC'));
$diff = $date_FIT->getTimestamp() - $date_UNIX->getTimestamp();
echo 'The difference (in seconds) between FIT and Unix timestamps is '. number_format($diff);

默认情况下，从FIT文件中读取的类型为date_time和local_date_time的字段将添加此差异，以便可以将其视为Unix时间。如果需要FIT时间戳，则可以将'garmin_timestamps'选项设置为true。

用开发者数据覆盖

fit标准允许开发者定义数据含义，而无需更改正在使用的fit配置文件。他们可以定义标准中已包含的数据 - 例如，心率、步频、功率等。默认情况下，如果开发者这样做，数据将覆盖常规的$pFFA->data_mesgs['record']数组中的任何内容。如果您不希望发生这种情况，将“overwrite_with_dev_data”选项设置为false。数据仍然可以在$pFFA->data_mesgs['developer_data']中找到。

分析

以下函数返回可以用于创建表格/图表的数据数组

array $pFFA->hrPartionedHRmaximum(int $hr_maximum);
array $pFFA->hrPartionedHRreserve(int $hr_resting, int $hr_maximum);
array $pFFA->powerPartioned(int $functional_threshold_power);
array $pFFA->powerHistogram(int $bucket_width = 25);

要对这些函数进行高级控制或与其他传感器数据（例如步频或速度）一起使用，请使用底层函数

array $pFFA->partitionData(string $record_field='', $thresholds=null, bool $percentages = true, bool $labels_for_keys = true);
array $pFFA->histogram(int $bucket_width=25, string $record_field='');

存在函数，可以根据用户提供的数据的百分比来确定阈值

array $pFFA->hrZonesMax(int $hr_maximum, array $percentages_array=[0.60, 0.75, 0.85, 0.95]);
array $pFFA->hrZonesReserve(int $hr_resting, int $hr_maximum, array $percentages_array=[0.60, 0.65, 0.75, 0.82, 0.89, 0.94 ]) {
array $pFFA->powerZones(int $functional_threshold_power, array $percentages_array=[0.55, 0.75, 0.90, 1.05, 1.20, 1.50]);

心率

存在用于分析心率数据的函数

// hr_FT is heart rate at Functional Threshold, or Lactate Threshold Heart Rate
array $pFFA->hrMetrics(int $hr_resting, int $hr_maximum, string $hr_FT, $gender);
// e.g. $pFFA->hrMetrics(52, 189, 172, 'male');

心率指标

  • TRIMP（训练脉冲）
  • 强度因素

功率

存在三个用于分析功率数据的函数

array $pFFA->powerMetrics(int $functional_threshold_power);
array $pFFA->criticalPower(int or array $time_periods);  // e.g. 300 or [600, 900]
array $pFFA->quadrantAnalysis(float $crank_length, int $ftp, int $selected_cadence = 90, bool $use_timestamps = false);  // Crank length in metres

功率指标

  • 平均功率
  • 千焦耳
  • 标化功率（假设您的功率输出保持恒定）
  • 变异性指数（标化功率/平均功率的比率）
  • 强度因素（标化功率/功能阈限功率的比率）
  • 训练压力评分（基于相对强度和持续时间的工作量）

临界功率（或最大努力）是在活动期间以指定时间段内维持的最高平均功率。您可以提供一个时间段（以秒为单位），或一个时间段数组。

象限分析通过比较踏频和功率来观察踏频和功率，可以深入了解骑行的神经肌肉需求。

请注意，如果服务器上已加载PHP Trader扩展，则$pFFA->criticalPower和一些功率指标（标化功率、变异性指数、强度因素、训练压力评分）将使用该扩展。如果没有加载扩展，它将使用内置的简单移动平均算法，这对于大型文件来说性能要差得多！

功率分析演示在此处可用。

其他方法

返回一个以时间戳为键的布尔数组。true == 计时器暂停（例如，自动暂停）

array isPaused()

返回一个包含请求骑行数据的JSON对象

array getJSON(float $crank_length = null, int $ftp = null, array $data_required = ['all'], int $selected_cadence = 90)
/**
 * $data_required can be ['all'] or a combination of:
 * ['timestamp', 'paused', 'temperature', 'lap', 'position_lat', 'position_long', 'distance', 'altitude', 'speed', 'heart_rate', 'cadence', 'power', 'quadrant-analysis']
 */

返回一个齿轮变换信息数组（如果有，例如使用Shimano D-Fly无线Di2发射器）

// By default, time spent in a gear whilst the timer is paused (e.g. autopause) is ignored. Set to false to include.
array gearChanges($bIgnoreTimerPaused = true)

致谢

此类已使用ANT（thisisant.com）提供的软件开发工具包（SDK）中可用的信息创建。

作为最低要求，我建议阅读SDK中包含的三个PDF文件

  1. fit文件类型描述
  2. fit SDK入门指南
  3. 灵活且互操作的数据传输（fit）协议

然后是'Profile.xls'电子表格以及Java/C/C++示例。