当前位置：首页 > news >正文

鸿蒙开发-想做AR应用？AR Engine从零开始

news 2026/6/3 20:31:09

想做一个 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 上下文letcontext:arViewController.ARViewContext=newarViewController.ARViewContext();// 初始化（异步操作）awaitcontext.init();

init()会做这些事情：

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

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

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

检查设备是否支持 AR

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

letsupported=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 页面时，记得销毁上下文，释放资源：

awaitcontext.destroy();

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

ARView 组件

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

import{arEngine,arViewController}from'@kit.AREngine';@Entry@Componentstruct ARPage{privatecontext:arViewController.ARViewContext=newarViewController.ARViewContext();asyncaboutToAppear(){awaitthis.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 的核心技术。它做的事情是：

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

有了平面识别，你就可以把虚拟物体"放"在真实的平面上。比如用户对准地面，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@Componentstruct ARPage{privatecontext:arViewController.ARViewContext=newarViewController.ARViewContext();@StateinitStatus:string='初始化中...';asyncaboutToAppear(){// 检查设备是否支持letsupported=arViewController.isARTypeSupported(arEngine.ARFeatureType.ARENGINE_FEATURE_TYPE_SLAM);if(!supported){this.initStatus='设备不支持 AR';return;}try{awaitthis.context.init();this.initStatus='AR 初始化成功';}catch(err){leterror=errasBusinessError;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%')}}