garfielt/php-fit-file-analysis

此包最新版本（v3.2.0）没有提供许可证信息。

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

维护者

详细信息

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

主页

源代码

安装: 10

依赖: 0

建议: 0

安全: 0

星标: 1

关注者: 2

分支: 49

v3.2.0 2018-04-19 11:44 UTC

Requires (Dev)

Unknown License 99ab97bdc1bb2d45c129b6db849dcc16c03c617e

garminFit

This package is not auto-updated.

Last update: 2024-09-20 10:09:00 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页面获取更多信息。

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

这里有几个选择

更现代的方式：在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时间是从1970年1月1日UTC 00:00:00以来的秒数，但是FIT标准指定时间戳（即日期_time类型和local_date_time类型的字段）表示从1989年12月31日UTC 00:00:00以来的秒数。

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文件读取的日期时间字段和本地日期时间字段将添加此差值，以便它们可以被视为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++示例。