HarmonyOS 7 + Spatial Recon Kit-C++：3DGS 输入帧内参与位姿的版本一致性门禁【鸿蒙心迹】

3DGS 重建的输入不只是"一组照片"。每一帧还要与对应的相机内参、位姿和采集顺序保持一致。画面本身清晰、尺寸也满足要求，如果中途切换了相机裁剪策略，却继续沿用旧内参；或者图像与位姿来自相邻两个时刻，系统接口仍可能收到格式完整的数据，最终模型却出现重影、拉伸和局部漂移。

本文用 PoseLatch 演示工程，把问题放在调用 HMS_SpatialRecon_PushFrame 之前解决。示例任务为 RECON-CALIB-0077，会话为 recon_g31。文中的统计是为说明门禁设计准备的演示向量，不代表真实设备跑分；能力支持范围、结构体字段与 SDK 版本以当前官方文档和本地头文件为准。

一、格式合法与语义一致是两回事

官方资料对 3DGS 输入给出了明确边界：开发前检查设备支持；输入图像使用规定尺寸和格式；普通帧需要相机内参以及四元数加平移构成的位姿；所有帧推送完成后再启动重建。它们构成接入的硬边界，却不会替业务决定"这一张图和这一组参数是否真的属于同一采集时刻"。

PoseLatch 的异常样本很典型。采集开始时使用 calib-r4，图像保持 1080 × 1440 RGB。第 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_MISMATCH，1 帧 POSE_NOT_FINITE，1 帧 QUATERNION_NORM，1 帧 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 收敛到一个不可含糊的数据包中，避免后续函数再从多个可变对象临时拼装。

struct IntrinsicsSnapshot {
    double focalX;
    double focalY;
    double principalX;
    double principalY;
    uint32_t revision;
};

struct PoseSnapshot {
    double qx;
    double qy;
    double qz;
    double qw;
    double tx;
    double ty;
    double tz;
    int64_t poseTsNs;
};

struct FrameEnvelope {
    uint64_t sequence;
    int64_t captureTsNs;
    uint32_t width;
    uint32_t height;
    const uint8_t* rgbData;
    size_t rgbBytes;
    IntrinsicsSnapshot intrinsics;
    PoseSnapshot pose;
};

应用层结构的价值是把"同一帧"定义清楚。captureTsNs 与 poseTsNs 都来自同一单调时钟域；如果上游无法保证这一点，不能直接相减，而应先做时钟域转换或改用同源序号。rgbData 的所有权也必须明确：门禁和推帧期间缓冲区保持有效，调用完成后再由生产者回收。

这里没有把示例结构说成 Spatial Recon Kit 的官方结构。通过门禁后，适配层再按当前 SDK 头文件把字段写入 HMS_SpatialRecon_DataFrame。这样既避免编造系统字段，也让应用的质量合同可以独立测试。

易错点是保存"指向当前内参对象的指针"。相机配置变化后，旧帧看到的内容会被新配置覆盖。这里复制四个数值和 revision，确保异步队列中的每个 envelope 都保留采集当时的快照。

四、门禁按不可恢复程度排序

这段代码解决什么问题。 它在进入系统接口之前检查指针、尺寸、字节数、内参 revision、时间配对、有限值、四元数模长与序号单调性，并返回稳定的拒绝码。

enum class GateCode {
    ACCEPTED,
    EMPTY_IMAGE,
    INVALID_SIZE,
    INTRINSICS_REV_MISMATCH,
    PAIR_SKEW_EXCEEDED,
    POSE_NOT_FINITE,
    QUATERNION_NORM,
    FRAME_ORDER_REGRESSION
};

class FrameCoherenceGate {
public:
    explicit FrameCoherenceGate(uint32_t calibrationRevision)
        : calibrationRevision_(calibrationRevision) {}

    GateCode Check(const FrameEnvelope& f) {
        if (f.rgbData == nullptr || f.rgbBytes == 0) return GateCode::EMPTY_IMAGE;
        if (f.width != 1080 || f.height != 1440) return GateCode::INVALID_SIZE;
        if (f.intrinsics.revision != calibrationRevision_) {
            return GateCode::INTRINSICS_REV_MISMATCH;
        }
        const int64_t skew = std::llabs(f.captureTsNs - f.pose.poseTsNs);
        if (skew > 8'000'000) return GateCode::PAIR_SKEW_EXCEEDED;
        if (!PoseIsFinite(f.pose)) return GateCode::POSE_NOT_FINITE;
        const double norm = QuaternionNorm(f.pose);
        if (norm < 0.98 || norm > 1.02) return GateCode::QUATERNION_NORM;
        if (hasLast_ && f.sequence <= lastSequence_) {
            return GateCode::FRAME_ORDER_REGRESSION;
        }
        lastSequence_ = f.sequence;
        hasLast_ = true;
        return GateCode::ACCEPTED;
    }

private:
    uint32_t calibrationRevision_;
    uint64_t lastSequence_ = 0;
    bool hasLast_ = false;
};

排序很重要。空指针和尺寸错误没有继续计算的价值；revision 不匹配意味着整帧语义不属于当前会话；时间偏差超限说明图像与位姿不再是一对；最后才做数学约束。这样诊断码稳定，不会因为一帧同时存在多个问题而随机变化。

四元数模长不在范围内时，本例直接拒绝，而不是静默归一化。轻微浮点误差可以归一化，但明显偏离可能说明字段顺序、内存布局或数据来源错误。自动修复会把输入故障伪装成正常帧。若项目决定允许归一化，也应在诊断里记录 NORMALIZED，并限制可修复区间。

序号只在帧被接受后推进。被拒绝帧不会改变 lastSequence_，后续正常帧仍可继续。门禁自身属于采集会话，不能跨 session 复用；销毁或重新创建 recon_g31 时，序号状态也要一起重置。

有限值检查要覆盖内参和位姿全部标量。focalX、focalY 应为正数，主点应落在可解释范围；平移分量和四元数都不能出现 NaN 或 Infinity。项目还可以根据场景定义相邻帧位移与旋转速度上限，用于发现时间错配，但这类阈值不能凭感觉写死。缓慢扫房间与快速绕拍小物体的运动分布完全不同，应分别建立验收样本。

时间偏差只是配对质量的一部分。即使两个时间戳只差 2 ms，如果它们来自不同单调时钟，数值也没有可比性。FrameEnvelope 的构造点必须证明两个时间属于同一时钟域；否则保存 sourceClockId，并在上游做同步。门禁遇到未知时钟域直接拒绝，不能把"数字很接近"当成同源证据。

五、通过门禁后才调用系统接口

HMS_SpatialRecon_PushFrame 是系统边界，不应该承担应用数据整理。适配层只做两件事：把通过门禁的 envelope 映射到当前 SDK 的数据结构，并记录系统返回码。所有帧推送结束后，先封存采集，再调用 HMS_SpatialRecon_StartSession。

这段代码解决什么问题。 它把"校验、推帧、封存、启动"变成不可逆的阶段，防止启动重建后仍有采集线程继续推送。

class ReconIngress {
public:
    GateCode Push(const FrameEnvelope& envelope) {
        if (phase_ != Phase::CAPTURING) return GateCode::FRAME_ORDER_REGRESSION;
        GateCode code = gate_.Check(envelope);
        if (code != GateCode::ACCEPTED) {
            audit_.RecordRejected(envelope.sequence, code);
            return code;
        }

        HMS_SpatialRecon_DataFrame sdkFrame{};
        FillSdkFrameFromEnvelope(envelope, sdkFrame); // 按本地 SDK 头文件映射
        HMS_SpatialReconStatus status =
            HMS_SpatialRecon_PushFrame(session_, &sdkFrame);
        audit_.RecordPush(envelope.sequence, status);
        return status == SPATIAL_RECON_STATUS_SUCCESS
            ? GateCode::ACCEPTED : GateCode::EMPTY_IMAGE;
    }

    HMS_SpatialReconStatus SealAndStart() {
        phase_ = Phase::SEALED;
        HMS_SpatialReconStatus status =
            HMS_SpatialRecon_StartSession(session_, nullptr, OnFinished);
        if (status == SPATIAL_RECON_STATUS_SUCCESS) phase_ = Phase::RECONSTRUCTING;
        return status;
    }
};

示例用 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_MISMATCH=2、POSE_NOT_FINITE=1、QUATERNION_NORM=1、FRAME_ORDER_REGRESSION=1。红色标注集中在 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/C++）
• Spatial Recon Kit API
• Spatial Recon Kit 官方话题与能力说明