更新 Kalman Filter 文档，更新 RMVL 安装、顶层使用的文档

cv-rmvl · Mar 27, 2024 · 64f6cad · 64f6cad
1 parent 4409ea8
commit 64f6cad
Show file tree

Hide file tree

Showing 9 changed files with 108 additions and 69 deletions.
diff --git a/doc/intro.markdown b/doc/intro.markdown
@@ -7,16 +7,16 @@
 
 #### 前世今生{#YAT}
 
-RMVL 起源于 SRVL（SCUT Robotlab Vision Library——华南理工大学机器人实验室视觉库），由华南理工大学华南虎战队视觉组成员共同研发，于实验室团队内部自建的 Gitea 服务进行代码托管和功能维护，主要用于参加 [RoboMaster 系列赛事](https://www.robomaster.com)。该项目在 RM2021 赛季内部技术交流活动后，即 2021 年 8 月正式启动，总共经过 3 届队员传承、更迭，依次开发了 1.x ~ 4.x 共 4 个系列的版本。
+RMVL 起源于 SRVL（SCUT Robotlab Vision Library——华南理工大学机器人实验室视觉库），由华南理工大学华南虎战队视觉组成员共同研发，于实验室团队内部自建的 Gitea 服务完成代码托管，组员在此之上进行功能开发和维护。SRVL 主要用于参加 [RoboMaster 系列赛事](https://www.robomaster.com)。该项目在 RM2021 赛季内部技术交流活动后，即 2021 年 8 月正式启动，总共经过 3 届队员传承、更迭，依次开发了 1.x ~ 4.x 共 4 个系列的版本。
 
-- **1.x** —— *2021.10* 发布<span style="color: green">（未开源）</span>，主要解决了 2021 赛季步兵、英雄代码混乱的情况，初步尝试了使用抽象工厂设计模式进行代码架构的设计，届时，SRVL 开发者和使用者的不同需求需要在 SRVL 编译过程中修改编译选项。
-- **2.x** —— *2022.01* 发布<span style="color: green">（未开源）</span>，在上一版设计模式使用后出现了维护困难的情况（多个 @ref function_modules 共同组合，导致产生非常多的派生工厂）后，移除了原先所有的设计模式，各功能模块仅单独存在，不再另外设置组合或其他强依赖关系。此外， **2.x** 相较于 **1.x** 添加了全新的内容： @ref group 。
-- **3.x** —— *2022.08* 发布<span style="color: green">（未开源）</span>，架构功能大变更。在开发上，添加了自动化构建测试工具，添加了一系列单元测试；在功能上，移除了原先所有的 `group` 组件，重定义并完善 `group` 组件，在此系列代码基础上，后续完成了 **RM2023 版整车状态估计** ；在使用上，顶层模块与视觉库完全分离，由用户自行实现，进一步降低了依赖关系，此外还加入了更加规范且方便的编译安装方式。
-- **4.x** —— 未发布，但于 2023 年登陆 [Github](https://github.com) 平台<span style="color: green">（已开源）</span>，更名为 RMVL，并发布 RMVL **1.x** 系列版本，该系列彻底形成了面向对象迭代器设计模式与责任链设计模式相互结合的代码架构。4.x 版本在设计之初主要为了简化数据组件的开发，移除了不属于 @ref data_components 管理的，但在 @ref function_modules 中被设置的信息。此外还为各个 @ref function_modules 加入了 `XxxInfo` 的信息类。该版本首次加入命名空间 `rm`，并且极大程度简化并统一了参数模块的定义方式。
+- **1.x** —— *2021.10* 发布<span style="color: green">（未开源）</span>，主要针对 RoboMaster 2021 赛季步兵、英雄代码混乱的情况进行设计，初步尝试了使用抽象工厂设计模式来设计代码架构，届时，SRVL 开发者和使用者的不同需求需要在 SRVL 编译过程中修改编译选项。
+- **2.x** —— *2022.01* 发布<span style="color: green">（未开源）</span>，使用抽象工厂设计模式后出现了维护困难的情况，包括但不限于多个 @ref function_modules 共同组合，导致产生非常多的派生工厂，此版本针对这一弊端移除了原先所有的设计模式，各功能模块仅单独存在，不再另外设置组合或其他强依赖关系。此外， **2.x** 相较于 **1.x** 添加了全新的内容： @ref group 。
+- **3.x** —— *2022.08* 发布<span style="color: green">（未开源）</span>，架构、功能进一步完善。在开发上，添加了 CI-CD 自动化构建测试工具，使用 GoogleTest 为已有的组件、模块添加了单元测试，使用 benchmark 为部分功能添加了性能基准测试；在功能上，移除原先所有的 `group` 组件，重定义并完善了 `group` 组件所应当具备的功能，后续在此系列代码基础上，完成了 **RM2023 版整车状态估计** ；在使用上，顶层模块与视觉库完全分离，涉及到各个功能开启或关闭的逻辑功能将设置在顶层模块，这一部分内容由用户自行实现。此外，该版本完善了 CMake 的项目构建方式，并且可通过 `make install/uninstall` 完成编译安装、卸载。
+- **4.x** —— *2023.09* 发布<span style="color: green">（已开源）</span>，并登陆 [Github](https://github.com) 平台，更名为 RMVL，并发布 RMVL **1.x** 系列版本，该系列彻底形成了面向对象迭代器设计模式与责任链设计模式相互结合的代码架构。 **4.x** 版本在设计之初主要为了简化数据组件的开发，移除了不属于 @ref data_components 管理的，但在 @ref function_modules 中被设置的信息。此外还为各个 @ref function_modules 加入了 `XxxInfo` 的信息类。该版本首次加入命名空间 `rm`，避免了与其他库命名冲突的情况。此外，该版本极大程度简化并统一了参数模块的定义方式，将原先繁琐的参数定义、加载的功能使用自定义的参数文件 `*.para` 以及一组 CMake 函数 `rmvl_generate_para` 自动完成 C++ 代码生成与文档注解生成，为了更进一步简化参数模块的设计，RMVL 提供了 Visual Studio Code 的插件，为 `*.para` 文件提供语法高亮、代码提示、悬浮提示与代码块，并为 RMVL 中的部分函数与宏提供了代码提示、悬浮提示与代码块。
 
 #### 使用对象与基本情况
 
-RMVL 为硬件设备的二次开发、网络通信、串口通信以及运动、控制、视觉算法提供了相应的支持库，为工业、日常环境下某些特征的识别、追踪等提供了完整的流程，同时也可为 RoboMaster 参赛者提供有关装甲板识别与运动追踪、能量机关识别与运动追踪等自动瞄准的完整内容，具体可提供的内容如下
+RMVL 为硬件设备二次开发、网络通信、串口通信以及运动、控制、视觉算法提供了相应的支持库，为工业、日常环境下某些特征的识别、追踪等提供了完整的流程，同时也可为 RoboMaster 参赛者提供有关装甲板识别与运动追踪、能量机关识别与运动追踪等自动瞄准的完整内容，具体可提供的内容如下
 
 - 机器人在一些经典的、特有的工作环境下的功能需求，涉及到运动追踪、视觉识别等内容
 - 控制、通信、数据结构的基础工具库
@@ -33,7 +33,7 @@ RMVL 具有模块化结构，这意味着该软件包包含了多个共享或静
 
 - @ref core (**core**) —— 包含主要的工具库、数据读写、宏定义、版本管理等内容，以及 rm::Exception 异常管理模块就在此处定义。
 
-- @ref camera (**camera**) —— 目前包含 3 种相机厂商 SDK 的二次开发工具库，，具体可参考下表。
+- @ref camera (**camera**) —— 目前包含 3 种相机厂商 SDK 的二次开发工具库，具体可参考下表。
   |         厂商          | 简称 |
   | :-------------------: | :--: |
   |    奥普特机器视觉     | OPT  |
@@ -54,7 +54,7 @@ RMVL 具有模块化结构，这意味着该软件包包含了多个共享或静
 
 - @ref combo (**combo**) —— 这种类型的组件由一系列特征组成，并使用 `std::vector<feature::ptr>` 来存储它们，特征的数量通常不会太多，并且这类特征在物理空间中通常是刚性的，即特征之间大致具备尺度不变的特点。开发中，一般会使用若干特征以及附带信息用于构造 `combo` 的派生对象。此外 RMVL 提供了默认 `combo`，即 rm::DefaultCombo ，用于表示单独的无关联的 `feature`。
 
-- @ref tracker (**tracker**) —— `tracker` 是在时间上包含了许多相同物理特性的 `combo`，从而形成一个 `combo` 的时间序列，在 RMVL 中，则通过使用 `std::deque<combo::ptr>` 来表示这个时间序列。在功能上，`tracker` 不仅表示了不同时间下相同的 `combo` 的相关信息，还能处理在某个时间点上获取到不正确的 `combo` 的异常情况。此外 RMVL 提供了默认 `tracker`，即 rm::DefaultFeature ，用于表示无需时间序列信息的 `combo`。
+- @ref tracker (**tracker**) —— `tracker` 是在时间上包含了许多相同物理特性的 `combo`，从而形成一个 `combo` 的时间序列，在 RMVL 中，则通过使用 `std::deque<combo::ptr>` 来表示这个时间序列。在功能上，`tracker` 不仅表示了不同时间下相同的 `combo` 的相关信息，还能处理在某个时间点上获取到不正确的 `combo` 的异常情况。此外 RMVL 提供了默认 `tracker`，即 rm::DefaultTracker ，用于表示无需时间序列信息的一组 `combo`。
 
 - @ref group (**group**) —— 如果多个追踪器在物理空间上具有一定的相关性，比如共享轴旋转、刚性连接等属性，它们可以一起形成一个序列组 `group`，从而能够表示更加高级的物理信息。序列组使用 `std::vector<tracker::ptr>` 来存储这些追踪器。此外 RMVL 提供了默认 `group`，即 rm::DefaultGroup ，用于表示若干无相关性的一组 `tracker`，即退化成了 `std::vector<tracker::ptr>`。
 
@@ -66,9 +66,9 @@ RMVL 具有模块化结构，这意味着该软件包包含了多个共享或静
   </center>
   识别得到的各种图像以及提取到的特征和组合体均保存至识别模块信息 `rm::DetectInfo` 中。
 
-- @ref compensator (**compensator**) —— 补偿器通常是功能模块中的第一个用于修正数据组件的算法模块，<span style="color: green">主要在涉及到 RM 的赛事中使用</span>。补偿器主要负责修正弹道下坠的影响。计算得到的子弹飞行时间 `tof` 以及补偿增量 `compensation` 均保存至补偿模块信息 `rm::CompensateInfo` 中。
+- @ref compensator (**compensator**) —— 补偿器通常是功能模块中的第一个用于修正数据组件的算法模块，<span style="color: green">主要在 RoboMaster 赛事中使用</span>。补偿器主要负责修正弹道下坠的影响。计算得到的子弹飞行时间 `tof` 以及补偿增量 `compensation` 均保存至补偿模块信息 `rm::CompensateInfo` 中。
 
-- @ref predictor (**predictor**) —— 对于需要考虑目标追踪的机器人而言，必须要引入目标预测环节，使得伺服机构能够恒定追踪、捕获目标，<span style="color: green">在 RM 赛事中一般用于保证弹丸能够准确击中敌方目标</span>。一般而言，每一个预测模块会针对特定的数据组件（派生的 `group` 对象）进行 `Kt`、`B`、`Bs` 3 种预测量类型的计算，每种预测量类型都包含 9 种预测对象，每个预测对象之间对于 3 种预测量来说都是线性关系，例如在 @ref gyro_predictor 中对于 `ANG_Y` 预测对象的 3 种预测量都是单独计算的，这也便于后续的 **决策模块** 能够自由组合这些预测量。同样，计算得到的各类预测量均被保存至预测模块信息 `rm::PredictInfo` 中。
+- @ref predictor (**predictor**) —— 对于需要考虑目标追踪或存在较长通讯延迟的机器人而言，必须要引入目标预测环节，使得伺服机构能够恒定追踪、捕获目标，<span style="color: green">在 RoboMaster 赛事中一般用于保证弹丸能够准确击中敌方目标</span>。一般而言，每一个预测模块会针对特定的数据组件（派生的 `group` 对象）进行 2~3 种预测量类型的计算，包括动态响应预测量 `Kt`、静态响应预测量 `B`、射击延迟预测量 `Bs`，每种预测量类型都包含 9 种预测对象，每个预测对象之间对于 3 种预测量类型来说都是线性关系，例如在 @ref gyro_predictor 中对于 `ANG_Y` 预测对象的 3 种预测量都是单独计算的，这也便于后续的 **决策模块** 能够自由组合这些预测量。同样，计算得到的各类预测量均被保存至预测模块信息 `rm::PredictInfo` 中。
 
 - @ref decider (**decider**) —— 在经过识别、补偿和预测 3 个步骤后，需要使用特定的策略来获得当前时刻的最优目标，结合前三个步骤的信息（包含识别模块信息 `DetectInfo` 、补偿模块信息 `CompensateInfo` 、预测模块信息 `PredictInfo` ）导出到决策模块信息 `rm::DecideInfo` 中。
 
@@ -102,7 +102,7 @@ for (auto &p_detector : detectors)
 
 #### 低耦合逻辑 {#intro_low_coupled_logic}
 
-RMVL 的 **extra** 模块中的各个功能模块之间的耦合度非常低，它们不会相互影响或依赖。例如，自动瞄准的功能可以通过以下代码实现，它们之间共享的数据组件是对象是一个序列组列表：`groups`。
+RMVL 的 **extra** 模块中的各个功能模块之间的耦合度非常低，它们在代码上不会设置强依赖关系。例如，自动瞄准的功能可以通过以下代码实现，它们之间共享的数据组件是一个序列组列表：`groups`。
 
 ```cpp
 #include <rmvl/detector.hpp>

diff --git a/doc/root.markdown.in b/doc/root.markdown.in
@@ -13,4 +13,4 @@ RMVL 说明文档 {#mainpage}
 - @ref citelist
 @refs_modules@
 @refs_extra@
-- @ref para
+- Parameter modules. @ref para
diff --git a/doc/tutorials/extra/upper/upper_init.md b/doc/tutorials/extra/upper/upper_init.md
@@ -33,7 +33,7 @@
 @add_checkbox_y
 数据链路层
 @end_checkbox
-@add_checkbox_n
+@add_checkbox_y
 运输层/应用层
 @end_checkbox
 
@@ -140,8 +140,7 @@ int main()
 
 @add_toggle{运输层/应用层}
 
-@todo
-本小节暂无
+目前基于运输层的设备属于 Ethernet 设备，目前有支持 OPC UA 通信协议的 @ref opcua ，可以查阅对应的说明文档 @ref tutorial_modules_opcua 。
 
 @end_toggle
 

diff --git a/doc/tutorials/introduction/linux/install.md b/doc/tutorials/introduction/linux/install.md
@@ -91,7 +91,7 @@ make -j8 && sudo make install
 sudo apt install libeigen3-dev
 ```
 
-#### 1.3 硬件设备 SDK
+#### 1.3 硬件设备 SDK{#install_hardware_sdk}
 
 <table class="markdownTable">
 <tr class="markdownTableHead">
@@ -128,7 +128,7 @@ sudo apt install libeigen3-dev
 </table>
 @note 以上与相机相关的 SDK 在进行二次封装得到的库都需要链接到 OpenCV。
 
-#### 1.4 onnxruntime
+#### 1.4 onnxruntime{#install_onnxruntime}
 
 onnxruntime 库是目前数字识别所依赖的第三方库，如果有需要开启此功能，则需要安装 onnxruntime
 
@@ -151,6 +151,8 @@ onnxruntime 库是目前数字识别所依赖的第三方库，如果有需要
   rm -r onnxruntime-linux-x64-1.12.0 && rm onnxruntime-linux-x64-1.12.0.tgz
   ```
 
+至此 onnxruntime 安装完成。
+
 ### 2. 配置 RMVL 项目
 
 进入编译空间，没有 `build` 文件夹请先创建

diff --git a/doc/tutorials/introduction/linux/use.md b/doc/tutorials/introduction/linux/use.md
@@ -12,7 +12,8 @@
 
 **注意**
 
-<span style="color: red">必须确保您已经成功安装了 RMVL</span>。如果你不熟悉 CMake，请移步到 CMake [教程](https://cmake.org/cmake/help/latest) 
+- <span style="color: red">必须确保您已经成功安装了 RMVL</span>。如果你不熟悉 CMake，请移步到 CMake [教程](https://cmake.org/cmake/help/latest) 
+- 本示例使用到了 rm::ArmorDetector 模块，需要提前安装 onnxruntime 的 C++ 开发包，可参考 @ref install_onnxruntime 的内容，若未安装，请安装后再重新编译 RMVL。
 
 ### 详细步骤