u-space 0.0.7 → 0.0.11

package/docs/api-plugin-u-manager.md

@@ -0,0 +1,123 @@
+# u-manager
+
+`u-manager` 是一套全面的加载器和解析器，用于从服务器路径流式传输、解密并显示结构化场景数据。支持场景、拓扑、动画、属性和相机视点。
+
+所有加载器均继承自 Three.js 的 `Loader`，并提供 `setPath(path)` 方法，在调用 `loadAsync()` 前配置基础数据目录。
+
+## `SceneLoader`
+
+从服务端场景包加载完整场景树（模型、组、形状、拉伸区域），并自动将所有已加载对象按 `id` 和 `sid` 注册到 `viewer.objectManager`。
+
+```typescript
+import { SceneLoader } from 'u-space/plugins/u-manager';
+
+const sceneLoader = new SceneLoader(viewer);
+sceneLoader.setPath('./scenes/my-scene');
+sceneLoader.setKey('YOUR_LICENSE_KEY'); // 官方授权场景必需
+const group = await sceneLoader.loadAsync();
+viewer.scene.add(group);
+```
+
+**方法：**
+
+| 方法             | 说明                                                          |
+| :--------------- | :------------------------------------------------------------ |
+| `setKey(key)`    | 设置授权场景的 RSA 解密密钥。                                 |
+| `loadAsync()`    | 加载并解析场景，返回包含完整层级的 `Group`。                  |
+| `clearCache()`   | 从 `objectManager` 中移除此加载器注册的所有 ID。              |
+| `dispose()`      | 清除缓存并释放水印叠加层。                                    |
+
+## `TopologiesLoader` / `TopologyParser`
+
+加载拓扑图数据并将其转换为 `Topology` 对象。
+
+```typescript
+import { TopologiesLoader } from 'u-space/plugins/u-manager';
+
+const loader = new TopologiesLoader();
+loader.setPath('./scenes/my-scene');
+const topologies = await loader.loadAsync(); // Topology[]
+viewer.scene.add(...topologies);
+```
+
+## `VisionsLoader` / `VisionsParser`
+
+加载命名相机视点，并将相机飞行到指定视点。
+
+```typescript
+import { VisionsLoader, VisionsParser } from 'u-space/plugins/u-manager';
+
+const visionsLoader = new VisionsLoader();
+visionsLoader.setPath('./scenes/my-scene');
+const visionsData = await visionsLoader.loadAsync();
+// visionsData 是 Record<string, IVisions[]>
+
+const visionsParser = new VisionsParser(viewer);
+
+// 飞行到指定视点
+await visionsParser.flyTo(visionsData['HOME'][0]);
+
+// 飞行到主（默认）视点
+await visionsParser.flyToPrimary(visionsData['HOME']);
+```
+
+**`IVisions` 字段：**
+
+| 字段       | 类型          | 说明                            |
+| :--------- | :------------ | :------------------------------ |
+| `camera`   | `'P' \| 'O'` | 相机类型：透视或正交。          |
+| `position` | `IVector3`    | 相机世界位置。                  |
+| `target`   | `IVector3`    | 相机朝向目标点。                |
+| `zoom`     | `number`      | 相机缩放级别。                  |
+| `primary`  | `boolean`     | 是否为默认视点。                |
+
+## `AnimationsLoader` / `AnimationsParser`
+
+加载关键帧动画数据，并通过 `tweenAnimation` 驱动 `Object3D` 的变换。
+
+```typescript
+import { AnimationsLoader, AnimationsParser } from 'u-space/plugins/u-manager';
+
+const animLoader = new AnimationsLoader();
+animLoader.setPath('./scenes/my-scene');
+const animationsData = await animLoader.loadAsync(); // IAnimations[]
+
+// 查找特定对象的动画
+const data = animationsData.find((a) => a.modelId === myModel.userData.id);
+
+const parser = new AnimationsParser(viewer, myModel);
+parser.initTransform(); // 保存初始位置/旋转/缩放
+
+await parser.play(data.keyframes); // 播放动画序列
+
+// 中途停止
+parser.stop();
+
+// 重置到初始变换
+parser.reset();
+```
+
+## `PropertiesLoader`
+
+加载与模型关联的结构化属性元数据（如 BIM 属性）。
+
+```typescript
+import { PropertiesLoader } from 'u-space/plugins/u-manager';
+
+const propsLoader = new PropertiesLoader();
+propsLoader.setPath('./scenes/my-scene');
+const properties = await propsLoader.loadAsync(); // IProperties[]
+
+// 查找模型的属性
+const modelProps = properties.filter(p => p.modelId === myModel.userData.id);
+```
+
+**`IProperties` 字段：**
+
+| 字段      | 类型             | 说明                     |
+| :-------- | :--------------- | :----------------------- |
+| `modelId` | `string`         | 关联模型的 ID。          |
+| `group`   | `string`         | 属性分组/类别名称。      |
+| `key`     | `string`         | 属性键名。               |
+| `value`   | `string \| null` | 属性值。                 |
+| `label`   | `string \| null` | 属性的显示标签。         |

package/docs/api-tools.md

@@ -0,0 +1,254 @@
+# Tools API
+
+`u-space` 提供了一组实用工具类，包括测量、剖切和标注功能。
+
+## MeasureTool
+
+用于 3D 场景中的距离测量、面积测量和角度测量，测量结果会以可视化线条渲染到场景中。
+
+```typescript
+import { MeasureTool } from 'u-space';
+
+const measureTool = new MeasureTool(viewer.scene);
+```
+
+### `measureDistance(pointA, pointB, options?)`
+
+测量两点之间的距离，并在场景中绘制连线。
+
+```typescript
+const result = measureTool.measureDistance(
+  { x: 0, y: 0, z: 0 },
+  { x: 5, y: 0, z: 5 },
+  { lineColor: 0xffff00 },
+);
+console.log(result.value, result.unit); // 7.071 m
+```
+
+### `measureArea(points, options?)`
+
+测量由 3 个或更多共面点围成的多边形面积。
+
+```typescript
+const result = measureTool.measureArea([
+  { x: 0, y: 0, z: 0 },
+  { x: 5, y: 0, z: 0 },
+  { x: 5, y: 0, z: 5 },
+  { x: 0, y: 0, z: 5 },
+], { lineColor: 0x00ff00 });
+console.log(result.value, result.unit); // 25 m²
+```
+
+### `measureAngle(pointA, vertex, pointC, options?)`
+
+测量以中间点为顶点的夹角（单位：度）。
+
+```typescript
+const result = measureTool.measureAngle(
+  { x: 3, y: 0, z: 0 },
+  { x: 0, y: 0, z: 0 },
+  { x: 0, y: 0, z: 3 },
+);
+console.log(result.value, result.unit); // 90 °
+```
+
+### `MeasureResult`
+
+所有测量方法返回 `MeasureResult` 对象：
+
+| 属性     | 类型        | 说明                               |
+| :------- | :---------- | :--------------------------------- |
+| `id`     | `string`    | 测量的唯一标识。                   |
+| `type`   | `string`    | `'distance'` / `'area'` / `'angle'`。|
+| `value`  | `number`    | 测量值。                           |
+| `unit`   | `string`    | 单位（`m`、`m²`、`°`）。          |
+| `points` | `Vector3[]` | 测量点坐标。                       |
+| `object` | `Group`     | 场景中的可视化对象。               |
+
+### `MeasureStyleOptions`
+
+| 属性        | 类型                  | 默认值     | 说明         |
+| :---------- | :-------------------- | :--------- | :----------- |
+| `lineColor` | `ColorRepresentation` | 因方法而异 | 线条颜色。   |
+
+### 管理方法
+
+```typescript
+measureTool.get('measure_dist_0');  // 获取指定测量
+measureTool.remove('measure_dist_0'); // 移除指定测量
+measureTool.removeAll();              // 清除全部
+measureTool.getAll();                 // 获取所有测量结果
+measureTool.dispose();                // 释放资源
+```
+
+---
+
+## ClippingTool
+
+提供剖切面和剖切盒功能，基于 WebGPU 的 `ClippingGroup` 实现。需要被剖切的对象必须是 `ClippingGroup` 的子节点。
+
+```typescript
+import { ClippingTool } from 'u-space';
+
+const clippingTool = new ClippingTool(viewer.scene);
+
+// 将场景中已有的物体移入 ClippingGroup，使其受剖切影响
+clippingTool.attach();
+```
+
+### `attach()` / `detach()`
+
+`attach()` 将场景根节点的所有子对象移入内部的 `ClippingGroup`，使其受剖切面影响。`detach()` 反向操作，将对象移回场景根节点。
+
+也可以手动将对象添加到 `clippingTool.group` 中：
+
+```typescript
+clippingTool.group.add(myModel); // 仅 myModel 受剖切
+```
+
+### `addPlane(id, options?)`
+
+添加一个剖切面。
+
+```typescript
+clippingTool.addPlane('cutY', {
+  normal: { x: 0, y: -1, z: 0 },  // 法线方向
+  constant: 1.5,                    // 距离原点的偏移
+  showHelper: true,                 // 显示 Helper
+  helperSize: 5,
+  helperColor: 0xff0000,
+});
+```
+
+#### `ClippingPlaneOptions`
+
+| 属性          | 类型                  | 默认值             | 说明                     |
+| :------------ | :-------------------- | :----------------- | :----------------------- |
+| `normal`      | `{x, y, z}`          | `{x:0, y:-1, z:0}` | 法线方向。               |
+| `constant`    | `number`              | `0`                | 距原点偏移。             |
+| `showHelper`  | `boolean`             | `false`            | 是否显示 PlaneHelper。   |
+| `helperSize`  | `number`              | `5`                | Helper 尺寸。            |
+| `helperColor` | `ColorRepresentation` | `0xff0000`         | Helper 颜色。            |
+
+### `addBox(id, box, options?)` / `addBoxFromObject(id, object, padding?, options?)`
+
+添加由 6 个面组成的剖切盒。
+
+```typescript
+import { Box3 } from 'three/webgpu';
+
+// 从 Box3 创建
+const box = new Box3().setFromObject(myModel);
+clippingTool.addBox('clipBox', box);
+
+// 从对象创建（带边距）
+clippingTool.addBoxFromObject('clipBox', myModel, 0.5);
+```
+
+### 动态调整
+
+```typescript
+clippingTool.setPlaneConstant('cutY', 2.0); // 修改剖切位置
+viewer.render();
+```
+
+### Helper 控制
+
+```typescript
+clippingTool.showHelper('cutY', 5, 0xff0000);
+clippingTool.hideHelper('cutY');
+```
+
+### 管理方法
+
+```typescript
+clippingTool.get('cutY');       // 获取 Plane 对象
+clippingTool.removePlane('cutY'); // 移除单个
+clippingTool.removeBox('clipBox'); // 移除剖切盒（6 个面）
+clippingTool.removeAll();          // 移除全部
+clippingTool.enable();             // 启用剖切
+clippingTool.disable();            // 禁用剖切
+clippingTool.dispose();            // 释放资源（对象移回场景根节点）
+```
+
+---
+
+## AnnotationManager
+
+管理 3D 标注，支持引线标注和 HTML 标签。配合 `CSSRenderer` 使用可实现 HTML 浮动标签。
+
+```typescript
+import { AnnotationManager } from 'u-space';
+
+const annotationManager = new AnnotationManager(viewer.scene);
+```
+
+### `setCSSObjectFactory(factory)`
+
+设置 CSS 对象工厂函数（来自 `CSSRenderer`），使标注可渲染为 CSS 叠加元素。
+
+```typescript
+annotationManager.setCSSObjectFactory(
+  (el) => viewer.cssRenderer.createCSS2DObject(el),
+);
+```
+
+### `add(id, options)`
+
+添加一个标注。
+
+```typescript
+annotationManager.add('label-01', {
+  position: { x: 0, y: 3, z: 0 },
+  content: '<b>设备 A</b><br>温度: 25°C',
+  labelOffset: { x: 0, y: 2, z: 0 },
+  showLeaderLine: true,
+  lineColor: 0xffffff,
+  labelStyle: {
+    background: 'rgba(0, 0, 0, 0.8)',
+    padding: '8px 12px',
+    borderRadius: '6px',
+  },
+});
+```
+
+#### `AnnotationOptions`
+
+| 属性             | 类型                      | 默认值      | 说明                   |
+| :--------------- | :------------------------ | :---------- | :--------------------- |
+| `position`       | `{x, y, z}`              | —           | 标注锚点位置。         |
+| `content`        | `string`                 | —           | HTML 内容。            |
+| `labelOffset`    | `{x, y, z}`              | `{0, 2, 0}` | 标签相对锚点的偏移。   |
+| `showLeaderLine` | `boolean`                | `true`      | 是否显示引线。         |
+| `lineColor`      | `ColorRepresentation`    | `0xffffff`  | 引线颜色。             |
+| `labelStyle`     | `Partial<CSSStyleDeclaration>` | —      | 自定义 CSS 样式。      |
+
+### `addText(text, position, options?)`
+
+快捷添加纯文本标注。
+
+```typescript
+annotationManager.addText('入口', { x: 5, y: 0, z: 0 });
+```
+
+### 更新与控制
+
+```typescript
+annotationManager.updateContent('label-01', '温度: 30°C');
+annotationManager.updatePosition('label-01', { x: 1, y: 3, z: 0 });
+annotationManager.show('label-01');
+annotationManager.hide('label-01');
+annotationManager.showAll();
+annotationManager.hideAll();
+```
+
+### 管理方法
+
+```typescript
+annotationManager.get('label-01');   // 获取标注对象
+annotationManager.remove('label-01'); // 移除标注
+annotationManager.removeAll();        // 移除全部
+annotationManager.keys();             // 获取所有 ID
+annotationManager.size;               // 标注数量
+annotationManager.dispose();          // 释放资源
+```

package/docs/api-viewer.md

@@ -101,35 +101,101 @@ const camera = viewer.createOrthographicCamera();
 viewer.setCamera(camera);
 ```
 
-### `controls.setCameraViewpoint(viewpoint, enableTransition?)`
+### `resize(width?, height?)`
 
-将相机平滑过渡到指定的位置、目标和缩放。
+手动触发容器尺寸更新。可选传入指定宽高。
 
 ```typescript
-await viewer.controls.setCameraViewpoint({
-  position: { x: 10, y: 5, z: 10 },
-  target: { x: 0, y: 0, z: 0 },
-  zoom: 1.0,
+// 手动触发 resize（如容器尺寸变化后）
+viewer.resize();
+
+// 指定新尺寸
+viewer.resize(800, 600);
+```
+
+### `screenshot(options?)`
+
+捕获当前渲染画面并返回 Data URL。
+
+```typescript
+const dataUrl = await viewer.screenshot();
+
+// 指定格式和分辨率
+const dataUrl = await viewer.screenshot({
+  width: 1920,
+  height: 1080,
+  type: 'image/png',
+  quality: 1.0,
 });
+```
+
+#### `ScreenshotOptions`
+
+| 属性      | 类型                                            | 默认值        | 说明                   |
+| :-------- | :---------------------------------------------- | :------------ | :--------------------- |
+| `width`   | `number`                                        | 容器宽度      | 截图宽度。             |
+| `height`  | `number`                                        | 容器高度      | 截图高度。             |
+| `type`    | `'image/png'` \| `'image/jpeg'` \| `'image/webp'` | `'image/png'` | 图片格式。             |
+| `quality` | `number`                                        | `1.0`         | 图片质量（0-1）。      |
+
+### `setBackground(background)`
+
+设置场景背景颜色、纹理或清除背景。
+
+```typescript
+viewer.setBackground(0x333333);       // 颜色
+viewer.setBackground('#87ceeb');      // CSS 颜色字符串
+viewer.setBackground(hdrTexture);     // 纹理
+viewer.setBackground(null);           // 清除背景
+```
+
+### `setEnvironment(envMap)`
+
+设置场景环境贴图（用于反射/IBL）。
+
+```typescript
+viewer.setEnvironment(hdrTexture);
+viewer.setEnvironment(null); // 清除
+```
+
+### `enableShadow()` / `disableShadow()`
+
+开启或关闭阴影渲染。
+
+```typescript
+viewer.enableShadow();
+viewer.disableShadow();
+```
+
+### `enableFog(options?)` / `enableFogExp2(options?)` / `disableFog()`
+
+开启线性雾、指数雾或关闭雾效。
+
+```typescript
+// 线性雾
+viewer.enableFog({ color: 0xcccccc, near: 10, far: 100 });
+
+// 指数雾
+viewer.enableFogExp2({ color: 0xcccccc, density: 0.01 });
 
-// 禁用过渡动画，立即跳转
-await viewer.controls.setCameraViewpoint(viewpoint, false);
+// 关闭雾效
+viewer.disableFog();
 ```
 
-**参数：**
+#### `FogOptions`
 
-| 参数               | 类型                   | 默认值  | 说明                                |
-| :----------------- | :--------------------- | :------ | :---------------------------------- |
-| `viewpoint`        | `CameraViewpointData`  | —       | 包含 `position`、`target`、`zoom`。 |
-| `enableTransition` | `boolean`              | `true`  | 是否启用平滑过渡动画。             |
+| 属性    | 类型                  | 默认值      | 说明           |
+| :------ | :-------------------- | :---------- | :------------- |
+| `color` | `ColorRepresentation` | `0xcccccc`  | 雾的颜色。     |
+| `near`  | `number`              | `10`        | 雾的起始距离。 |
+| `far`   | `number`              | `100`       | 雾的结束距离。 |
 
-#### `CameraViewpointData`
+#### `FogExp2Options`
 
-| 属性       | 类型       | 说明                 |
-| :--------- | :--------- | :------------------- |
-| `position` | `IVector3` | 相机位置。           |
-| `target`   | `IVector3` | 相机注视目标位置。   |
-| `zoom`     | `number`   | 相机缩放值。         |
+| 属性      | 类型                  | 默认值      | 说明           |
+| :-------- | :-------------------- | :---------- | :------------- |
+| `color`   | `ColorRepresentation` | `0xcccccc`  | 雾的颜色。     |
+| `density` | `number`              | `0.01`      | 雾的密度。     |
 
 ## 调试工具
 

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 插件：曲线路径动画