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

鸿蒙开发-AR画面数据怎么流转？ARFrame数据详解

news 2026/6/4 23:00:55

AR 帧数据怎么获取和使用？AREngine_ARFrame 详解

上一篇文章聊了 ARSession 在空间建模中的角色，这篇文章来看看更具体的东西——ARFrame，也就是 AR Engine 每一帧采集到的数据。

AREngine_ARFrame 是什么

AREngine_ARFrame是 AR Engine 中存储单帧 AR 数据的结构体。和 ARSession 一样，它也是一个不透明句柄，你不能直接访问它的内部字段。

typedefstructAREngine_ARFrameAREngine_ARFrame;

文档里对它的描述是：“定义一个结构体，用于存储 AR Engine 中捕获的单帧 AR 图像数据，包含特定时间戳下的相机图像、追踪状态、锚点及 AR 相关信息。”

拆开来看，一帧 AR 数据包含了这些信息：

相机图像：当前帧的画面，就是摄像头看到的内容
追踪状态：AR Engine 对相机位置的追踪是否正常
锚点：在物理空间中固定的参考点，用来稳定虚拟内容
时间戳：这一帧被采集的时间
其他 AR 信息：比如检测到的平面、特征点等

从 ARSession 获取 ARFrame

下面是 ARFrame 数据的完整流转过程：

ARFrame 不是你自己创建的，而是从 ARSession 里获取的。AR Engine 每一帧都会更新 ARSession 的内部状态，你通过 AR Engine 的 API 来获取当前帧的 ARFrame。

获取到 ARFrame 之后，你可以做两件事：

用 AR Engine 自己的 API 来处理（比如渲染虚拟物体、检测平面等）
通过 PushARFrame 把它推给空间建模系统

对于空间建模场景，你需要在每一帧的更新循环中获取 ARFrame，然后推入空间建模会话。

PushARFrame 的完整流程

把 ARFrame 推入空间建模的流程是这样的：

HMS_SpatialReconStatusHMS_SpatialRecon_PushARFrame(HMS_SpatialRecon_Session*spatialReconSession,AREngine_ARSession*arSession,AREngine_ARFrame*arFrame);

三个参数之间的关系：

spatialReconSession：告诉空间建模系统"我要给你送数据了"
arSession：告诉空间建模系统"这些数据来自哪个 AR 会话"
arFrame：具体的一帧数据

你可以把 arSession 理解为"信封上的寄件人地址"，arFrame 理解为"信封里的信"。空间建模系统需要同时知道寄件人和信的内容，才能正确处理。

ARFrame 里对空间建模最有用的信息

虽然 ARFrame 是个不透明句柄，你不能直接读它的字段，但空间建模系统在内部会使用这些信息：

相机图像

这是最核心的数据——空间建模需要原始的图像像素来构建 3D 模型。AR Engine 获取的图像已经经过了预处理（去畸变、色彩校正等），质量比自己直接从摄像头获取的要好。

相机姿态

AR Engine 的 SLAM 追踪会给出每一帧相机在 3D 空间中的精确位置和旋转。空间建模系统需要这些信息来确定每张图像是从哪个角度拍摄的，这样才能正确地把多张图像"拼"成一个 3D 模型。

如果你用 PushFrame 手动推帧，这些姿态数据需要你自己提供。用 PushARFrame 的话，AR Engine 已经帮你算好了。

特征点

AR Engine 在追踪过程中会检测图像中的特征点（比如角点、纹理丰富的区域）。这些特征点不仅帮助 AR Engine 自己做追踪，也能帮助空间建模系统理解场景的几何结构。

时间戳

每帧都有精确的时间戳，空间建模系统用它来排序帧和计算帧间运动。

ARFrame 的质量对建模的影响

ARFrame 的质量直接决定了空间建模的效果。以下是几个影响质量的因素：

追踪状态

如果 AR Engine 的追踪丢失了（Lost），说明它无法确定相机的位置。这种情况下推入的 ARFrame 缺少可靠的姿态数据，会严重影响建模质量。

建议的做法是：在推帧之前检查追踪状态，如果追踪丢失就跳过这一帧。宁可少推几帧质量好的数据，也不要推一堆姿态不准的垃圾数据。

运动模糊

如果用户移动手机太快，图像会出现运动模糊。模糊的图像对空间建模来说几乎没用——特征点检测不出来，纹理信息也丢失了。

你可以在 UI 上提示用户"请缓慢移动手机"，或者通过分析连续帧之间的图像质量来自动过滤掉模糊帧。

光线条件

太暗或者太亮的环境都会影响图像质量。AR Engine 在低光环境下的追踪精度也会下降。如果用户的扫描环境光线不好，可以在 UI 上给出提示。

扫描角度

空间建模需要从多个角度拍摄同一个物体/场景。如果用户只从一个方向扫，建出来的模型会有很多"盲区"。你可以在 UI 上引导用户从不同角度扫描，比如"请从左侧扫一下"、“请从上方扫一下”。

什么时候停止推帧

推帧的质量控制和停止判断流程：

推帧不是越多越好。有几个停止的时机：

扫描时间够了：一般来说，扫描一个中等大小的房间需要 30 秒到 2 分钟。扫描一个小型物体可能只需要 10-20 秒
帧数达到上限：系统有最大帧数限制，推够了就不能再推了（PushARFrame 会返回SPATIAL_RECON_STATUS_EXCEEDS_MAXIMUM）
覆盖足够了：如果你实现了覆盖率检测，当场景的各个角度都被扫描到之后就可以停止

停止推帧后，调用 StartSession 启动重建就行。

ARFrame 和 DataFrame 的关系

你可能注意到了，ARFrame 和前面讲的 DataFrame 有很多相似之处——都有图像数据、相机参数、时间戳。其实它们本质上是同一类东西，只是来源不同：

DataFrame：你自己构造的，需要手动填充所有字段
ARFrame：AR Engine 自动生成的，你只需要获取和传递

空间建模系统内部会把 ARFrame 转换成统一的格式来处理。所以不管你是用 PushFrame 还是 PushARFrame，最终的效果是一样的——只是数据来源和便利程度不同。

ARFrame 内部的数据流

虽然 ARFrame 是个不透明句柄，你不能直接读它的字段，但了解一下它内部的数据流转过程，对你理解空间建模的工作原理很有帮助。

当 AR Engine 采集到一帧图像后，会依次做这些处理：

图像预处理：对原始摄像头数据做去畸变、色彩校正等操作，得到干净的图像
特征提取：在图像中检测特征点（角点、边缘等），这些特征点是追踪的基础
姿态估计：通过匹配当前帧和上一帧的特征点，计算相机的运动，得出新的位置和旋转
地图更新：把新的特征点加入到环境地图中，同时优化已有的地图点

这些处理的结果都封装在 ARFrame 里。当你调用 PushARFrame 的时候，空间建模系统会从 ARFrame 中提取需要的信息（主要是图像和姿态），然后用这些信息来构建 3D 模型。

所以你看，ARFrame 不只是"一帧图像"那么简单——它包含了 AR Engine 对这一帧的全部理解和分析结果。

用 PushFrame 还是 PushARFrame：一个实际的决策场景

举一个具体的例子来帮你做选择。

假设你要做一个"房产看房"APP，有两种场景：

场景一：实时扫描。用户到了一个新房子里，拿着手机在房间里走一圈，APP 实时构建房间的 3D 模型。这种场景用 PushARFrame 最合适——AR Engine 负责追踪和采集，空间建模负责重建，用户只需要走就行。

场景二：从视频重建。你有一个之前拍摄的房间视频文件，想从这个视频重建 3D 模型。这种场景只能用 PushFrame——你需要自己逐帧读取视频，提取每一帧的图像数据，然后手动构造 DataFrame。相机姿态可能需要用一些离线的 SLAM 工具来计算，或者如果视频是用稳定的支架拍的，可以用一个简单的线性插值来估算。

大多数 APP 都是场景一，所以 PushARFrame 是最常用的。但知道 PushFrame 的存在也很重要，它给了你更多的灵活性。