HarmonyOS 7 / API 26 3DGS 模型首屏黑屏排查：相机、灯光和资源包围盒实战

HarmonyOS 7 / API 26 3DGS 模型首屏黑屏排查：相机、灯光和资源包围盒实战

这个问题比“模型加载失败”更隐蔽

3DGS 或 3D 模型接入时，经常会遇到一种很烦的问题：接口没有报错，模型文件也确实加载了，但页面第一屏就是黑的，或者只看到一小块漂在角落里。开发者第一反应容易去怀疑模型格式，结果查半天发现文件没坏，问题出在相机、灯光、模型包围盒和首帧状态上。

HarmonyOS 7 / API 26 的 3DGS 端侧重建方向，不能只看“模型能不能被加载”。真正在应用里交付时，要看用户第一次进入页面能不能稳定看到主体。首屏看不到主体，后面旋转、缩放、滤镜做得再多也没意义。

我会把这个问题分成四类：

这篇不讨论端侧重建算法本身，只讨论模型已经存在以后，如何让 ArkGraphics 3D 侧的首屏预览稳定下来。

官方能力边界先定住

Spatial Recon Kit 负责 3DGS 相关的重建和资源能力，ArkGraphics 3D 负责把资源放进场景里，提供相机、灯光、节点、材质、动画等能力。也就是说，首屏黑屏这类问题，大多数不应该回头去重跑重建，而应该先检查 3D 场景侧。

一个比较稳的判断顺序是：

1. 文件是否存在，大小是否异常；
2. 场景是否初始化成功；
3. 模型是否有包围盒数据；
4. 相机是否对准模型中心；
5. 灯光是否能照亮主体；
6. 首帧是否有加载完成和失败兜底。

7. 案例一：模型加载成功，但相机没对准

   第一个案例很常见：模型资源加载成功，场景也没有报错，但用户看到的是空页面。这种情况下，先不要急着换模型，先把模型的中心点和包围盒打印出来。

   复现步骤

   1. 加载一个模型资源；
   2. 不设置默认相机，只使用引擎默认视角；
   3. 页面打开后观察首屏；
   4. 打印模型中心点、宽高深和相机位置；
   5. 根据包围盒重置相机，再观察首屏是否恢复。

   6. interface Vec3 { x: number; y: number; z: number; } interface ModelBounds { center: Vec3; size: Vec3; radius: number; } interface CameraPose { eye: Vec3; target: Vec3; up: Vec3; } export class CameraPresetBuilder { build(bounds: ModelBounds): CameraPose { const safeRadius = Math.max(bounds.radius, 1); const distance = safeRadius * 2.8; return { eye: { x: bounds.center.x, y: bounds.center.y + safeRadius * 0.45, z: bounds.center.z + distance }, target: bounds.center, up: { x: 0, y: 1, z: 0 } }; } }

      这段代码的核心是用模型包围盒反推相机位置。很多黑屏问题不是模型没有加载，而是相机离得太远、太近，或者根本没有看向模型中心。

      页面里要保留首帧状态

      type FirstFramePhase = 'idle' | 'loading' | 'visible' | 'empty' | 'failed'; interface FirstFrameState { phase: FirstFramePhase; message: string; bounds?: ModelBounds; } export class FirstFrameProbe { private state: FirstFrameState = { phase: 'idle', message: '' }; start(): void { this.state = { phase: 'loading', message: '正在准备 3D 首帧' }; } visible(bounds: ModelBounds): void { this.state = { phase: 'visible', message: '模型首帧已显示', bounds }; } empty(reason: string): void { this.state = { phase: 'empty', message: reason }; } failed(error: Error): void { this.state = { phase: 'failed', message: error.message }; } snapshot(): FirstFrameState { return { ...this.state }; } }

      这里不要只写一个 loading。首帧问题需要分清“加载中”“已显示”“空画面”“失败”。这四种状态给用户看到的 UI 不一样，给开发者看的日志也不一样。

      案例二：模型在，但灯光和背景让它看起来像没显示

      第二个案例也很常见：模型确实在场景里，但颜色很暗，背景也暗，最后用户看到的是一片黑。这个时候继续改资源路径没有用，要处理默认灯光和背景。

      复现步骤

      1. 使用深色背景；
      2. 加载一个暗色模型；
      3. 不配置环境光和主光源；
      4. 打开页面观察首屏；
      5. 加入默认环境光、主光源和轮廓光；
      6. 再观察模型边缘和主体是否可见。

      7. type LightRole = 'ambient' | 'key' | 'rim'; interface LightPreset { role: LightRole; intensity: number; color: string; direction?: Vec3; } export class SceneLightPresetFactory { buildDefault(): LightPreset[] { return [ { role: 'ambient', intensity: 0.35, color: '#FFFFFF' }, { role: 'key', intensity: 0.9, color: '#FFF7ED', direction: { x: -0.4, y: -0.8, z: -0.2 } }, { role: 'rim', intensity: 0.45, color: '#93C5FD', direction: { x: 0.5, y: -0.2, z: 0.8 } } ]; } }

         我会保留三层光：环境光保证整体不黑，主光源保证主体有明暗关系，轮廓光保证模型边缘能从背景里分出来。不是所有项目都需要复杂灯光，但默认灯光不能没有。

         首帧验收不要只靠肉眼

         interface FirstFrameCheckResult { hasAsset: boolean; hasBounds: boolean; cameraReady: boolean; lightReady: boolean; message: string; } export class FirstFrameChecker { check(asset: SpatialAsset, bounds: ModelBounds | undefined, camera: CameraPose | undefined, lights: LightPreset[]): FirstFrameCheckResult { if (!asset.localUri || asset.byteSize <= 0) { return { hasAsset: false, hasBounds: false, cameraReady: false, lightReady: false, message: '模型资源无效' }; } if (!bounds || bounds.radius <= 0) { return { hasAsset: true, hasBounds: false, cameraReady: false, lightReady: false, message: '模型包围盒异常' }; } if (!camera) { return { hasAsset: true, hasBounds: true, cameraReady: false, lightReady: false, message: '默认相机未设置' }; } if (lights.length === 0) { return { hasAsset: true, hasBounds: true, cameraReady: true, lightReady: false, message: '缺少默认灯光' }; } return { hasAsset: true, hasBounds: true, cameraReady: true, lightReady: true, message: '首帧检查通过' }; } }

         这个检查器的作用是把“看起来没显示”变成几个可以判断的条件。资源、包围盒、相机、灯光只要有一个没准备好，就不要把页面当成成功态。

         推荐的接入结构

         我会把 3DGS 预览页拆成四个小模块：

         模块	负责内容	不负责内容
         SpatialAssetRepository	资源路径、大小、格式、封面图	相机、灯光、页面布局
         CameraPresetBuilder	根据包围盒生成默认相机	模型加载、重建会话
         SceneLightPresetFactory	生成默认灯光组合	页面状态和用户交互
         FirstFrameChecker	判断首屏是否真的可见	修复模型文件本身

         这四个模块单独看都不复杂，但组合起来能解决很多首屏问题。后面换模型、换设备、换横竖屏，也不用每次都从页面里复制一堆判断。

         export class SpatialPreviewBootstrap { private cameraBuilder = new CameraPresetBuilder(); private lightFactory = new SceneLightPresetFactory(); private checker = new FirstFrameChecker(); async prepare(asset: SpatialAsset, scene: ThreeDSceneController): Promise<FirstFrameCheckResult> { await scene.init('spatial-preview-surface'); await scene.loadAsset(asset); const bounds = await this.readBounds(asset); const camera = this.cameraBuilder.build(bounds); const lights = this.lightFactory.buildDefault(); await scene.applyDefaultCamera(); await scene.applySoftLight(); return this.checker.check(asset, bounds, camera, lights); } private async readBounds(asset: SpatialAsset): Promise<ModelBounds> { return { center: { x: 0, y: 0, z: 0 }, size: { x: 1.2, y: 1.8, z: 1.2 }, radius: 1.2 }; } }

         这里的代码不是要替代官方接口，而是给接入结构定边界。实际项目里读取包围盒、设置相机、创建灯光都要按当前 SDK 写法接上。结构先稳住，接口替换起来才不乱。

         最后总结

         3DGS 首屏黑屏不要只盯着“模型有没有加载”。更实际的排查顺序是：资源存在、场景初始化、包围盒有效、相机对准、灯光可见、失败有兜底。

         HarmonyOS 7 / API 26 的 3DGS 能力很适合做空间展示，但越是新能力，越不能只追一个成功截图。首屏预览是用户接触 3D 内容的第一秒，这一秒如果黑屏、偏移、太暗或者没兜底，后面的交互都白搭。把相机、灯光和首帧检查做成可复用模块，后续接不同模型、不同设备和不同页面都会稳很多。