Release Note 6.8.x

6.8.x 版本发布日志

npm install @realsee/five@6.8
Copy

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

通过 Work 加载

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

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

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

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

模型的射线检测

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）替代字符串拼接。