工程 Demo：PoseGate（PO-208）｜方向：3DGS 重建输入数据门禁
说明：本文所有采集记录、运行状态和 DevEco Studio／手机配图均为专门构造的技术示例，不代表实际采集、训练、渲染或真机测试。

先说这次要挡住什么

3DGS 项目最让人头疼的环节未必是建模，而是输入数据看起来齐全，实际却有两类难以肉眼发现的元数据问题：相机位姿中的角度单位没有统一，或者采集时间戳在导出、合并时倒退。重建任务开始前，文件目录通常已经整理好，帧号也能连续排列，表面检查不会报警；等进入后续空间重建流程，轨迹异常才会变成昂贵的排查工作。PoseGate 不碰 3DGS 算法内部，而是在把位姿清单交给重建阶段以前，建立一道可解释、可复核、可阻断的离线门禁。

这里故意只准备六条构造数据，任务编号统一为 PO-208。F-003 写了 yawDeg=450，明显超出项目约定的正负一百八十度；F-006 的 tMs=150 则小于前一行 F-005 的一百六十毫秒。其余四条符合当前规则，因此预期静态结果是 PASS 4 / HOLD 2。这不是重建成功率、画质指标，也不是某款设备实际跑出来的测评成绩，而是六条 JSON 的规则判断。

为什么不直接检查帧数

前一轮已经讨论过输入帧序与缺口，这里换一个更深的位置：帧号连续只说明文件清单能排上队，不能证明同一场景的位姿元数据可用。F-003 即使有图片，姿态角超范围也需要判断是否存在单位换算错误；F-006 即使文件命名正确，也不能在当前约定下带着倒退的采样时间继续流转。门禁不负责推断真实姿态，更不擅自把四百五十度修成九十度，因为修正需要了解相机坐标系、角度约定和上游导出协议。把不明确的数据标成 HOLD，比悄悄改好看更加可追溯。

输入契约定义四件事：会话标识、单位声明、每条采样的帧标识，以及位置和姿态的基本字段。这里 angleUnit=deg 指角度由度数表示，timeUnit=ms 指时间戳单位为毫秒；position 是长度为三的有限数字数组，至于米还是其他空间单位，需要项目协议另行固定。JSON 示例仅展示两条异常记录，完整六条样例放在 ZIP 的 fixtures/poses.json 中。

{
  "sessionId": "PO-208",
  "angleUnit": "deg", "timeUnit": "ms",
  "frames": [
    {"frame":"F-003","tMs":80,"position":[0.2,0,0],
     "yawDeg":450,"pitchDeg":1,"rollDeg":0},
    {"frame":"F-006","tMs":150,"position":[0.5,0,0],
     "yawDeg":14,"pitchDeg":1,"rollDeg":0}
  ]
}

把单位放在数据顶层有两个现实好处。其一，审查者打开报告就能知道规则为什么如此设定；其二，当上游换了导出工具或者新版格式时，可以先触发契约不匹配，而不是一边吞下变化一边尝试估算结果。任何自称支持全部相机外参格式的通用校验器都容易误判，本例从开始就只针对自定义的 JSON 清单。特别需要强调，华为 Spatial Recon Kit 的官方介绍说明其具备三维内容处理能力，不意味着该 Kit 对外要求本文这个 JSON 结构；这是示例项目在调用后续重建功能之前自行添加的保护层。

把“发现问题”写成确定性函数

核心判断按原始采样顺序逐条扫描，而不是先按时间排序。排序虽然能让倒退看似消失，但也会抹掉现场证据。对角度，我们检查三个 Euler 字段是否为有限数，再应用项目规定的 yaw 和 roll 正负一百八十度、pitch 正负九十度门槛。对时间，我们要求相邻输入的 tMs 严格递增；对于重复帧号，单独加入报告。注意示例中的阈值只是数据接口约定，不等价于对所有相机坐标系都有效的物理定律。

function auditPoseRows(frames) {
  const pass = [], hold = [];
  let previousTime = -Infinity;
  const seen = new Set();
  for (const p of frames) {
    const faults = [];
    if (seen.has(p.frame)) faults.push('DUPLICATE_FRAME');
    seen.add(p.frame);
    const angles = [p.yawDeg, p.pitchDeg, p.rollDeg];
    if (!Array.isArray(p.position) || p.position.length !== 3 ||
        !p.position.every(Number.isFinite) ||
        !angles.every(Number.isFinite) || !Number.isFinite(p.tMs)) {
      faults.push('NON_FINITE_OR_MISSING_FIELD');
    } else {
      if (Math.abs(p.yawDeg) > 180 || Math.abs(p.pitchDeg) > 90 ||
          Math.abs(p.rollDeg) > 180) faults.push('ANGLE_OUT_OF_RANGE');
      if (p.tMs <= previousTime) faults.push('TIME_REGRESSION');
      previousTime = p.tMs;
    }
    faults.length ? hold.push({ frame: p.frame, faults }) : pass.push(p.frame);
  }
  return { pass, hold };
}

这个函数返回两组结构化数据，便于命令行退出码、CI 任务和页面提示共同消费。hold 里的原因代码比一句“文件错误”有用：ANGLE_OUT_OF_RANGE 表示角度门槛触发，TIME_REGRESSION 表示时间不前进，NON_FINITE_OR_MISSING_FIELD 说明字段无法安全参与计算。实现时不应先 Number(value) 再判断，因为空字符串可能被强制转换成零，伪装成一个有效位置。遇到 NaN、Infinity、字段缺失，检查器应该保守地阻断。

还有一处细节：角度非法并不意味着时间状态可以不更新。比如 F-003 虽然角度越界，仍是输入中的真实上一条记录；校验邻近时间时，如果跳过它，可能无意中放过额外的时间倒退。完整脚本明确将顺序比较和字段错误记录分离，最大限度保留原始证据，而不是试着帮采集器“修数据”。

让本地脚本能在 CI 中拦住问题

真正放进工具目录的是 Node.js 版本，依赖 node:fs/promises、node:path 和 node:url 等标准库，不需要安装一个名字很像官方 SDK 的虚构包。它在当前项目目录读取 fixtures/poses.json，对字段类型、会话编号、重复帧号、姿态上下界和时间顺序做检查，然后把结果写入 reports/pose-report.json。异常时设置退出码 2；CI 可以把非零退出码视为阻断，但是否允许人工签收再放行，必须由团队单独决定。

// tools/pose-audit.mjs 的实际入口；完整可运行版本见同目录 tools/
const data = JSON.parse(await readFile('./fixtures/poses.json', 'utf8'));
if (data.angleUnit !== 'deg' || data.timeUnit !== 'ms')
  throw new Error('WRONG_UNIT_CONTRACT');
const result = auditPoseRows(data.frames);
await mkdir('./reports', { recursive: true });
await writeFile('./reports/pose-report.json',
  JSON.stringify({ taskId: 'PO-208', ...result }, null, 2));
console.log(`PO-208 PASS ${result.pass.length} / HOLD ${result.hold.length}`);
process.exitCode = result.hold.length ? 2 : 0;

文章节选强调审查思路；实际可执行的脚本包含更完整的非空校验和路径处理，以 ZIP 中 tools/pose-audit.mjs 为准。运行时在对应 Demo 目录执行 node tools/pose-audit.mjs，再打开 JSON 报告，不必装 DevEco Studio。它不会触发拍摄，不会重建点云，不会向远端服务提交素材，反而方便把隐私敏感的拍摄数据与审计摘要分开保存。报告建议记录会话号和错误原因，避免默认收集照片内容或者精确地点信息。

手机界面只把 Node 产生的构造审查概念转成易读页面。顶部显示任务 PO-208，红色卡片分别为 F-003 / 角度越界 / yaw=450° 与 F-006 / 时间回退 / 150≤160 ms；其余四帧显示 PASS。这个界面是展示稿，不代表脚本已经在鸿蒙端运行。如果未来需要真正联动，需要另做可信的报告传递、签名和读取流程，不能把图片里的“导出预检清单”按钮当作已实现的系统能力。

调试路径应该怎样安排

第一组验证只检查理想数据：六行时间严格增加，角度全部在约定区间内，预期 PASS 6 / HOLD 0。第二组保留本例的 F-003 和 F-006，预期 PASS 4 / HOLD 2。第三组把 angleUnit 改成 rad 而不改变数据，应该直接拒绝整个会话，而不是按度数继续计算。第四组故意把位置元素写成字符串、空值或无穷大，报告必须指出字段不可用。第五组重复一条帧 ID；第六组使用两个相同时间戳。后面这些都是推荐的故障注入场景，不能据此写成已在真机逐项通过。

本地脚本的校验还应该处理文件读写失败：样例 JSON 不存在时，输出明确的读取错误；报告目录不可写时，任务应失败，而不是只在控制台打印“通过”。CI 记录要保存使用的输入文件版本与规则版本，若后续调整角度范围，不同批次的 PASS 数字才能被正确解释。真正的视觉重建质量还受图像覆盖率、模糊、曝光、姿态估计精度等因素影响，纯元数据检查无法回答这些问题。

本轮结论与使用边界

这一道门禁的价值是在昂贵任务之前保留可追责的输入契约，而不是号称能预测 3DGS 重建效果。可复用的部分包括 schema 验证、逐行错误归因、退出码与清单落盘；不可直接照搬的部分包括 Euler 角范围、坐标系定义、帧间时间尺度和业务接受阈值。工程接入时应根据官方能力说明、使用设备与真实导出格式逐项确认，尤其不能把本文的 PO-208 JSON 当成 Spatial Recon Kit 的公共 API 入参。理解这条边界后，出问题时至少能先确定是不是输入契约失守，再决定要不要排查渲染和算法层。

官方参考与核对日期（2026-10-20）： 华为 Spatial Recon Kit 能力目录 https://developer.huawei.com/consumer/cn/doc/；3DGS 重建官方技术指南入口 https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/spatial-recon-c-spatial-recon-pipeline。资料用于确认技术领域和能力边界。