u-space 0.0.7 → 0.0.9

package/docs/api-objects.md

@@ -39,31 +39,31 @@ const myModel = new Model();
 `loadAsync` 方法负责从 URL 加载资产并将其添加到组中。
 
 ```typescript
-await myModel.loadAsync(options: ModelLoadOptions)
+await myModel.loadAsync(parameters: ModelParameters)
 ```
 
-#### `ModelLoadOptions`
+#### `ModelParameters`
 
-| 属性         | 类型      | 说明                                                                                                               |
-| :----------- | :-------- | :----------------------------------------------------------------------------------------------------------------- |
-| `url`        | `string`  | `.gltf` 或 `.glb` 文件的 URL。                                                                                     |
-| `cache`      | `boolean` | （可选）启用内存缓存。若模型已加载过，则直接从内存中获取。默认 `false`。                                           |
-| `persistent` | `boolean` | （可选）使用浏览器 Cache API 启用持久化磁盘缓存，适合较大的模型。默认 `false`。                                    |
+| 属性         | 类型      | 默认值 | 说明                                                                                    |
+| :----------- | :-------- | :----- | :-------------------------------------------------------------------------------------- |
+| `url`        | `string`  | —      | `.gltf` 或 `.glb` 文件的 URL。                                                          |
+| `cache`      | `boolean` | `true` | 启用内存缓存。若模型已加载过，则直接从内存中获取并克隆。                                |
+| `persistent` | `boolean` | `true` | 使用浏览器 Cache API 启用持久化磁盘缓存，适合较大的模型。                               |
 
 #### 缓存示例
 
 ```javascript
-// 从网络加载并持久化
+// 默认开启双层缓存，直接加载即可
 const model1 = new Model();
-model1.loadAsync({ url: 'model.glb', persistent: true });
+model1.loadAsync({ url: 'model.glb' });
 
-// 稍后，将从 Cache API 加载
+// 禁用内存缓存（每次都从网络或持久化缓存重新加载）
 const model2 = new Model();
-model2.loadAsync({ url: 'model.glb', persistent: true });
+model2.loadAsync({ url: 'model.glb', cache: false });
 
-// 从内存缓存快速加载
+// 完全禁用缓存
 const model3 = new Model();
-model3.loadAsync({ url: 'model.glb', cache: true, persistent: true });
+model3.loadAsync({ url: 'model.glb', cache: false, persistent: false });
 ```
 
 ### 动画
@@ -124,6 +124,39 @@ viewer.addEventListener('beforeRender', (e) => {
 });
 ```
 
+### 空间查询
+
+#### `getBoundingBox()`
+
+获取模型的轴对齐包围盒（AABB）。
+
+```typescript
+const box = myModel.getBoundingBox();
+const size = box.getSize(new Vector3());
+console.log('模型尺寸:', size);
+```
+
+#### `getCenter()`
+
+获取模型包围盒的中心点。
+
+```typescript
+const center = myModel.getCenter();
+console.log('模型中心:', center);
+```
+
+### 材质操作
+
+#### `setMaterial(material)`
+
+将模型内所有 Mesh 的材质统一替换为指定材质。
+
+```typescript
+import { MeshStandardMaterial } from 'three/webgpu';
+
+myModel.setMaterial(new MeshStandardMaterial({ color: 0xff0000 }));
+```
+
 ### 清除缓存
 
 可通过 `Model` 类的静态方法手动清除内部缓存：

package/docs/api-plugin-atmosphere.md

@@ -0,0 +1,10 @@
+# atmosphere
+
+天空和大气渲染插件。目前为占位实现，`enable()` / `disable()` / `dispose()` 方法可用，但尚未实现具体功能。
+
+```typescript
+import { Atmosphere } from 'u-space/plugins/atmosphere';
+
+const atmosphere = new Atmosphere(viewer);
+atmosphere.enable();
+```

package/docs/api-plugin-curve-movement.md

@@ -0,0 +1,38 @@
+# curve-movement
+
+沿样条路径对相机或对象进行动画。提供两个具体子类：`CurveMovementCamera` 和 `CurveMovementObject`。
+
+```typescript
+import { CurveMovementObject } from 'u-space/plugins/curve-movement';
+import { Vector3 } from 'three/webgpu';
+
+const movement = new CurveMovementObject(viewer, myModel);
+movement.setFromPoints([
+  new Vector3(0, 0, 0),
+  new Vector3(10, 2, 0),
+  new Vector3(20, 0, 10),
+]);
+movement.speed = 0.05;    // 每秒进度
+movement.loop = 'repeat'; // 'once' | 'repeat' | 'pingpong'
+movement.autoLookAt = true;
+
+movement.play();
+// movement.pause() / movement.resume() / movement.stop()
+
+// 监听事件
+movement.addEventListener('update', ({ progress }) => console.log(progress));
+movement.addEventListener('complete', () => console.log('完成'));
+```
+
+**`CurveMovement` 属性：**
+
+| 属性            | 类型                               | 默认值    | 说明                                 |
+| :-------------- | :--------------------------------- | :-------- | :----------------------------------- |
+| `path`          | `Curve<Vector3> \| null`           | `null`    | 样条路径。                           |
+| `progress`      | `number`                           | `0`       | 当前归一化进度（0–1）。              |
+| `speed`         | `number`                           | `0.1`     | 每秒进度单位。                       |
+| `loop`          | `'once' \| 'repeat' \| 'pingpong'` | `'once'`  | 循环行为。                           |
+| `autoLookAt`    | `boolean`                          | `true`    | 朝向路径切线方向。                   |
+| `lookAtOffset`  | `number`                           | `0`       | Y 轴旋转偏移量（弧度）。             |
+| `positionOffset`| `Vector3`                          | `(0,0,0)` | 叠加到每个位置上的世界坐标偏移量。   |
+| `direction`     | `1 \| -1`                          | `1`       | 当前行进方向。                       |

package/docs/api-plugin-keyboard-controls.md

@@ -0,0 +1,40 @@
+# keyboard-controls
+
+为激活相机提供 WASD 或方向键的平移和旋转控制。
+
+```typescript
+import { KeyboardControls, ACTION } from 'u-space/plugins/keyboard-controls';
+
+const keyboardControls = new KeyboardControls(viewer);
+
+// 可选：自定义移动速度
+keyboardControls.moveDistanceDelta = 0.5;
+keyboardControls.rotateAngleDelta = (Math.PI / 180) * 2;
+
+// 激活监听
+keyboardControls.enable();
+// 之后：
+keyboardControls.disable();
+```
+
+**默认按键绑定**（`keyboardControls.keys`）：
+
+| 按键         | 动作     |
+| :----------- | :------- |
+| `W`          | 向前移动 |
+| `S`          | 向后移动 |
+| `A`          | 向左移动 |
+| `D`          | 向右移动 |
+| `Q`          | 向上移动 |
+| `E`          | 向下移动 |
+| `ArrowLeft`  | 向左旋转 |
+| `ArrowRight` | 向右旋转 |
+| `ArrowUp`    | 向上旋转 |
+| `ArrowDown`  | 向下旋转 |
+
+通过 `ACTION` 常量重新绑定任意按键：
+
+```typescript
+import { ACTION } from 'u-space/plugins/keyboard-controls';
+keyboardControls.keys['Space'] = ACTION.MOVE_UP;
+```

package/docs/api-plugin-minimap.md

@@ -0,0 +1,36 @@
+# minimap
+
+生成一个 2D 小地图叠加层，在 3D 场景中跟踪目标对象。渲染到注入 `viewer.el` 的 `<canvas>` 元素中。
+
+```typescript
+import { Minimap } from 'u-space/plugins/minimap';
+
+const minimap = new Minimap(viewer);
+minimap.target = myCharacterModel; // 要跟踪并显示的 Object3D
+minimap.setSize(300, 300);         // 宽高（像素）
+
+// 可选：设置小地图场景样式
+minimap.scene.background = new THREE.Color(0x111111);
+
+minimap.enable();
+// 之后：
+minimap.disable();
+minimap.dispose();
+```
+
+**属性：**
+
+| 属性          | 类型                  | 说明                                     |
+| :------------ | :-------------------- | :--------------------------------------- |
+| `target`      | `Object3D \| null`    | 小地图居中显示的对象。                   |
+| `scene`       | `Scene`               | 小地图内部的 Three.js 场景。             |
+| `camera`      | `OrthographicCamera`  | 正交俯视相机。                           |
+| `marker`      | `Object3D`            | 显示主相机位置/朝向的箭头网格。          |
+| `needsUpdate` | `boolean`             | 设置为 `true` 可强制重新渲染小地图。     |
+
+**方法：**
+
+- `setSize(width, height)` — 调整小地图画布和相机视锥大小。
+- `enable()` — 将画布附加到 `viewer.el` 并开始渲染。
+- `disable()` — 移除画布并停止渲染。
+- `dispose()` — 禁用并清理所有资源。

package/docs/api-plugin-object-controls.md

@@ -0,0 +1,67 @@
+# object-controls
+
+对场景中的 3D 对象进行交互式移动、旋转、缩放操作。继承自 Three.js `TransformControls`，集成了 u-space `Viewer` 生命周期管理。
+
+```typescript
+import { ObjectControls } from 'u-space/plugins/object-controls';
+
+const controls = new ObjectControls(viewer, {
+  mode: 'translate', // 'translate' | 'rotate' | 'scale'，默认 'translate'
+  space: 'world',    // 'world' | 'local'，默认 'world'
+  size: 1,           // 控件显示大小，默认 1
+});
+
+controls.enable();
+controls.attach(myMesh); // 将控件附加到目标对象
+
+// 切换模式（直接赋值，继承自 TransformControls）
+controls.mode = 'rotate';
+controls.space = 'local';
+
+// 监听变换事件
+controls.addEventListener('objectChange', () => {
+  console.log(myMesh.position);
+});
+
+controls.addEventListener('dragging-changed', ({ value }) => {
+  console.log('拖拽中：', value); // true = 开始，false = 结束
+});
+```
+
+**说明：**
+
+- `enable()` 时将 gizmo 加入场景并切换 `frameloop` 为 `'always'`，确保拖拽时连续渲染。
+- 拖拽期间自动挂起 `viewer.controls`（CameraControls）以避免冲突；`disable()` 时无论如何都强制还原相机控制，防止 mid-drag 调用 disable 导致相机卡死。
+- 监听 `viewer` 的 `cameraChange` 事件，`viewer.setCamera()` 切换相机后 gizmo 自动同步，无需手动更新。
+
+**构造选项（`ObjectControlsOptions`）：**
+
+| 选项     | 类型                               | 默认值        | 说明             |
+| :------- | :--------------------------------- | :------------ | :--------------- |
+| `mode`   | `'translate' \| 'rotate' \| 'scale'` | `'translate'` | 初始变换模式。   |
+| `space`  | `'world' \| 'local'`               | `'world'`     | 初始变换空间。   |
+| `size`   | `number`                           | `1`           | gizmo 大小。     |
+| `showX`  | `boolean`                          | `true`        | 显示 X 轴手柄。  |
+| `showY`  | `boolean`                          | `true`        | 显示 Y 轴手柄。  |
+| `showZ`  | `boolean`                          | `true`        | 显示 Z 轴手柄。  |
+
+**方法：**
+
+| 方法        | 说明                                                         |
+| :---------- | :----------------------------------------------------------- |
+| `enable()`  | 将 gizmo 加入场景，切换 frameloop 为 `'always'`。           |
+| `disable()` | 移除 gizmo，还原 frameloop 和 CameraControls。               |
+| `attach(object)` | 将控件附加到指定 Object3D。                             |
+| `detach()`  | 解除当前附加对象。                                           |
+| `dispose()` | 完全释放所有资源。                                           |
+
+**属性：**
+
+| 属性       | 类型      | 说明                                  |
+| :--------- | :-------- | :------------------------------------ |
+| `isActive` | `boolean` | 当前是否已调用 `enable()`（只读）。   |
+| `object`   | `Object3D \| undefined` | 当前附加的对象（继承自 TransformControls）。 |
+| `mode`     | `string`  | 当前变换模式，可直接赋值切换。        |
+| `space`    | `string`  | 当前变换空间，可直接赋值切换。        |
+
+> 由于 `ObjectControls` 直接继承 `TransformControls`，所有原生属性（`translationSnap`、`rotationSnap`、`scaleSnap`、`showX/Y/Z` 等）和事件均可直接使用，参考 [Three.js TransformControls 文档](https://threejs.org/docs/#examples/en/controls/TransformControls)。

package/docs/api-plugin-tiles.md

@@ -0,0 +1,26 @@
+# tiles
+
+提供与 `3d-tiles-renderer` 和地理空间数据的集成。主要导出 `ArcgisTilesRenderer`，可流式加载 ArcGIS Online 3D 瓦片并将地球重新定向到指定地理位置。
+
+```typescript
+import { ArcgisTilesRenderer } from 'u-space/plugins/tiles';
+
+const arcgisTilesRenderer = new ArcgisTilesRenderer(viewer);
+
+// 设置原点为经度、纬度、高度
+arcgisTilesRenderer.invalidate(120.002269, 30.284849, 4);
+
+// 瓦片持续流式加载，使用 always 模式
+viewer.frameloop = 'always';
+
+arcgisTilesRenderer.enable();
+```
+
+**方法：**
+
+| 方法                        | 说明                                                                                           |
+| :-------------------------- | :--------------------------------------------------------------------------------------------- |
+| `invalidate(lon, lat, alt)` | 将瓦片原点设置为指定的 WGS84 坐标（度）。可多次调用。返回一个取消订阅的函数。                  |
+| `enable()`                  | 将瓦片添加到场景并启动更新循环。                                                               |
+| `disable()`                 | 从场景中移除瓦片并暂停更新循环。                                                               |
+| `dispose()`                 | 禁用并完全释放瓦片渲染器。                                                                     |

package/docs/api-plugin-topology-drawer.md

@@ -0,0 +1,74 @@
+# topology-drawer
+
+在 3D 场景中交互式绘制拓扑路径图。点击场景中的任意对象表面放置节点，自动连接成路径；点击空白处则落回不可见的地面平面。事件检测通过 `viewer.interactionManager` 实现（`scene.addEventListener` 冒泡）。
+
+```typescript
+import { TopologyDrawer } from 'u-space/plugins/topology-drawer';
+
+const drawer = new TopologyDrawer(viewer, {
+  groundY: 0,       // 空白区域兜底地面的 Y 坐标，默认 0
+  snapRadius: 1.0,  // 自动吸附已有节点的世界单位半径，默认 1.0
+  nodeRadius: 0.3,
+  nodeColor: 0x0088ff,
+  edgeRadius: 0.1,
+  edgeColor: 0x00ddff,
+  previewColor: 0xffff00, // 预览线颜色
+});
+
+drawer.enable();
+```
+
+**操作说明：**
+
+| 操作 | 效果 |
+| :--- | :--- |
+| 左键点击空白 / 模型表面 | 放置新节点，与上一节点自动连边 |
+| 左键点击已有节点（`snapRadius` 范围内） | 吸附并连接到该节点，不新增节点 |
+| 左键点击已有边 | 切断该边，在点击处插入新节点并重连两端 |
+| 右键 / `Escape` | 结束当前路径链，下次点击开始新路径 |
+| `Ctrl / Cmd + Z` | 撤销最后一步（节点、边或结束路径） |
+
+**方法：**
+
+| 方法 | 说明 |
+| :--- | :--- |
+| `enable()` | 进入绘制模式，将拓扑与地面平面加入场景。同时自动将 `viewer.interactionManager.pointerMoveEventsEnabled` 置为 `true`（用于预览线跟随光标），并在 `disable()` 时恢复为原值。 |
+| `disable()` | 退出绘制模式，已绘内容仍保留在场景中。恢复 `pointerMoveEventsEnabled` 为调用 `enable()` 前的值。 |
+| `finishPath()` | 结束当前路径链（等同于右键 / Escape）。 |
+| `undo()` | 撤销最后一步操作。 |
+| `clear()` | 清空所有已绘节点、边和路径。 |
+| `exportData()` | 以 JSON 可序列化格式导出当前拓扑数据。 |
+| `importData(data)` | 加载 `exportData()` 返回的数据，替换当前内容。 |
+| `dispose()` | 完全释放所有资源并从场景移除拓扑。 |
+
+**属性：**
+
+| 属性 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `topology` | `Topology` | 底层 `Topology` 对象，可进一步访问节点、边和路径方法。 |
+
+**导出 / 导入：**
+
+```typescript
+// 导出
+const data = drawer.exportData();
+// data: { nodes: Record<string, {x,y,z}>, edges: Array<{from,to,weight}> }
+
+// 导入
+drawer.importData(data);
+```
+
+**结合 `SceneLoader` 在模型表面绘制：**
+
+```typescript
+import { SceneLoader } from 'u-space/plugins/u-manager';
+import { TopologyDrawer } from 'u-space/plugins/topology-drawer';
+
+const sceneLoader = new SceneLoader(viewer);
+sceneLoader.setPath('./scenes/my-scene');
+const group = await sceneLoader.loadAsync();
+viewer.scene.add(group);
+
+const drawer = new TopologyDrawer(viewer, { snapRadius: 1.0 });
+drawer.enable(); // 可直接在加载的模型表面点击绘制
+```

package/docs/api-plugin-tracking-controls.md

@@ -0,0 +1,23 @@
+# tracking-controls
+
+使相机平滑跟随移动的 `Object3D` 目标。
+
+```typescript
+import { TrackingControls } from 'u-space/plugins/tracking-controls';
+
+const tracking = new TrackingControls(viewer);
+tracking.target = myMovingObject;
+tracking.type = 'box3';         // 'position'（世界原点）或 'box3'（包围盒中心）
+tracking.offset.set(0, 5, 0);   // 相机目标偏移量
+
+tracking.enable();
+// tracking.disable();
+```
+
+**属性：**
+
+| 属性     | 类型                    | 默认值       | 说明                                                      |
+| :------- | :---------------------- | :----------- | :-------------------------------------------------------- |
+| `target` | `Object3D \| null`      | `null`       | 要跟踪的对象。                                            |
+| `type`   | `'position' \| 'box3'` | `'position'` | 跟踪世界位置还是包围盒中心。                              |
+| `offset` | `Vector3`               | `(0,0,0)`    | 在移动相机前叠加到跟踪位置上的偏移量。                    |

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` | 属性的显示标签。         |