3DGS 重建的输入不只是“一组照片”。每一帧还要与对应的相机内参、位姿和采集顺序保持一致。画面本身清晰、尺寸也满足要求如果中途切换了相机裁剪策略却继续沿用旧内参或者图像与位姿来自相邻两个时刻系统接口仍可能收到格式完整的数据最终模型却出现重影、拉伸和局部漂移。本文用PoseLatch演示工程把问题放在调用HMS_SpatialRecon_PushFrame之前解决。示例任务为RECON-CALIB-0077会话为recon_g31。文中的统计是为说明门禁设计准备的演示向量不代表真实设备跑分能力支持范围、结构体字段与 SDK 版本以当前官方文档和本地头文件为准。一、格式合法与语义一致是两回事官方资料对 3DGS 输入给出了明确边界开发前检查设备支持输入图像使用规定尺寸和格式普通帧需要相机内参以及四元数加平移构成的位姿所有帧推送完成后再启动重建。它们构成接入的硬边界却不会替业务决定“这一张图和这一组参数是否真的属于同一采集时刻”。PoseLatch的异常样本很典型。采集开始时使用calib-r4图像保持1080 × 1440RGB。第 73 帧后预览链调整了裁剪区域图像尺寸在输出端仍被恢复成规定尺寸但主点位置已经变化。若仅检查 width、height 和数据指针帧可以继续向下流动内参却不再描述当前图像。另一个问题来自异步管线。图像、相机位姿和 UI 预览往往由不同线程产生。队列拥塞时图像时间captureTs与位姿时间poseTs可能错配四元数也可能包含非有限值或未归一化数据。重建接口返回成功只能说明调用被接受不能替代应用自己的输入语义校验。因此本例在系统接口前设置FrameCoherenceGate。它不修改 Spatial Recon Kit 的行为只检查应用准备的数据包是否符合当前会话合同。通过后才填充 SDK 结构并推送被拒绝的帧进入诊断记录不进入重建会话。二、先把会话合同钉死本次任务RECON-CALIB-0077在13:21创建诊断页电量显示68%。会话固定为recon_g31输入合同是1080 × 1440、RGB、calib-r4。图像与位姿的最大允许配对偏差为8 ms帧序号必须严格递增四元数模长允许落在[0.98, 1.02]。演示共观察 186 个候选帧181 帧进入系统会话5 帧被应用门禁拒绝2 帧INTRINSICS_REV_MISMATCH1 帧POSE_NOT_FINITE1 帧QUATERNION_NORM1 帧FRAME_ORDER_REGRESSION。已接受帧的图像/位姿配对偏差 P95 为4.6 ms。门禁状态从CAPTURING进入SEALED之后才进入RECONSTRUCTING示例进度为72%。calib-r4不是 SDK 参数而是应用为一组内参定义的版本标识。只要分辨率、裁剪、数字变焦、镜头或图像方向会改变像素坐标与光线之间的关系就生成新 revision。会话合同不接受混用 revision需要切换时结束当前采集段并创建新段而不是把新旧帧塞进同一包。最大偏差8 ms也是项目阈值不是官方固定值。它应由相机帧率、运动速度、位姿来源和验收数据决定。本文保留这一数值是为了让代码、图片和诊断页共享同一套可核对事实。内参 revision 需要跟着像素几何变化而不是跟着“相机是否还是同一个”变化。假设原图先裁掉左侧 40 像素再缩放回1080 × 1440即使镜头和焦距没有改变principalX也必须按裁剪与缩放重新计算。若图像旋转了 90 度焦距和主点的轴关系也会变化。把输出尺寸恢复正确并不能自动恢复内参语义。因此采集链必须把图像变换写成可追踪元数据。每次 crop、resize、rotate 都产生新的几何变换记录最终内参由原始标定和这条记录推导推导结果生成 revision。若某个图像处理节点无法给出变换参数这一段输出就不进入普通帧重建。与其猜测主点不如改用成套 AR 帧接口或重新建立可验证的采集链。位姿合同还要写清坐标系约定四元数分量顺序、左手或右手系、平移单位、相机到世界还是世界到相机。本文示例只验证有限值与模长不宣称完成坐标系转换。实际项目应准备一个静止相机和一段沿单轴平移的黄金序列用可观察运动方向验证外参语义。字段齐全却坐标系相反比空指针更难排查。三、用显式数据包承载图像与位姿这段代码解决什么问题。它把图像信息、内参、位姿、两个时间戳和 revision 收敛到一个不可含糊的数据包中避免后续函数再从多个可变对象临时拼装。structIntrinsicsSnapshot{doublefocalX;doublefocalY;doubleprincipalX;doubleprincipalY;uint32_trevision;};structPoseSnapshot{doubleqx;doubleqy;doubleqz;doubleqw;doubletx;doublety;doubletz;int64_tposeTsNs;};structFrameEnvelope{uint64_tsequence;int64_tcaptureTsNs;uint32_twidth;uint32_theight;constuint8_t*rgbData;size_t rgbBytes;IntrinsicsSnapshot intrinsics;PoseSnapshot pose;};应用层结构的价值是把“同一帧”定义清楚。captureTsNs与poseTsNs都来自同一单调时钟域如果上游无法保证这一点不能直接相减而应先做时钟域转换或改用同源序号。rgbData的所有权也必须明确门禁和推帧期间缓冲区保持有效调用完成后再由生产者回收。这里没有把示例结构说成 Spatial Recon Kit 的官方结构。通过门禁后适配层再按当前 SDK 头文件把字段写入HMS_SpatialRecon_DataFrame。这样既避免编造系统字段也让应用的质量合同可以独立测试。易错点是保存“指向当前内参对象的指针”。相机配置变化后旧帧看到的内容会被新配置覆盖。这里复制四个数值和 revision确保异步队列中的每个 envelope 都保留采集当时的快照。四、门禁按不可恢复程度排序这段代码解决什么问题。它在进入系统接口之前检查指针、尺寸、字节数、内参 revision、时间配对、有限值、四元数模长与序号单调性并返回稳定的拒绝码。enumclassGateCode{ACCEPTED,EMPTY_IMAGE,INVALID_SIZE,INTRINSICS_REV_MISMATCH,PAIR_SKEW_EXCEEDED,POSE_NOT_FINITE,QUATERNION_NORM,FRAME_ORDER_REGRESSION};classFrameCoherenceGate{public:explicitFrameCoherenceGate(uint32_tcalibrationRevision):calibrationRevision_(calibrationRevision){}GateCodeCheck(constFrameEnvelopef){if(f.rgbDatanullptr||f.rgbBytes0)returnGateCode::EMPTY_IMAGE;if(f.width!1080||f.height!1440)returnGateCode::INVALID_SIZE;if(f.intrinsics.revision!calibrationRevision_){returnGateCode::INTRINSICS_REV_MISMATCH;}constint64_tskewstd::llabs(f.captureTsNs-f.pose.poseTsNs);if(skew8000000)returnGateCode::PAIR_SKEW_EXCEEDED;if(!PoseIsFinite(f.pose))returnGateCode::POSE_NOT_FINITE;constdoublenormQuaternionNorm(f.pose);if(norm0.98||norm1.02)returnGateCode::QUATERNION_NORM;if(hasLast_f.sequencelastSequence_){returnGateCode::FRAME_ORDER_REGRESSION;}lastSequence_f.sequence;hasLast_true;returnGateCode::ACCEPTED;}private:uint32_tcalibrationRevision_;uint64_tlastSequence_0;boolhasLast_false;};排序很重要。空指针和尺寸错误没有继续计算的价值revision 不匹配意味着整帧语义不属于当前会话时间偏差超限说明图像与位姿不再是一对最后才做数学约束。这样诊断码稳定不会因为一帧同时存在多个问题而随机变化。四元数模长不在范围内时本例直接拒绝而不是静默归一化。轻微浮点误差可以归一化但明显偏离可能说明字段顺序、内存布局或数据来源错误。自动修复会把输入故障伪装成正常帧。若项目决定允许归一化也应在诊断里记录NORMALIZED并限制可修复区间。序号只在帧被接受后推进。被拒绝帧不会改变lastSequence_后续正常帧仍可继续。门禁自身属于采集会话不能跨 session 复用销毁或重新创建recon_g31时序号状态也要一起重置。有限值检查要覆盖内参和位姿全部标量。focalX、focalY应为正数主点应落在可解释范围平移分量和四元数都不能出现 NaN 或 Infinity。项目还可以根据场景定义相邻帧位移与旋转速度上限用于发现时间错配但这类阈值不能凭感觉写死。缓慢扫房间与快速绕拍小物体的运动分布完全不同应分别建立验收样本。时间偏差只是配对质量的一部分。即使两个时间戳只差 2 ms如果它们来自不同单调时钟数值也没有可比性。FrameEnvelope的构造点必须证明两个时间属于同一时钟域否则保存 sourceClockId并在上游做同步。门禁遇到未知时钟域直接拒绝不能把“数字很接近”当成同源证据。五、通过门禁后才调用系统接口HMS_SpatialRecon_PushFrame是系统边界不应该承担应用数据整理。适配层只做两件事把通过门禁的 envelope 映射到当前 SDK 的数据结构并记录系统返回码。所有帧推送结束后先封存采集再调用HMS_SpatialRecon_StartSession。这段代码解决什么问题。它把“校验、推帧、封存、启动”变成不可逆的阶段防止启动重建后仍有采集线程继续推送。classReconIngress{public:GateCodePush(constFrameEnvelopeenvelope){if(phase_!Phase::CAPTURING)returnGateCode::FRAME_ORDER_REGRESSION;GateCode codegate_.Check(envelope);if(code!GateCode::ACCEPTED){audit_.RecordRejected(envelope.sequence,code);returncode;}HMS_SpatialRecon_DataFrame sdkFrame{};FillSdkFrameFromEnvelope(envelope,sdkFrame);// 按本地 SDK 头文件映射HMS_SpatialReconStatus statusHMS_SpatialRecon_PushFrame(session_,sdkFrame);audit_.RecordPush(envelope.sequence,status);returnstatusSPATIAL_RECON_STATUS_SUCCESS?GateCode::ACCEPTED:GateCode::EMPTY_IMAGE;}HMS_SpatialReconStatusSealAndStart(){phase_Phase::SEALED;HMS_SpatialReconStatus statusHMS_SpatialRecon_StartSession(session_,nullptr,OnFinished);if(statusSPATIAL_RECON_STATUS_SUCCESS)phase_Phase::RECONSTRUCTING;returnstatus;}};示例用FillSdkFrameFromEnvelope明确隔离 SDK 映射。文章不展开未核对的结构体字段开发时应以安装的 API 26/当前 SDK 头文件为准。StartSession是异步操作成功返回不代表重建已完成完成状态由回调或进度查询确认。本例把CAPTURING → SEALED设置成单向转换。封存后生产线程即使晚到也只能收到拒绝不会与重建并发修改输入集合。若启动失败可以保留已封存清单用于诊断但不能直接回到采集状态追加几帧更安全的做法是关闭本轮会话、生成新 generation并重新建立合同。系统返回码与应用拒绝码要分开记录。INTRINSICS_REV_MISMATCH是应用在调用前发现的问题SPATIAL_RECON_STATUS_INVALID_FRAME_DATA则来自系统边界。两者不能合并成PUSH_FAILED否则统计无法判断应修采集链还是核对 SDK 结构。日志字段至少包括 sequence、gateCode、sdkStatus、sessionId 和 generation。会话启动前还应生成一份不可变清单写入 accepted sequence 范围、calibration revision、帧数、拒绝摘要和时间偏差统计。重建完成后把清单与结果关联。这样模型出现问题时可以判断它用了哪一批输入而不是依赖内存中的最后状态。清单不需要保存原图内容可保存受控摘要和必要元数据。若StartSession成功后应用退到后台不要销毁并重建会话。官方资料提供 running mode 用于前后台资源调度调用时机位于启动之后、完成之前。页面销毁与重建会话也不是同一个概念UI 可以离开Native 任务继续UI 返回时通过 sessionId 查询而不是再创建recon_g31的第二个实例。图中的 DevEco Studio 画面是演示配图。左侧为PoseLatch工程中间 C 代码显示calib-r4、8 ms、四元数模长范围和 revision 检查右侧模拟器展示181 / 186底部日志列出 5 类拒绝结果。它用于对应文章逻辑不冒充真实 IDE 截图或实机测试证据。六、ArkTS 只接收稳定快照采集和重建核心位于 C页面不应该持有原始指针也不应根据零散回调自己累加统计。Native 层把审计快照一次性返回 ArkTS页面只渲染状态并使用 generation 隔离旧会话。这段代码解决什么问题。它让页面在切换会话或离开后忽略旧进度同时保证轮询定时器与页面生命周期成对释放。interface ReconAuditSnapshot { taskId: string sessionId: string phase: CAPTURING | SEALED | RECONSTRUCTING | COMPLETED | FAILED observed: number accepted: number rejected: number progress: number calibrationRevision: string } Entry Component struct FrameCoherencePage { State audit?: ReconAuditSnapshot private generation: number 0 private timerId: number -1 aboutToAppear(): void { const current this.generation this.timerId setInterval(async () { const next await PoseLatchNative.queryAudit(recon_g31) if (current this.generation) this.audit next }, 500) } aboutToDisappear(): void { this.generation if (this.timerId 0) clearInterval(this.timerId) this.timerId -1 } }页面状态不会反向驱动 Native 会话。启动、暂停、恢复和销毁都通过单独命令进入状态机查询只返回不可变快照。这样可以避免 UI 重组时重复调用StartSession。进度显示72%只是当前快照回调晚到时先比较 generation再决定是否刷新。资源释放需要特别克制。定时器要清除Native 会话在确定不再使用时调用HMS_SpatialRecon_DestroySession图像缓冲区按所有权回收完成回调里避免执行耗时任务。若应用切换前后台应在StartSession之后、重建完成之前按当前状态调用HMS_SpatialRecon_SetRunningMode而不是重新创建会话。七、运行页展示门禁结果而不是漂亮模型运行页时间为13:21状态栏显示 5G、Wi-Fi、信号和68%电量。任务RECON-CALIB-0077、会话recon_g31、合同1080 × 1440 RGB / calib-r4均在首屏可见。进度卡显示72%阶段为RECONSTRUCTING帧统计为181 / 186 accepted。把门禁结果放在主页面是为了让采集人员在开始重建前就看到异常。如果 5 个拒绝全部集中在某次相机配置变化后继续采更多帧并不能改善数据集应先固定内参 revision。页面不会显示“自动修复成功”因为本文策略没有静默修复。P95 配对偏差4.6 ms是已接受集合的统计。被拒绝的超限样本不应混入这个数字否则指标会被门禁行为本身扭曲。诊断报告同时保存阈值8 ms、样本数和时间单位避免后续只看到一个没有上下文的 P95。页面还可以显示输入覆盖的序号范围例如1–186并标记缺口。缺口本身不一定错误因为应用主动拒绝坏帧真正需要关注的是缺口是否连续集中。如果 5 个拒绝散落在整段采集中可能只是个别异常如果都集中在 revision 切换点则说明采集状态机没有正确分段。统计的目的不是把数字做得漂亮而是帮助决定是否值得启动重建。在用户点击“开始重建”前页面应明确给出门禁判断本例 181 帧可用、5 帧已隔离、合同保持calib-r4允许继续。若有效帧不足或关键角度桶缺失可以要求补采但补采仍必须发生在CAPTURING阶段。已经SEALED的会话不允许为追求数量而重新打开。八、详情页解释五帧为何被挡住详情页与运行页内容明显不同。它列出INTRINSICS_REV_MISMATCH2、POSE_NOT_FINITE1、QUATERNION_NORM1、FRAME_ORDER_REGRESSION1。红色标注集中在calib-r4与四元数范围[0.98,1.02]用于说明系统调用前的应用门禁。每条拒绝记录只保存 sequence、原因、revision 和必要数值不保存完整图像。对于POSE_NOT_FINITE记录哪个分量非法对于四元数模长异常记录 norm对于 revision 不匹配记录 expected/actual对于序号回退记录 last/current。这样的诊断足以定位上游不必把原始用户场景长期留在日志里。详情页还显示状态链CAPTURING → SEALED → RECONSTRUCTING。如果出现StartSession失败状态停在SEALED并记录系统返回码不会把页面强行推进到运行中。若用户取消先停止生产者再等待正在执行的推帧调用退出最后销毁会话避免句柄与缓冲区的交叉释放。九、验证需要人工构造坏帧仅用正常相机流很难覆盖门禁。单元测试应构造明确坏包把calib-r4改成calib-r5让poseTs比captureTs晚9 ms把qw设为 NaN把四元数模长改成0.90重复上一帧序号把宽度改为 1079把 RGB 指针设为空。每个向量都应得到唯一稳定拒绝码。集成测试再验证阶段边界封存后调用 Push 必须拒绝StartSession只能执行一次页面离开后旧快照不能刷新新页面前后台变化只调整 running mode重建完成或失败后才允许销毁。还要模拟回调与取消同时发生确认回调不访问已释放对象。并发测试应让图像生产者、位姿生产者和封存命令故意交错。门禁需要保证 envelope 在进入队列前已经完整不能让消费者看到一半旧字段、一半新字段。封存动作先阻止新 envelope 入队再等待队列排空最后改变 phase。若先改变 phase 再等待仍在执行的 Push 可能被误记为封存后调用若只等待不关入口队列则永远排不空。故障注入还要覆盖内存所有权。让生产者在 Push 返回前提前复用 RGB 缓冲区检查测试是否能捕获内容摘要变化让 Native 会话销毁后触发完成回调确认 generation 防护生效。此类测试不一定进入日常冒烟但在调整相机或 NAPI 适配层时应重复执行。真正的设备验收应使用官方支持设备和适用地域模拟器不能替代 Spatial Recon Kit 实机验证。验收记录要区分三层结果应用门禁是否通过、系统接口是否接受、最终模型是否满足业务质量。三者不能合并成一个“成功”。模型质量问题也不能反推所有输入都非法需要结合优化后相机参数、日志和重建结果继续分析。十、把不确定性挡在系统边界之前3DGS 输入管线最危险的错误不是明显崩溃而是“每个字段看起来都像真的”。图片清晰、尺寸正确、四元数有四个值、平移也有三个值但它们并不属于同一时刻或同一标定版本。等模型出现重影后再查往往已经失去原始关联证据。本文的取舍是把输入变成可审计合同一个 envelope 对应一张图、一组内参、一组位姿、一个序号和一对时间session 只接受一个 calibration revision采集封存后不再追加。门禁不能保证模型一定优秀却能排除一类可重复、可解释的输入污染。实际项目应根据相机链路重新标定阈值不照搬8 ms和[0.98,1.02]。如果使用HMS_SpatialRecon_PushARFrame让 AR Engine 提供成套帧也仍要管理 ARSession 与重建 Session 的生命周期确保在StartSession前完成推送。应用自建数据管线则更需要把 revision、时钟域和缓冲区所有权写进设计而不是留给调用点猜测。门禁也有边界。它能证明输入满足已声明合同不能证明纹理足够丰富、曝光稳定或视角覆盖充分这些属于另一层采集质量问题。不要把所有模型缺陷都归因于内参与位姿也不要因为门禁通过就声称重建已成功。输入一致性、系统执行结果和模型验收必须分别给出证据。最终可交付的不是一句“PushFrame 返回成功”而是一条完整证据链官方规格已核对应用合同有版本坏帧有拒绝码接受集合有清单启动后阶段可观测完成后结果可追溯。做到这些模型异常才有机会被定位而不是在相机、Native、算法和渲染之间反复猜测。官方参考重建三维场景C/CSpatial Recon Kit APISpatial Recon Kit 官方话题与能力说明