想做一个 AR 应用先搞懂 AR Engine 的基本能力你有没有玩过那种把虚拟家具放到真实房间里的 APP或者那种对着杂志封面弹出 3D 动画的效果这些都叫 AR——增强现实Augmented Reality就是在真实世界的画面上叠加虚拟内容。在 HarmonyOS 里AR 能力由AR Engine提供。今天我们来看看它的基本用法怎么初始化 AR 会话、怎么做平面识别、怎么管理 AR 场景。下面是 AR 应用的完整生命周期流程不支持支持权限拒绝权限授予失败成功检查设备是否支持 AR提示用户申请相机/陀螺仪/加速度计权限提示需要权限创建 ARViewContextcontext.init 初始化处理错误码使用 ARView 组件显示画面页面切换时 pause/resume页面销毁时 context.destroyAR 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}fromkit.AREngine;import{BusinessError}fromkit.BasicServicesKit;// 创建 ARView 上下文letcontext:arViewController.ARViewContextnewarViewController.ARViewContext();// 初始化异步操作awaitcontext.init();init()会做这些事情初始化 AR 会话Session设置 AR 渲染场景打开相机开始运动跟踪如果初始化失败会抛出错误码。常见的错误201权限未授予801设备不兼容不是所有设备都支持 AR1009200010相机不可用可能被其他 APP 占用了1009200007配置不支持检查设备是否支持 AR在初始化之前建议先检查设备是否支持letsupportedarViewController.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}fromkit.AREngine;EntryComponentstruct ARPage{privatecontext:arViewController.ARViewContextnewarViewController.ARViewContext();asyncaboutToAppear(){awaitthis.context.init();}aboutToDisappear(){this.context.destroy();}build(){Column(){arEngine.ARView({arViewContext:this.context}).width(100%).height(100%)}}}ARView组件会显示相机的实时画面并在上面叠加 AR 内容。SLAM运动跟踪 平面识别SLAMSimultaneous Localization and Mapping即时定位与地图构建是 AR 的核心技术。下面是 SLAM 的工作流程水平面垂直面摄像头采集画面传感器获取运动数据SLAM 算法融合视觉惯性数据运动跟踪: 计算手机位姿平面识别: 分析画面中的平面输出相机位置和朝向识别到平面?地面/桌面墙壁在平面上放置虚拟物体SLAMSimultaneous Localization and Mapping即时定位与地图构建是 AR 的核心技术。它做的事情是运动跟踪通过摄像头画面和传感器数据实时计算手机在 3D 空间中的位置和朝向。平面识别分析摄像头画面找到现实世界中的水平面比如地面、桌面和垂直面比如墙壁。有了平面识别你就可以把虚拟物体放在真实的平面上。比如用户对准地面APP 识别出这是一个水平面然后用户点击屏幕就在那个位置放一个虚拟的椅子。图像跟踪IMAGE 特性图像跟踪是另一个常用功能——让 AR Engine 识别特定的图片然后在图片上方叠加 3D 内容。添加参考图片首先你需要告诉 AR Engine “要跟踪哪些图片”// 添加图片到跟踪列表// AR Engine 最多支持 50 张参考图片图片的质量会影响识别效果。AR Engine 会从三个维度评价图片质量宽高比越接近 1:1 越好1.0-1.5Excellent1.5-2.0Good2.0-2.5Fit2.5不推荐分辨率以 640x480 为基准0.9Excellent0.7-0.9Good0.45-0.7Fit0.35-0.45Unfit0.2 以下不推荐图像内容颜色单一的图片比如纯色识别效果差有丰富纹理和细节的图片识别效果好有反光、光斑的图片可能识别失败添加模式// NORMAL 模式超过 50 张就报错// UPDATE 模式超过 50 张自动删除最旧的人脸相关能力AR Engine 还提供了丰富的人脸相关能力人脸关键点LandmarkType左眼、右眼鼻尖嘴巴左侧、右侧人脸中心微表情ARBlendShapeType闭左眼/闭右眼瞪大眼嘴巴张开/闭合微笑/皱眉等等……这些能力可以用来做 AR 贴纸——比如给用户脸上加一个猫耳朵或者根据嘴巴张合来触发动画。完整示例一个基础 AR 页面import{arEngine,arViewController}fromkit.AREngine;import{BusinessError}fromkit.BasicServicesKit;EntryComponentstruct ARPage{privatecontext:arViewController.ARViewContextnewarViewController.ARViewContext();StateinitStatus:string初始化中...;asyncaboutToAppear(){// 检查设备是否支持letsupportedarViewController.isARTypeSupported(arEngine.ARFeatureType.ARENGINE_FEATURE_TYPE_SLAM);if(!supported){this.initStatus设备不支持 AR;return;}try{awaitthis.context.init();this.initStatusAR 初始化成功;}catch(err){leterrorerrasBusinessError;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%)}}这个页面会检查设备是否支持 SLAM初始化 AR 上下文显示 AR 相机画面页面销毁时自动清理资源注意事项1. 设备兼容性不是所有设备都支持 AR。ARView组件在部分 Phone、部分 Tablet、TV 上可用在不支持的设备上调用会返回 801 错误码。一定要先用isARTypeSupported检查。2. 权限AR 需要相机、陀螺仪、加速度计三个权限。如果用户拒绝了任何一个初始化会失败错误码 201。3. 资源管理AR 会占用相机和传感器资源。不用的时候一定要pause()或destroy()否则相机可能被一直占用。4. 线程安全AR Engine 的回调可能在不同的线程里更新 UI 时要注意线程切换。小结AR Engine 的基本使用流程isARTypeSupported— 检查设备是否支持new ARViewContext()— 创建上下文context.init()— 初始化需要权限在页面里使用arEngine.ARView组件显示 AR 画面context.pause()/context.resume()— 暂停/恢复context.destroy()— 销毁释放资源下一篇我们深入看看 AR Engine 的高级能力——图像跟踪、深度估计、Mesh 识别。