u-space 0.0.7 → 0.0.11

package/docs/api-managers.md

@@ -98,8 +98,189 @@ viewer.objectManager.removeByName('sedan');
 viewer.objectManager.removeByType('Model');
 ```
 
+### 显隐控制
+
+#### `show(id: string)` / `hide(id: string)`
+
+控制对象的可见性。
+
+```typescript
+viewer.objectManager.hide('car-01');
+viewer.objectManager.show('car-01');
+```
+
+#### `isolate(ids: string[])`
+
+孤立显示：仅显示指定 ID 的对象，隐藏其余所有。
+
+```typescript
+viewer.objectManager.isolate(['car-01', 'car-02']);
+```
+
+#### `showAll()`
+
+恢复显示所有已管理对象。
+
+```typescript
+viewer.objectManager.showAll();
+```
+
+### 材质操作
+
+#### `setOpacity(id: string, opacity: number)`
+
+设置指定对象所有材质的透明度。
+
+```typescript
+viewer.objectManager.setOpacity('building-01', 0.3);
+viewer.objectManager.setOpacity('building-01', 1.0); // 恢复不透明
+```
+
+### 空间查询
+
+#### `getBoundingBox(id?: string)`
+
+获取指定对象的包围盒，不传 `id` 则返回所有已管理对象的包围盒。
+
+```typescript
+const box = viewer.objectManager.getBoundingBox('car-01');
+const allBox = viewer.objectManager.getBoundingBox(); // 全部对象
+```
+
+### 遍历与过滤
+
+#### `forEach(callback)`
+
+遍历所有已管理对象。
+
+```typescript
+viewer.objectManager.forEach((object, ids) => {
+  console.log(`对象: ${object.name}, IDs: ${Array.from(ids).join(', ')}`);
+});
+```
+
+#### `filter(predicate)`
+
+按条件过滤对象，返回匹配的数组。
+
+```typescript
+const cars = viewer.objectManager.filter((obj) => obj.name.startsWith('car'));
+```
+
 ### 工具方法
 
 - `getAll()`：返回所有已跟踪对象的 `Set<Object3D>`。
 - `clear()`：从所有内部映射中移除所有对象。
 - `size`：返回当前管理器跟踪的唯一对象总数。
+
+---
+
+## SceneManager
+
+`SceneManager` 用于管理多个场景的创建、注册、切换和序列化。
+
+```typescript
+import { SceneManager } from 'u-space';
+
+const sceneManager = new SceneManager();
+```
+
+### 方法
+
+#### `create(key, options?)`
+
+创建并注册一个新场景。
+
+```typescript
+const scene = sceneManager.create('indoor', { background: 0x333333 });
+```
+
+#### `add(key, scene)` / `get(key)` / `remove(key)`
+
+手动注册、获取或移除场景。
+
+```typescript
+sceneManager.add('outdoor', existingScene);
+const scene = sceneManager.get('outdoor');
+sceneManager.remove('outdoor');
+```
+
+#### `serialize(key)`
+
+将场景元数据序列化为 JSON 快照。
+
+```typescript
+const snapshot = sceneManager.serialize('indoor');
+// { name, background, environmentRotation, children }
+```
+
+#### `keys()` / `size` / `clear()`
+
+列出所有场景 key、获取场景数量或清空。
+
+---
+
+## LightManager
+
+`LightManager` 提供灯光的便捷创建、预设和 Helper 可视化。
+
+```typescript
+import { LightManager } from 'u-space';
+
+const lightManager = new LightManager(viewer.scene);
+```
+
+### 灯光创建
+
+```typescript
+lightManager.addAmbient('ambient', { color: 0xffffff, intensity: 0.5 });
+lightManager.addDirectional('sun', { position: { x: 5, y: 10, z: 5 }, castShadow: true });
+lightManager.addPoint('bulb', { position: { x: 0, y: 3, z: 0 }, intensity: 2 });
+lightManager.addSpot('spot', { position: { x: 0, y: 10, z: 0 }, angle: Math.PI / 6 });
+lightManager.addHemisphere('hemi', { skyColor: 0x87ceeb, groundColor: 0x362907 });
+```
+
+### 灯光预设
+
+一键应用常见场景的灯光配置：
+
+```typescript
+lightManager.applyPreset('indoor');     // 室内：环境光 + 顶部点光源
+lightManager.applyPreset('outdoor');    // 室外：半球光 + 方向光（阳光）
+lightManager.applyPreset('studio');     // 摄影棚：三点布光
+lightManager.applyPreset('warehouse');  // 仓库：多点光源照明
+```
+
+| 预设        | 配置                                    |
+| :---------- | :-------------------------------------- |
+| `indoor`    | 环境光 + 2 个点光源                     |
+| `outdoor`   | 半球光 + 方向光（带阴影）               |
+| `studio`    | 环境光 + 主光 + 补光 + 轮廓光           |
+| `warehouse` | 环境光 + 4 个点光源（四角分布）         |
+
+### Helper 可视化
+
+```typescript
+lightManager.showHelper('sun');              // 显示单个灯光 Helper（默认 size=5, color=0xff0000）
+lightManager.showHelper('sun', 2, 0x00ff00); // 自定义尺寸和颜色
+lightManager.showAllHelpers();               // 显示所有灯光 Helper
+lightManager.hideHelper('sun');              // 隐藏单个
+lightManager.hideAllHelpers();               // 隐藏所有
+```
+
+#### `showHelper(id, size?, color?)`
+
+| 参数    | 类型                  | 默认值      | 说明              |
+| :------ | :-------------------- | :---------- | :---------------- |
+| `id`    | `string`              | —           | 灯光 ID。         |
+| `size`  | `number`              | `5`         | Helper 尺寸。     |
+| `color` | `ColorRepresentation` | `0xff0000`  | Helper 颜色。     |
+
+### 管理
+
+```typescript
+lightManager.get('sun');     // 获取灯光
+lightManager.remove('sun');  // 移除灯光
+lightManager.removeAll();    // 移除所有
+lightManager.dispose();      // 清理
+```

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)`    | 在移动相机前叠加到跟踪位置上的偏移量。                    |