@realsee/five/ai_guides/features/load-progress.md

Realsee Renderer SDK

# 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](../../five/model/index.d.ts), [Tile](../../five/model/tile3d/tile.d.ts), [PanoTextureEvent](../../five/controllers/events.d.ts)

## 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)

```ts
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)!");
}
```

#### 监控细化进度 (Refine Progress)

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

```ts
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.");
}
```

#### 监听加载完成事件

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

#### (Advanced) Tile 级别进度

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

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

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

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

```ts
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}`);
});
```

### 2. Panorama Loading (全景图加载)

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

#### 监听加载进度

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

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

#### 生命周期事件

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

```ts
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);
});
```

## Related

*   [Five Class](../api.md): Five 核心类 API 索引。

---

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