# ext2-BoosterPose

**Repository Path**: liaoyoupeng/ext2-booster-pose

## Basic Information

- **Project Name**: ext2-BoosterPose
- **Description**: 这里是Booster K1 机器人使用MIND+姿势识别模型
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-10
- **Last Updated**: 2026-09-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Booster 姿势识别（BoosterPose）

`BoosterPose` 是一个适用于 Mind+ V2 **Python 积木模式**的扩展，面向 **Booster K1 机器人**的人体姿势识别。
该扩展基于 **TensorFlow PoseNet + 自定义分类头（两层全连接）**，支持 **实时识别人体姿势、读取识别结果与置信度、姿势变化事件触发** 等功能，用法与 AI 图像分类一致，可用于体感交互、动作检测、教学演示等场景。

> 本扩展推理运行于 **Booster K1 机器人**的 ROS2 环境，底层自动生成 Python 并在机器人上执行。

## 一、扩展概述

| 项目 | 内容 |
| --- | --- |
| 扩展 ID | `BoosterPose` |
| 中文名 | Booster 姿势识别 |
| 英文名 | Booster Pose Recognition |
| 版本 | 0.0.1 |
| 模式 | `python-block`（Python 积木模式） |
| 适用平台 | Windows / macOS / Linux（Mind+ 端）；实际推理运行于 **Booster K1 机器人** |
| 核心能力 | 通过摄像头实时识别人体姿势（如「端坐 / 低头 / 举手」等） |
| 技术栈 | TensorFlow PoseNet 特征提取（特征维度 14739） + 自定义分类头 + ROS2 图像订阅 |

## 二、工作原理

1. **初始化**：加载两个模型
   - **PoseNet**（通用姿态模型，提取 heatmap + offsets 特征）
   - **分类头**（你的训练产物：`model.json` + `metadata.json` + `weights.bin`，含标签列表）
2. **订阅摄像头**：通过 ROS2 订阅机器人头部彩色图像话题（默认 `/boostercamera/head/rgb`），每收到一帧就做推理。
3. **推理**：图像预处理（BGR→RGB、缩放到 257×257、归一化）→ PoseNet 提取特征 → 全连接分类头输出各类概率 → 取最高概率。
4. **判定**：最高概率 ≥ 阈值（默认 0.8）且标签与上一次不同，则记为「姿势发生变化」事件，并保存当前结果与置信度。
5. **读取**：主程序通过「姿势识别结果 / 置信度 / 是否变化」等积木取用结果。

> 默认开启**镜像翻转**（`_pose_mirror = True`），即像照镜子一样，你的左手在画面左侧，符合直觉。

## 三、运行环境与依赖

扩展运行于 **Booster K1 机器人**的 ROS2 环境，生成的 Python 会自动追加以下系统路径并依赖：

- Python 包：`tensorflow`（tf.compat.v1）、`opencv-python`(cv2)、`numpy`、`rclpy`、`sensor_msgs`、`cv_bridge`、`protobuf`
  - 其中 `tensorflow` / `opencv-python` / `numpy` / `protobuf` 已在 `extension/public/requirements.txt` 声明；
  - `rclpy` / `sensor_msgs` / `cv_bridge` 为 ROS2(Humble) 系统包，由机器人系统环境提供（生成代码已通过 `sys.path` 追加对应路径，无需 pip 安装）。
- 系统路径：`/usr/lib/python3/dist-packages`、`/opt/ros/humble/...`、`/opt/booster/BoosterRos2`
- 环境变量：`FASTRTPS_DEFAULT_PROFILES_FILE`（已自动设置）

## 四、积木说明

| 积木 | 类型 | 函数 | 说明 |
| --- | --- | --- | --- |
| `初始化姿势识别模型 路径:[PATH]` | 命令 | `initPoseModel` | 加载 PoseNet 与分类头模型 |
| `启动姿势识别订阅 话题:[TOPIC] 阈值:[THRESH]` | 命令 | `startPoseSubscriber` | 订阅摄像头并启动后台推理线程 |
| `姿势识别结果` | 报告 | `getPoseLabel` | 返回当前姿势标签（未识别时为 `None`） |
| `姿势识别置信度` | 报告 | `getPoseConfidence` | 返回当前置信度（0~1 浮点） |
| `识别到姿势 [CLASS]？` | 布尔 | `isPose` | 判断当前是否等于指定姿势 |
| `姿势发生变化？` | 布尔 | `poseChanged` | 事件型：检测到新姿势时为真一次 |
| `停止姿势识别订阅` | 命令 | `stopPoseSubscriber` | 停止订阅与推理线程 |

### 4.1 初始化姿势识别模型 路径:[PATH]

- **参数**：`PATH`（字符串）模型目录绝对路径，默认 `/home/booster/Workspace/mind+vison/my_pose`（相对路径会基于脚本目录解析）。
- **作用**：读取模型目录，加载 PoseNet 与分类头，打印标签列表。
- **注意**：模型目录必须包含 `model.json`、`metadata.json`、`weights.bin`（或 `model.weights.bin`）以及可用的 `posenet/`（详见第七节）。**必须先执行本积木，再执行「启动订阅」**。

### 4.2 启动姿势识别订阅 话题:[TOPIC] 阈值:[THRESH]

- **参数**：
  - `TOPIC`（字符串）ROS2 图像话题，默认 `/boostercamera/head/rgb`。
  - `THRESH`（数字）置信度阈值，默认 `0.8`（建议 `0.9`，越严格越不易误报）。
- **作用**：创建 ROS2 节点与订阅，开启后台守护线程持续推理。
- **注意**：同一节点只创建一次；重复调用不会叠加订阅。

### 4.3 姿势识别结果（报告）

返回当前姿势标签字符串（如 `"端坐"`）；尚未识别到任何有效姿势前返回 `None`。读取的是「最近一次有效识别结果」，低置信度帧不会把它覆盖成 `None`（已修复误报，见第八节）。

### 4.4 姿势识别置信度（报告）

返回最近一次有效识别的置信度（0~1 浮点，如 `0.93`），用于显示、记录或更细判断。

### 4.5 识别到姿势 [CLASS]？（布尔）

- **参数**：`CLASS`（字符串）默认 `"端坐"`。
- 返回 `True` 当且仅当当前姿势标签等于 `CLASS`，用于持续状态判断（如端坐检测、举手检测）。

### 4.6 姿势发生变化？（布尔）★ 事件积木

- 检测到**新姿势**（与上一次不同且置信度达标）时返回 `True` 一次，读取后自动复位，下次再读为 `False`，直到出现下一个新姿势。
- 用于触发一次性动作（语音播报、拍照、计数等）。
- **⚠ 双重消费陷阱**：本积木是「消费型」——一旦读到 `True` 即清空事件。请勿在同一循环轮次里重复读取（例如既接到「如果」又接到「打印」），否则第二次读到的是 `False`。应只读取一次并存入变量。

推荐写法：

```
如果 ( 姿势发生变化？ ) 那么
    设置 my_var 为 姿势识别结果
    打印 ( "这是" + my_var + 姿势识别置信度 )
    语音合成 ( "这是" + my_var )
    等待 5 秒
```

### 4.7 停止姿势识别订阅（命令）

设置停止标志、销毁订阅对象、后台线程退出。用于程序结束释放资源，或切换模型/话题前调用。

## 五、示例程序

### 方式 A：事件触发（推荐，用于语音播报/计数）

```
初始化姿势识别模型 路径: /home/booster/Workspace/mind+vison/my_pose
启动姿势识别订阅 话题: /boostercamera/head/rgb  阈值: 0.9

循环 永远 执行：
    如果 ( 姿势发生变化？ ) 那么
        设置 my_var 为 姿势识别结果
        打印 ( "这是" + my_var + 姿势识别置信度 )
        语音合成 ( "这是" + my_var )
        等待 5 秒
```

### 方式 B：持续状态判断（用于实时控制）

```
循环 永远 执行：
    如果 ( 识别到姿势 "举手"？ ) 那么
        前进
    否则 如果 ( 识别到姿势 "低头"？ ) 那么
        停止
```

## 六、可调参数（全局变量，默认已在扩展内设置）

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `_pose_conf_threshold` | `0.8`（被「启动订阅」阈值参数覆盖） | 识别置信度阈值 |
| `_pose_recognize_interval` | `0.5` | 最小推理间隔（秒），限制帧率避免过载 |
| `_pose_mirror` | `True` | 是否镜像翻转图像 |
| `_pose_input_resolution` | `257` | PoseNet 输入分辨率 |
| `_pose_feature_dim` | `14739` | 特征维度 |

如需修改，可在生成的 Python 中调整对应变量（高级用法）。

## 七、PoseNet 模型部署说明（重要）

`posenet/` 通用模型随扩展提供，位于 `extension/public/posenet/`（含 `group1-shard1of2.bin`、`group1-shard2of2.bin`、`model-stride16.json`）。`extension/public/` 在构建时会**原样打包进产物目录**。

程序运行时按以下顺序查找 PoseNet（见 `func.js` 的 `_pose_find_posenet`）：

1. 模型目录下的 `posenet/`（即你传给「初始化模型」的 `PATH/posenet`）；
2. `get_asset_path_by_name("posenet")` —— 通过扩展资源路径 API 定位打包的 posenet；
3. `get_asset_path_by_name("posenet/model-stride16.json")` 的目录；
4. `/home/booster/mindplus/.lib/thirdExtension/*/posenet`；
5. `/home/booster/extensions/BoosterPose/posenet`。

> **说明**：Python 代码实际运行在机器人（`/home/booster/...`）上。若 Mind+ 未把 `public/` 资源自动同步到机器人，`get_asset_path_by_name` 可能解析到 PC 路径而不可达，此时会落到第 4/5 项兜底。最稳妥的做法是把 `posenet/` 预置到机器人上的兜底路径之一（推荐 `/home/booster/extensions/BoosterPose/posenet`），无论是否自动推送都能加载。

## 八、已知问题与修复

### 「这是 None 0.59…」误报

- **现象**：日志中出现 `这是None0.594...`，即把低置信度帧（如 0.59 < 阈值）误报为姿势。
- **根因**：低置信度帧本应被忽略（标签为 `None`），但旧逻辑会无条件把 `_pose_result` 覆盖成 `{label: None}`。
- **修复（已应用）**：将 `_pose_result` 赋值与「姿势变化」事件置位都缩进进 `if new_label is not None:`，`_pose_result` 永远停在最近一次**有效**识别上。

### `type object has no attribute '_TYPE_SUPPORT'`（ROS2 消息类型被覆盖）

- **现象**：模型加载成功，但在 `create_subscription(Image, ...)` 处崩溃，报 `'pybind11_type' has no attribute '_TYPE_SUPPORT'`。
- **根因**：`booster_robotics_sdk_python` 的 `import *` 导出了同名 `Image` 类，覆盖了 `sensor_msgs.msg.Image`，导致 rclpy 收到未注册类型。
- **修复（已应用）**：改用 `from sensor_msgs.msg import Image as PoseImage`，订阅处使用 `PoseImage`，别名不会被 SDK 覆盖。

## 九、支持列表

| 运行环境 | 支持 | 备注 |
| --- | --- | --- |
| Booster K1 机器人 | ✅ | 需摄像头与 ROS2 环境；模型目录含 `model.json`/`metadata.json`/`weights.bin` |
| 个人电脑（Python 运行时） | — | 依赖机器人摄像头硬件，纯 PC 无法运行 |

## 十、更新日志

### V0.0.1


- 支持模型初始化、姿势识别订阅、结果/置信度读取、姿势判断与变化事件
- 修复 ROS2 `Image` 类型冲突与低置信度误报问题
- 自带 `posenet/` 通用模型，并支持多路径兜底查找

## 十一、开发指南

更详细的 Mind+ V2 扩展开发说明请参考：[Mind+官方扩展开发文档](https://mindplus.dfrobot.com.cn/mp2/Extensions/)