一、前言
给桌面物品拍照，通常是为了以后还能认出它。正面照片能够留下颜色和局部细节，但当回看需求变成“侧面的轮廓怎样”“转到背面还能看到什么”，记录方式就需要容纳观察方向的变化。本系列的“桌面三维记录册”围绕这一需求展开：固定静态物品，采集多视角信息，尝试在设备端重建，再验证产物能否用于交互式浏览。
这里先把浏览写成目标。保存了文件，甚至能够播放一段围绕物品的视频，都不能直接说明用户已经可以自主选择观察方向。后续需要分别检查重建、保存、加载和视角操作。本篇先解释记录的价值，整理能力入口与实验条件；具体设备返回值和产物表现留待实机记录。
3DGS的全称是3D Gaussian Splatting。理解它，可以先看组成场景的单个高斯点。高斯点带有位置、颜色、透明度、旋转和缩放等属性，可以用三维高斯椭球理解。
位置说明这个单元分布在哪里；旋转描述椭球的朝向；缩放影响它沿不同方向的形态与范围；颜色和透明度参与外观表达。一个单元不足以表达桌面物品，许多这样的单元共同构成场景。先理解“带属性的空间单元”，再理解“多个单元共同表达外观”，就不必一开始进入训练公式或渲染实现。
图1用于解释高斯点概念，图中组合关系不代表实测重建产物或测量精度。
“点”这个名称容易让人想到物体表面的精确采样坐标，但高斯点包含空间范围与外观属性，不能直接当作精确测量点。即便某个视角看起来接近原物，也还需要另外的依据，才能讨论尺寸误差或几何精度。本系列首先关心可见外观是否值得保留，以及预期观察范围内能否稳定浏览。
因此，样本选择从用途开始：是否确实需要多角度回看？能否固定摆放，并在相近条件下重复采集？希望观察哪些表面？如果需求只是辨认物品或保存正面标签，照片已经可能足够；如果轮廓和不同侧面的细节都重要，三维记录便值得进入实验。
这是一套业务选择准则，不是重建成功率排序。反光、低纹理和复杂形状可以作为样本标签，帮助后续解释差异。本篇不据此宣布某种材质必然成功或失败。具体样本尚未选定，也不预填任何已经采集的物品。
二、变量与条件
一次重建结果只有连同条件保存，才有比较价值。同一物品换了设备、系统构建或照明，结果发生变化时，不能仅凭文件名称判断原因。因此，“桌面三维记录册”首先需要实验档案。
版本信息分开记录。设备实际系统构建号、开发SDK版本与API级别则描述执行环境。共享资料将视觉重建和会话管理的起始版本标为6.1.0(23)，另将NG回调标为从26.0.0开始。现有资料没有给出这些标记与HarmonyOS 7.0的准确对应关系。
设备范围同样需要分层理解。Phone、Tablet、PC/2in1和TV，说明Kit适用的设备类型；具体设备是否支持重建仍需查询。该资料同时限定使用地区为中国境内，不含香港特别行政区、澳门特别行政区和中国台湾，并明确暂不支持模拟器。
| 分组 | 拟记录字段 | 填写规则 |
|---|---|---|
| 关联标识 | experimentId、sampleId、baselineId | 分别关联实验、样本和比较基线 |
| 设备环境 | 型号、芯片、系统完整构建号、地区 | 据目标设备填写 |
| 开发环境 | SDK版本、API级别、DevEco Studio版本 | 据实际工程环境填写 |
| 样本条件 | 名称、材质、纹理、形状、摆放、照明、预期浏览范围 | 记录观察与目标，不预判质量 |
| 证据来源 | 文档链接、更新时间、读取时间、日志引用 | 区分文档依据与实机证据 |
| 后续测量 | 阶段耗时、工具及版本、单位、采样方法、条件 | 未测量留空，不填0 |
图3为实验档案界面规划，展示待填写字段，不是设备信息采集截图。
代码C1用JSON表达档案骨架。全部字段均为应用自定义；三个标识在实际建档时分配。null表示当前未知，notExecuted表达尚未执行，两者共同避免把空值误读为失败或零耗时。
{"experimentId":null,"sampleId":null,"baselineId":null,"device":{"model":null,"chip":null,"systemBuild":null,"region":null},"development":{"sdkVersion":null,"apiLevel":null,"devEcoStudioVersion":null},"sample":{"name":null,"materialObservation":null,"textureObservation":null,"shape":null,"placement":null,"lighting":null,"expectedViewRange":null},"supportQuery":{"executionState":"notExecuted","rawStatus":null,"environmentRef":null,"evidenceRefs":[]},"measurements":{"stageDuration":null,"unit":null,"toolAndVersion":null,"method":null,"conditions":null},"evidenceRefs":[]}正式记录时，evidenceRefs关联包含来源类型和时间信息的证据条目。环境变化应留下可区分的基线记录；否则两次任务看似属于同一实验，实际上可能无法直接比较。
三、执行过程
3.1 分清职责和证据来源
系统提供输入接收、关键帧选择、重建与保存能力。应用负责组织采集，将图像与对应的相机信息关联起来，管理工作目录、任务和档案，并保存原始返回值。外部实验工具负责后续性能测量及辅助记录，具体工具和方法在第6篇确定。
这一区分直接影响结论的来源。重建接口返回值用来说明相应调用的结果；温度、内存与能耗等指标需要各自的采样方法，不能包装成重建接口直接给出的数据。外部工具也不承担替代性的云端重建。
图2为职责与证据流向规划，外部工具区域只承担测量和辅助记录。
3.2 制定支持查询步骤
实机检查先登记环境，再核对目标SDK中头文件、接口和库是否可用。随后按会话指南引入依赖。代码C2的CMake片段沿用指南中的entry目标名，接入工程时应对应实际原生库目标。
# 加入已有原生库目标的 CMakeLists.txt find_library( spatialrecon-lib libspatial_recon_ndk.z.so ) target_link_libraries(entry PUBLIC ${spatialrecon-lib} )下面的C++片段展示查询与解释分支。QuerySupport是应用函数，系统接口名称保持原样；注释中的记录动作仍需应用实现。
#include"spatial/spatial_recon_interface.h"HMS_SpatialReconStatusQuerySupport(){constHMS_SpatialReconStatus supportStatus=HMS_SpatialRecon_IsSupport(SPATIAL_RECON_MODEL_TYPE_GS);// 应用应保存 supportStatus 原值，并关联环境与日志。if(supportStatus==SPATIAL_RECON_STATUS_SUCCESS){// 当前设备支持该特性；继续核对后续前置条件。}elseif(supportStatus==SPATIAL_RECON_STATUS_DEVICE_NOT_SUPPORT){// 记录能力受阻，停止依赖该能力的重建步骤。}else{// 保留原值并待查，不自动归类为支持。}returnsupportStatus;}指南明确了支持与不支持的两个返回值。保留其他返回值的分支是应用的防御性设计，不代表资料已经确认还有某种特定错误。查询成功只允许继续检查；查询不支持时，档案和采集协议可以保留，但不能继续宣称设备能够完成端侧重建。
图4为能力检查页规划，当前状态为“尚未查询”，没有支持成功的实机证据。
3.3 核对输入与会话前置条件
重建输入包含图像、相机内参与位姿。图像提供外观信息；内参描述相机成像关系，例如资料列出的焦距和主点参数；位姿描述拍摄时相机的位置与朝向。应用必须保持这些信息与对应图像的关联，完整采集协议留给第2篇。
共享重建指南对尺寸给出了明确约束：宽度1080像素、高度1440像素，其他尺寸的结果未定义。虽然其中AR Engine示例注释使用了“推荐”措辞，正文对两种输入路径的限制更明确，本系列按该限制规划，不能将宽高互换或视为任选分辨率。
输入有两条路径：推入AR Engine数据帧前，需要先更新AR引擎的计算结果；自行组装HMS_SpatialRecon_DataFrame时，资料要求RGB格式。当前资料示例没有完整展开位姿字段，本篇不补写字段名或转换代码。系统会从推入的数据帧中选取关键帧，因此应用推入帧数不能直接充当关键帧数，也没有依据新增关键帧计数查询接口。
会话用于管理系统状态。创建前，workPath必须指向已经存在的应用文件目录子目录。代码C3仅用生命周期伪代码说明责任，其中中文动作是应用需实现的逻辑，不是系统API。
前提：支持查询成功，且开发环境已核对 workPath ← 应用选定的工作目录 检查 workPath 已存在且属于应用文件目录的子目录 spatialReconSession ← nullptr createStatus ← HMS_SpatialRecon_CreateSession( SPATIAL_RECON_MODEL_TYPE_GS, workPath, &spatialReconSession) 保存 createStatus 原值及环境关联 若 createStatus != SPATIAL_RECON_STATUS_SUCCESS：记录并结束本流程 应用持有 spatialReconSession；本片段不提交任务 准备释放时，禁止再向该会话提交操作 确认该会话所有相关任务均已结束，且没有并发访问 HMS_SpatialRecon_DestroySession(spatialReconSession) spatialReconSession ← nullptr；不再使用该会话及其其他引用会话指南明确：重建或保存进行中销毁会话会导致未定义行为，销毁后也不得继续操作。页面关闭不能直接替代“任务全部结束”的判断。
还要提前登记后续执行约束：同一时刻只能有一个会话进行重建；每次调用HMS_SpatialRecon_StartSession后，要按应用前后台情况调用HMS_SpatialRecon_SetRunningMode设置运行模式；同一时刻只能有一个会话保存MP4。完整调度与完成判定在第4篇展开，本篇代码没有提交重建任务。
四、观测结果
当前能够确认的是资料中的入口与约束，以及应用拟采用的记录方式。支持查询、会话创建和产物检查都尚未执行。把这些信息分开，后续才不会把“接口有文档”误写成“目标设备已验证”。
观测记录按检查项保存执行状态、原始返回值、环境关联、证据引用、可得结论和下一步。当前各项可采用下表；其中“待关联”表示字段尚未填写，不代表已经存在设备日志。
| 检查项 | 执行状态 | 原始返回值 | 环境／实机证据 | 当前结论与下一步 |
|---|---|---|---|---|
| 支持查询 | 未执行 | null | 待关联／无 | 设备能力待验证；先登记环境 |
| 会话创建 | 未执行 | null | 待关联／无 | 创建结果未知；核对工作目录 |
| 输入接收 | 未执行 | null | 待关联／无 | 有效性待验证；准备采集协议 |
| 重建 | 未执行 | null | 待关联／无 | 尚无完成证据；留待第4篇 |
| 保存 | 未执行 | null | 待关联／无 | 尚无输出文件；单独记录保存结果 |
| 浏览 | 待验证 | null | 待关联／无 | 尚无交互证据；留待第7篇 |
C1中的executionState是应用状态，rawStatus用于保存实际取得的系统返回值。两者不能混为一个系统枚举。浏览阶段还涉及不同模块，其证据应按对应接口和操作保存，不能统一套用HMS_SpatialReconStatus解释。
图5为观测记录界面规划，状态保持“尚未查询”或“待验证”，不展示运行日志。
后续即使支持查询返回成功，也只能确认设备支持该特性；会话创建成功，仍不能证明输入有效、产物可用或耗时合适。每一层结论都需要对应阶段的证据，不能用前一层成功填满整张表。
交给第2篇的是档案结构、待分配的样本与基线标识、待填环境字段，以及已经明确的输入约束。采集条件表将继续填写距离、路径、背景与照明；形成批次后，再通过标识关联。阶段耗时及测量方法仍为空，只有发生实际测量，才记录工具、单位、起止边界和实验条件。
五、结论
“值得做成3DGS”在本篇指一个有理由投入实验的需求：多角度外观回看具有价值，样本可以固定并重复采集，设备能力有可核验的入口。它还不是针对某种物品的质量保证。最佳距离、最少帧数和材质成功率，都需要后续比较，不能从接口说明推导出来。
预期观察范围也必须提前限定。物品底面或被遮挡区域如果没有采集，应单独记录，不能因为正面外观完整就承诺全方位恢复。高斯点共同表达场景，不自动构成测量级扫描依据；没有几何真值与误差评价，本系列不报告尺寸精度。
输出与加载同样需要分开。共享重建指南的保存部分提到PLY与运镜MP4；加载指南列出MP4、PLY、GLB。这两份列表不能推导出重建接口可以输出GLB，也不能保证任意同扩展名文件兼容。后续应从实际保存产物出发，核对加载路径。播放运镜视频可以展示既定路线，但不能代替自由视角浏览验证。
接下来，第2、3篇形成可追溯的输入批次，第4篇记录实际重建与保存，第5、6篇在相同证据基础上评价质量与成本，第7篇验证浏览，第8篇整理复现材料。任何阶段受阻，都保留其环境、原始信息与待补条件，让下一步建立在已经取得的证据上。
