@realsee/five/ai_guides/release_notes/6.6.md

Realsee Renderer SDK

# 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）下的显示错误。