@realsee/five-webgpu 1.0.0-alpha.1

package/ai_guides/release_notes/6.7.md

@@ -0,0 +1,401 @@
+# Release Note 6.7.x
+> 6.7.x 版本发布日志
+
+```shell
+npm install @realsee/five@6.7
+```
+
+## five.laod 的多 Work 的非阻塞性加载
+> `five.load` 时，现在可选择追加或者替换。
+> 并且在切换过程中，可以不再发生切换/锁定视角等妨碍用户持续操作的行为。
+> 这方面的改动只要适用于多项目下，项目追加，分批次加载的情况。
+
+### 使用 `FiveLoadOptions.mode` 在控制 替换 / 追加项目
+
+```ts
+// 替换项目
+// mode: 'replace' 默认
+five.load([parseWork(json1), parseWork(json2)], 'inherit', { mode: 'replace' });
+
+// 追加项目
+// mode: 'add'
+five.load(parseWork(json2), 'inherit', { mode: 'add' });
+```
+
+注意事项：
+- Work 的唯一标识依旧是 `workCode`。 同一场景下，不允许出现两个相同的 `workCode` 的 Work。如果出现会报错处理。
+- 如果通过 `replace` 替换的 Work 的 `workCode` 和当前场景中有一样的（相当于替换一个一样的 Work），则会保留之前的 Work 的模型，直接挂在到新 Work 上，而不是重新加载。
+
+### 重新定义 `state=inherit` 的行为
+
+```ts
+five.load(parseWork(json), 'inherit', { mode: 'add' });
+```
+当 `state=inherit` 时，在切换过程中，可以不再发生切换/锁定视角等妨碍用户持续操作的行为。
+
+- 在模型态：保持当前视角状态
+- 在全景态：如果当前 work 存在则不改变。不存在切换到一个可用的全景点。
+
+## work 更加精简和灵活
+> 针对大项目，对 work 的 json。做精简优化，减少网络传输时间。并且增加灵活性。
+
+### panorama.pattern 模版
+> 通过模版的模式匹配减少重复内容。
+> panoram 中的 hash，index 等参数的重复度很高，对一样的内容可以通过这种方式减少文件长度。
+
+Before:
+```json
+"panorama": {
+  "count": 465,
+  "list": [
+    {
+      "index": 0,
+      "derived_id": 0,
+      "derived_id_str": "auto3d-light-vEY8Zp4lPlkZ7R9K_1735117678",
+      "up": "images/cube_2048/0/0fd265355dbb94cb22fb930e52dd3c19/0_u.jpg",
+      "down": "images/cube_2048/0/0fd265355dbb94cb22fb930e52dd3c19/0_d.jpg",
+      "left": "images/cube_2048/0/0fd265355dbb94cb22fb930e52dd3c19/0_l.jpg",
+      "right": "images/cube_2048/0/0fd265355dbb94cb22fb930e52dd3c19/0_r.jpg",
+      "front": "images/cube_2048/0/0fd265355dbb94cb22fb930e52dd3c19/0_f.jpg",
+      "back": "images/cube_2048/0/0fd265355dbb94cb22fb930e52dd3c19/0_b.jpg",
+      "size_list": [ 2048, 4096 ],
+      "tiles": [ 1, 2, 3 ],
+
+    },
+    {
+      "index": 1,
+      "derived_id": 0,
+      "derived_id_str": "auto3d-light-vEY8Zp4lPlkZ7R9K_1735117799",
+      "up": "images/cube_2048/1/a6ca1991fc6bdb2dbd1a1003d9f62394/1_u.jpg",
+      "down": "images/cube_2048/1/a6ca1991fc6bdb2dbd1a1003d9f62394/1_d.jpg",
+      "left": "images/cube_2048/1/a6ca1991fc6bdb2dbd1a1003d9f62394/1_l.jpg",
+      "right": "images/cube_2048/1/a6ca1991fc6bdb2dbd1a1003d9f62394/1_r.jpg",
+      "front": "images/cube_2048/1/a6ca1991fc6bdb2dbd1a1003d9f62394/1_f.jpg",
+      "back": "images/cube_2048/1/a6ca1991fc6bdb2dbd1a1003d9f62394/1_b.jpg",
+      "size_list": [ 2048, 4096 ],
+      "tiles": [ 1, 2, 3 ],
+    },
+    {
+      "index": 2,
+      "derived_id": 0,
+      "derived_id_str": "auto3d-light-vEY8Zp4lPlkZ7R9K_1735117912",
+      "up": "images/cube_2048/2/567f94406885bf06f5586d7972da2b5e/2_u.jpg",
+      "down": "images/cube_2048/2/567f94406885bf06f5586d7972da2b5e/2_d.jpg",
+      "left": "images/cube_2048/2/567f94406885bf06f5586d7972da2b5e/2_l.jpg",
+      "right": "images/cube_2048/2/567f94406885bf06f5586d7972da2b5e/2_r.jpg",
+      "front": "images/cube_2048/2/567f94406885bf06f5586d7972da2b5e/2_f.jpg",
+      "back": "images/cube_2048/2/567f94406885bf06f5586d7972da2b5e/2_b.jpg",
+      "size_list": [ 2048, 4096 ],
+      "tiles": [ 1, 2, 3 ],
+    },
+    {
+      "index": 3,
+      "derived_id": 0,
+      "derived_id_str": "auto3d-light-vEY8Zp4lPlkZ7R9K_1735118067",
+      "up": "images/cube_2048/3/fa70f0f26594d3023a3824c9a92033da/3_u.jpg",
+      "down": "images/cube_2048/3/fa70f0f26594d3023a3824c9a92033da/3_d.jpg",
+      "left": "images/cube_2048/3/fa70f0f26594d3023a3824c9a92033da/3_l.jpg",
+      "right": "images/cube_2048/3/fa70f0f26594d3023a3824c9a92033da/3_r.jpg",
+      "front": "images/cube_2048/3/fa70f0f26594d3023a3824c9a92033da/3_f.jpg",
+      "back": "images/cube_2048/3/fa70f0f26594d3023a3824c9a92033da/3_b.jpg",
+      "size_list": [ 2048, 4096 ],
+      "tiles": [ 1, 2, 3 ],
+    },
+    ...
+  ]
+}
+```
+
+After:
+```json
+"panorama": {
+  "count": 465,
+  "pattern": {
+    "up": "images/cube_2048/{index}/{hash}/{index}_u.jpg",
+    "down": "images/cube_2048/{index}/{hash}/{index}_d.jpg",
+    "left": "images/cube_2048/{index}/{hash}/{index}_l.jpg",
+    "right": "images/cube_2048/{index}/{hash}/{index}_r.jpg",
+    "front": "images/cube_2048/{index}/{hash}/{index}_f.jpg",
+    "back": "images/cube_2048/{index}/{hash}/{index}_b.jpg",
+    "size_list": [ 2048, 4096 ],
+    "tiles": [ 1, 2, 3]
+  },
+  "list": [
+    {
+      "hash": "0fd265355dbb94cb22fb930e52dd3c19",
+      "derived_id": 0,
+      "derived_id_str": "auto3d-light-vEY8Zp4lPlkZ7R9K_1735117678",
+      "index": 0
+    },
+    {
+      "hash": "a6ca1991fc6bdb2dbd1a1003d9f62394",
+      "derived_id": 0,
+      "derived_id_str": "auto3d-light-vEY8Zp4lPlkZ7R9K_1735117799",
+      "index": 1
+    },
+    {
+      "hash": "567f94406885bf06f5586d7972da2b5e",
+      "derived_id": 0,
+      "derived_id_str": "auto3d-light-vEY8Zp4lPlkZ7R9K_1735117912",
+      "index": 2
+    },
+    {
+      "hash": "fa70f0f26594d3023a3824c9a92033da",
+      "derived_id": 0,
+      "derived_id_str": "auto3d-light-vEY8Zp4lPlkZ7R9K_1735118067",
+      "index": 3
+    },
+    ...
+  ]
+}
+```
+
+### 相对路径
+> 在序列话 Work Json 时。资源的地址，均尝试存储为 `base_url` 的相对地址，减少存储的开销。
+
+- 可以通过 `work.getURL` 获取到完整地址。
+  ```ts
+  // 获取图片地址
+  work.getURL(work.observers[0].image.left);
+  ```
+
+- 可以通过修改 `work.baseURL=` 修改前缀。
+
+### 一些字段的新增、废弃与兼容
+- 现在 accessable_nodes 与 visible_nodes 不再有行为差异。visible_nodes 将废弃。
+- observers[].derived_id 的缺损值不再是 undefiend. 而是 0。
+- observers[].derived_id_str 的缺损值不再是 undefiend. 而是 空字符串。
+- 优化 at3d / pbm 的 material_textures 的参数的各种兼容问题 以及 错误的警告信息。
+
+### model 支持 coordinate 以及 up_axis
+- model.coordinate 同 `tileeset.rootMeta.coordinate`。声明 `file_url` 的世界坐标。
+- model.up_axis 设置 `file_url` 模型的上方向, 仅针对 obj / ply 等自身没有上方向定义的模型格式。
+
+### toJSON 方法
+- 通过 `work.toJSON()` 可以获取到当前序列化后的标准 Work Json。类型为 `WorkJson`
+- 该方法并不是返回当时 `parseWork` 时的 Json。 而是从 work 数据中序列化后的结果。
+- 并不包含 `_signature` `certificate` 等字段。
+
+### work-downloader 的速度优化
+
+- 优化 对于 avif 格式的 cube 图的处理的效率。
+- 优化 全景图片瓦片的切割参数，该有尽有。
+- 优化 图片的清晰度参数，目前均使用 95 最为图片质量。
+
+## 模型优化材质展示, 3d-tile，以及碰撞计算
+
+### glTF 模型材质 与 动画
+> 优化 Gltf PBR 材质渲染。
+> 对技术美术输出的模型，更准确的还原。
+
+- 解决混合底色是白色的问题 从修改 CustomBlending 改为在着色器中处理，所以只有使用 PBM 的材质支持。three 默认材质不处理这个改动。
+- 优化 gltf 骨骼绑定，对于骨骼关联大于 4 的情况，使用前 4 个权重大的骨骼，并归一化。并且考虑通过整形数组 normalize 的情况。
+- 修改 gltf 中对 uv2 copy 的逻辑，添加当检测到有 occlusionTexture 材质时，如果没有 uv2 自动拷贝 uv -> uv2。
+
+### glTF 预览工具
+
+地址： [https://vradmin.lianjia.com/gltf/](https://vradmin.lianjia.com/gltf/)
+
+- 支持加载 线上 / 本地文件。gltf / glb。
+- 支持链接 单独的 gltf / glb 动画文件。
+- 内置了 gltf 官方测试集。[https://github.com/KhronosGroup/glTF-Sample-Assets/](https://github.com/KhronosGroup/glTF-Sample-Assets/)
+- 内置多个环境光照，以及上传自定义环境光照 (.exr)。
+
+### 优化模型碰撞
+
+扩展 threejs 的 Raycaster。 支持多个自定义参数。
+
+```ts
+declare module 'three' {
+
+  export interface Raycaster {
+    /**
+     * 只捕获第一个交点
+     */
+    firstHitOnly?: boolean;
+
+    /**
+     * 对交点进行筛选
+     */
+    hitFilter?: (intersect: THREE.Intersection) => boolean;
+
+    /**
+     * 作用楼层
+     */
+    floorIndex?: number;
+  }
+
+}
+```
+
+- firstHitOnly - 只捕获第一个交点。比获取全部取第一个更快获取到结果。
+- hitFilter - 过滤函数，可以根据逻辑否绝一些交点。配合 firstHitOnly 可以更加匹配业务需求。
+- floorIndex - 过滤楼层。默认为当前显示楼层，-1 为所有楼层。其他数字则定向对应的楼层。
+
+同时一些内部逻辑变化
+
+- 内置事件生成的 Raycaster。均设置 firstHitOnly = true。
+- 交点获取，内置过滤掉了 模型裁剪 clippers 中的内容。
+
+### 3d-tile 支持通过内存上限动态调整 maxScreenSpaceError。
+> 目的是通过有限的内存，获取到最清晰的模型效果。
+
+```ts
+// 设置内存最高缓存到 512 MB
+five.modelScene.parameter.set('maxMemoryUsage', 512);
+
+// 设置 maxScreenSpaceError 到 32
+five.modelScene.parameter.set('maxScreenSpaceError', 32);
+
+// 设置通过内存上限动态调整 maxScreenSpaceError
+five.modelScene.parameter.set('memoryAdjustedScreenSpaceError', true);
+```
+
+当设置的 `maxScreenSpaceError` 已经全部加载完毕后，发现内存空间仍有剩余。则会尝试降低 `maxScreenSpaceError` 知道内存大体到达 `maxMemoryUsage` 设置的水平。
+
+- 如果设置的 `maxScreenSpaceError` 已经全部加载完毕后，内存已经大于 `maxMemoryUsage` 设置的水平则不会变化。
+- 因为是动态尝试， 所以悲观情况下会出现在 `maxMemoryUsage` 附近摆动的情况。导致模型反复加载/销毁。
+- 只针对 layer 生效。多个 layer 是单独计算，并不是综合计算。
+
+## 全景浏览
+
+### moveToPano 新增 effect=model 模型过渡效果
+
+通过过渡到模型实现点位游走效果
+
+```ts
+five.moveToPano(0, {
+  effect: 'model',
+});
+```
+
+目前支持:
+
+- fly - 通过相机移动方式变化
+- instant - 直接变化
+- fade - 通过渐变方式变化
+- montage - 通过渐变穿插到黑屏方式变化
+- spread - 通过扩散方式变化
+- zoomin - 通过放大变化
+- zoomout - 通过缩小变化
+- model - 通过过度到模型
+
+### moveToPano 新增参数 effectEasing 控制前后全景图的切换进度
+
+```ts
+function easeInQuad(x: number): number {
+  return x * x;
+};
+
+five.moveToPano({
+  workCode: "axv2ZQMaKZcMl5Bc6x",
+  panoIndex: 51,
+}, {
+  latitude: 0.5314685806864204,
+  longitude: 4.324187623631265,
+  fov: 90,
+  effectEasing: easeInQuad
+})
+```
+
+- effectEasing 生命一个函数，接受一个 0 到 1 的数字， 返回一个 0 到 1 的数字。
+- 当值为 0 时显示前一个全景图。 为 1 时显示后一个全景图。 中间数值为两个全景图的混合， 数值表示混合比例。
+- 用于 地面-天空 等切换切换占比差异较大的情况下单独设置。
+
+### 全景图支持航拍点的差异显示
+
+默认逻辑为:
+```ts
+const five = new Five({
+  panorama: {
+    aerialObserverMinHeight: 5,
+    panoCircleMeshCreator: (observer, options) => {
+      const distance = observer.position.distanceTo(observer.standingPosition);
+      if (distance > options.aerialObserverMinHeight) {
+        return new PanoCircleMeshSolid();
+      } else {
+        return new PanoCircleMesh();
+      }
+    },
+  }
+}
+```
+- 如果距地大于 5 米的点位为航拍点。
+- 如果是航拍点，则使用 PanoCircleMeshSolid， 否则使用 PanoCircleMesh。
+- 内部逻辑。航拍点会面向相机展示。
+
+业务可以修改或介入这个逻辑。
+
+## 渲染以及后处理
+
+重写了渲染相关的逻辑。将 scene-renderer 和 postprocessing 分开
+
+- scene-renderer 场景的渲染相关，需要多次渲染场景采样比如抗锯齿（aa），或者对场景内容改变，必须点云的点融合等。
+- postprocessing 后处理，将 scene-renderer 的结果通过多次处理，比如轮廓增强，调整亮度等，将最终处理后的结果显示到画布上。
+
+### 提供的 scene-renderer
+
+- scene-renderer - 直接渲染
+- point-cloud-high-quality-scene-renderer - 点云融合渲染
+- ssaa-scene-renderer - SSAA算法的抗锯齿渲染
+
+```ts
+// 通过 renderMode 切换
+
+// 直接渲染
+five.renderMode = 'default';
+
+// 点云融合渲染
+five.renderMode = 'point-cloud-high-quality';
+
+// SSAA算法的抗锯齿渲染
+five.renderMode = 'ssaa';
+```
+
+### 内置后处理
+- adaptive-luminance-pass - 屏幕空间动态亮度
+- eye-dome-lighting-pass - 轮廓增强
+
+```ts
+// 开启 eye-dome-lighting-pass
+five.enableEDL = true;
+
+// 开启 adaptive-luminance-pass
+five.enableAdaptiveLuminance = true;
+```
+
+### 自定义后处理
+
+后处理支持 THREE 对于 后处理 Pass 的定义。可以自定义追加。
+
+注意：目前不支持 mask 模版剔除部分的逻辑。
+
+```ts
+
+interface Pass {
+  enabled: boolean;
+  needsSwap: boolean;
+  clear: boolean;
+  renderToScreen: boolean;
+  setSize(width: number, height: number): void;
+  render(
+    renderer: THREE.WebGLRenderer,
+    writeBuffer: THREE.WebGLRenderTarget,
+    readBuffer: THREE.WebGLRenderTarget,
+    deltaTime?: number,
+    maskActive?: boolean
+  ): void;
+}
+
+const myPass: Pass = ...;
+
+this.fiveRenderer.composer.addPass(myPass)
+```
+
+## 其他
+
+- 不再使用分层渲染。enableLayeringRendering 参数废弃。
+- 修复 涉嫌计算 intersectRaycaster, 如果 origin 离得太近会出现取不到的问题，优化 bvhbox 的距离判断逻辑。
+- 优化近处点云碰撞时，规避掉角度大 distanceToRay / distance > 0.07 的点云。
+- 修复多个 five 实例间，共用同一个 work 时 proxy 指向错误 five 实例的问题。
+- 修复 mesh 模型 material.vertexMarks 没有同步 parameterValue.vertexMarks 的问题

package/ai_guides/release_notes/6.8.md

@@ -0,0 +1,208 @@
+# 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_compression_spz 扩展。
+
+### 支持 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.gSHDegree 设置球谐光照阶数，支持 0, 1, 2 阶，默认为 0 阶。
+```
+const five = new Five({
+    parameters: {
+        gsSHDegree: 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 中的所有元素。
+
+### 动画优化
+处理额外动画骨骼未绑定导致的错误, 出现的抖动。
+
+## 模型 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.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.create 事件，发生在所有事件创建时。
+5. gestureEvent.center gestureEvent.pointers 中加入了 buttons button shiftKey ctrlKey metaKey altKey 字段。
+
+## 内部机制改动
+1. glTF 加载 mesh / points 都将直接使用 PBM 材质，而不是作为 PBM_Mesh 扩展形式去替换覆盖使用three内置材质的方式。
+2. 应用 animation pointer 以及 动画优化的原因。目前会重写 hack THREE.PropertyBinding.findNode。
+3. 打包不再合并 .d.ts 文件。便于文档可以更便于找到对应的类型声明。

package/ai_guides/support.md

@@ -0,0 +1,23 @@
+# Browser Support (浏览器支持)
+
+- **Summary**: Five 依赖 WebGL 渲染，支持所有现代浏览器。
+
+## Compatibility
+
+Five 需要浏览器支持 **WebGL 1.0** (推荐 WebGL 2.0 以获得更好性能)。
+
+| Browser | Version Requirement | Note |
+| :--- | :--- | :--- |
+| **Chrome** | >= 69 | 推荐使用最新版 |
+| **Safari** | >= 9 | iOS Safari >= 9 |
+| **Firefox** | >= 45 | |
+| **Edge** | >= 13 | |
+| **Android Webview** | >= 93 (Chrome内核) | |
+
+## WebXR Support
+
+如果需要使用 VR 模式 (XRPanorama)，需要浏览器支持 [WebXR Device API](https://developer.mozilla.org/en-US/docs/Web/API/WebXR_Device_API)。
+
+## Related
+
+*   [Quick Start](./quick-start.md)