【HarmonyOS 7新能力｜029】3DGS工程封装：把接入逻辑放进可维护的分层结构
3DGS（3D Gaussian Splatting）让多视角图像重建和新视角渲染有了更灵活的表达方式，但工程难点远不止"调用一次重建"。拍摄覆盖不足、模糊帧进入计算、相机位姿失败、资源峰值过高、应用退到后台后仍继续优化，都会让结果不可用。
本文把端侧三维重建拆成采集交互、会话、数据治理、重建编排、资源和呈现六层。文中的类型、阶段与策略是应用侧教学封装，不代表 HarmonyOS 7 官方 3DGS API、算法实现或性能指标；能力范围、硬件条件和接口应以当前 SDK 与华为官方资料为准。图片中的质量数值均为设计示意，不是实测结论。
一、先定义可交付的重建目标
"把物体变成 3D"无法直接验收。第一版应限定对象大小、拍摄距离、环境光、输出用途与最低完整性。例如仅支持静态小型物体，输出用于本机预览，不承诺精密测量，也不处理透明和强反光表面。
验收目标包括：用户获得覆盖引导；明显模糊帧被拒绝；位姿异常时停止并提示补拍；任务可取消；资源超过预算时降级或失败；结果通过完整性检查后才进入预览；原始图像默认不上传。
二、把采集计划变成显式数据
采集不是随手拍一圈。应用应描述目标、推荐视角、已覆盖区域和缺口，形成可恢复的会话。
ts
interface CapturePlan {
sessionId: string
targetName: string
expectedViews: number
elevationBands: ReadonlyArray<'low' | 'middle' | 'high'>
minOverlap: number
}
interface CaptureProgress {
acceptedFrames: number
rejectedFrames: number
missingBands: ReadonlyArray<string>
}expectedViews 和重叠阈值只是产品策略，需根据目标设备与算法实测确定，不能当成通用标准。
三、每张图像都绑定可信元数据
图像需要与拍摄时间、方向、尺寸、焦距信息和会话版本关联。只保存文件路径，后续很难判断它属于哪一次采集或是否已经过旋转。
ts
interface CaptureFrame {
id: string
sessionId: string
revision: number
width: number
height: number
rotation: 0 | 90 | 180 | 270
capturedAt: number
localUri: string
}元数据进入清单，重建任务读取不可变快照。用户补拍后生成新 revision，旧任务的迟到结果不能覆盖新任务。
四、帧质量门禁早于重建
模糊、曝光异常、重复视角和缺少纹理的帧应在重建前识别。质量门禁不需要替代算法，只负责淘汰明确无效输入并给出可操作反馈。
ts
interface FrameQuality {
frameId: string
sharpness: number
exposure: 'low' | 'normal' | 'high'
duplicateOf?: string
accepted: boolean
reasons: ReadonlyArray<string>
}
function canUse(q: FrameQuality): boolean {
return q.accepted && q.exposure === 'normal' && q.duplicateOf === undefined
}阈值由目标设备样本标定，并保留人工复核入口，避免算法误判后用户无法继续。
五、重建流程采用阶段状态机
重建包含输入冻结、位姿估计、初始化、优化、验证和导出。把它压成一个 loading 会导致取消和恢复无从落地。
ts
type ReconstructionStage =
| 'preparing'
| 'estimating-pose'
| 'initializing'
| 'optimizing'
| 'validating'
| 'completed'
| 'failed'
| 'cancelled'
interface ReconstructionJob {
id: string
revision: number
stage: ReconstructionStage
progress: number
checkpointUri?: string
}只有验证通过才能进入 completed。取消是终态，后台回调只能清理资源，不能偷偷恢复执行。
六、分层结构隔离算法变化
采集层提供引导和覆盖反馈；会话层管理状态、取消和进度；数据治理层处理筛帧、元数据与隐私；编排层组织位姿、初始化和优化；资源层控制内存、温控与持久化；呈现层只消费稳定输出。
页面不直接持有重建引擎对象，算法适配器也不修改 UI。未来更换模型或增加云端备选时，业务会话和验收规则仍可复用。
七、算法接入收口为窄接口
ts
interface ReconstructionInput {
jobId: string
manifestUri: string
outputDirectory: string
}
interface ReconstructionArtifact {
sceneUri: string
metadataUri: string
previewUri: string
}
interface ReconstructionPort {
run(input: ReconstructionInput, signal: AbortSignal): Promise<ReconstructionArtifact>
release(): Promise<void>
}适配器把平台错误映射为有限错误码，确保失败时关闭句柄、释放加速资源和临时缓冲区。
八、资源预算是运行时门禁
端侧优化可能持续占用内存、算力和电量。启动前检查可用存储与设备状态，运行中监控内存峰值、温度等级和应用可见性。
ts
interface ResourceBudget {
maxMemoryBytes: number
maxTemporaryBytes: number
maxElapsedMs: number
allowBackground: boolean
}
function deadlineExceeded(startedAt: number, budget: ResourceBudget): boolean {
return Date.now() - startedAt >= budget.maxElapsedMs
}触发预算后应保存安全检查点、降级或明确失败，不能依靠系统强杀来结束。
九、检查点只保存可恢复状态
并非每个内部缓冲区都适合持久化。检查点应包含算法版本、输入清单摘要、阶段、必要参数和已验证的中间产物引用。
ts
interface JobCheckpoint {
jobId: string
algorithmVersion: string
manifestDigest: string
stage: ReconstructionStage
artifactUris: ReadonlyArray<string>
savedAt: number
}恢复前核对版本和输入摘要。不匹配时从安全阶段重新开始，避免把旧中间结果套到新图片上。
十、结果质量需要多维验收
是否能打开预览不是质量通过。至少检查输入覆盖、位姿有效比例、空洞区域、异常漂浮点、目标外区域和多个保留视角的重投影表现。
ts
interface QualityReport {
validPoseRatio: number
uncoveredRegions: ReadonlyArray<string>
artifactWarnings: ReadonlyArray<string>
holdoutChecksPassed: boolean
status: 'passed' | 'needs-more-capture' | 'failed'
}阈值必须来自产品场景和设备实验。报告应允许返回"需要补采"，而不是强行给出成功模型。
十一、隐私和数据保留必须显式
环绕拍摄可能带入人脸、室内环境和文档。默认在本地处理，采集前提示用户清理敏感背景；原始图像、临时文件、检查点和最终模型分别定义保留期限与删除入口。
ts
interface RetentionPolicy {
keepSourceFrames: boolean
deleteTemporaryOnSuccess: boolean
deleteTemporaryOnCancel: boolean
exportRequiresConfirmation: boolean
}日志只记录任务号、阶段、耗时、错误码和资源指标，不记录图片内容与精确环境信息。
十二、用故障注入完成验收
测试覆盖：覆盖不足、连续重复视角、模糊帧、旋转元数据错误、位姿失败、用户中途补拍、任务取消、应用退后台、存储耗尽、内存预算触发、温控降级、检查点版本不匹配、导出失败和删除流程。
还要连续运行多轮任务，确认句柄、内存和临时目录回到基线；对同一输入重复执行时，阶段与报告可复现。只有正常与失败链路都能安全收束，才说明工程封装完整。
3DGS 的体验上限由算法决定，交付下限却由工程边界决定。把采集质量、状态机、算法适配、资源预算、检查点、质量报告和隐私清理纳入同一链路，端侧三维重建才能从一次炫酷演示变成可维护的产品能力。