想做一个 AR 应用？先搞懂 AR Engine 的基本能力

你有没有玩过那种"把虚拟家具放到真实房间里"的 APP？或者那种"对着杂志封面弹出 3D 动画"的效果？这些都叫 AR——增强现实（Augmented Reality），就是在真实世界的画面上叠加虚拟内容。

在 HarmonyOS 里，AR 能力由 AR Engine 提供。今天我们来看看它的基本用法：怎么初始化 AR 会话、怎么做平面识别、怎么管理 AR 场景。

下面是 AR 应用的完整生命周期流程：

AR Engine 能做什么？

AR Engine 提供了多种 AR 特性，通过 ARFeatureType 枚举来选择：

特性	说明	典型用途
SLAM	运动跟踪 + 平面识别	把虚拟物体放在地上
DEPTH	深度估计	判断物体远近
MESH	环境 Mesh 识别	重建 3D 空间结构
IMAGE	图像跟踪	对着图片弹出 3D 内容
SEMANTIC_DENSE	高精几何重建	精确的 3D 建模
SEMANTIC	平面及物体语义	识别地面、墙面、天花板
FACE	人脸识别与跟踪	AR 贴纸、换脸
BODY	人体骨骼点识别	体感游戏、动作捕捉

今天我们重点讲最基础也最常用的：SLAM（运动跟踪 + 平面识别）。

权限要求

AR Engine 需要三个权限：

• ohos.permission.CAMERA：相机权限（AR 需要摄像头画面）
• ohos.permission.GYROSCOPE：陀螺仪权限（感知手机朝向）
• ohos.permission.ACCELEROMETER：加速度计权限（感知手机移动）

记得在 module.json5 里声明这些权限。

初始化 AR 场景

AR Engine 的使用流程是：创建 ARViewContext → 初始化 → 使用 → 暂停/恢复 → 销毁。

import { arViewController } from '@kit.AREngine';
import { BusinessError } from '@kit.BasicServicesKit';

// 创建 ARView 上下文
let context: arViewController.ARViewContext = new arViewController.ARViewContext();

// 初始化（异步操作）
await context.init();

init() 会做这些事情：

1. 初始化 AR 会话（Session）
2. 设置 AR 渲染场景
3. 打开相机
4. 开始运动跟踪

如果初始化失败，会抛出错误码。常见的错误：

• 201：权限未授予
• 801：设备不兼容（不是所有设备都支持 AR）
• 1009200010：相机不可用（可能被其他 APP 占用了）
• 1009200007：配置不支持

检查设备是否支持 AR

在初始化之前，建议先检查设备是否支持：

let supported = arViewController.isARTypeSupported(arEngine.ARFeatureType.ARENGINE_FEATURE_TYPE_SLAM);
if (!supported) {
  console.info('This device does not support AR SLAM');
  return;
}

暂停和恢复

AR 应用在切到后台时，应该暂停相机跟踪和场景渲染，节省资源：

// 暂停
context.pause();

// 恢复
context.resume();

一般在页面的 onPageHide 生命周期里调用 pause()，在 onPageShow 里调用 resume()。

销毁

退出 AR 页面时，记得销毁上下文，释放资源：

await context.destroy();

这会销毁 AR 会话和渲染场景，关闭相机。如果不销毁，相机可能会一直被占用，其他 APP 就用不了相机了。

ARView 组件

AR Engine 提供了一个 ARView 组件，用来显示 AR 画面。你可以在 ArkUI 页面里直接使用：

import { arEngine, arViewController } from '@kit.AREngine';

@Entry
@Component
struct ARPage {
  private context: arViewController.ARViewContext = new arViewController.ARViewContext();

  async aboutToAppear() {
    await this.context.init();
  }

  aboutToDisappear() {
    this.context.destroy();
  }

  build() {
    Column() {
      arEngine.ARView({ arViewContext: this.context })
        .width('100%')
        .height('100%')
    }
  }
}

ARView 组件会显示相机的实时画面，并在上面叠加 AR 内容。

SLAM：运动跟踪 + 平面识别

SLAM（Simultaneous Localization and Mapping，即时定位与地图构建）是 AR 的核心技术。下面是 SLAM 的工作流程：

SLAM（Simultaneous Localization and Mapping，即时定位与地图构建）是 AR 的核心技术。它做的事情是：

1. 运动跟踪：通过摄像头画面和传感器数据，实时计算手机在 3D 空间中的位置和朝向。
2. 平面识别：分析摄像头画面，找到现实世界中的水平面（比如地面、桌面）和垂直面（比如墙壁）。

有了平面识别，你就可以把虚拟物体"放"在真实的平面上。比如用户对准地面，APP 识别出这是一个水平面，然后用户点击屏幕，就在那个位置放一个虚拟的椅子。

图像跟踪（IMAGE 特性）

图像跟踪是另一个常用功能——让 AR Engine 识别特定的图片，然后在图片上方叠加 3D 内容。

添加参考图片

首先，你需要告诉 AR Engine “要跟踪哪些图片”：

// 添加图片到跟踪列表
// AR Engine 最多支持 50 张参考图片

图片的质量会影响识别效果。AR Engine 会从三个维度评价图片质量：

宽高比（越接近 1:1 越好）：

• 1.0-1.5：Excellent
• 1.5-2.0：Good
• 2.0-2.5：Fit
• 2.5+：不推荐

分辨率（以 640x480 为基准）：

• 0.9+：Excellent
• 0.7-0.9：Good
• 0.45-0.7：Fit
• 0.35-0.45：Unfit
• 0.2 以下：不推荐

图像内容：

• 颜色单一的图片（比如纯色）识别效果差
• 有丰富纹理和细节的图片识别效果好
• 有反光、光斑的图片可能识别失败

添加模式

// NORMAL 模式：超过 50 张就报错
// UPDATE 模式：超过 50 张自动删除最旧的

人脸相关能力

AR Engine 还提供了丰富的人脸相关能力：

人脸关键点（LandmarkType）：

• 左眼、右眼
• 鼻尖
• 嘴巴左侧、右侧
• 人脸中心

微表情（ARBlendShapeType）：

• 闭左眼/闭右眼
• 瞪大眼
• 嘴巴张开/闭合
• 微笑/皱眉
• 等等……

这些能力可以用来做 AR 贴纸——比如给用户脸上加一个猫耳朵，或者根据嘴巴张合来触发动画。

完整示例：一个基础 AR 页面

import { arEngine, arViewController } from '@kit.AREngine';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct ARPage {
  private context: arViewController.ARViewContext = new arViewController.ARViewContext();
  @State initStatus: string = '初始化中...';

  async aboutToAppear() {
    // 检查设备是否支持
    let supported = arViewController.isARTypeSupported(
      arEngine.ARFeatureType.ARENGINE_FEATURE_TYPE_SLAM
    );
    if (!supported) {
      this.initStatus = '设备不支持 AR';
      return;
    }

    try {
      await this.context.init();
      this.initStatus = 'AR 初始化成功';
    } catch (err) {
      let error = err as BusinessError;
      this.initStatus = `初始化失败: ${error.code} - ${error.message}`;
    }
  }

  aboutToDisappear() {
    this.context.destroy();
  }

  build() {
    Column() {
      Text(this.initStatus)
        .fontSize(18)
        .margin(20)

      arEngine.ARView({ arViewContext: this.context })
        .width('100%')
        .layoutWeight(1)
    }
    .width('100%')
    .height('100%')
  }
}

这个页面会：

1. 检查设备是否支持 SLAM
2. 初始化 AR 上下文
3. 显示 AR 相机画面
4. 页面销毁时自动清理资源

注意事项

1. 设备兼容性

不是所有设备都支持 AR。ARView 组件在部分 Phone、部分 Tablet、TV 上可用，在不支持的设备上调用会返回 801 错误码。一定要先用 isARTypeSupported 检查。

2. 权限

AR 需要相机、陀螺仪、加速度计三个权限。如果用户拒绝了任何一个，初始化会失败（错误码 201）。

3. 资源管理

AR 会占用相机和传感器资源。不用的时候一定要 pause() 或 destroy()，否则相机可能被一直占用。

4. 线程安全

AR Engine 的回调可能在不同的线程里，更新 UI 时要注意线程切换。

小结

AR Engine 的基本使用流程：

1. isARTypeSupported — 检查设备是否支持
2. new ARViewContext() — 创建上下文
3. context.init() — 初始化（需要权限）
4. 在页面里使用 arEngine.ARView 组件显示 AR 画面
5. context.pause() / context.resume() — 暂停/恢复
6. context.destroy() — 销毁释放资源

下一篇我们深入看看 AR Engine 的高级能力——图像跟踪、深度估计、Mesh 识别。