@realsee/five/ai_guides/features/pano-tile.md

Realsee Renderer SDK

# Panorama Tile

- **Summary**: 全景模式下的瓦片加载策略，支持多分辨率层级（LOD）和视锥体裁剪，以优化全景浏览的性能和清晰度。
- **Schema**: WorkTile 接口及相关配置参数。
- **Concepts**: LOD (Level of Detail), Frustum Culling, Tile URL Generation.
- **Configuration**: tileLevelForFov, tileMaxRequest, imageOptions.
- **Examples**: 瓦片数据结构查看与 Five 初始化配置。

## Schema

> **Definition**: [WorkImage](../../five/work/work.d.ts), [ImageOptions](../../five/types/imageOptions.d.ts)

### WorkObserver.images
点位全景图数据结构，包含瓦片列表。

```typescript
interface WorkImage {
  /** 分辨率列表 */
  sizeList: readonly number[];
  /** 瓦片信息列表，按 level 排序 */
  tiles: readonly WorkTile[];
  // ... 其他基础图片 URL
}
```

### ImageOptions
全景图及瓦片的图片处理配置。

```typescript
interface ImageOptions {
  /** 图片尺寸参数 (例如 512, 1024...) */
  size?: number;
  /** 图片质量参数 (0-100) */
  quality?: number;
  /** 图片格式参数 */
  format?: "jpg" | "jpeg" | "png" | "heif" | "heic" | "webp" | "avif";
  /** URL 转换函数 */
  transform?: (url: string, options: ImageURLOptions) => string;
}
```

## Concepts

### Tile Parsing (瓦片解析)
在 `Five` 加载 `Work` 数据时，`WorkParser` 会解析 `panorama.size_list` (或 `panorama.tiles`) 字段。
- **Level 计算**: `level = log2(size / 512)`。
- **URL 生成**:
  - 如果 `size > baseSize` (通常是初始全景图大小)，URL 中的 `/cube_{size}/` 部分会被动态替换（通过 `replaceImageSize` 函数）。
  - 如果 `size <= baseSize`，直接使用基础全景图 URL，并设置 `scale`。
- **排序**: 解析后的 `tiles` 数组会按 `level` 升序排列。

### sizeList
- **类型**: `readonly number[]`
- **说明**: 包含所有可用的分辨率（以像素为单位）。
- **示例**: `[2048, 6144]` 表示该点位全景图有两个层级，分别是 2048px 和 6144px。
- **图片路径**: 每个层级的图片路径都是 `cube_{size}`，`{size}` 是层级分辨率，必须与 `sizeList` 中的值对应。并必须存在 2048px 层级的图片。

### Level of Detail (LOD) & Loading Strategy
`PanoramaController` 使用 `Tiling` 类来管理瓦片加载：
- **LOD 选择**: 根据当前的视场角 (`FOV`) 和视图大小 (`viewSize`)，计算所需的最佳瓦片层级。默认策略会优先保证画面清晰度，同时考虑网络开销。
- **视锥体裁剪 (Frustum Culling)**: 仅加载当前相机视锥体可见范围内的瓦片面。
- **并发控制**: 通过 `tileMaxRequest` 限制同时进行的网络请求数量，避免阻塞。

## Configuration

在初始化 `Five` 时，可以通过 `panorama` 配置参数来配置瓦片加载行为。

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `tileLevelForFov` | `(fov: number, viewSize: Vector2) => number` \| `false` | `undefined` | 自定义函数，用于根据当前 FOV 和视图尺寸决定加载哪个层级的瓦片。返回 `level` 数值。如果设置为 `false`，则禁用动态瓦片加载。默认使用内部策略。 |
| `tileMaxRequest` | `number` | `3` | 最大的瓦片图片并发请求数。增加此值可能加快加载速度，但也可能导致网络拥塞。 |
| `imageOptions` | `ImageOptions` | `undefined` | 全景图及瓦片的图片处理配置。可用于全局控制图片的加载格式（如强制使用 WebP）、质量压缩比例或通过 `transform` 函数自定义图片 URL。 |

## Examples

### 查看瓦片数据结构

```typescript
import { Five } from "@realsee/five";

const five = new Five();

five.on("loaded", () => {
  const observer = five.work.observers[0];
  if (observer && observer.images && observer.images.tiles) {
    console.log("Available Tiles:", observer.images.tiles);
    observer.images.tiles.forEach(tile => {
      console.log(`Level: ${tile.level}, Size: ${tile.size}, Scale: ${tile.scale}`);
    });
  }
});
```

### 配置瓦片加载策略与图片参数

```typescript
import { Five } from "@realsee/five";

const five = new Five({
  // 自定义瓦片层级选择策略
  tileLevelForFov: (fov, viewSize) => {
    // 简单示例：FOV 小于 60 度时强制使用 Level 2，否则使用 Level 1
    if (fov < 60) {
      return 2;
    }
    return 1;
  },
  // 限制并发请求数
  tileMaxRequest: 6,
  // 图片加载配置
  imageOptions: {
    // 强制请求 WebP 格式的图片
    format: "webp",
    // 图片质量设置为 80%
    quality: 80,
    // (可选) 自定义 URL 转换逻辑
    // transform: (url, options) => {
    //   return url + `?x-oss-process=image/format,webp/quality,q_80`;
    // }
  }
});
```

## Related
- [Mode](./mode.md): 了解不同模态下 Work 数据的表现。
- [ImageOptions](./image-options.md): 了解图片加载配置选项。

---

```yaml
tags: [全景瓦片, 高清全景, 分片加载, 瓦片, 全景图, 分辨率, 按需加载, pano-tile, observer, LOD, tile]
```