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
}
Copy

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;
}
Copy

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

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

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

Related

• Mode: 了解不同模态下 Work 数据的表现。
• ImageOptions: 了解图片加载配置选项。

---

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