# Release Note 6.8.x

> 6.8.x 版本发布日志

    npm install @realsee/five@6.8

## Gaussian Splatting (3DGS) 支持

> Five 现已支持 Gaussian Splatting (3DGS) 渲染管线。这是一种基于点的渲染技术，能够提供高质量的实时渲染效果。 仅在 WebGL2 环境下可用。

### 文件格式支持

1. `.splat` 文档及工具 GitHub - antimatter15/splat: WebGL 3D Gaussian Splat Viewer
2. `.spz` 文档及工具 GitHub - nianticlabs/spz: File format for 3D Gaussian splats. About 10x smaller than the PLY equival
3. `.glb` `.gltf` 对应的 KHR_gaussian_splatting, KHR_gaussian_splatting_compression_spz, KHR_gaussian_splatting_compression_spz_2 扩展。

### 支持 3d-tile

> 通过 3d-tile 标准，使用 glb 作为模型格式。

    {
      "asset": {
        "version": "1.0",
      },
      "geometricError": 265.4529731527354,
      "root": {
        "boundingVolume": {
           "box": [
             0.9499778747558594,  3.5037269592285156,    17.48550033569336,
             97.01779174804688,   0.0,                   0.0,
             0.0,                 88.27268981933594,     0.0,
             0.0,                 0.0,                   20.292869567871094
           ]
        },
        "content": {
          "uri": "splat.glb"
        },
        "geometricError": 66.36324328818385,
        "refine": "ADD"
      },
      "transform": [
         1.0,      0.0,      0.0,      0.0,
         0.0,      1.0,      0.0,      0.0,
         0.0,      0.0,      1.0,      0.0,
         0.0,      0.0,      0.0,      1.0
       ]
    }

### 通过 Work 加载

    {
      "work_code": "",
      "model": {
        "layers": {
           "tileset_url": "tileset.json",
           "name": "poincare_3dgs",
           "type": "gaussian_splatting"
        }
      }
    }

### 配置球谐光照阶数 (SH Degree)

可以通过 `five.parameter.gaussianSplattingSHDegree` 设置球谐光照阶数，支持 0, 1, 2 阶，默认为 0 阶。

    const five = new Five({
        parameters: {
            gaussianSplattingSHDegree: 1 // 设置为 1 阶 SH
        }
    });

### 模型的射线检测

gaussian_splatting 的模型同时也支持 rayscast 射线检测。同点云的处理保持一致。但是因为 gaussian_splatting 的射线交点对应的法线方向是一个估算值，精度并不高。请酌情使用。

## glTF 模型支持增强

> 新增了对更多 glTF 扩展的支持，提升了模型的表现力和动画能力。

### 扩展新增及优化

#### KHR_animation_pointer

> KHR_animation_pointer 允许动画通道指向 glTF 资产中任何对象的任何属性。

默认的 animtion 只能修改 node 的 transform 实现节点的平移、旋转和缩放

这个能力可以实现材质动画。比如：

- 通过 uv transform 实现 texture 的移动，变化贴图位置。
- 通过修改 material 上的材质属性，可以动态修改金属粗糙，透明度，自发光程度。
- 通过修改 node 的 KHR_node_visibility 的扩展值，显隐某个节点。
- 等等

#### KHR_node_visibility

> 允许设置节点的可见性属性。 用于 配合 KHR_animation_pointer 实现显隐效果。

#### KHR_materials_clearcoat

> 用于在材质上添加一层透明涂层，模拟车漆、碳纤维、清漆木材等真实世界中的表面效果。

这个能力可以实现材质动画。比如

- 漆面等光滑的表面
- 塑料薄膜
- 等等

#### KHR_materials_transmission

> 物理透光材质扩展，用于实现光线真正穿过物体的透明 / 半透明效果。

这个能力可以实现材质动画。比如

- 玻璃等即透光也反射的表面
- 等等

#### KHR_materials_emissive_strength

> 调整自发光强度

#### KHR_materials_unlit

> 不感光材质 正确解析 KHR_materials_unlit。是否感光作用到对应的 material 上，而不是 gltf 中的所有元素。

### 动画优化

- 处理额外动画骨骼未绑定导致的错误，出现的抖动。
- 修复 glTF 骨骼 weight 为整型时，导致 boneTransform 计算出错进而引发射线检测错误的问题。gltf parser 在加载非 float 数据时，现已自动转换为 float 使用。

## 模型 ViewLayer 加载策略优化

> 优化了 ViewLayer 的加载和显隐逻辑，以减少内存占用并提高性能。

#### 默认加载策略变更

默认情况下，Five 不再加载所有图层，而是根据优先级仅加载一个图层。 优先级顺序：mesh > point_cloud > gaussian_splatting > 其他类型。

#### 显隐与内存管理

- 显示: 当 viewLayer.visible = true 时，开始加载资源。
- 隐藏: 当 viewLayer.visible = false 时，释放该图层占用的所有内存资源。

#### 加载进度

- 新增 tile.content.loadProgress 属性，用于查看每个瓦片的加载进度 (0-1)。
- 新增 tile.content.byteLength 属性，可在加载过程中获取瓦片内容的字节长度。
- 同时，model.tileLoad 和 model.tileUnload 事件被添加，用于监控瓦片的生命周期。
- 加载函数（loadGltf, loadPly 等）现在支持 onDownloadProgress 回调，用于监控文件下载进度。

#### 射线检测增强

- 射线交点 Intersection 对象新增了 tile, model, viewLayer 字段，便于在射线检测时获取更详细的上下文信息。
- raycaster.hitFilter 回调函数的参数类型定义已更新，包含 model, viewLayer, tile 等上下文信息。

## Work 结构改变

### Observer 支持 uv 计算工具函数

为 WorkObserver 提供了更多实用的工具函数，便于进行坐标和 UV 转换。 UV 转换工具函数

- observer.vectorToEquirectangularUv: 将方向向量转化为全景图 uv。
- observer.equirectangularUvToVector: 将全景图 uv 转化为方向向量。
- observer.vectorToCubemapUv: 将方向向量转化为立方体贴图 uv。
- observer.cubemapUvToVector: 将立方体贴图 uv 转化为方向向量。

### five.panoId

新增 `five.panoId` 属性，使其与 `work.observer` 保持一致。

### derived_id 类型变更

derived_id 的类型从 `number` 改为 `number | string`。

## 全景图滤镜

新增了全景图滤镜功能，支持实时调整全景图的亮度、对比度、饱和度、色温和色调等参数。

通过 `five.modelScene.parameter.set('panoFilter', filter)` 绑定。 支持的参数如下：

- color: 颜色调整，包含色温 (Temperature) 和色调 (Tint)。
- highlightShadow: 高光和阴影的独立调节。包括高光 (Highlight) 和阴影 (Shadow) 全局（Global）。
- contrast: 对比度调整。
- saturation: 饱和度调整。

## 新增后处理效果 (Post-Processing Passes)

新增了三个可选的内置后处理 Pass，用于增强视觉效果。

- FlowingLight2DPass: 2D 流光效果，通常用于在屏幕空间绘制流动的光线（如道路流光）。
- FlowingLight3DPass: 3D 流光效果，基于深度缓冲区在三维模型表面绘制流光。
- GaussianBlurPass: 高斯模糊效果，可用于实现毛玻璃等视觉特效。

## 工具优化

### Work Viewer

> https://vradmin.lianjia.com/project/

- 支持 debug -> stateSync。可以打开两个页面，均开启 stateSync。两边同步相机状态。
- 支持 work.json 拖拽加载加载。

### Model Viewer

> https://vradmin.lianjia.com/poincare/

- 支持 debug -> stateSync。可以打开两个页面，均开启 stateSync。两边同步相机状态。
- 支持 模型文件拖拽加载加载。

### glTF Viewer

> https://vradmin.lianjia.com/gltf/

- 支持 debug -> stateSync。可以打开两个页面，均开启 stateSync。两边同步相机状态。
- 支持 模型文件拖拽加载加载。
- 支持 额外绑定动画文件（仅读取 gltf 的 animations 的部分，并绑定到当前的模型上）。
- 支持 额外绑定动画的单独播放和暂停。

## 友好文档

全面重构了文档结构，使其更适合 AI 辅助编程工具 (如 Cursor, Copilot) 阅读和索引。

- 文档目录迁移至 ai_guides/，并在 package.json 中新增 ai 字段指向该目录。
- 文档内容包含源码链接 (source 字段)，直接指向对应的 .ts 定义文件。
- 提供了更清晰的 API 定义和概念说明，例如新增了 ViewLayer 的详细文档。
- TypeScript 支持: 优化了 .d.ts 打包方式，声明文件现在与源码文件一一对应，提升了 IDE 的跳转体验。

## 其他

1. 优化 mapview 下滚动缩放。避免滚落所发有时会退回的问题。
2. 优化 floorplan 从下向上看时的交互的屏幕上下滑动反人类下意识的问题。
3. 优化 camera.autoNearFar 的计算结果。优化对于小物品的 near 过远以及 出现 z-fighting 的问题。
4. 添加了 gesture.fire 事件，发生在任意事件被触发。
5. gestureEvent.center gestureEvent.pointers 中加入了 buttons button shiftKey ctrlKey metaKey altKey 字段。
6. 修复 gesture.momentum 前没有触发 gesture.create 的问题。
7. 修复 gesture.pan 中 preventDefault 无法阻止触发 gesture.momentum 的问题。
8. 修复 gesture.pan 中第一次并没有 event.isFirst = true 的问题。
9. 添加自定义着色器 mainPanoColor 插入点，可以修改 pano0Color、pano1Color。
10. 新增 `parameter.resolveValue('xxx')` 快速获取单个参数的最终值，无需创建完整的 `ResolvedParameterValue` 对象。
11. 新增 `pano.prepare` 事件（ExtendableEvent），支持通过 `waitUntil(promise)` 在点位切换前插入异步操作。`PanoEvent` 和 `PanoPrepareEvent` 新增 `pano` 字段，包含目标点位信息。
12. `PanoPrepareEvent` 新增 `options`（`MovePanoOptions`）和 `prevMode`（`Mode`）字段。`options` 可在回调中直接修改（如修改 `effect`、`duration`、`longitude`、`latitude`、`fov` 等），修改后的值将影响实际的点位切换行为。

## 内部机制改动

1. glTF 加载 mesh / points 都将直接使用 PBM 材质，而不是作为 PBM_Mesh 扩展形式去替换覆盖使用three内置材质的方式。
2. 应用 animation pointer 以及 动画优化的原因。目前会重写 hack THREE.PropertyBinding.findNode。
3. 打包不再合并 .d.ts 文件。便于文档可以更便于找到对应的类型声明。
4. Parameter 性能优化：新增 `resolveValueTo` 支持对象复用以减少 GC，版本标识改用整数哈希（`versionNumber: number`）替代字符串拼接。