HarmonyOS 6.1 全栈实战录 - 03 动力捕获：AR Engine 人体骨骼点识别与体感交互引擎深度实战

HarmonyOS 6.1 AR人体骨骼识别技术解析与实战本文深入探讨了HarmonyOS 6.1 AR Engine中人体骨骼识别的核心技术。系统通过深度学习模型实现20个关键骨骼点的实时跟踪，覆盖头部、躯干和四肢，构建完整的运动学拓扑结构。文章详细解析了ARType.BODY会话配置、坐标映射转换等核心API，并提供了Native层高性能接口的深度优化建议。最后通过"体感深蹲计数器

轻口味

3030人浏览 · 2026-05-07 07:50:39

轻口味 · 2026-05-07 07:50:39 发布

HarmonyOS 6.1 全栈实战录 - 03 动力捕获：AR Engine 人体骨骼点识别与体感交互引擎深度实战

引言

HarmonyOS 6.1 全栈系列更新到了第三篇，回顾下前面两篇：

01 篇：深入探索了 HDS (Harmony Design System) 下的“光感”交互引擎，实现了沉浸式视效的物理表达。
02 篇：攻克了 AR Engine 人脸微表情感知，实现了 64 维 Blend Shapes 的高精度数字镜像。

本篇目标我们解锁 AR Engine 的“人体感知”版图，深入拆解 20 个骨骼关键点 的识别与跟踪机制。我们将从 ArkTS 声明式绘制到 Native 高性能数据流，全方位构建一套企业级的体感交互引擎，并实战开发一个“体感健身计数器”。骨骼识别和追踪也是HarmonyOS 6.1新提供的能力：
在这里插入图片描述

一、核心感知模型：20 骨骼点与动力学拓扑

在 HarmonyOS 6.1 的 AR Engine 中，人体跟踪不再仅仅是简单的“轮廓检测”，而是基于深度学习模型的 运动学拓扑重建。系统能够实时识别并输出 20 个关键骨骼点，这构成了体感游戏、虚拟试衣、以及手势指令的核心。而且HarmonyOS 提供的骨骼点识别追踪能力不止支持单人，还支持双人。

1.1 20 骨骼点布局深度解析

AR Engine 识别的 20 个骨骼点覆盖了人体的主要关节，其索引与语义定义严格遵循生物力学标准：

头部与躯干（Core Hub）：
- NOSE (0): 头部定位点。
- NECK (1): 颈部转动支点。
- LEFT_SHOULDER (2) / RIGHT_SHOULDER (5): 肩膀宽度基准。
- LEFT_HIP (8) / RIGHT_HIP (11): 骨盆支撑点。
上肢动力链（Upper Extremities）：
- LEFT_ELBOW (3) -> LEFT_WRIST (4): 左臂运动轨迹。
- RIGHT_ELBOW (6) -> RIGHT_WRIST (7): 右臂运动轨迹。
下肢支撑链（Lower Extremities）：
- LEFT_KNEE (9) -> LEFT_ANKLE (10): 左腿支撑强度。
- RIGHT_KNEE (12) -> RIGHT_ANKLE (13): 右腿支撑强度。
  人体骨骼点示意图如下：

1.2 拓扑链接关系与运动矢量

单纯的点坐标无法构成“人体”，关键在于 Skeleton Connection。

躯干闭环：肩膀 -> 肩膀 -> 胯部 -> 胯部 -> 肩膀，形成稳定的核心躯干矩形。这是判断人体正侧面旋转的关键。
肢体角度计算：通过向量 $BA⃗\vec{BA}$ (大腿) 与 $BC⃗\vec{BC}$ (小腿) 的点积，可以实时计算膝关节张角 $θ=arccos⁡(BA⃗⋅BC⃗∣BA⃗∣∣BC⃗∣)\theta = \arccos(\frac{\vec{BA} \cdot \vec{BC}}{|\vec{BA}||\vec{BC}|})$ ，这是实现健身动作识别（如深蹲、开合跳）的数学基础。

二、架构深度拆解：API 23 的人体感知管线

在 HarmonyOS 6.1 中，人体跟踪的开发范式遵循 Session -> Frame -> Body -> Landmarks 的异步响应式结构。

2.1 会话配置：ARType.BODY 的深度定制

在 API 23 中，开启人体感知需要显式配置 ARType.BODY。值得注意的是，maxDetectedBodyNum 参数决定了 NPU 的负载，单人模式下性能最优。

// 【轻口味 Demo】配置人体跟踪会话
viewContext.config = {
  type: arEngine.ARType.BODY,           // 开启人体感知模式
  maxDetectedBodyNum: 1,                // 设置追踪人数（1或2）
  planeFindingMode: arEngine.ARPlaneFindingMode.DISABLED, // 禁用平面检测以优化功耗
  powerMode: arEngine.ARPowerMode.NORMAL, // 在精度与发热间取得平衡
  focusMode: arEngine.ARFocusMode.AUTO,   // 保持画面锐利
};

2.2 坐标映射与显示矫正

AR Engine 输出的骨骼点坐标 ARBodyLandmark2D 是 归一化坐标 (Normalized Coordinates)，其范围在 $[0, 1]$ 之间。

坐标转换公式： $Xpixel=Xnorm×WidthdisplayX_{pixel} = X_{norm} \times Width_{display}$ ，但必须考虑预览流（通常是 4:3）与 UI 容器（通常是全屏）之间的 Aspect Ratio 适配。
深度建议：使用 RelativeContainer 配合 px2vp 转换函数，确保在不同分辨率（Mate 60 vs MatePad）下骨架线段不发生拉伸变形。

三、 API 参考：ArkTS 与 Native 接口深度解析

为了实现企业级的鲁棒性，开发者必须理解感知管线中每一个核心接口的物理意义。

3.1 ArkTS 核心接口详解

在 ArkTS 侧，HarmonyOS主要通过响应式回调获取结构化数据。

arViewController.ARViewContext：
- init(): 异步初始化方法。它是整个 AR 会话的“总闸”，只有在返回 Promise<void> 成功后，底层的相机流和感知线程才会真正就绪。
- config: 这是一个包含多种模式的配置对象。对于人体跟踪，必须设置 type: arEngine.ARType.BODY。
ARFrame.acquireBodySkeleton()：
- 功能：从当前时间戳的帧数据中提取所有被追踪的人体对象。
- 返回值：arEngine.ARBody[] 数组。如果视野内没人，则返回空数组。
arEngine.ARBody.getLandmarks2D()：
- 语义：返回当前人体对象的 20 个关键点。
- 结构：每个元素包含 x, y (归一化坐标) 和 type (骨骼点类型索引)。

3.2 Native (C++) 关键接口详解

对于高性能需求场景，NDK 提供了更底层的指针级操作。

HMS_AREngine_ARBody_GetSkeletonPointData2D：
- 原型：void HMS_AREngine_ARBody_GetSkeletonPointData2D(const AREngine_ARSession *session, const AREngine_ARBody *arBody, const float **skeletonPoints2D)。
- 深度解析：通过传入一个二级指针，直接获取底层算法输出的原始数据地址。这种 0 拷贝（Zero-Copy） 机制避免了大数据量在 JS 引擎与 C++ 引擎之间的频繁搬运，是实现 120Hz 极速反馈的关键。
HMS_AREngine_ARBody_GetSkeletonConfidence：
- 作用：获取每个骨骼点的置信度。
- 实战意义：在人体发生重叠或部分出屏时，置信度会显著下降。建议设置阈值（如 0.6），低于该值的点应在渲染时置为透明，否则会出现骨架“瞬间飞出”的视觉 Bug。
HMS_AREngine_ARBody_GetSkeletonConnection：
- 功能：获取骨骼点之间的链接关系索引。
- 优势：官方定义的拓扑结构会自动适配不同的人体姿态，开发者无需手动硬编码“肩膀连脖子”这类逻辑，直接遍历链接数组即可绘制完整骨架。
HMS_AREngine_ARConfig_SetBodyDetectedNum：
- 调优策略：在“单人体感”App 中，务必将此值显式设为 1。这能让 NPU 聚焦于单一目标的特征提取，显著提升边缘检测的稳定性并降低发热。

四、项目实战：构建“Harmony Fit”体感深蹲计数器

接下来我们将实现一个具体的案例场景：通过监测人体膝盖张角，自动计算深蹲次数并提供实时视觉反馈。

3.1 核心业务逻辑：动作识别算法

动作识别的核心在于维护一个简单的有限状态机（FSM）：

State 0 (Standing): 膝盖角度 > 160°。
State 1 (Squatting): 膝盖角度 < 100°。
触发条件: 从 State 0 进入 State 1 再回到 State 0，计为一次成功深蹲。

/**
 * @filename SquatCounter.ets
 * 基于 20 骨骼点实现的深蹲计数引擎
 */
class SquatCounter {
  private isSquatting: boolean = false;
  private count: number = 0;
  private thresholdDown: number = 100; // 下蹲判定角度
  private thresholdUp: number = 160;   // 站立判定角度

  // 计算三点构成的夹角（角度制）
  calculateAngle(p1: arEngine.ARBodyLandmark2D, p2: arEngine.ARBodyLandmark2D, p3: arEngine.ARBodyLandmark2D): number {
    const v1 = { x: p1.x - p2.x, y: p1.y - p2.y };
    const v2 = { x: p3.x - p2.x, y: p3.y - p2.y };
    const dotProduct = v1.x * v2.x + v1.y * v2.y;
    const mag1 = Math.sqrt(v1.x * v1.x + v1.y * v1.y);
    const mag2 = Math.sqrt(v2.x * v2.x + v2.y * v2.y);
    const angle = Math.acos(dotProduct / (mag1 * mag2)) * (180 / Math.PI);
    return angle;
  }

  process(landmarks: Map<arEngine.ARBodyLandmarkType, arEngine.ARBodyLandmark2D>): number {
    if (landmarks.has(arEngine.ARBodyLandmarkType.LEFT_HIP) && 
        landmarks.has(arEngine.ARBodyLandmarkType.LEFT_KNEE) && 
        landmarks.has(arEngine.ARBodyLandmarkType.LEFT_ANKLE)) {
      
      const kneeAngle = this.calculateAngle(
        landmarks.get(arEngine.ARBodyLandmarkType.LEFT_HIP)!,
        landmarks.get(arEngine.ARBodyLandmarkType.LEFT_KNEE)!,
        landmarks.get(arEngine.ARBodyLandmarkType.LEFT_ANKLE)!
      );

      // 状态机切换逻辑
      if (!this.isSquatting && kneeAngle < this.thresholdDown) {
        this.isSquatting = true;
        console.info('[轻口味 Demo]', '检测到下蹲动作');
      } else if (this.isSquatting && kneeAngle > this.thresholdUp) {
        this.isSquatting = false;
        this.count++;
        console.info('[轻口味 Demo]', `深蹲完成！当前次数: ${this.count}`);
      }
    }
    return this.count;
  }
}

3.2 界面实现：响应式骨架与实时计数

利用 Shape 渲染器实现高性能的骨架跟随效果。

@Component
struct ARBodyMirror {
  @State bodyInfos: BodyInfo[] = [];
  @State squatCount: number = 0;
  private counter: SquatCounter = new SquatCounter();

  // 帧更新回调：数据驱动渲染
  private onFrameUpdate(bodies: arEngine.ARBody[]) {
    this.bodyInfos = bodies.map(b => {
      const landmarks = b.getLandmarks2D();
      const map = arLandmarksToMap(landmarks);
      // 更新计数逻辑
      this.squatCount = this.counter.process(map);
      return { trackId: b.trackId, landmarks: landmarks };
    });
  }

  build() {
    Stack() {
      // 1. AR 底座
      ARView({ context: this.arContext }).width('100%').height('100%')

      // 2. 矢量骨架层
      Shape() {
        ForEach(this.bodyInfos, (info: BodyInfo) => {
          this.drawBones(arLandmarksToMap(info.landmarks))
        })
      }.width('100%').height('100%')

      // 3. 计数看板
      Column() {
        Text(`今日深蹲: ${this.squatCount}`)
          .fontSize(48)
          .fontColor(Color.White)
          .fontWeight(FontWeight.Bold)
          .textShadow({ radius: 10, color: Color.Black })
        Text('请保持全身在相机视野内')
          .fontSize(16)
          .fontColor('#CCFFFFFF')
      }
      .margin({ top: 100 })
    }
  }
}

3.3 运行效果

示例中如果没有识别到人体则红色提醒“未检测到人体”：
在这里插入图片描述

识别到人体或动作后进行正常的深蹲计数，并且顶部绿色框标识“追踪中”：
在这里插入图片描述

五、 Native 进阶：性能瓶颈与 NDK 优化

在 120Hz 刷新率的旗舰机型上，ArkTS 层的数据同步可能会成为瓶颈。

4.1 0 拷贝数据访问

使用 HMS_AREngine_ARBody_GetSkeletonPointData2D 接口可以绕过 JS 序列化开销，直接在 Native 层进行动作识别计算。

// Native 层高性能处理
const float *skeletonPoints2D = nullptr;
HMS_AREngine_ARBody_GetSkeletonPointData2D(arSession, arBody, &skeletonPoints2D);

// 获取置信度：过滤遮挡产生的抖动点
const float *confidences = nullptr;
HMS_AREngine_ARBody_GetSkeletonConfidence(arSession, arBody, &confidences);

for (int j = 0; j < 20; j++) {
    if (confidences[j] < 0.6) continue; // 剔除不可信的点
    // ... 执行 Native 向量计算
}