鸿蒙开发-空间建模的C语言接口有哪些？spatial_recon_interface详解

HarmonyOS 空间建模的 C API 长什么样？带你过一遍 spatial_recon_interface.h

如果你想做一个空间扫描 APP，用户拿着手机在房间里转一圈，你的 APP 就能把整个房间的 3D 模型建出来。这种功能听起来很高端，但 HarmonyOS 的 SpatialReconKit 已经把核心能力封装好了。不过 SpatialReconKit 的空间建模部分不是用 ArkTS 写的，而是提供了 C 语言的 API 接口。

为什么要用 C API？因为空间建模涉及大量的图像处理和 3D 计算，C 语言的性能优势在这里就体现出来了。你需要通过 NDK（Native Development Kit）来调用这些接口。

入口在哪

所有空间建模的 C API 都声明在spatial_recon_interface.h这个头文件里。引用方式是：

#include<SpatialReconKit/spatial_recon_interface.h>

链接的库是libspatial_recon_ndk.z.so，对应的系统能力是SystemCapability.Graphics.SpatialRecon。这些信息在你配置 CMakeLists.txt 或者 build-profile.json5 的时候会用到。

先搞清楚有哪些结构体

spatial_recon_interface.h 定义了 5 个核心结构体，它们是整个空间建模 API 的数据基础：

• HMS_SpatialRecon_Session：会话句柄，你可以理解为"一次空间建模任务"的代表。所有的操作（推帧、启动、暂停、查询进度）都要通过它来进行
• HMS_SpatialRecon_DataFrame：数据帧，包含一帧图像的所有信息——相机内参、姿态、时间戳、图像像素数据等
• HMS_SpatialRecon_ModelWriteInfo：模型写入配置，告诉系统要把建好的 3D 模型保存到哪里、用什么格式、要不要附带音频和地理信息
• AREngine_ARSession：AR Engine 的会话句柄，是一个不透明句柄（opaque handle），你不能直接访问它的内部结构
• AREngine_ARFrame：AR 帧数据，包含一帧 AR 图像的相机图像、追踪状态、锚点等信息

前三个是空间建模自己的结构体，后两个是来自 AR Engine 的，用于和 AR 系统联动。后面的文章会逐个详细讲。

枚举类型：给状态和选项起个名字

除了结构体，还定义了 6 个枚举类型，用来表示各种状态和配置选项。

HMS_SpatialReconStatus —— 操作状态

这个枚举是最重要的，几乎每个 API 函数都会返回它，告诉你操作成功了还是失败了，失败的原因是什么。

SPATIAL_RECON_STATUS_SUCCESS=0// 成功SPATIAL_RECON_STATUS_EXCEEDS_MAXIMUM=1023700001// 超过最大帧数SPATIAL_RECON_STATUS_DEVICE_NOT_SUPPORT=801// 设备不支持SPATIAL_RECON_STATUS_INVALID_WORK_PATH=1023700002// 工作路径无效SPATIAL_RECON_STATUS_INVALID_FRAME_DATA=1023700003// 帧数据无效SPATIAL_RECON_STATUS_STAGE_NOT_INITIALIZED=1023700004// 会话未初始化SPATIAL_RECON_STATUS_STAGE_BUILDING=1023700005// 重建已开始SPATIAL_RECON_STATUS_STAGE_NOT_FINISHED=1023700006// 重建未完成SPATIAL_RECON_STATUS_FAILED=1023700007// 重建失败

每个状态码都有对应的含义。比如你调用HMS_SpatialRecon_PushFrame推帧的时候，如果返回SPATIAL_RECON_STATUS_INVALID_FRAME_DATA，说明你传入的帧数据有问题，可能是图像数据为空或者内参不对。如果返回SPATIAL_RECON_STATUS_EXCEEDS_MAXIMUM，说明推的帧数已经到上限了。

HMS_SpatialReconModelType —— 模型类型

目前只支持一种模型类型：3DGS（3D Gaussian Splatting）。

SPATIAL_RECON_MODEL_TYPE_GS// 3DGS模型，用于场景重建

虽然现在只有一种，但这个枚举预留了扩展空间，未来可能会支持其他 3D 模型类型。

HMS_SpatialReconRunningMode —— 运行模式

空间建模支持前台和后台两种运行模式。这个设计考虑到了实际使用场景——用户在扫描空间的时候可能会切出去看消息或者接电话。

SPATIAL_RECON_RUNNING_FOREGROUND_MODE// 前台模式，系统分配更多资源，重建速度快SPATIAL_RECON_RUNNING_BACKGROUND_MODE// 后台模式，系统优先处理前台应用，重建速度较慢

当 APP 切到后台时，你应该调用HMS_SpatialRecon_SetRunningMode把模式切到后台模式，这样系统就不会因为你的建模任务占用太多资源而影响用户的其他操作。等 APP 回到前台再切回来。

HMS_SpatialReconStage —— 重建阶段

告诉你当前建模任务走到了哪一步。

SPATIAL_RECON_STAGE_INIT// 初始化阶段，准备资源和环境SPATIAL_RECON_STAGE_BUILDING// 重建阶段，处理数据并构建3D模型SPATIAL_RECON_STAGE_PAUSED// 已暂停SPATIAL_RECON_STAGE_FINISHED// 重建成功完成SPATIAL_RECON_STAGE_SAVING// 保存阶段，3D模型正在保存为文件SPATIAL_RECON_STAGE_UNKNOWN// 阶段未知

你可以通过HMS_SpatialRecon_GetProgress同时获取进度比例和当前阶段，然后在 UI 上给用户展示一个进度条，比如"重建中… 65%"。

HMS_SpatialReconOutputFormat —— 输出格式

决定导出的 3D 模型用什么文件格式。

SPATIAL_RECON_OUTPUT_FORMAT_PLY// PLY格式，常见的3D点云格式SPATIAL_RECON_OUTPUT_FORMAT_MP4// MP4格式，视频格式

PLY 格式适合在 3D 查看器里打开，MP4 格式适合分享给别人看。

HMS_SpatialReconImageDataFormat —— 图像数据格式

目前只支持 RGB 格式。

SPATIAL_RECON_IMAGEDATA_FORMAT_RGB// RGB格式，红绿蓝三通道

核心函数一览

spatial_recon_interface.h 定义了 12 个函数，覆盖了空间建模的完整生命周期。我们按功能分组来看：

设备能力检测

HMS_SpatialReconStatusHMS_SpatialRecon_IsSupport(HMS_SpatialReconModelType type);

在做任何空间建模操作之前，先调用这个函数检查设备是否支持。它会返回SPATIAL_RECON_STATUS_SUCCESS表示支持，或者SPATIAL_RECON_STATUS_DEVICE_NOT_SUPPORT表示不支持。支持情况可能因设备硬件、系统版本而异。

会话管理（5 个函数）

HMS_SpatialReconStatusHMS_SpatialRecon_CreateSession(HMS_SpatialReconModelType type,constchar*workPath,HMS_SpatialRecon_Session**outSpatialReconSession);HMS_SpatialReconStatusHMS_SpatialRecon_DestroySession(HMS_SpatialRecon_Session*spatialReconSession);HMS_SpatialReconStatusHMS_SpatialRecon_StartSession(HMS_SpatialRecon_Session*spatialReconSession,HMS_SpatialRecon_ModelWriteInfo*writeInfo,HMS_SpatialReconCallbackFunc onSpatialReconFinished);HMS_SpatialReconStatusHMS_SpatialRecon_PauseSession(HMS_SpatialRecon_Session*spatialReconSession);HMS_SpatialReconStatusHMS_SpatialRecon_ResumeSession(HMS_SpatialRecon_Session*spatialReconSession);

创建、销毁、启动、暂停、恢复——会话的完整生命周期管理。后面有专门的文章详细讲。

数据输入（2 个函数）

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

两种数据输入方式：一种是自己构造 DataFrame 推进去，另一种是直接推 AR Engine 的帧。前者更灵活，后者更方便。后面也会有专门的文章讲。

进度查询和结果获取（3 个函数）

HMS_SpatialReconStatusHMS_SpatialRecon_GetProgress(HMS_SpatialRecon_Session*spatialReconSession,float*progress,HMS_SpatialReconStage*stage);HMS_SpatialReconStatusHMS_SpatialRecon_GetRefinedFrame(HMS_SpatialRecon_Session*spatialReconSession,intiFrame,HMS_SpatialRecon_DataFrame*outFrame);HMS_SpatialReconStatusHMS_SpatialRecon_SaveResultToFile(HMS_SpatialRecon_Session*spatialReconSession,HMS_SpatialRecon_ModelWriteInfo*writeInfo,HMS_SpatialReconCallbackFunc onSaved);

GetProgress 查询进度，GetRefinedFrame 获取优化后的相机参数，SaveResultToFile 把结果导出到文件。

运行模式设置（1 个函数）

HMS_SpatialReconStatusHMS_SpatialRecon_SetRunningMode(HMS_SpatialRecon_Session*spatialReconSession,HMS_SpatialReconRunningMode runningMode);

在前台/后台之间切换运行模式。

回调函数类型

typedefvoid(*HMS_SpatialReconCallbackFunc)(HMS_SpatialReconStatus);

这是一个函数指针类型定义，用于异步操作的完成通知。有两个地方会用到它：HMS_SpatialRecon_StartSession的第三个参数（重建完成回调）和HMS_SpatialRecon_SaveResultToFile的第三个参数（保存完成回调）。

空间建模 API 函数分类

spatial_recon_interface.h 中的 12 个函数可以按功能分为以下几类：

一个典型的空间建模流程

把这些 API 串起来，一个完整的空间建模流程大概是这样的：

1. 调用HMS_SpatialRecon_IsSupport检查设备是否支持
2. 调用HMS_SpatialRecon_CreateSession创建会话，指定模型类型和工作目录
3. 循环调用HMS_SpatialRecon_PushFrame（或HMS_SpatialRecon_PushARFrame）把一帧帧的数据喂进去
4. 数据推完后，调用HMS_SpatialRecon_StartSession启动重建
5. 通过HMS_SpatialRecon_GetProgress轮询进度
6. 重建完成后，调用HMS_SpatialRecon_SaveResultToFile导出结果
7. 最后调用HMS_SpatialRecon_DestroySession销毁会话，释放资源

注意第 3 步和第 4 步的顺序——必须先推完所有帧数据，再调用 StartSession。一旦 StartSession 被调用了，就不能再推帧了，PushFrame 会返回失败。

下面是空间建模的完整生命周期流程图：

核心结构体：空间建模的数据基础

spatial_recon_interface.h 定义了 5 个核心结构体，它们是整个空间建模 API 的数据基础：

这就是 spatial_recon_interface.h 的全貌。后面的几篇文章会分别深入 Session 会话管理、DataFrame 数据帧、ModelWriteInfo 模型写入、ARSession 和 ARFrame 这些具体的结构体和函数。