# 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, ImageOptions

### WorkObserver.images

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

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

### ImageOptions

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

    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

### 查看瓦片数据结构

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

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

    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: 了解不同模态下 Work 数据的表现。
- ImageOptions: 了解图片加载配置选项。

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