HarmonyOS 7.0 端侧3DGS实验②：距离、视角与背景

一、前言

同一件桌面物品，第一次靠近拍摄，第二次退远一些、绕到背面，又换了背景。即使后续重建出现差异，也很难回答：主要影响来自距离、覆盖范围，还是背景？增加照片数量并不能补回没有记录的条件。

“桌面三维记录册”需要先建立可比较的输入批次。第1篇用experimentId、sampleId和baselineId关联实验、样本与基线，本篇继续使用这些标识，增加采集条件、路线和逐次推入记录。目标是让每批输入都能说明：计划改变什么、实际发生什么、依据保存在哪里。

当前尚未取得具体样本、设备实测和采集批次。因此，以下内容是一套待执行的实验协议，计划值与实际值分别保存。距离分组、路线和背景对照属于本文设计，不是官方最佳实践。重建完成留给第4篇确认，质量差异留给第5篇评价；本篇先解决输入是否能够被解释和追溯的问题。

二、变量与条件

2.1 继承环境，明确适用范围

每个批次关联第1篇的环境档案，保留设备型号、芯片、系统完整构建号、SDK版本和API级别，以及样本、摆放、照明与预期浏览范围。关联应指向当次使用的确定记录；环境改变后，不能只更新同一份档案，让旧批次失去原来的条件。

共享资料中的重建与会话指南将起始版本标为6.1.0(23)。HarmonyOS 7.0继续作为系列定位，现有资料不足以建立二者的准确映射，也不能据此称接口为“7.0新增”。本篇不引入NG回调。

2.2 一次只主动改变一个因素

先登记共同基准，再分别建立距离、覆盖和背景对照。距离变化批次与背景变化批次各自对照基准，不直接互作基准，否则比较中又会混入多个变化。

对照组	主动改变项	计划保持一致	必须另记的影响或偏差
距离组	相机至物品参考点的距离	样本、背景、照明、观察方向集合、镜头、变焦和采样规则	画面占比、出框、对焦与路径偏差
覆盖组	方位范围；高度另设子实验	距离、样本、背景、照明和镜头设置	帧数、时长、采样密度与遮挡
背景组	预先定义的背景条件	样本位置、距离、路线、灯位和采样规则	反射、曝光变化与物品误移动

距离要说明测量两端、单位和工具。桌面俯视图上的水平路线半径，与相机到物品参考点的空间距离并不相同；相机高度改变时，不能继续用同一个半径值代替空间距离。

重复次数与执行顺序在采集前登记，实际中断和偏差在执行后补充。固定灯位也不意味着受光和曝光必然不变：设备或操作者可能遮光，背景也可能改变反射。这些伴随变化是解释结果时需要考虑的混杂因素。

代码C1为应用自定义的JSON骨架。plannedConditions保存计划，actualConditions按相同条件结构填写实测与观察；当前整体未知，使用null。标识在建档时分配，notExecuted沿用前篇的应用执行状态。

{
  "experimentId": null,
  "sampleId": null,
  "baselineId": null,
  "captureBatchId": null,
  "environmentRef": null,
  "executionState": "notExecuted",
  "changedFactor": null,
  "plannedConditions": {
    "placementRef": null,
    "lightingRef": null,
    "distance": {
      "value": null,
      "unit": null,
      "referencePoint": null,
      "cameraReference": null,
      "measurementMethod": null,
      "toolAndVersion": null
    },
    "coverage": {
      "azimuthRange": null,
      "cameraHeight": null,
      "pitchRange": null,
      "targetSurfaces": null
    },
    "lens": null,
    "zoom": null,
    "samplingRule": null,
    "background": {
      "color": null,
      "pattern": null,
      "material": null,
      "placement": null
    }
  },
  "actualConditions": null,
  "pathRef": null,
  "actualPathEvidenceRefs": [],
  "repeatPlan": null,
  "executionOrder": null,
  "deviations": null,
  "evidenceRefs": []
}

changedFactor填写本批主动改变的因素；基准批次应明确标为基准。pathRef关联计划路线，实际路线证据另存。证据条目继续保留来源类型、时间和关联对象，避免把一张现场照片误用为整批条件始终不变的证明。

三、执行过程

3.1 固定物品，把路线写成可重复的计划

路线从物品摆放开始定义：记录桌面位置、物品朝向和参考点，然后指定设备起点、移动方向、路径分段、停留或采样位置，以及结束条件。每段还应说明希望观察的表面，让路线与预期浏览范围对应。

俯视图适合表达设备绕到了哪些方位，却不能表达完整三维位姿。相机高度、俯仰范围和朝向规则需要文字或侧视标记补充。路线表上的“经过背面”，也应与真实图像中的背面可见性分别核对。

图1为计划路径与界面规划，不代表AR Engine实测轨迹；高度和俯仰信息需与俯视路线一起阅读。

单批采集期间保持物品静止。若误碰物品，应记录发生位置、时间及受影响范围；无法确认前后条件一致时，结束该批并重新建批。不能把移动前后的输入默认为同一静态场景。

底面与被遮挡区域单列为未覆盖区域。为了补拍底面而翻动物品，会改变物品与环境的关系，不能直接混入原批。现场辅助照片可以记录摆放与灯位，但它们是否属于重建输入也要明确区分。

3.2 距离对照：保留原始构图变化

距离组先登记各条件及测量方法，再按同一观察方向集合采集。镜头与变焦设置保持一致，不通过变焦补偿物品大小。实际距离依据测量记录填写，并保留测量对应的路线位置；手持绕行不能只用起点距离代表全程。

比较取景时，选择对应观察方向的完整画幅，记录物品占比和边缘是否出框。若需要量化占比，还应说明采用包围框还是区域面积等方法。不同裁剪会掩盖距离带来的构图变化，因此不能把裁剪后的局部图作为原始取景对照。

图2保留实拍对照槽位，照片与测距记录待补；当前没有距离效果结论。

如果某距离条件出现对焦变化、模糊或出框，先登记现象与帧引用。详细质量标签由第3篇补充，不能凭单张照片清晰就宣布该距离适合重建，也不据此设置最佳距离或成功阈值。

3.3 覆盖对照：先确定看哪些方向

覆盖组拆成方位与高度两个子实验。研究方位时保持高度与俯仰规则一致；研究高度时固定方位范围，单独登记高度条件。一次同时增加绕行范围和俯拍层次，后续很难解释新增信息来自哪里。

本协议默认保持采样密度规则一致，例如按相同的方位分段规则安排采样，具体间隔在执行前确定。覆盖扩大后，实际帧数和采集时长可能随之增加，必须一起记录。这种比较反映一套采集方案的变化，不能单独证明覆盖范围的因果效果。

若后续需要隔离帧数影响，应另设匹配输入规模的对照，同时说明匹配帧数可能改变采样密度。图1中的路径分段用于核对计划覆盖，表面是否可见仍要检查图像；走完路线、获得可见信息和得到良好重建，是不同层次的事实。

3.4 背景对照：只在批次之间替换

背景条件需要描述颜色、图案、材质、放置位置及其与物品的关系。“干净背景”或“复杂背景”不足以复现现场。例如，仅记录“有图案”仍不够，还需要保留图案分布和背景摆放证据。

背景只在不同批次之间替换。替换后重新核对物品位置与朝向、路线参考和灯位，并记录核对依据。如果更换材料时同时改变颜色与纹理，本次比较的是整体背景条件，不能把后续差异单独归因于纹理。

图3的真实背景对照素材待补，不能用合成照片补作采集证据。

固定照明布置后，仍需观察阴影、反射和曝光是否变化。背景替换若伴随物品移动，也应进入偏差记录。协议只规定如何描述和控制条件，不预设某种背景必然改善重建。

3.5 输入检查：图像、内参与位姿必须对应

相机内参描述成像关系，位姿描述拍摄时相机的位置与朝向。应用需要把它们关联到同一帧，不能将相邻帧的信息随意配对。

明确限定输入图像宽1080像素、高1440像素，其他尺寸结果未定义。检查对象是输入数据，界面预览区域或手机截图尺寸不能代替数据尺寸证据。帧标识和关联字段齐全，也不意味着数值、坐标约定与数据有效性已经核验。

图4展示待核验的检查结构；实际尺寸、检查结果与原始返回值尚未取得。

AR Engine路径要求推入前先更新AR计算结果。C2用text伪代码表达顺序，中文动作均为应用待实现逻辑。资料未完整提供的成功判定和有效性检查保留为核验前提，不新增系统枚举。

前提：设备支持与环境已核验，spatialReconSession 已成功创建
前提：arSession、arConfig 已按目标SDK要求创建
前提：配置、更新和输入有效性的判定依据已核清；否则停止

previewStatus ← HMS_AREngine_ARConfig_SetPreviewSize(
    arSession, arConfig, 1080, 1440)
保存 previewStatus 原值
若不能确认配置成功：记录原因，结束本流程
按目标SDK要求完成其余AR配置、使配置生效并准备 arFrame
若这些前提未满足：结束本流程

对每次计划输入：
    arUpdateStatus ← HMS_AREngine_ARSession_Update(arSession, arFrame)
    保存本次AR更新原值与证据关联
    若更新失败或无法确认成功：
        记录未推入原因；不调用推入接口
        结束本次输入处理
    核对本次图像尺寸、图像与内参及位姿对应关系、数据有效性
    若检查失败或仍待核验：
        记录原因；不调用推入接口
        结束本次输入处理
    spatialPushStatus ← HMS_SpatialRecon_PushARFrame(
        spatialReconSession, arSession, arFrame)
    保存本次调用序号、帧关联、spatialPushStatus 原值与证据
    若推入结果异常或无法解释：暂停后续推入，保留现场待核查

自组帧路径使用HMS_SpatialRecon_DataFrame，资料要求RGB格式。现有文本没有完整展开位姿字段、坐标约定与缓冲区要求，因此本篇不补写转换实现。图像若经过旋转、缩放或裁剪，不能只修改宽高便视作合规；相关数据对应关系未核清时，停止该输入路径。

系统会自动选择关键帧。采集帧数、推入调用次数和逐次返回值应分别保存，调用次数或成功返回次数都不能推算关键帧数。

批次隔离也必须落实到输入集合。本文计划为各对照批次使用各自新建的重建会话，并关联会话记录，避免旧输入混入。具体调度与后续内容衔接；不假定存在清空输入或离线重放接口。会话要求工作目录为已存在的应用文件目录子目录，并在所有相关任务完成后才能销毁会话。换批次不能成为提前销毁运行中会话的理由。

四、记录结果

当前可交付的是协议与记录结构，尚无采集、推入或重建结果。下面以单批详情表列出待填内容；实际执行后，每批独立填写，并关联C1。未知数值使用null，不能用0表示“还没有测”。

记录项	当前内容	后续填写依据
批次、样本、基线	待关联	建档记录
改变因素	待填写	对照计划
计划／实际条件	待填写／null	条件表与现场证据
覆盖偏差与中断	null	路线分段和事件记录
采集帧数	null	按帧标识统计，注明去重规则
推入调用次数	null	逐次调用记录
原始返回值引用	待关联	AR更新、Spatial Recon推入分别保存
采集时长及测量方法	null／待填写	起止事件、单位、工具及版本
执行状态	未执行	执行后依据事实更新
系统关键帧数	未知	无对应证据，不由调用数推算

图5为空记录界面规划，未知数量显示“—”，执行状态为“未执行”，不展示运行日志。

计时需要先定义边界。本文拟从应用登记“开始本批采集”到登记“结束本批采集”计算整段时长，中断单独记录；若另算有效采集时长，应说明扣除规则。工具、单位及实际起止证据执行后填写，采集时长不能标成重建耗时。

C3展示一次输入尝试的记录骨架。AR更新返回值属于AREngine_ARStatus，推入返回值属于HMS_SpatialReconStatus，两者不能共用状态解释。以下字段均为应用字段，不是SDK结构成员。

{
  "captureBatchId": null,
  "frameId": null,
  "inputEvidenceRef": null,
  "sessionRecordRef": null,
  "arUpdate": {
    "executionState": "notExecuted",
    "rawStatus": null,
    "evidenceRefs": []
  },
  "inputCheck": {
    "executionState": "notExecuted",
    "actualWidth": null,
    "actualHeight": null,
    "correspondenceEvidenceRef": null,
    "result": null,
    "evidenceRefs": []
  },
  "spatialPush": {
    "executionState": "notExecuted",
    "callSequence": null,
    "rawStatus": null,
    "notCalledReason": null,
    "evidenceRefs": []
  }
}

更新失败时，仍应保存该次尝试，即使没有可关联的有效帧；重复推入同一帧则分别记录调用。统计不能直接数JSON条目充当采集帧数。真正执行后，若因前置检查受阻而零次推入，才可据记录填写0及原因。

下一步需补齐样本与环境、具体分组和测量工具，核验输入检查依据，再取得实拍和逐次调用证据。三段示例用于解释设计，不构成完整采集工程；权限、AR生命周期、原始数据导出与位姿转换均未在此实现。

五、结论

这套协议能够提高条件与证据的可追溯性，但不能保证重建质量，也不能推出最佳距离、最少帧数或背景成功率。路线覆盖只是计划与执行信息，底面和遮挡面仍需明确列出，不能扩展为全表面恢复或测量级扫描承诺。

本篇交付采集协议、待填写的基准条件、路径说明、批次与调用模板，以及证据缺口。取得真实数据后才能交付基准批次，空记录不能称为已完成采集。

第3篇沿用相同标识补充曝光、反光和低纹理标签；第4篇记录实际重建与保存；第5篇再将缺陷关联回输入条件。原始图像和相机信息能否持久化并重新推入，还需补充依据和验证。档案中的证据关联仅表示能够查找记录，不等同于已经形成可重放的数据包。