技术栈：HarmonyOS Spatial Recon Kit（场景背景）／Node.js 20+／ESM／JSON／四元数数学
Demo：PoseQuatGate｜任务编号：PQ-406

我这次想处理的不是重建速度，也不是模型里的高斯点数，而是素材流转中一个看起来很不起眼的字段：相机姿态里的旋转四元数。前一次检查采集帧时间戳，能够解释采集顺序有没有回退；但是时间正常不意味着姿态合法。一个全零旋转值可能从序列化环节进入文件，一组非单位四元数也可能被误当成可靠方向。它们不应该等到后续的可视化或计算环节才被发现。

我定义了一种项目内部 JSON 交换格式，约定 q 按 [x, y, z, w] 排列，用 Node.js 做进入下一工序前的离线检查。华为公开资料确认 HarmonyOS 提供 Spatial Recon Kit 与 3DGS 端侧重建能力；检查器的输入合同和 0.02 容差属于 Demo 自身规则。

工程里到底会怎样出错

例如一个文旅展馆扫描团队，将五个相机位姿记录汇总给三维同事。大家约定一个姿态对象里必须有 id 和 q。正常的正向单位姿态可以写成 [0,0,0,1]；旋转约九十度的示例可以用 [0,0.70710678,0,0.70710678]；而 [0,0,0,0] 连可归一化的方向都没有。这些都是构造记录，并不来源于实际相机。若只检查字段是否存在，全零数组照样能通过；若采用 q.every(Boolean)，合法的零分量反而会被错杀。检查重点必须转到数组结构、数字有效性与长度。

我把目标拆成三层：首先检查是否恰好四个有限数字；接着检查模长是否接近零；最后计算 |‖q‖-1|。这里“接近零”的项目阈值取 1e-6，与单位长度偏差的阈值 0.02 是两个完全不同的判断。不能为了让一张示意图顺利显示，就把坏记录统一归一化。对于全零四元数，除以长度本身就没有意义；对于模长明显异常的值，随意修正可能掩盖上游数据约定错误。

代码之前先固定业务词汇。PASS 是符合当前输入合同，不代表重建一定成功；HOLD_SHAPE 是维度或数字问题；HOLD_ZERO 是不能安全归一化；HOLD_NORM 是非零却超过项目容差。输出中同时保留原始四元数与模长，方便追溯源文件，避免下游只看到一个红色告警而无法定位来源。

最小判定函数

下面的第一段是真正可单独运行的 JavaScript 逻辑。浮点数误差可以存在，但 NaN、无穷大与字符串形式数字不会被悄悄转换。字段合同越窄，异常责任越容易判明。此次故意不用任何没有验证的 HarmonyOS 3DGS API。

export function inspectQuaternion(q, tolerance = 0.02) {
  if (!Array.isArray(q) || q.length !== 4 ||
      !q.every((v) => typeof v === 'number' && Number.isFinite(v))) {
    return { status: 'HOLD_SHAPE', norm: null };
  }
  const norm = Math.hypot(...q);
  if (norm < 1e-6) return { status: 'HOLD_ZERO', norm };
  if (Math.abs(norm - 1) > tolerance) {
    return { status: 'HOLD_NORM', norm };
  }
  return { status: 'PASS', norm };
}

我保留负号的合法性：[0,0,0,-1] 与 [0,0,0,1] 表达同一旋转，不能因为最后一位是负值就拒绝。也不能仅凭单位长度判断坐标系是左手还是右手、参考坐标轴是否一致；这些需要额外合同和外参数据。本文只承担数值输入卫生检查。若工程传来旋转矩阵、欧拉角或其他分量顺序，应该在适配层明确转换，不能将不同表示硬塞进这条规则。

把单条检查变成可交接的批次报告

一个批次可能包含很多相机记录。只输出第一条错误会让返工反复发生，我选择把五条结果都写成 JSON 报告。报告里记录任务编号 PQ-406、样本 ID、结果、模长与本次采用的阈值。每次重跑覆盖新报告，而不是把历史结果无限追加；这样便于在版本管理里观察真实差异，也避免过期记录混到当前交付中。

import { readFile, writeFile, mkdir } from 'node:fs/promises';
import { inspectQuaternion } from './quaternion.mjs';
const input = JSON.parse(await readFile('fixtures/poses.json', 'utf8'));
const rows = input.map((item) => ({
  id: item.id,
  q: item.q,
  ...inspectQuaternion(item.q)
}));
const pass = rows.filter((r) => r.status === 'PASS').length;
const report = { task: 'PQ-406', pass, hold: rows.length - pass, rows };
await mkdir('reports', { recursive: true });
await writeFile('reports/pose-report.json', JSON.stringify(report, null, 2));

第二段代码只用 Node.js 标准库，读写是显式等待的。示例在当前工作目录运行，因此我会从项目根目录执行；交给 CI 时，需要使用脚本所在路径构造绝对地址，避免工作目录变化导致误读其他同名文件。生产环境还应对 JSON 文件体积设上限，限制不可信输入，并采取临时文件写入后原子替换报告的方案。这里只展示核心门禁，不把这些工程补强伪装成已经完成。

用五条刻意制造的数据验证

我准备了五个样本：CAM-61 的单位姿态、CAM-62 的近似九十度旋转、CAM-63 的模长 1.08、CAM-64 的全零值，以及 CAM-65 的负单位姿态。期望分类依次是 PASS、PASS、HOLD_NORM、HOLD_ZERO、PASS。这是比较容易人工计算的一组数据，能同时覆盖负号合法与两类阻断。它没有采样噪声模型，也不包含真正的相机外参求解过程。

第三段代码专门核对这组结果，不依赖截图里的颜色判断。测试不通过就抛异常，让流水线及时发现检查器自己被改坏的情况。测试还应该继续加入 null、空数组、字符串和非法浮点值，本文将它们列为扩展用例，实际随包的测试文件包含代表性的异常输入。

import assert from 'node:assert/strict';
import { inspectQuaternion } from './quaternion.mjs';
const expected = ['PASS', 'PASS', 'HOLD_NORM', 'HOLD_ZERO', 'PASS'];
const inputs = [
  [0, 0, 0, 1], [0, 0.70710678, 0, 0.70710678],
  [0, 0, 0, 1.08], [0, 0, 0, 0], [0, 0, 0, -1]
];
assert.deepEqual(inputs.map((q) => inspectQuaternion(q).status), expected);
console.log('PQ-406 PASS 3 / HOLD 2');

验证顺序也很重要。我先执行 node --check 检查脚本语法，再运行构造数据得到退出码与报告，然后比较 PASS/HOLD 计数和每条样本的状态。正常模式会生成完整报告，即使存在 HOLD 也能退出；CI 模式可以约定出现 HOLD 时置 process.exitCode = 2，阻断素材进入重建队列。这个退出码是项目脚本自定义语义，不是系统错误码。日志中的 PQ-406 应贯穿运行、截图示意和报告，否则现场排查会把两个批次混在一起。

状态、异常与边界

如果脚本在读文件时遇到路径不存在或 JSON 语法错误，应当把失败归入“批次不可读取”，不能把它当作某条相机姿态的 HOLD_NORM。数学值不合格和基础设施失败是两条处理通道：前者让美术或采集同事重新导出，后者让构建或交付人员修复路径与格式。处理后保留错误原因，但日志避免打印包含用户个人空间位置的信息。大量输入时可以分批处理，并在报告中保留总数与错误数。

图片里的手机列表是展示离线报告的界面示意。实际工程若在 ArkUI 页面展示，可以把状态映射为文本和颜色，再提供“查看问题记录”的入口；但不应把 Node.js 的文件系统调用直接搬进 ArkTS 页面。

一个额外的测试是交换分量顺序。例如把同一组数从 [x,y,z,w] 误写成 [w,x,y,z]，模长可能仍然等于一，数值门禁就无法识别它。这个失败模式提醒我：数值正确只是合同的一个维度，必须把数据坐标系、旋转方向、单位以及来源版本放在外层元数据中。只有上游和下游对这些字段作出了相同约定，才能解释该姿态的物理意义。对没有坐标合同的旧批次，我宁愿标注“待人工确认”，而不是给它加一个看似安全的自动转换开关。

另一个容易忽略的细节是数组里包含极小的非零值。例如四个分量都在浮点噪声级别，它虽然数学上不是全零，但归一化可能放大噪声。示例使用 1e-6 的近零门禁，具体项目还要结合导出格式精度讨论阈值；如果数据经过定点量化，就更不该照搬这个常数。报告中应持久化规则版本和阈值，使日后升级判断规则后还能重放原批次，解释为什么一组原本通过的输入变成了需要复核。

交付前我会让报告和原始记录同批封存，避免只交一个“绿色通过”的数字。采集素材在工程链路中被多次转换，最怕的不是一次显式失败，而是错误被静默标准化后流入下一环节。预检工具最有价值的地方，是给出清晰的拒绝理由、输入假设和下一步责任边界，而不是代替重建算法做结论。

官方资料：华为 HarmonyOS 空间计算能力（含 3DGS 端侧重建）；华为 HarmonyOS 开发文档中心（Spatial Recon Kit）。这两处资料用于确认产品能力范围。本文示例限定为 Node.js 20+ 的离线自定义质量检查。