Resource Loading Progress (资源加载进度)

• Summary: 监控 3D 模型与全景图的加载状态和实时进度。
• Schema: Model, Tile, PanoTextureEvent
• Concepts: Loaded vs Refined, Level of Detail (LOD), Panorama Lifecycle
• Configuration: minLevelOfDetail, maxScreenSpaceError
• Examples: 状态检查、进度监听、生命周期事件

Schema

Definition: Model, Tile, PanoTextureEvent

Concepts

在 3D Tiles 模型（如 Five 的 Work 模型）中，"加载" 分为两个阶段：

1. Loaded (初步加载完成):

   • 表示模型已经加载了足够用于显示的基础数据。
   • 受 minLevelOfDetail 参数影响。只有当满足最小 LOD 要求的 Tile 加载完毕后，loaded 才会变为 true。
   • 通常作为 "首屏加载完成" 的标志，此时模型可能还比较模糊。

2. Refined (细化完成):

   • 表示模型在当前视角下，已经加载了所有必要的高清数据，达到了最佳渲染效果。
   • 受 maxScreenSpaceError 参数影响。该值越小，需要的 Tile 精度越高，细化完成所需的时间越长。
   • 这是一个动态状态。当相机移动时，可能会因为需要加载新的高清分块而从 refined: true 变为 false。

Instance Properties

Model Status

Property	Type	Description
five.model.loaded	boolean	检查模型是否已完成初步加载 (Loaded)。
five.model.refined	boolean	检查模型是否已完成细化 (Refined)。
five.model.refineProgress	[number, number]	细化进度元组 [current, total] (已加载/总需加载)。

Examples

1. Model Loading (模型加载)

检查当前状态 (State Checking)

if (five.model.loaded) {
  console.log("Model is ready (basic data loaded)!");
}

if (five.model.refined) {
  console.log("Model is fully refined (high-res data loaded)!");
}
Copy

监控细化进度 (Refine Progress)

five.model.refineProgress 提供了当前视图下模型细化的整体进度。

const [current, total] = five.model.refineProgress;
console.log(`Model Refine Progress: ${current} / ${total}`);

if (current === total && total > 0) {
  console.log("Model is fully refined for current view.");
}
Copy

监听加载完成事件

five.on("modelLoaded", () => {
  console.log("Model has been loaded.");
});
Copy

(Advanced) Tile 级别进度

对于 3dtiles 类型的模型，你可以访问具体的 Tile 对象来查看进度。

// 仅示例，通常在调试或特定渲染逻辑中使用
const progress = tile.content.loadProgress; // [0, 1]
Copy

Tile Lifecycle Monitoring (Tile 生命周期监控)

监控单个 Tile 的加载与卸载事件，用于更精细的调试或资源统计。

five.on("model.tileLoad", (tile) => {
  console.log(`Tile loaded: ${tile.debugLabel}, Size: ${tile.content.byteLength}`);
});

five.on("model.tileUnload", (tile) => {
  console.log(`Tile unloaded: ${tile.debugLabel}`);
});
Copy

2. Panorama Loading (全景图加载)

全景图通常在用户移动到某个点位时按需加载。

监听加载进度

使用 pano.texture.progress 事件获取当前全景图的加载进度。

five.on("pano.texture.progress", (event) => {
  const { progress, pano } = event;
  console.log(`Pano ${pano.panoIndex} loading: ${(progress * 100).toFixed(1)}%`);
});
Copy

生命周期事件

• pano.texture.load: 开始加载。
• pano.texture.success: 加载完成。
• pano.texture.error: 加载失败。

five.on("pano.texture.load", (event) => {
  console.log(`Started loading pano ${event.pano.panoIndex}`);
});

five.on("pano.texture.success", (event) => {
  console.log(`Finished loading pano ${event.pano.panoIndex}`);
});

five.on("pano.texture.error", (event) => {
  console.error(`Failed to load pano ${event.pano.panoIndex}`, event.error);
});
Copy

Related

• Five Class: Five 核心类 API 索引。

---

tags: [加载进度, 加载完成, 首屏, 高清, 细化, 全景加载, 模型加载, loading, progress, refined, loaded, event, tile-load, loading-bar]
Copy