姿势识别工具包（GRT）

姿势识别工具包（GRT）是一个跨平台、开源的C++机器学习库，专为实时姿势识别而设计。

构建状态：

• 主分支：
  • 
• 开发分支：
  • 

当前版本：0.2.5

关于GRT需要了解的关键点：

• 该工具包由两部分组成：全面的C++ API和前端图形用户界面（GUI）。您可以在本仓库中获取C++ API和GUI的源代码；GUI的预编译版本可在此处下载：[http://www.nickgillian.com/wiki/pmwiki.php/GRT/Download]
• C++ API和GUI均设计用于处理实时传感器数据，但也可用于更传统的离线机器学习任务。
• GRT的输入可以是任意N维浮点向量——这意味着您可以将GRT与摄像头、Kinect、Leap Motion、加速度计或其他任何您可能自行搭建的自定义传感器配合使用。
• 工具包定义了一个通用的Float类型，默认为双精度浮点数，但可通过GRT主Typedefs头文件轻松更改为单精度。
• GRT的VectorFloat和MatrixFloat类的精度会根据主Float精度自动更新。
• 工具包将类别标签0保留为特殊的空手势类别标签，用于自动手势检测。因此，如果您希望使用手势检测功能，请避免将任何手势标记为类别标签0。
• 训练数据和模型以自定义的**.grt*文件格式保存。这些文件由一个简单的头部和主数据集组成。除了.grt文件外，您还可以通过在保存或加载文件时使用.csv*扩展名来导入/导出CSV格式的数据。
• 几乎所有GRT类都支持以下函数：
  • predict( ... )：使用输入数据(...)和预先训练好的模型进行预测，例如分类或回归。
  • train( ... )：使用输入数据(...)训练一个新的模型，随后可用于实时预测。
  • save( ... )：将模型或数据集保存到文件中。文件格式可以是自定义的GRT文件（.grt）或CSV文件（.csv）。
  • load( ... )：从文件中加载预先训练好的模型或数据集。文件格式可以是自定义的GRT文件（.grt）或CSV文件（.csv）。
  • reset()：重置模块，例如重置滤波器模块会清除其历史缓冲区中的值并将其设置为零。
  • clear()：清除模块，移除所有预先训练好的模型、权重等。例如，清除滤波器模块会删除滤波器系数、历史缓冲区等。
• 带下划线的函数，如train_( ... )，会将输入参数作为引用传递，因此在处理非常大的数据集时效率更高。

核心资源

• GRT官网：http://www.nickgillian.com/grt
• GRT维基：https://github.com/nickgillian/grt/wiki
• GRT论坛：http://www.nickgillian.com/forum
• GRT API参考：http://nickgillian.com/grt/api/0.2.5/
• GRT源代码：https://github.com/nickgillian/grt
• GRT GUI下载：http://www.nickgillian.com/wiki/pmwiki.php/GRT/Download
• GRT《机器学习研究期刊》论文：grt.pdf

核心算法

GRT支持广泛的监督与非监督机器学习算法，适用于分类、回归和聚类任务，包括：

• 分类： Adaboost、决策树、动态时间规整、高斯混合模型、隐马尔可夫模型、k近邻、朴素贝叶斯、随机森林、支持向量机、Softmax，以及更多…(https://github.com/nickgillian/grt/wiki/reference#classifiers)

• 回归： 线性回归、逻辑回归、神经网络（多层感知机）

• 聚类： k均值、聚类树、高斯混合模型。

除了上述机器学习算法外，工具包还包含大量用于预处理、特征提取和后处理的算法。

更多详细信息请参阅维基。

GRT 扩展

目前已有多个扩展和第三方应用将 GRT 用作后端机器学习系统，其中包括：

• ofGrt：GRT 的一个扩展，专为 openFrameworks 设计。
• ml-lib，由 Ali Momeni 和 Jamie Bullock 开发：ml-lib 是一套用于 Max 和 Pure Data 的机器学习外部库，旨在跨多种平台运行，包括 OS X、Windows 和 Linux，以及 Intel 和 ARM 架构。
• ESP，由 David A. Mellis 和 Ben Zhang 开发：这是一款交互式应用，旨在通过应用机器学习技术，帮助初学者在交互项目中更熟练地使用传感器。该系统基于 openFrameworks 构建，并提供了多个有趣的示例，分别针对 Arduino 传感器模块 以及更通用的输入数据流（例如网络数据）。
• Android 移植版：您可以在 这里 找到 GRT 的 Android 特定移植版本。

GRT 架构

为了在保持一致性的同时提供灵活性，GRT 采用了面向对象的模块化架构。该架构围绕一组核心 模块 和一个中央 手势识别流水线 构建。

模块和流水线的输入均为 N 维浮点向量，这使得工具包能够灵活适应不同类型的输入信号。
每个模块中的算法既可以作为独立类单独使用，也可以通过流水线将多个模块串联起来，构建更为复杂的手势识别系统。GRT 包含用于预处理、特征提取、聚类、分类、回归和后处理的模块。

该工具包的源代码结构如下：

• ClassificationModules：包含所有 GRT 分类算法，如 AdaBoost、朴素贝叶斯、K 近邻、支持向量机等。
• ClusteringModules：包含所有 GRT 聚类算法，包括 K 均值、高斯混合模型和自组织映射。
• ContextModules：包含所有 GRT 上下文模块，这些模块可以连接到手势识别流水线，为实时分类系统提供额外的上下文信息。
• CoreAlgorithms：包含一些在整个 GRT 中广泛使用的算法，如粒子滤波器、主成分分析和受限玻尔兹曼机。
• CoreModules：包含所有 GRT 基础类，如 MLBase、Classifier、FeatureExtraction 等。
• DataStructures：包含所有用于记录、保存和加载数据集的 GRT 类。
• FeatureExtractionModules：包含所有 GRT 特征提取模块，如快速傅里叶变换、量化器和时域特征。
• PostProcessingModules：包含所有 GRT 后处理模块，如类别标签过滤器和类别标签超时过滤器。
• PreProcessingModules：包含所有 GRT 预处理模块，包括低通滤波器、高通滤波器、死区处理等。
• RegressionModules：包含所有 GRT 回归模块，如多层感知器神经网络、线性回归和逻辑回归。
• Util：包含大量辅助类，如日志记录、工具类、时间戳、随机数生成和矩阵操作等。

入门示例

本示例演示了 GRT 的几个关键组件，例如：

• 如何从文件（例如 CSV 文件）加载数据集
• 如何将数据集拆分为训练集和测试集
• 如何设置一个新的手势识别流水线，并向流水线中添加分类算法
• 如何使用训练数据集训练新的分类模型
• 如何将训练好的流水线保存到文件或从文件加载
• 如何使用自动测试数据集测试分类模型的准确率
• 如何使用手动测试数据集测试分类模型的准确率
• 如何打印详细的测试结果，例如精确率、召回率和混淆矩阵

您可以在 GRT 的 examples 文件夹中找到此源代码以及大量其他示例和教程。

您应该使用一个参数运行此示例，该参数指向您想要加载的文件，例如：

 ./example my_data.csv

您可以在 GRT 的主数据目录中找到几个示例 CSV 文件和其他数据集。

//包含 GRT 主头文件
#include <GRT/GRT.h>
using namespace GRT;
using namespace std;

int main (int argc, const char * argv[]) {
  //从命令行解析训练数据文件名
  if (argc != 2) {
    cout << "错误：未能从命令行解析数据文件名。";
    cout << "您应该使用一个指向数据文件的参数来运行此示例\n";
    return EXIT_FAILURE;
  }
  const string filename = argv[1];

  //从文件加载一些训练数据
  ClassificationData trainingData;

  cout << "正在加载数据集..." << endl;
  if (!trainingData.load(filename)) {
    cout << "错误：未能从文件加载训练数据\n";
    return EXIT_FAILURE;
  }

  cout << "数据加载完成" << endl;

  //打印一些关于训练数据的统计信息
  trainingData.printStats();

  //将训练数据划分为训练集和测试集。80 表示 80% 的数据将用于训练，20% 将作为测试集返回
  cout << "正在将数据拆分为训练/测试集..." << endl;
  ClassificationData testData = trainingData.split(80);

  //创建一个新的手势识别流水线
  GestureRecognitionPipeline pipeline;

  //向流水线中添加 KNN 分类器，K 值为 10
  pipeline << KNN(10);

  //使用训练数据训练流水线
  cout << "正在训练模型..." << endl;
  if (!pipeline.train(trainingData)) {
    cout << "错误：未能训练流水线！\n";
    return EXIT_FAILURE;
  }

  //将流水线保存到文件
  if (!pipeline.save("HelloWorldPipeline.grt")) {
    cout << "错误：未能保存流水线！\n";
    return EXIT_FAILURE;
  }

  //从文件加载流水线
  if (!pipeline.load("HelloWorldPipeline.grt")) {
    cout << "错误：未能加载流水线！\n";
    return EXIT_FAILURE;
  }

  //使用测试数据测试流水线
  cout << "正在测试模型..." << endl;
  if (!pipeline.test(testData)) {
    cout << "错误：未能测试流水线！\n";
    return EXIT_FAILURE;
  }

  //打印一些关于测试的统计信息
  cout << "流水线测试准确率：" << pipeline.getTestAccuracy() << endl;

  //手动将测试数据集输入流水线进行预测
  Float testAccuracy = 0.0;
  for (UINT i=0; i<testData.getNumSamples(); i++) {
    pipeline.predict(testData[i].getSample());

    if (testData[i].getClassLabel() == pipeline.getPredictedClassLabel()) {
      testAccuracy++;
    }
  }
  cout << "手动测试准确率：" << testAccuracy / testData.getNumSamples() * 100.0 << endl;
   
  //获取流水线中的类别标签向量
  Vector< UINT > classLabels = pipeline.getClassLabels();

  //打印精确率
  cout << "精确率：";
  for (UINT k=0; k<pipeline.getNumClassesInModel(); k++) {
    cout << "\t" << pipeline.getTestPrecision(classLabels[k]);
  }cout << endl;

  //打印召回率
  cout << "召回率：";
  for (UINT k=0; k<pipeline.getNumClassesInModel(); k++) {
    cout << "\t" << pipeline.getTestRecall(classLabels[k]);
  }cout << endl;

  //打印 F1 分数
  cout << "F1 分数：";
  for (UINT k=0; k<pipeline.getNumClassesInModel(); k++) {
    cout << "\t" << pipeline.getTestFMeasure(classLabels[k]);
  }cout << endl;

  //打印混淆矩阵
  MatrixFloat confusionMatrix = pipeline.getTestConfusionMatrix();
  cout << "混淆矩阵：\n";
  for (UINT i=0; i<confusionMatrix.getNumRows(); i++) {
    for (UINT j=0; j<confusionMatrix.getNumCols(); j++) {
      cout << confusionMatrix[i][j] << "\t";
    }cout << endl;
  }

  return EXIT_SUCCESS;
}

教程和示例

您可以在 examples 文件夹中找到大量的教程和示例。此外，您还可以在 GRT 的官方维基上找到丰富的示例和参考资料：

http://www.nickgillian.com/wiki/pmwiki.php?n=GRT.GestureRecognitionToolkit

如果您使用 CMake 构建 GRT，在成功构建主 GRT 库之后，构建目录中会自动生成一个 examples 文件夹。然后您可以直接从该示例目录运行示例应用程序。要运行任何示例，请在 grt/build/examples 目录下打开终端并运行：

./ExampleName

其中 ExampleName 是您想要运行的示例应用程序的名称。

论坛

请注意，目前论坛服务器出现故障，我们正在努力修复。在此期间，请使用 GitHub 的问题和拉取请求。

旧论坛的链接如下：http://www.nickgillian.com/forum/

Bug 报告

请将 Bug 提交到 GitHub Bug 跟踪器。

贡献

欢迎所有贡献，用户可以通过以下几种方式为工具包做出贡献：

• 改进由 Doxygen 生成的 API（通过提高现有代码文档的覆盖率和质量）
• 改进可在 维基 中找到的高级文档
• 添加新的示例或教程，或改进现有示例和教程
• 添加新的 单元测试，以帮助确保当前函数的质量并及早发现潜在的 Bug

请为任何贡献提交 拉取请求。

GRT 浮点精度

GRT 默认使用双精度浮点值。工具包的精度由以下 Float 类型定义指定：

typedef double Float; ///< 此类型定义用于在整个 GRT 中设置浮点精度

如果需要，可以通过修改 GRT/Util/GRTTypedefs.h 头文件中定义的主 GRT Float 类型定义值，轻松将其更改为单精度精度。

VectorFloat 和 MatrixFloat 数据结构

GRT 在整个工具包中使用两种主要的数据结构：Vector 和 Matrix。它们都是模板类，因此可以泛化为任何 C++ 类型。关于这些数据类型，需要了解的主要内容如下：

• Vector: 继承自 STL vector 类。

// 创建一个包含 3 个元素的整数向量
Vector< int > vec1(3);

// 创建一个包含 2 个元素的字符串向量
Vector< string > vec2(2);

// 创建一个包含 5 个 Foo 对象的向量
Vector< Foo > vec3(5);

• Matrix: 提供用于存储二维数组的基类。

// 创建一个 3x2 大小的整数矩阵
Matrix< int > mat1(3,2);

// 创建一个 2x2 大小的字符串矩阵
Matrix< string > mat2(2,2);

// 创建一个 5x3 大小的 Foo 矩阵
Matrix< Foo > mat3(5,3);

• VectorFloat: 提供用于存储浮点向量数据的主要数据结构。VectorFloat 的精度将自动与 GRT Float 的精度保持一致。

// 创建一个包含 10 个元素的新向量
VectorFloat vector( 10 );
for(UINT i=0; i<vector.getSize(); i++){ 
    vector[i] = i*1.0; 
}

• MatrixFloat: 提供用于存储浮点矩阵数据的主要数据结构。MatrixFloat 的精度将自动与 GRT Float 的精度保持一致。

// 创建一个 5x2 的浮点矩阵
MatrixFloat matrix(5,2);

// 遍历矩阵中的数据，并将其设置为一个简单的递增值
UINT counter = 0;
for(UINT i=0; i<matrix.getNumRows(); i++){
    for(UINT j=0; j<matrix.getNumCols(); j++){
        matrix[i][j] = counter++;
    }
}

构建 GRT

您可以在 build 文件夹中找到一个 CMakeLists 文件，可用于为您的机器自动生成 Makefile。

请阅读 build 文件夹中的 README 文件，以了解如何将 GRT 构建成适用于 Linux、OS X 或 Windows 的静态库。

在您的 C++ 项目中安装和使用 GRT

有关如何在您的 C++ 项目中构建、安装和使用 GRT 的详细信息，请参阅 build 目录。

许可证

手势识别工具包采用 MIT 许可证授权。

特此授予任何人免费获取本软件及其相关文档文件（以下简称“软件”）副本的权利，允许其在不受限制的情况下处理该软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售该软件副本的权利；并允许向任何获得该软件的人提供该软件，但须遵守以下条件：

上述版权声明和本许可声明应包含在该软件的所有副本或实质性部分中。 本软件按“原样”提供，不提供任何形式的明示或暗示保证，包括但不限于适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权所有者均不对任何索赔、损害或其他责任负责，无论该等责任是基于合同、侵权行为或其他原因而产生，亦无论该等责任是否与本软件或其使用有关，或因其他方式而产生。

GRT (Gesture Recognition Toolkit) 快速上手指南

GRT 是一个跨平台、开源的 C++ 机器学习库，专为实时手势识别设计。它支持多种传感器输入（如摄像头、Kinect、Leap Motion、加速度计等），并提供丰富的分类、回归和聚类算法。

环境准备

系统要求

• 操作系统: Windows, macOS, Linux (跨平台支持)
• 编译器: 支持 C++11 标准的编译器 (如 GCC, Clang, MSVC)
• 构建工具: CMake (推荐版本 3.0+)

前置依赖

GRT 核心库主要依赖标准 C++ 库，无重型外部依赖。若需使用图形界面 (GUI) 或特定扩展，请参考官方 Wiki 安装额外依赖（如 openFrameworks, Qt 等）。本指南专注于核心 C++ API 的使用。

安装步骤

1. 克隆源代码

从 GitHub 获取最新源码：

git clone https://github.com/nickgillian/grt.git
cd grt

2. 编译与安装

使用 CMake 进行构建：

mkdir build
cd build
cmake ..
make
sudo make install

注：在 Windows 上，可使用 Visual Studio 打开生成的 .sln 文件进行编译，或使用 cmake --build . 命令。

3. 验证安装

编译完成后，可在 build 目录或示例文件夹中找到可执行文件。确保头文件和库文件已正确链接到您的项目中。

基本使用

以下示例演示了如何使用 GRT 加载数据、划分训练/测试集、构建识别管道、训练 KNN 模型并评估准确率。

代码示例 (main.cpp)

// 引入 GRT 主头文件
#include <GRT/GRT.h>
using namespace GRT;
using namespace std;

int main (int argc, const char * argv[]) {
  // 检查命令行参数
  if (argc != 2) {
    cout << "Error: failed to parse data filename from command line. ";
    cout << "You should run this example with one argument pointing to a data file\n";
    return EXIT_FAILURE;
  }
  const string filename = argv[1];

  // 1. 加载数据集 (支持 .grt 或 .csv 格式)
  ClassificationData trainingData;
  cout << "Loading dataset..." << endl;
  if (!trainingData.load(filename)) {
    cout << "ERROR: Failed to load training data from file\n";
    return EXIT_FAILURE;
  }
  cout << "Data Loaded" << endl;
  trainingData.printStats();

  // 2. 划分训练集和测试集 (80% 训练，20% 测试)
  cout << "Splitting data into training/test split..." << endl;
  ClassificationData testData = trainingData.split(80);

  // 3. 创建手势识别管道
  GestureRecognitionPipeline pipeline;

  // 4. 添加分类器 (此处使用 K-近邻算法)
  // KNN 构造函数参数：K 值
  if (!pipeline.setClassifier( KNN(5) )) {
    cout << "ERROR: Failed to set classifier\n";
    return EXIT_FAILURE;
  }

  // 5. 训练模型
  cout << "Training model..." << endl;
  if (!pipeline.train( trainingData )) {
    cout << "ERROR: Failed to train model\n";
    return EXIT_FAILURE;
  }

  // 6. 在测试集上评估模型
  cout << "Testing model..." << endl;
  if (!pipeline.test( testData )) {
    cout << "ERROR: Failed to test model\n";
    return EXIT_FAILURE;
  }

  // 7. 输出测试结果 (精确率、召回率、混淆矩阵等)
  pipeline.printTestResults();

  // 8. 保存训练好的管道到文件 (.grt 格式)
  if (!pipeline.save("trained_pipeline.grt")) {
    cout << "ERROR: Failed to save pipeline\n";
    return EXIT_FAILURE;
  }

  // 9. (可选) 加载已保存的管道进行实时预测
  /*
  GestureRecognitionPipeline loadedPipeline;
  if (!loadedPipeline.load("trained_pipeline.grt")) {
      cout << "ERROR: Failed to load pipeline\n";
      return EXIT_FAILURE;
  }
  // 实时预测示例: loadedPipeline.predict(inputVector);
  */

  return EXIT_SUCCESS;
}

运行示例

假设您有一个名为 my_data.csv 的数据集文件，编译并运行程序的命令如下：

g++ -std=c++11 main.cpp -o gesture_example -lgrt
./gesture_example my_data.csv

注意：实际编译时请根据您的安装路径调整 -I (头文件路径) 和 -L (库文件路径) 参数，或直接使用 CMake 管理项目依赖。

关键说明

• 输入数据: GRT 接受任意维度的浮点向量作为输入，适用于各类传感器数据。
• 类标签: 请避免使用 0 作为有效手势的类标签，因为 0 被保留为“空手势”（用于自动手势检测）。
• 文件格式: 支持自定义 .grt 格式以及通用的 .csv 格式进行数据导入导出。
• 核心函数: 几乎所有模块都支持 train(), predict(), save(), load(), reset() 和 clear() 方法。