@realsee/five 6.8.0-alpha.0 → 6.8.0-alpha.10

package/ai_guides/features/work.md

@@ -0,0 +1,303 @@
+# Work (VR 数据实体)
+
+- **Summary**: Work 是 Five 中最核心的数据实体，代表一个完整的 VR 项目，包含渲染场景所需的所有资源与配置。
+- **Schema**: 包含 Observer, Model, Initial 等核心数据的接口。
+- **Concepts**: Work Entity, Observer, WorkCode, Parsing。
+- **Examples**: 数据加载、访问与多 Work 管理。
+
+## Schema
+
+> **Definition**: [Work](../../five/work/work.d.ts), [LooseWork](../../five/work/looseWorkType.d.ts), [WorkJson](../../five/work/workJsonType.d.ts)
+
+`Work` 及其相关核心接口定义如下：
+
+```ts
+import * as THREE from "three";
+import type { Mode } from "@realsee/five";
+
+type CubeFace = 'up' | 'down' | 'left' | 'right' | 'front' | 'back';
+
+/** Work 实体：VR 项目的根对象 */
+export interface Work {
+  /** 唯一标识 (Work ID) */
+  workCode: string;
+  /** 项目名称 */
+  name: string;
+  /** 资源加载的基础路径 (Base URL) */
+  baseURL: string;
+  /** 数据签发人 */
+  issuer: string;
+  /** 过期时间 */
+  expire: Date;
+  /** 允许访问的安全域名列表 */
+  allowHosts: readonly string[];
+
+  /** 初始化参数 (默认模态、视角等) */
+  initial: WorkInitial;
+  /** 相对位姿 (用于多 Work 拼接时的坐标变换) */
+  transform: THREE.Matrix4;
+
+  /** 模型参数 (3D 模型资源信息) */
+  model?: WorkModel;
+  /** 全景点位信息 (所有可观测点位的列表) */
+  observers: readonly WorkObserver[];
+}
+
+/** 观察点：空间中可驻足观看的点位 */
+export interface WorkObserver {
+  /** 所属 Work 引用 */
+  work: Work;
+  /** 在 observers 数组中的索引 */
+  index: number;
+  /** 点位序号 (通常与 index 相同) */
+  panoIndex: number;
+  /** 点位唯一 ID (通常格式为 `${workCode}[${panoIndex}]`) */
+  panoId: string;
+
+  /** 点位是否激活可用 */
+  active: boolean;
+  /** 点位是否可加载 */
+  loadable: boolean;
+
+  /** 点位所在楼层索引 */
+  floorIndex: number;
+
+  /** 点位在模型坐标系下的观察位置 (用于渲染相机位置) */
+  position: THREE.Vector3;
+  /** 点位在模型坐标系下的地面位置 (用于导航和 UI 定位) */
+  standingPosition: THREE.Vector3;
+  /** 点位和模型的旋转对齐四元数 */
+  quaternion: THREE.Quaternion;
+  /** 点位和模型的旋转对齐矩阵 */
+  matrix: THREE.Matrix4;
+
+  /** 可连通的相关点位序号 (用于全景游走) */
+  accessibleNodes: readonly number[];
+
+  /** 点位全景图资源信息 */
+  images: WorkImage;
+
+  /** 获取点位的全局坐标 */
+  getWorldPosition(this: WorkObserver): THREE.Vector3;
+
+  /** 获取点位的全局地面坐标 */
+  getWorldStandingPosition(this: WorkObserver): THREE.Vector3;
+
+  /** 将方向向量转化为全景图 uv */
+  vectorToEquirectangularUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector2;
+  /** 将全景图 uv 转化为方向向量 */
+  equirectangularUvToVector(uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
+  /** 将方向向量转化为获六视图 uv */
+  vectorToCubemapUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): [cubeFace: CubeFace, cubemapUv: THREE.Vector2];
+  /** 将六视图 uv 转化为方向向量 */
+  cubemapUvToVector(cubeFace: CubeFace, uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
+}
+
+/** 初始化位姿参数 */
+export interface WorkInitial {
+  work: Work;
+  /** 模态 */
+  mode?: Mode;
+  /** 点位序号 */
+  panoIndex?: number;
+  /** 相机水平角 */
+  longitude?: number;
+  /** 相机俯仰角 */
+  latitude?: number;
+  /** 相机可视角度（垂直）*/
+  fov?: number;
+  /** 相机观察点位置 [x, y, z] */
+  offset?: THREE.Vector3;
+  /** 相机距离观察点距离 */
+  distance?: number;
+}
+
+/** 模型数据 */
+export interface WorkModel {
+  /** work */
+  work: Work;
+  /** 模型文件地址 at3d / domez */
+  file?: string;
+  /** 模型贴图文件地址 */
+    textures?: readonly string[];
+  /** 模型贴图文件地址的父目录 */
+  textureBase?: string;
+  /** 指定上方向，对于 obj， ply 等定义不明确的需要指定上方向 */
+  upAxis?: string;
+  /** 3d tile */
+  layers: readonly WorkModelLayer[];
+}
+
+/** 模型图层信息 */
+export interface WorkModelLayer {
+  /** work */
+  work: Work;
+  /** 模型类型 point_cloud mesh gaussian_splatting */
+  type: 'point_cloud' | 'mesh' | 'gaussian_splatting';
+  /** 模型名称 */
+  name: string;
+  /** 指定上方向 */
+  upAxis: string;
+  /** tileset.json 地址 */
+  tileset: string;
+}
+
+/** 全景图资源信息 */
+export interface WorkImage {
+  work: Work;
+  /** 分辨率表 */
+  sizeList: readonly number[];
+  /** 瓦片信息 */
+  tiles: readonly WorkTile[];
+  /** 缩略图/预览图等 */
+  [key: string]: any;
+}
+```
+
+## Concepts
+
+### Work Entity (项目实体)
+Work 是 Five 渲染内容的基石。它不仅包含资源地址，还包含空间结构数据。由于数据通常带有数字签名（防止篡改），开发者**不应手动修改** Work 对象中的属性，尤其是资源路径和坐标数据。
+
+### Data Types (数据类型)
+Five 中有三种与 Work 相关的类型，它们分别对应不同的使用场景：
+
+*   **LooseWork (宽泛数据)**:
+    *   **来源**: 通常是服务端下发的原始 JSON 数据。
+    *   **特点**: 结构宽松，允许缺省值（如使用默认模态）、简写（如 URL 模板）和非标准类型（如数组表示向量）。
+    *   **用途**: 作为 `parseWork(json)` 的输入。
+*   **Work (运行时实体)**:
+    *   **来源**: 由 `parseWork` 解析生成。
+    *   **特点**: 结构严谨，数据已标准化（如 URL 已补全，向量转为 `THREE.Vector3`），且被冻结（不可变）。
+    *   **用途**: Five 内部渲染使用的核心对象，传给 `five.load(work)`。
+*   **WorkJson (标准序列化)**:
+    *   **来源**: 由 `workToJson(work)` 生成。
+    *   **特点**: 纯 JSON 结构，去除了运行时对象（如 THREE.Vector3），但保留了标准化的数据结构。
+    *   **用途**: 用于数据持久化存储或跨端传输。
+
+### Layers vs File (数据源关系)
+
+`WorkModel` 提供了两种定义模型数据的方式，其中 `layers` 是现代标准，`file` 主要用于兼容旧数据或简单场景。
+
+*   **`layers`**: (推荐) 数组结构，用于定义多层级、多类型的模型资源。
+    *   支持 **3DTiles** 格式的分块加载。
+    *   支持多种类型混合：`mesh` (模型), `point_cloud` (点云), `gaussian_splatting` (高斯泼溅)。
+    *   **默认行为**: 列表中的所有图层默认都会被加载并显示。
+*   **`file`**: (兼容) 字符串路径，用于定义单文件的 Mesh 模型。
+    *   仅支持部分格式（如 `.at3d`, `.obj`, `.glb`）。
+    *   不支持点云或高斯泼溅。
+
+**加载优先级与兼容逻辑 (Fallback)**:
+
+Five 在运行时会将 `file` 视为一个虚拟的 `mesh` 图层。加载逻辑如下：
+
+1.  **优先加载 Layers**:
+    Five 会遍历 `work.model.layers` 并加载其中定义的所有图层（包括 Mesh, PointCloud, GaussianSplatting 等）。
+
+2.  **File 的条件加载**:
+    检查当前已加载的图层中是否存在 `type: 'mesh'` 的图层。
+    *   **存在 Mesh 层**: 忽略 `work.model.file` 字段（认为 `layers` 已经提供了更高精度的模型）。
+    *   **不存在 Mesh 层**: 如果 `work.model.file` 有值，Five 会自动创建一个临时的 Mesh ViewLayer 来加载该文件。
+
+
+
+### Observer (观察点)
+Observer 是 VR 空间中预设的观察位置。在 **Panorama (全景)** 模式下，相机必须停留在某个 Observer 上。
+*   **position**: 相机镜头的物理位置。
+*   **standingPosition**: 对应的地面位置（脚底）。通常用于下绘制点位图标，或计算点位间的导航距离。
+*   **accessibleNodes**: 定义了该点位可以“走到”哪些相邻点位，构成了全景游走的图结构。
+
+### WorkCode (唯一标识)
+`workCode` 是 Work 的全局唯一标识符。
+*   **单 Work 场景**: 通常不需要显式关注。
+*   **多 Work 场景**: 当 Five 同时加载多个 Work（如拼接的大型空间）时，必须通过 `workCode` 来区分不同 Work 下的同名属性（如 `panoIndex`）。
+
+### Parsing (数据解析)
+从服务端获取的原始 JSON 数据（LooseWork）可能包含相对路径或简写。`parseWork` 函数负责将其标准化为严格的 `Work` 对象，处理 URL 拼接、默认值填充和数据校验。
+
+## Examples
+
+### 1. 解析与加载 Work
+最基础的用法是从 API 获取数据并加载。
+
+```ts
+import { Five, parseWork } from "@realsee/five";
+
+const five = new Five();
+five.appendTo(document.getElementById("app"));
+
+// 1. 获取数据
+fetch("https://vrlab-public.ljcdn.com/release/web/work.json")
+  .then(res => res.json())
+  .then(json => {
+    // 2. 解析数据
+    const work = parseWork(json);
+    // 3. 加载到 Five
+    five.load(work);
+  });
+```
+
+### 2. 访问 Work 数据
+加载完成后，可以通过 `five.work` 访问当前数据。
+
+```ts
+// 获取所有观察点
+const observers = five.work.observers;
+
+// 获取当前所在的观察点
+const currentPanoIndex = five.state.panoIndex;
+const currentObserver = observers[currentPanoIndex];
+
+console.log("当前点位坐标:", currentObserver.position);
+console.log("可通往的点位:", currentObserver.accessibleNodes);
+```
+
+### 3. 多 Work 加载与管理
+Five 支持同时加载多个 Work，常用于楼盘小区的多个样板间拼接，或大型商业空间的区域拼接。
+
+```ts
+const work1 = parseWork(json1);
+const work2 = parseWork(json2);
+
+// 同时加载两个 Work
+five.load([work1, work2]);
+
+// 切换到指定 Work 的指定点位
+five.setState({
+  mode: "Panorama",
+  workCode: work2.workCode, // 必须指定 workCode
+  panoIndex: 0
+});
+```
+
+### 4. 追加与替换 Work
+可以使用 `load` 方法的参数来控制是替换当前场景还是追加到当前场景。
+
+```ts
+const work3 = parseWork(json3);
+
+// 追加 Work (保留原有场景)
+// 第二个参数 "inherit" 表示保持当前相机视角和模态不变，不重置为新 Work 的初始视角
+five.load(work3, "inherit", { mode: "add" });
+
+// 替换 Work (清空原有场景) - 默认行为
+five.load(work3, "inherit", { mode: "replace" });
+```
+
+## Common Pitfalls
+
+*   **数据不可变性**: Work 数据包含签名信息，直接修改 `work.observers[0].position.x = 100` 虽不会报错，但可能导致渲染异常或签名验证失败。请视 Work 为只读对象。
+*   **坐标系**: Five 使用 **Y-Up 右手坐标系**，单位为**米**。与 Three.js 默认坐标系一致。
+*   **跨域问题 (CORS)**: `baseURL` 指向的资源服务器必须配置正确的 CORS 头，否则 WebGL 无法加载纹理。
+*   **parseWork 必选**: 永远不要尝试手动构造 `Work` 对象，总是使用 `parseWork`。服务端数据结构可能会升级，`parseWork` 会处理兼容性。
+
+## Related
+
+*   [State](./state.md): 了解如何通过 State 切换点位。
+*   [Mode](./mode.md): 了解不同模态下 Work 数据的表现。
+
+---
+
+```yaml
+tags: [work, core, entity, observer]
+```

package/ai_guides/glossary.md

@@ -0,0 +1,93 @@
+# Glossary (术语表)
+
+- **Summary**: Five SDK 中的核心术语定义与解释。
+- **Audience**: 开发者、AI 助手。
+
+## Core Entities (核心实体)
+
+### Five
+SDK 的核心入口类。一个 `Five` 实例对应一个 `<canvas>` 渲染上下文，负责管理场景生命周期、渲染循环、用户交互和状态更新。
+
+### Work
+VR 看房的**运行时实体**。通常指经过 `parseWork` 解析后生成的标准化数据对象。
+- **LooseWork**: 服务端下发的原始 JSON 数据，结构较宽松。
+- **WorkJson**: `workToJson` 生成的标准序列化数据，用于存储。
+- **包含内容**: Observers, Panorama, Model, Plan 等。
+
+### Vertex Marks (顶点标记)
+在模型顶点上通过 `_feature_id_rsmask` 属性进行的标记。
+- 用于在特定视角（如俯视）下控制 Mesh 的显隐（例如隐藏天花板）。
+- 属于材质配置的一部分。
+
+### Observer
+**观察点**。对应现实空间中拍摄全景图的一个物理位置。
+- 属性包含：位置 (position)、旋转 (quaternion)、关联的全景图信息。
+- 用户在“全景模式”下，实际上是在不同的 Observer 之间跳转。
+
+## State & Coordinates (状态与坐标)
+
+### Mode (模式)
+Five 定义的五种浏览状态：
+1.  **Panorama (全景)**: 第一人称视角，固定在某个点位观察 360° 景象。
+2.  **Floorplan (户型图)**: 2D 顶视视角，查看房屋平面结构。
+3.  **Topview (顶视)**: 3D 俯视视角，可自由旋转查看房屋立体结构。
+4.  **Model (模型)**: 自由漫游视角，可像游戏一样在模型中自由行走（脱离全景点位）。
+5.  **Map (地图)**: 类似 Google Earth 的操作方式，用于大场景鸟瞰。
+
+### Pose (位姿)
+描述相机状态的数据结构。
+- **Panorama 模式下**: 使用球面坐标 `(Longitude, Latitude)` + `Fov`。
+- **其他模式下**: 使用 `(x, y, z)` 坐标或变换矩阵。
+
+### PanoIndex
+**全景索引**。当前所在的 Observer 在 `work.observers` 数组中的下标 (从 0 开始)。
+
+### Fov (Field of View)
+**视场角**。决定了视野的宽窄。
+- 数值越大，视野越广（广角）。
+- 数值越小，视野越窄（长焦/放大）。
+
+## Rendering (渲染)
+
+### Pano Tile (全景瓦片)
+为了在移动端快速加载高分辨率全景图（如 8K/16K），将全景图切分为多个小块（瓦片）。Five 会根据当前视角按需加载可见区域的瓦片。
+
+### Quasi / Mesh
+**三维模型**。通过激光扫描或视觉算法重建的空间几何结构。在 Five 中，全景图贴在几何模型上，从而实现“从全景中看出立体感”的效果。
+
+### G-Buffer / Geometry Buffer
+用于后处理的几何缓冲区，包含深度 (Depth)、法线 (Normal)、ID 等信息，用于实现高级特效（如轮廓线、SSAO）。
+
+### ViewLayer
+管理 `Model` 内部特定 3D 资源（如 Mesh、PointCloud、Gaussian Splatting）的图层。
+- 继承自 `Tile3D`。
+- 拥有独立的 `Parameter` 配置（覆盖上层配置）。
+- 支持可见性控制 (`visible`) 和优先级加载。
+
+### Gaussian Splatting (3DGS)
+一种基于点的 3D 渲染技术，通过各向异性高斯球（Splat）来表示场景。
+- 相比传统 Mesh，能更真实地还原复杂光照和细节。
+- Five 支持 `.spz` 和 `.splat` 格式的 3DGS 渲染。
+
+### 3D Tiles Refinement (细化)
+3D Tiles 加载过程中的状态概念：
+- **Loaded (已加载)**: 瓦片的基本数据已下载并解析，满足最低显示要求 (`minLevelOfDetail`)。
+- **Refined (已细化)**: 瓦片已加载最高质量数据，满足当前视角的屏幕空间误差要求 (`maxScreenSpaceError`)。
+- `five.model.refineProgress` 可用于监控当前视角的细化进度。
+
+## Interaction (交互)
+
+### Raycast (射线检测)
+将屏幕上的 2D 点击坐标转换为 3D 空间中的射线，用于检测用户点击了哪个物体（如点击地面移动、点击标签）。
+
+### Tap / Press / Pan / Pinch
+Five 封装的手势事件：
+- **Tap**: 轻触。
+- **Press**: 长按。
+- **Pan**: 拖拽/平移。
+- **Pinch**: 双指缩放。
+
+---
+```yaml
+tags: [glossary, terminology, definitions]
+```

package/ai_guides/intro.md

@@ -0,0 +1,23 @@
+# Introduction (介绍)
+
+- **Summary**: Five 是贝壳如视提供的三维空间渲染 SDK，基于 Three.js 开发，帮助开发者在浏览器中构建高质量的 VR 看房与空间交互应用。
+
+## Overview
+
+**Five** 提供了丰富的三维空间展示与交互能力，核心功能模块如下：
+
+*   **全景浏览**: 支持高分辨率全景图的高效加载与平滑浏览。详见 [Pano Tile](./features/pano-tile.md)。
+*   **空间漫游**: 支持在三维模型中自由行走、跳转。详见 [Mode](./features/mode.md)。
+*   **模型渲染**: 内置高效的模型加载策略 (3DTile) 与灵活的材质配置。详见 [Model](./features/model.md) 与 [Material](./features/material.md)。
+*   **交互事件**: 完善的事件系统，支持手势、射线检测等。详见 [Event](./features/event.md) 与 [Raycast](./features/raycast.md)。
+*   **状态管理**: 统一的 State 设计，便于状态保存与还原。详见 [State](./features/state.md)。
+
+## Resources
+
+*   [官方网站](https://realsee.com)
+*   [开发者中心](https://open-platform.realsee.com/)
+
+## Related
+
+*   [Quick Start](./quick-start.md): 快速开始指南。
+*   [Browser Support](./support.md): 浏览器兼容性说明。

package/ai_guides/quick-start.md

@@ -0,0 +1,69 @@
+# Quick Start (快速开始)
+
+- **Summary**: 本指南介绍如何安装 Five 并加载一个基础 VR 场景。
+
+## Installation
+
+通过 npm 或 yarn 安装：
+
+```bash
+npm install three@^0.117.1 @realsee/five
+# or
+yarn add three@^0.117.1 @realsee/five
+```
+
+> **注意**: Five 依赖 `three`，请确保安装了兼容的版本。
+
+## Basic Usage
+
+初始化 Five 实例并加载 Work 数据：
+
+```typescript
+import { Five, parseWork } from "@realsee/five";
+
+// 1. 创建 Five 实例
+const five = new Five();
+
+// 2. 挂载到 DOM
+const app = document.getElementById('app');
+if (app) {
+  // 设置容器全屏
+  app.style.width = '100vw';
+  app.style.height = '100vh';
+  five.appendTo(app);
+
+  // 监听窗口大小变化
+  window.addEventListener('resize', () => five.refresh());
+}
+
+// 3. 加载数据 (Work)
+// 这是一个公开测试数据
+const workURL = 'https://raw.githubusercontent.com/realsee-developer/dnalogel/main/open-works/real/80o024DE2xyva3j5BE/work.json';
+
+fetch(workURL)
+  .then(res => res.json())
+  .then(json => {
+    // 解析并加载
+    const work = parseWork(json);
+    return five.load(work);
+  })
+  .then(() => {
+    console.log("模型加载完成");
+  })
+  .catch(err => console.error(err));
+```
+
+## Next Steps
+
+掌握基础用法后，您可以探索更多核心功能：
+
+*   **控制视角与移动**: 了解如何通过代码控制相机。 -> [Five.updateCamera](./features/five.md) / [State](./features/state.md)
+*   **切换模态**: 在全景、模型、平面图之间切换。 -> [Mode](./features/mode.md)
+*   **监听事件**: 响应用户的点击和交互。 -> [Event](./features/event.md)
+*   **视觉调整**: 修改材质参数或开启后处理效果。 -> [Material](./features/material.md) / [Postprocessing](./features/postprocessing.md)
+*   **自定义配置**: 修改图片加载参数或渲染效果。 -> [ImageOptions](./features/image-options.md)
+
+## Related
+
+*   [Five](./features/five.md): Five 类完整 API 说明。
+*   [Work](./features/work.md): 了解 Work 数据结构。

package/ai_guides/release_notes/6.6.md

@@ -0,0 +1,86 @@
+# Release Note 6.6.x
+> 6.6.x 版本发布日志
+
+```shell
+npm install @realsee/five@6.6
+```
+
+## 依赖升级
+> 6.6.0 版本对开发环境依赖进行了较大幅度的升级，以支持更新的特性和更好的开发体验。
+
+- **Node.js**: 升级至 v20。
+- **TypeScript**: 升级至 v5.9.2 (tslib -> 2.8.1)。
+- **Vite**: 升级至 v7.1.2。
+- **Protobufjs**: 升级至 v7.5.3。
+
+## 核心性能优化
+
+### 内存泄漏修复
+针对大模型加载和销毁过程中的内存占用进行了多轮优化：
+- **实例销毁**: 修复了 `five.dispose()` 时，部分 WebGL 资源（纹理、几何体）及事件监听器未被完全释放的问题。
+- **加载过程**: 优化了模型下载和解析过程中临时对象的生命周期管理，解决了材质解析可能导致的内存驻留。
+- **瓦片加载**: 修复了全景图瓦片在特定网络环境下取消请求时可能导致的内存泄漏。
+
+### 射线检测 (Raycaster) 性能提升
+优化了 BVH (Bounding Volume Hierarchy) 射线碰撞检测逻辑，引入了“首个命中即停止”的机制，显著提升了点击交互性能。
+
+- **firstHitOnly**: 在 `THREE.Raycaster` 上扩展了 `firstHitOnly` 属性。当设置为 `true` 时，BVH 遍历算法会在找到第一个满足条件的交点后，利用该交点的距离对后续搜索进行剪枝（Pruning），避免遍历所有可能的交点。这对于点击拾取（Picking）操作有极大的性能提升。
+
+```typescript
+const raycaster = new THREE.Raycaster();
+// 开启首个命中优化
+raycaster.firstHitOnly = true;
+const intersects = five.model.intersectRaycaster(raycaster);
+```
+
+- **floorIndex**: 支持在射线检测时通过 filter 机制快速筛选楼层（需配合上层逻辑）。
+
+### Work 数据结构优化
+- **静态化存储**: 重构了 `Work` 数据解析逻辑 (`workParser`)。使用 `Object.defineProperty` 和 `Object.freeze` 将解析后的 Work 数据及其子对象（如 `Observer`, `Model`）定义为不可变对象。这有助于 V8 引擎进行 Hidden Class 优化，减少内存占用并提升属性访问速度。
+- **解析优化**: 增强了 `work.parse` 的容错能力，优化了对异常数据的处理逻辑。
+- **字段补充**: `work.observers` 中补充了 `panoId` 字段，修复了 `derivedIdStr` 的生成逻辑。
+
+## 新增特性
+
+### ImageBitmap 支持
+支持使用浏览器原生的 `ImageBitmap` API 替代传统的 `HTMLImageElement` 进行纹理加载。`ImageBitmap` 的解码过程可以在后台线程进行，避免了解码大图时阻塞主线程导致的掉帧现象。
+
+```typescript
+import { Five } from "@realsee/five";
+
+// 开启 Native ImageBitmap 支持 (全局配置)
+Five.useNativeImageBitmap = true;
+
+// 之后创建的 Five 实例将自动应用此配置
+const five = new Five({ ... });
+```
+
+### 图片 Exif 旋转支持
+`imageOptions` 新增 `forceUseExifOrientation` 参数。针对部分未在服务端处理旋转的图片，该参数可强制读取并应用图片 Exif 中的 Orientation 信息，确保渲染方向正确。
+
+```typescript
+const five = new Five({
+  imageOptions: {
+    forceUseExifOrientation: true
+  }
+});
+```
+
+### 航拍全景图优化
+优化了航拍全景图（Aerial Panorama）的交互体验，改进了视角限制和过渡效果，使其浏览更加自然顺畅。
+
+## 修复与改进
+
+### 兼容性修复
+- **Safari**:
+  - 修复了 BVH 碰撞检测在 Safari 下可能出现的精度不一致问题。
+  - 禁用 Safari 下的 `image.decode` 调用，修复了由此导致的 WebGL `updateTexture` 失败问题。
+- **微信**: 修复了点云（PointCloud）在微信查看器中因 Shader 兼容性问题导致的显示错误。
+- **High-DPI**: 修复了当屏幕分辨率导致计算出的瓦片尺寸超过 WebGL 材质尺寸上限（`MAX_TEXTURE_SIZE`）时，瓦片渲染黑屏的问题。
+
+### 逻辑修复
+- **moveToPano**: 修复了当目标点位即为当前点位时，`moveToPano` 命令可能被忽略的问题。
+- **交互逻辑**:
+  - 修复了 `panorama` 模式下点击走点可能出现回退的问题。
+  - 修复了 `model` 模式下 `onTapGesture` 回调中获取的 raycaster 状态不正确的问题。
+- **渲染显示**: 修复了全景图瓦片在正交相机（OrthographicCamera）下的显示错误。