u-space 0.0.5 → 0.0.9

package/docs/changelog.md

@@ -0,0 +1,105 @@
+# 更新日志
+
+## 0.0.8 (开发中)
+
+### 新增
+
+- **Viewer** — `resize()`、`screenshot()`、`setBackground()`、`setEnvironment()`、`enableShadow()`/`disableShadow()`、`enableFog()`/`enableFogExp2()`/`disableFog()`
+- **CameraControls** — `flyTo()`、`getCameraViewpoint()`、`lock()`/`unlock()`、`setViewMode('2d' | '3d')`
+- **ObjectManager** — `show()`/`hide()`、`isolate()`、`showAll()`、`setOpacity()`、`getBoundingBox()`、`forEach()`、`filter()`
+- **InteractionManager** — `enable()`/`disable()`、`setInteractable()`、`addIgnore()`/`removeIgnore()`
+- **Selection** — 新增框选（rubber-band）和单选/多选/切换模块，支持 `select`/`deselect`/`change` 事件
+- **MaterialEffects** — `wireframe()`/`removeWireframe()`、`transparent()`/`removeTransparent()`、`xray()`/`removeXray()`、`fadeIn()`/`fadeOut()`
+- **Model** — `getBoundingBox()`、`getCenter()`、`setMaterial()`
+- **SceneManager** — 新模块，多场景创建、注册、切换与序列化
+- **LightManager** — 新模块，灯光便捷创建、4 种预设（indoor/outdoor/studio/warehouse）、Helper 可视化
+- **MeasureTool** — 新工具，距离/面积/角度测量，结果可视化渲染到场景
+- **ClippingTool** — 新工具，基于 WebGPU `ClippingGroup` 的剖切面与剖切盒
+- **AnnotationManager** — 新工具，3D 引线标注 + HTML 浮动标签
+- **示例** — 新增 8 个交互式示例页面
+
+### 修复
+
+- **Selection** — 框选覆盖层改为挂载到容器元素（而非 canvas），修复框选矩形不可见的问题
+- **ClippingTool** — 从 `renderer.clippingPlanes`（WebGL API）重写为 `ClippingGroup`（WebGPU API），修复剖切无效的问题
+- **MaterialEffects** — fade 动画在对象移除场景后自动停止，避免内存泄漏
+- **InteractionManager** — `dispose()` 中清除 `clickTimer`，避免定时器泄漏
+- **LightManager** — 修复 `removeAll()`/`hideAllHelpers()` 中遍历 Map 同时删除的问题
+- **ObjectManager** — `setOpacity()` 先检查 `isMesh` 再类型转换
+- **ClippingTool** — `PlaneHelper` 颜色使用 `new Color(color).getHex()` 替代直接 `as number`
+- **MeasureTool** — 移除 WebGPU 不支持的 `linewidth` 属性
+
+---
+
+## 0.0.7
+
+### 变更
+
+- 文档拆分：将插件文档拆分为独立文件
+- 新增 CameraControls 独立文档页
+- 修复 getting-started 中的死链
+- 修复 sbmx loader 示例使用新的 MaterialEffects API
+
+---
+
+## 0.0.6
+
+### 新增
+
+- **MaterialEffects** — 可组合的材质特效系统，支持安全共享材质和 remove API
+- **RenderPipeline** — 内置 Bloom、SSGI、TRAA 后处理及 OutputComposer API
+- **CSSRenderer** — CSS2D / CSS2.5D / CSS3D 叠加渲染 HTML 元素
+- 从 `package.json` 导出 `version`，统一示例 importmap
+
+---
+
+## 0.0.5
+
+### 变更
+
+- 版本发布（无重大功能变更）
+
+---
+
+## 0.0.4
+
+### 新增
+
+- **Model** — 动画播放支持（`playAnimation`、`stopAnimation`、`updateAnimation`）
+- **ViewerEventMap** — 事件回调新增 `delta` 时间参数
+
+---
+
+## 0.0.3
+
+### 新增
+
+- **ObjectControls** 插件 — 交互式移动、旋转、缩放 3D 对象
+- **TopologyDrawer** 插件 — 在场景任意表面交互式绘制拓扑路径图
+- **Topology** — `exportData()` / `importData()` 数据序列化
+
+### 变更
+
+- **Interactions** — `contextmenu` 事件替换为 `rightclick`
+- **Poi** — 优化渲染性能，新增 `scaleFactor` 参数
+- 文档全面完善：本地搜索、侧边栏优化、各插件文档页
+
+---
+
+## 0.0.0
+
+### 新增
+
+- 项目初始化：Viewer 核心、WebGPU 渲染器、场景/相机/控制器
+- 模型加载系统：双层缓存（内存 + 持久化）、Draco/KTX2/Meshopt 支持
+- 交互系统：射线检测、事件冒泡、自定义 3D 对象事件
+- 对象系统：Model、Poi、Topology、基础网格（Sphere/Plane/Circle/Tube/Extrude/Shape）
+- ObjectManager 集中式对象注册
+- 补间动画系统
+- u-manager 插件：场景加载、动画、属性、视点管理
+- tiles 插件：ArcGIS 3D 瓦片 / GIS 地球渲染
+- minimap 插件：2D 小地图
+- keyboard-controls 插件：WASD 键盘控制
+- tracking-controls 插件：相机跟随
+- atmosphere 插件：天空/大气渲染
+- curve-movement 插件：曲线路径动画

package/docs/examples-guide.md

@@ -60,3 +60,133 @@
 - 监听 `beforeRender` 事件，通过 `model.updateAnimation(e.delta)` 推进动画时间。
 - 使用 `model.playAnimation(name)` 按名称播放单个动画，`model.playAllAnimations()` 播放全部。
 - 使用 `model.stopAnimation()` 停止动画播放。
+
+## 6. `test_css_renderer.html`：CSS2D / CSS2.5D / CSS3D 渲染器
+
+该示例演示了如何在 3D 场景中叠加渲染 HTML 元素，展示三种 CSS 渲染模式的效果差异。
+
+### 核心要点：
+
+- 使用 `viewer.cssRenderer.createCSS2DObject()` 创建始终面向相机、固定屏幕尺寸的 2D 标签。
+- 使用 `viewer.cssRenderer.createCSS25DObject()` 创建面向相机但随距离缩放的 2.5D 精灵。
+- 使用 `viewer.cssRenderer.createCSS3DObject()` 创建具有完整 3D 变换的面板。
+- CSS2.5D 和 CSS3D 对象需要设置 `scale`（通常 `0.01`），因为 HTML 元素的像素尺寸远大于 3D 世界单位。
+- 渲染器采用懒加载，仅在首次创建对应类型对象时初始化。
+
+## 7. `test_postprocessing.html`：后处理效果
+
+该示例演示了 `RenderPipeline` 的内置后处理功能，包括 Bloom、SSGI、TRAA 以及自定义后处理组合器。
+
+### 核心要点：
+
+- 使用 `viewer.renderPipeline.enableBloom()` / `disableBloom()` 运行时切换 Bloom 效果。
+- 使用 `viewer.renderPipeline.updateBloom()` 实时调整 strength、radius、threshold 参数。
+- 使用 `viewer.renderPipeline.enableSSGI()` / `disableSSGI()` 切换屏幕空间全局光照。
+- 使用 `viewer.renderPipeline.updateSSGI()` 实时调整 SSGI 参数（直接修改 uniform，无需重建节点图）。
+- 使用 `viewer.renderPipeline.enableTRAA()` / `disableTRAA()` 切换时间抗锯齿。
+- 使用 `viewer.renderPipeline.setOutputComposer()` 自定义后处理链（示例中实现了灰度滤镜）。
+- 使用 `setOutputComposer(null)` 恢复默认渲染管线。
+
+## 8. `test_viewer_utils.html`：Viewer 工具方法
+
+该示例演示了 `Viewer` 新增的便捷方法：截图导出、背景切换、雾效控制和阴影开关。
+
+### 核心要点：
+
+- 使用 `viewer.screenshot()` 导出当前渲染画面为 PNG 文件。
+- 使用 `viewer.setBackground(color)` 快速切换场景背景颜色。
+- 使用 `viewer.enableFog()` / `viewer.disableFog()` 控制雾效。
+- 使用 `viewer.enableShadow()` / `viewer.disableShadow()` 控制阴影渲染。
+- 使用 `viewer.resize(width, height)` 手动触发尺寸更新。
+
+## 9. `test_camera_controls.html`：CameraControls 增强方法
+
+该示例演示了 `CameraControls` 的飞行定位、视角存取、锁定和二三维切换功能。
+
+### 核心要点：
+
+- 使用 `viewer.controls.flyTo(position, target)` 将相机飞行到指定坐标。
+- 使用 `viewer.controls.getCameraViewpoint()` 获取当前视角数据。
+- 使用 `viewer.controls.setCameraViewpoint(data)` 恢复保存的视角。
+- 使用 `viewer.controls.lock()` / `unlock()` 锁定或解锁相机控制。
+- 使用 `viewer.controls.setViewMode('2d')` / `setViewMode('3d')` 在二三维视图间切换。
+
+## 10. `test_object_manager.html`：ObjectManager 增强方法
+
+该示例演示了 `ObjectManager` 的显隐控制、孤立显示、透明度设置、包围盒查询和过滤功能。
+
+### 核心要点：
+
+- 使用 `viewer.objectManager.show(id)` / `hide(id)` 控制对象可见性。
+- 使用 `viewer.objectManager.isolate(ids)` 孤立显示指定对象。
+- 使用 `viewer.objectManager.setOpacity(id, value)` 设置材质透明度。
+- 使用 `viewer.objectManager.getBoundingBox()` 查询所有对象的包围盒。
+- 使用 `viewer.objectManager.filter(predicate)` 按条件过滤对象。
+
+## 11. `test_material_effects.html`：MaterialEffects 增强效果
+
+该示例演示了材质效果系统的线框、半透明、X 光和淡入淡出功能。
+
+### 核心要点：
+
+- 使用 `MaterialEffects.wireframe(object)` 开启线框渲染模式。
+- 使用 `MaterialEffects.highlightColor(object, { opacity })` 设置半透明效果。
+- 使用 `MaterialEffects.highlightColor(object, { color, opacity, overwrite: true, depthWrite: false })` 实现 X 光透视效果。
+- 使用 `MaterialEffects.fadeOut(object)` / `fadeIn(object)` 执行淡入淡出动画。
+- 使用 `MaterialEffects.removeHighlightColor(object)` 恢复原始材质状态。
+
+## 12. `test_selection.html`：Selection 选择系统
+
+该示例演示了对象选择系统的单选和框选功能。
+
+### 核心要点：
+
+- 创建 `Selection` 实例并监听 `select`、`deselect`、`change` 事件。
+- 使用 `selection.select()` / `deselect()` / `toggle()` / `clear()` 进行程序化选择操作。
+- 使用 `selection.enableBoxSelection()` 开启鼠标框选模式。
+- 框选模式下可配合 `viewer.controls.lock()` 避免框选与相机旋转冲突。
+
+## 13. `test_measure.html`：MeasureTool 测量工具
+
+该示例演示了 3D 场景中的距离、面积和角度测量。
+
+### 核心要点：
+
+- 使用 `measureTool.measureDistance(pointA, pointB)` 测量两点距离。
+- 使用 `measureTool.measureArea(points)` 测量多边形面积。
+- 使用 `measureTool.measureAngle(pointA, vertex, pointC)` 测量夹角。
+- 测量结果以可视化线条渲染到场景中，返回的 `MeasureResult` 包含数值和单位。
+
+## 14. `test_annotation.html`：AnnotationManager 标注管理
+
+该示例演示了 3D 标注的创建、更新和管理，配合 `CSSRenderer` 实现 HTML 浮动标签。
+
+### 核心要点：
+
+- 创建 `AnnotationManager` 实例并通过 `setCSSObjectFactory()` 绑定 `CSSRenderer`。
+- 使用 `annotationManager.add(id, options)` 添加带引线和自定义样式的标注。
+- 使用 `annotationManager.addText(text, position)` 快捷添加纯文本标注。
+- 使用 `updateContent()` 动态更新标注内容，`updatePosition()` 移动标注位置。
+- 使用 `hideAll()` / `showAll()` 批量控制标注显隐。
+
+## 15. `test_clipping.html`：ClippingTool 剖切工具
+
+该示例演示了剖切面的创建和实时调整。
+
+### 核心要点：
+
+- 创建 `ClippingTool` 实例并调用 `attach()` 将场景物体移入 ClippingGroup。
+- 使用 `clippingTool.addPlane(id, options)` 添加剖切面。
+- 使用滑块通过 `clippingTool.setPlaneConstant()` 实时调整剖切位置。
+- 使用 `showHelper()` / `hideHelper()` 切换剖切面可视化辅助。
+
+## 16. `test_lights.html`：LightManager 灯光管理
+
+该示例演示了灯光管理器的灯光预设和 Helper 可视化功能。
+
+### 核心要点：
+
+- 创建 `LightManager` 实例并使用 `applyPreset()` 一键应用灯光预设。
+- 支持 4 种预设：`indoor`（室内）、`outdoor`（室外）、`studio`（摄影棚）、`warehouse`（仓库）。
+- 使用 `showAllHelpers()` / `hideAllHelpers()` 显示或隐藏灯光辅助可视化。
+- 每种预设会自动清除旧灯光并创建新的灯光组合。

package/docs/getting-started.md

@@ -119,13 +119,25 @@ box.addEventListener('pointerleave', (e) => {
 
 这样就完成了！你现在拥有一个基础的 `u-space` 应用。
 
+## 版本信息
+
+`u-space` 导出了 `version` 常量，同时在 `window.__USPACE__` 上挂载了版本信息，方便调试和版本检查。
+
+```typescript
+import { version } from 'u-space';
+console.log(version); // e.g. '0.0.5'
+
+// 也可以通过全局变量访问
+console.log(window.__USPACE__.version);
+```
+
 ## 下一步
 
 - 深入了解 [Viewer API](./api-viewer.md)
 - 探索如何 [加载模型与使用对象](./api-objects.md)
 - 理解 [交互系统](./api-interactions.md)
 - 使用 [Managers API](./api-managers.md) 注册和检索对象
-- 通过 [Plugins API](./api-plugins.md) 添加瓦片地图、小地图、键盘控制等功能
+- 通过插件添加 [瓦片地图](./api-plugin-tiles.md)、[小地图](./api-plugin-minimap.md)、[键盘控制](./api-plugin-keyboard-controls.md) 等功能
 - 使用 [Animations API](./api-animations.md) 为属性添加动画
 - 使用 [Effects API](./api-effects.md) 应用视觉特效
 - 浏览 [示例指南](./examples-guide.md)

package/docs/index.md

@@ -12,6 +12,10 @@ hero:
     - theme: alt
       text: API 文档
       link: /api-viewer
+    - theme: alt
+      text: 在线示例
+      link: /examples/
+      target: _self
 
 features:
   - title: WebGPU 优先
@@ -29,11 +33,15 @@ features:
 | 文档 | 说明 |
 | :--- | :--- |
 | [Viewer](./api-viewer) | 核心类：渲染器、场景、相机、控制器、事件 |
+| [CameraControls](./api-camera-controls) | 相机控制：飞行、视角切换、视点过渡 |
+| [CSSRenderer](./api-css-renderer) | CSS 渲染器：CSS2D / CSS2.5D / CSS3D 叠加 HTML 元素 |
+| [RenderPipeline](./api-render-pipeline) | 后处理管线：Bloom、SSGI、TRAA、自定义后处理 |
 | [Objects](./api-objects) | 3D 对象：模型加载、基础网格、Poi、Topology |
-| [Interactions](./api-interactions) | 交互管理：射线检测、鼠标/触摸事件 |
-| [Managers](./api-managers) | 对象管理：按 ID / 名称 / 类型检索 |
+| [Interactions](./api-interactions) | 交互管理：射线检测、鼠标/触摸事件、框选 |
+| [Managers](./api-managers) | 对象管理、场景管理、灯光管理 |
 | [Animations](./api-animations) | 补间动画：`tweenAnimation`、`Tween`、缓动模式 |
-| [Effects](./api-effects) | 视觉特效：高亮、流动、呼吸、流体（TSL） |
+| [Effects](./api-effects) | 视觉特效：高亮、呼吸、线框、淡入淡出、流动、流体（TSL） |
+| [Tools](./api-tools) | 工具：测量（距离/面积/角度）、剖切（面/盒）、标注管理 |
 
 ### 插件
 
@@ -41,12 +49,12 @@ features:
 
 | 插件 | 说明 |
 | :--- | :--- |
-| [keyboard-controls](./api-plugins#keyboard-controls) | WASD / 方向键控制相机移动与旋转 |
-| [minimap](./api-plugins#minimap) | 2D 小地图叠加层 |
-| [tiles](./api-plugins#tiles) | ArcGIS 3D 瓦片 / GIS 地球渲染 |
-| [u-manager](./api-plugins#u-manager) | 场景加载、拓扑、动画、属性、视点管理 |
-| [curve-movement](./api-plugins#curve-movement) | 沿样条曲线移动相机或对象 |
-| [tracking-controls](./api-plugins#tracking-controls) | 相机跟随移动目标 |
-| [atmosphere](./api-plugins#atmosphere) | 天空/大气渲染（开发中） |
-| [object-controls](./api-plugins#object-controls) | 交互式移动、旋转、缩放 3D 对象 |
-| [topology-drawer](./api-plugins#topology-drawer) | 在场景任意表面交互式绘制拓扑路径图 |
+| [keyboard-controls](./api-plugin-keyboard-controls) | WASD / 方向键控制相机移动与旋转 |
+| [minimap](./api-plugin-minimap) | 2D 小地图叠加层 |
+| [tiles](./api-plugin-tiles) | ArcGIS 3D 瓦片 / GIS 地球渲染 |
+| [u-manager](./api-plugin-u-manager) | 场景加载、拓扑、动画、属性、视点管理 |
+| [curve-movement](./api-plugin-curve-movement) | 沿样条曲线移动相机或对象 |
+| [tracking-controls](./api-plugin-tracking-controls) | 相机跟随移动目标 |
+| [atmosphere](./api-plugin-atmosphere) | 天空/大气渲染（开发中） |
+| [object-controls](./api-plugin-object-controls) | 交互式移动、旋转、缩放 3D 对象 |
+| [topology-drawer](./api-plugin-topology-drawer) | 在场景任意表面交互式绘制拓扑路径图 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-space",
-  "version": "0.0.5",
+  "version": "0.0.9",
   "type": "module",
   "types": "dist/src/index.d.ts",
   "module": "dist/index.js",