@realsee/five
Version:
Realsee Renderer SDK
223 lines (180 loc) • 10.3 kB
Markdown
Release Note 6.8.x
6.8.x 版本发布日志
```shell
npm install @realsee/five@6.8
```
# Gaussian Splatting (3DGS) 支持
Five 现已支持 Gaussian Splatting (3DGS) 渲染管线。这是一种基于点的渲染技术，能够提供高质量的实时渲染效果。
仅在 WebGL2 环境下可用。
## 文件格式支持
1. `.splat` 文档及工具 [GitHub - antimatter15/splat: WebGL 3D Gaussian Splat Viewer](https://github.com/antimatter15/splat)
2. `.spz` 文档及工具 GitHub - [nianticlabs/spz: File format for 3D Gaussian splats. About 10x smaller than the PLY equival](https://github.com/nianticlabs/spz)
3. `.glb` `.gltf` 对应的 KHR_gaussian_splatting, KHR_gaussian_splatting_compression_spz, KHR_gaussian_splatting_compression_spz_2 扩展。
## 支持 3d-tile
通过 3d-tile 标准，使用 glb 作为模型格式。
```json
{
"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 加载
```json
{
"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`）替代字符串拼接。