HarmonyOS 空间建模的 C API 长什么样带你过一遍 spatial_recon_interface.h如果你想做一个空间扫描 APP用户拿着手机在房间里转一圈你的 APP 就能把整个房间的 3D 模型建出来。这种功能听起来很高端但 HarmonyOS 的 SpatialReconKit 已经把核心能力封装好了。不过 SpatialReconKit 的空间建模部分不是用 ArkTS 写的而是提供了 C 语言的 API 接口。为什么要用 C API因为空间建模涉及大量的图像处理和 3D 计算C 语言的性能优势在这里就体现出来了。你需要通过 NDKNative Development Kit来调用这些接口。入口在哪所有空间建模的 C API 都声明在spatial_recon_interface.h这个头文件里。引用方式是#includeSpatialReconKit/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_ARSessionAR Engine 的会话句柄是一个不透明句柄opaque handle你不能直接访问它的内部结构AREngine_ARFrameAR 帧数据包含一帧 AR 图像的相机图像、追踪状态、锚点等信息前三个是空间建模自己的结构体后两个是来自 AR Engine 的用于和 AR 系统联动。后面的文章会逐个详细讲。枚举类型给状态和选项起个名字除了结构体还定义了 6 个枚举类型用来表示各种状态和配置选项。HMS_SpatialReconStatus —— 操作状态这个枚举是最重要的几乎每个 API 函数都会返回它告诉你操作成功了还是失败了失败的原因是什么。SPATIAL_RECON_STATUS_SUCCESS0// 成功SPATIAL_RECON_STATUS_EXCEEDS_MAXIMUM1023700001// 超过最大帧数SPATIAL_RECON_STATUS_DEVICE_NOT_SUPPORT801// 设备不支持SPATIAL_RECON_STATUS_INVALID_WORK_PATH1023700002// 工作路径无效SPATIAL_RECON_STATUS_INVALID_FRAME_DATA1023700003// 帧数据无效SPATIAL_RECON_STATUS_STAGE_NOT_INITIALIZED1023700004// 会话未初始化SPATIAL_RECON_STATUS_STAGE_BUILDING1023700005// 重建已开始SPATIAL_RECON_STATUS_STAGE_NOT_FINISHED1023700006// 重建未完成SPATIAL_RECON_STATUS_FAILED1023700007// 重建失败每个状态码都有对应的含义。比如你调用HMS_SpatialRecon_PushFrame推帧的时候如果返回SPATIAL_RECON_STATUS_INVALID_FRAME_DATA说明你传入的帧数据有问题可能是图像数据为空或者内参不对。如果返回SPATIAL_RECON_STATUS_EXCEEDS_MAXIMUM说明推的帧数已经到上限了。HMS_SpatialReconModelType —— 模型类型目前只支持一种模型类型3DGS3D 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 个函数可以按功能分为以下几类spatial_recon_interface.h设备能力检测会话管理数据输入进度与结果运行模式IsSupport 检查支持CreateSession 创建会话StartSession 启动重建PauseSession 暂停ResumeSession 恢复DestroySession 销毁PushFrame 推送数据帧PushARFrame 推送AR帧GetProgress 查询进度GetRefinedFrame 获取优化帧SaveResultToFile 保存结果SetRunningMode 前台/后台一个典型的空间建模流程把这些 API 串起来一个完整的空间建模流程大概是这样的调用HMS_SpatialRecon_IsSupport检查设备是否支持调用HMS_SpatialRecon_CreateSession创建会话指定模型类型和工作目录循环调用HMS_SpatialRecon_PushFrame或HMS_SpatialRecon_PushARFrame把一帧帧的数据喂进去数据推完后调用HMS_SpatialRecon_StartSession启动重建通过HMS_SpatialRecon_GetProgress轮询进度重建完成后调用HMS_SpatialRecon_SaveResultToFile导出结果最后调用HMS_SpatialRecon_DestroySession销毁会话释放资源注意第 3 步和第 4 步的顺序——必须先推完所有帧数据再调用 StartSession。一旦 StartSession 被调用了就不能再推帧了PushFrame 会返回失败。下面是空间建模的完整生命周期流程图否是否是开始IsSupport 检查设备支持?退出CreateSession 创建会话PushFrame 循环推送数据构造 DataFrame设置相机内参设置姿态和时间戳设置图像数据推送到会话StartSession 启动重建GetProgress 轮询进度重建完成?SaveResultToFile 保存结果DestroySession 销毁会话结束核心结构体空间建模的数据基础spatial_recon_interface.h 定义了 5 个核心结构体它们是整个空间建模 API 的数据基础这就是 spatial_recon_interface.h 的全貌。后面的几篇文章会分别深入 Session 会话管理、DataFrame 数据帧、ModelWriteInfo 模型写入、ARSession 和 ARFrame 这些具体的结构体和函数。