FMB Viewer

Appearance

加载与流式 ​

viewer.model.load() 负责把 .fmbv 模型装进场景。加载是流式的:结构树骨架先就绪(此时 load() 的 Promise 就 resolve,模型已可交互),几何分块在后台渐进到达。本页演示加载各阶段的事件时序,并给出进度与失败处理的标准写法。

下面的 demo 加载本站示例模型,HUD 上逐项打出各阶段相对 Viewer.create() 的耗时(loading-ms / skeleton-ms / geom-ready / loaded-ms):

可交互 demo · 右上 HUD 显示各加载阶段耗时,鼠标拖拽旋转,空格键 fit在新窗口打开 ↗

核心 API ​

ts
import { Viewer, ViewerError } from "@modelcubes/viewer-core";

const viewer = await Viewer.create(canvas);

viewer.on("model-skeleton-ready", (e) => console.log("骨架就绪", e.nodeCount, "节点"));
viewer.on("model-geom-progress", (e) => console.log(`几何分块 ${e.ready}/${e.total}`));
viewer.on("model-loaded", () => console.log("全部几何到达"));

try {
  await viewer.model.load("/fixtures/demo.fmbv"); // 骨架就绪即 resolve
  viewer.camera.fitView();
} catch (e) {
  if (e instanceof ViewerError) console.error("加载失败:", e.code, e.message);
}

行为要点 ​

  • load 接受五种来源:URL 字符串、URL 对象、Uint8Array、Blob、自定义 Range fetcher,各形态的示例见模型数据 (.fmbv)。URL 形态内部走 HTTP Range 流式拉取。
  • 骨架先行,几何渐进:load() 在 model-skeleton-ready(结构树 + 索引就绪)时 resolve,此时即可取景、选中、查询结构树;几何 LOD 分块继续后台流式加载,期间触发 model-geom-progress(ready / total),全部到达后触发 model-loaded。完整时序见事件系统。
  • 一次成功加载触发 4 个事件:model-loading → model-skeleton-ready → model-geom-progress(多次)→ model-loaded。也可不订阅事件、随时经 viewer.model.loadProgress 拉取进度快照。
  • 再次 load() 会替换当前模型:先卸载旧模型(触发 model-disposed)并取消未完成的旧加载(旧 Promise 以 Cancelled reject),再开始新时序;显式卸载用 viewer.model.unload()。
  • 失败处理只走 Promise reject:失败时 load() reject 一个带 code 的 ViewerError(InvalidModelSource / NetworkFailed / Cancelled 等,见常见错误)。事件清单里的 model-error 是预留通道,当前版本没有发射点,不要依赖它做错误处理。

加载时应用持久化视图(view-on-load) ​

load(source, opts) 的第二参可在加载阶段(骨架就绪)套用一个持久化视图(相机 / 隐藏 / 变换 / 外观 / 显示模式),消除「先 fit 再跳到持久化视图」的首帧闪烁:

ts
await viewer.model.load(modelUrl, { view: { fetch: true, select: 0 }, animateView: false });

opts.view 有三种形态({ state } / { document } / { fetch: true });应用结果经 view-applied 事件回报。.fmbview.json 文档格式、signature.nodeCount 守卫、sidecar URL 推导与各形态用法详见加载时应用视图。

相关 API ​