u-space 0.0.2 → 0.0.5

package/dist/plugins/u-manager/index.js

@@ -3342,16 +3342,27 @@ function requireWhichTypedArray() {
         var O = r(E);
         S = p(O, Symbol.toStringTag);
       }
-      s["$" + m] = b(S.get);
+      if (S && S.get) {
+        var C = b(S.get);
+        s[
+          /** @type {`$${import('.').TypedArrayName}`} */
+          "$" + m
+        ] = C;
+      }
     }
   }) : h(n, function(m) {
     var A = new t[m](), E = A.slice || A.set;
-    E && (s[
-      /** @type {`$${import('.').TypedArrayName}`} */
-      "$" + m
-    ] = /** @type {import('./types').BoundSlice | import('./types').BoundSet} */
-    // @ts-expect-error TODO FIXME
-    b(E));
+    if (E) {
+      var S = (
+        /** @type {import('./types').BoundSlice | import('./types').BoundSet} */
+        // @ts-expect-error TODO FIXME
+        b(E)
+      );
+      s[
+        /** @type {`$${import('.').TypedArrayName}`} */
+        "$" + m
+      ] = S;
+    }
   });
   var l = function(A) {
     var E = !1;
@@ -4591,43 +4602,11 @@ function require_stream_duplex$1() {
     }
   }), _stream_duplex$1;
 }
-var string_decoder = {}, safeBuffer = { exports: {} }, hasRequiredSafeBuffer;
-function requireSafeBuffer() {
-  return hasRequiredSafeBuffer || (hasRequiredSafeBuffer = 1, (function(h, d) {
-    var b = requireDist(), u = b.Buffer;
-    function p(f, o) {
-      for (var t in f)
-        o[t] = f[t];
-    }
-    u.from && u.alloc && u.allocUnsafe && u.allocUnsafeSlow ? h.exports = b : (p(b, d), d.Buffer = r);
-    function r(f, o, t) {
-      return u(f, o, t);
-    }
-    p(u, r), r.from = function(f, o, t) {
-      if (typeof f == "number")
-        throw new TypeError("Argument must not be a number");
-      return u(f, o, t);
-    }, r.alloc = function(f, o, t) {
-      if (typeof f != "number")
-        throw new TypeError("Argument must be a number");
-      var n = u(f);
-      return o !== void 0 ? typeof t == "string" ? n.fill(o, t) : n.fill(o) : n.fill(0), n;
-    }, r.allocUnsafe = function(f) {
-      if (typeof f != "number")
-        throw new TypeError("Argument must be a number");
-      return u(f);
-    }, r.allocUnsafeSlow = function(f) {
-      if (typeof f != "number")
-        throw new TypeError("Argument must be a number");
-      return b.SlowBuffer(f);
-    };
-  })(safeBuffer, safeBuffer.exports)), safeBuffer.exports;
-}
-var hasRequiredString_decoder;
+var string_decoder = {}, hasRequiredString_decoder;
 function requireString_decoder() {
   if (hasRequiredString_decoder) return string_decoder;
   hasRequiredString_decoder = 1;
-  var h = requireSafeBuffer().Buffer, d = h.isEncoding || function(E) {
+  var h = requireSafeBuffer$1().Buffer, d = h.isEncoding || function(E) {
     switch (E = "" + E, E && E.toLowerCase()) {
       case "hex":
       case "utf8":
@@ -5688,6 +5667,38 @@ var streamBrowser, hasRequiredStreamBrowser;
 function requireStreamBrowser() {
   return hasRequiredStreamBrowser || (hasRequiredStreamBrowser = 1, streamBrowser = requireEvents().EventEmitter), streamBrowser;
 }
+var safeBuffer = { exports: {} }, hasRequiredSafeBuffer;
+function requireSafeBuffer() {
+  return hasRequiredSafeBuffer || (hasRequiredSafeBuffer = 1, (function(h, d) {
+    var b = requireDist(), u = b.Buffer;
+    function p(f, o) {
+      for (var t in f)
+        o[t] = f[t];
+    }
+    u.from && u.alloc && u.allocUnsafe && u.allocUnsafeSlow ? h.exports = b : (p(b, d), d.Buffer = r);
+    function r(f, o, t) {
+      return u(f, o, t);
+    }
+    p(u, r), r.from = function(f, o, t) {
+      if (typeof f == "number")
+        throw new TypeError("Argument must not be a number");
+      return u(f, o, t);
+    }, r.alloc = function(f, o, t) {
+      if (typeof f != "number")
+        throw new TypeError("Argument must be a number");
+      var n = u(f);
+      return o !== void 0 ? typeof t == "string" ? n.fill(o, t) : n.fill(o) : n.fill(0), n;
+    }, r.allocUnsafe = function(f) {
+      if (typeof f != "number")
+        throw new TypeError("Argument must be a number");
+      return u(f);
+    }, r.allocUnsafeSlow = function(f) {
+      if (typeof f != "number")
+        throw new TypeError("Argument must be a number");
+      return b.SlowBuffer(f);
+    };
+  })(safeBuffer, safeBuffer.exports)), safeBuffer.exports;
+}
 var util = {}, hasRequiredUtil;
 function requireUtil() {
   if (hasRequiredUtil) return util;
@@ -9898,7 +9909,7 @@ function requireBn$1() {
           var _ = 67108863 ^ 67108863 >>> g << g;
           this.words[this.length - 1] &= _;
         }
-        return this.strip();
+        return this.length === 0 && (this.words[0] = 0, this.length = 1), this.strip();
       }, r.prototype.maskn = function(v) {
         return this.clone().imaskn(v);
       }, r.prototype.iaddn = function(v) {
@@ -11279,7 +11290,7 @@ function requireBn() {
           var q = 67108863 ^ 67108863 >>> _ << _;
           this.words[this.length - 1] &= q;
         }
-        return this._strip();
+        return this.length === 0 && (this.words[0] = 0, this.length = 1), this._strip();
       }, r.prototype.maskn = function(c) {
         return this.clone().imaskn(c);
       }, r.prototype.iaddn = function(c) {

package/dist/src/objects/Model.d.ts

@@ -1,4 +1,4 @@
-import { type Object3D } from 'three/webgpu';
+import { type Object3D, AnimationMixer, type AnimationAction, type AnimationClip } from 'three/webgpu';
 import { type InteractionEventMap } from '../interactions';
 import { BaseGroup } from './BaseGroup';
 export interface ModelParameters {
@@ -6,12 +6,25 @@ export interface ModelParameters {
     cache?: boolean;
     persistent?: boolean;
 }
+export interface PlayAnimationOptions {
+    loop?: boolean;
+    repetitions?: number;
+    timeScale?: number;
+    clampWhenFinished?: boolean;
+}
 export declare class Model extends BaseGroup<InteractionEventMap> {
     readonly isModel = true;
     type: string;
     private static memoryCache;
+    mixer: AnimationMixer | null;
+    animations: AnimationClip[];
+    private actions;
     constructor();
     loadAsync(parameters: ModelParameters): Promise<Object3D<import("three").Object3DEventMap> | null>;
+    playAnimation(nameOrIndex?: string | number, options?: PlayAnimationOptions): AnimationAction | null;
+    playAllAnimations(options?: PlayAnimationOptions): AnimationAction[];
+    stopAnimation(nameOrIndex?: string | number): void;
+    updateAnimation(delta: number): void;
     static clearMemoryCache(): void;
     static clearPersistentCache(): Promise<void>;
 }

package/dist/src/objects/Poi.d.ts

@@ -21,11 +21,15 @@ export interface PoiParameters {
     borderRadius?: number;
     /** Text position relative to the icon */
     textPosition?: 'top' | 'bottom' | 'left' | 'right';
+    /** Scale factor for mapping canvas pixels to world units */
+    scaleFactor?: number;
 }
 export declare class Poi extends BaseSprite<InteractionEventMap> {
     readonly isPoi = true;
     type: string;
     parameters: Required<PoiParameters>;
+    private _canvas;
+    private _lastParametersJSON;
     constructor(parameters?: PoiParameters);
     /**
      * Update the POI with new parameters

package/dist/src/viewers/Viewer.d.ts

@@ -14,15 +14,19 @@ export interface ViewerOptions {
 export interface ViewerEventMap {
     beforeControlsUpdate: {
         time: number;
+        delta: number;
     };
     afterControlsUpdate: {
         time: number;
+        delta: number;
     };
     beforeRender: {
         time: number;
+        delta: number;
     };
     afterRender: {
         time: number;
+        delta: number;
     };
     cameraChange: {
         camera: PerspectiveCamera | OrthographicCamera;

package/docs/api-objects.md

@@ -66,6 +66,64 @@ const model3 = new Model();
 model3.loadAsync({ url: 'model.glb', cache: true, persistent: true });
 ```
 
+### 动画
+
+`Model` 在加载含内置动画的模型（如 glTF/FBX）后，会自动初始化 `AnimationMixer` 并收集 `AnimationClip`。
+
+**属性：**
+
+| 属性         | 类型                        | 说明                                       |
+| :----------- | :-------------------------- | :----------------------------------------- |
+| `mixer`      | `AnimationMixer \| null`    | 动画混合器，加载含动画模型后自动创建。     |
+| `animations` | `AnimationClip[]`           | 模型内置的动画片段列表。                   |
+
+#### `playAnimation(nameOrIndex?, options?)`
+
+播放指定动画。不传参时播放第一个动画。
+
+```typescript
+// 按名称播放
+model.playAnimation('Walk');
+
+// 按索引播放
+model.playAnimation(0);
+
+// 带选项
+model.playAnimation('Run', {
+  loop: true,          // 是否循环（默认 true）
+  repetitions: 3,      // 循环次数（默认 Infinity）
+  timeScale: 1.5,      // 播放速度（默认 1）
+  clampWhenFinished: true, // 播放结束后停留在最后一帧（默认 false）
+});
+```
+
+#### `playAllAnimations(options?)`
+
+播放模型所有内置动画。参数同 `playAnimation`。
+
+```typescript
+model.playAllAnimations({ timeScale: 2 });
+```
+
+#### `stopAnimation(nameOrIndex?)`
+
+停止指定动画。不传参时停止所有动画。
+
+```typescript
+model.stopAnimation('Walk'); // 停止指定动画
+model.stopAnimation();       // 停止所有动画
+```
+
+#### `updateAnimation(delta)`
+
+推进动画时间，需在渲染循环中调用。`delta` 为帧间隔时间（秒），可从 Viewer 事件的 `delta` 属性获取。
+
+```typescript
+viewer.addEventListener('beforeRender', (e) => {
+  model.updateAnimation(e.delta);
+});
+```
+
 ### 清除缓存
 
 可通过 `Model` 类的静态方法手动清除内部缓存：
@@ -186,7 +244,9 @@ const poi = new Poi({
   backgroundColor: 'rgba(0,0,0,0.6)',
   textPosition: 'right',
 });
-await poi.updateAsync(); // 渲染 canvas 纹理
+// 构造时会自动调用 updateAsync()，无需手动调用
+// 如需更新参数，可再次调用：
+// await poi.updateAsync({ text: '新文字' });
 
 poi.position.set(10, 5, 10);
 viewer.scene.add(poi);
@@ -203,15 +263,16 @@ viewer.scene.add(poi);
 | `color`           | `string`                                    | `'#ffffff'`              | 文字颜色。                         |
 | `iconSize`        | `number`                                    | `64`                     | 图标大小（像素）。                 |
 | `padding`         | `number`                                    | `10`                     | 内容四周的内边距。                 |
-| `backgroundColor` | `string`                                    | `'rgba(0, 0, 0, 0.5)'`  | 背景填充颜色。                     |
+| `backgroundColor` | `string`                                    | `'rgba(0, 0, 0, 0)'`    | 背景填充颜色。                     |
 | `borderRadius`    | `number`                                    | `8`                      | 背景圆角半径。                     |
 | `textPosition`    | `'top' \| 'bottom' \| 'left' \| 'right'`   | `'right'`                | 文字相对图标的位置。               |
+| `scaleFactor`     | `number`                                    | `0.01`                   | canvas 像素到世界单位的缩放系数。  |
 
 ### 方法
 
 #### `updateAsync(parameters?)`
 
-使用可选的参数覆盖重新渲染 canvas 纹理。
+使用可选的参数覆盖重新渲染 canvas 纹理。构造时会自动调用一次，后续参数未变化时会跳过重绘。
 
 ```typescript
 await poi.updateAsync({ text: '更新后的标签', color: '#ffff00' });
@@ -306,6 +367,25 @@ viewer.render();
 
 返回节点的邻接表（邻居 ID → 边权重）。
 
+#### `exportData(): TopologyData`
+
+将当前拓扑图（节点和边）导出为 JSON 可序列化对象。
+
+```typescript
+const data = topo.exportData();
+// { nodes: Record<string, {x,y,z}>, edges: Array<{from,to,weight}> }
+```
+
+双向边在导出时会去重，只保留一条记录。
+
+#### `importData(data: TopologyData)`
+
+从 `exportData()` 返回的数据中还原拓扑图，替换当前所有节点、边和路径网格，并重新渲染。
+
+```typescript
+topo.importData(data);
+```
+
 #### `dispose()`
 
 清除图和路径网格。

package/docs/api-plugins.md

@@ -2,9 +2,7 @@
 
 `u-space` 架构包含一套丰富的插件，提供从 GIS 瓦片加载到键盘控制和场景管理等高级功能。所有插件从 `u-space/plugins/*` 命名空间导入。
 
-## 可用插件
-
-### `keyboard-controls`
+## `keyboard-controls`
 
 为激活相机提供 WASD 或方向键的平移和旋转控制。
 
@@ -45,7 +43,7 @@ import { ACTION } from 'u-space/plugins/keyboard-controls';
 keyboardControls.keys['Space'] = ACTION.MOVE_UP;
 ```
 
-### `minimap`
+## `minimap`
 
 生成一个 2D 小地图叠加层，在 3D 场景中跟踪目标对象。渲染到注入 `viewer.el` 的 `<canvas>` 元素中。
 
@@ -82,7 +80,7 @@ minimap.dispose();
 - `disable()` — 移除画布并停止渲染。
 - `dispose()` — 禁用并清理所有资源。
 
-### `tiles`
+## `tiles`
 
 提供与 `3d-tiles-renderer` 和地理空间数据的集成。主要导出 `ArcgisTilesRenderer`，可流式加载 ArcGIS Online 3D 瓦片并将地球重新定向到指定地理位置。
 
@@ -109,7 +107,7 @@ arcgisTilesRenderer.enable();
 | `disable()`                 | 从场景中移除瓦片并暂停更新循环。                                                               |
 | `dispose()`                 | 禁用并完全释放瓦片渲染器。                                                                     |
 
-### `u-manager`
+## `u-manager`
 
 `u-manager` 是一套全面的加载器和解析器，用于从服务器路径流式传输、解密并显示结构化场景数据。支持场景、拓扑、动画、属性和相机视点。
 
@@ -233,7 +231,7 @@ const modelProps = properties.filter(p => p.modelId === myModel.userData.id);
 | `value`   | `string \| null` | 属性值。                 |
 | `label`   | `string \| null` | 属性的显示标签。         |
 
-### `curve-movement`
+## `curve-movement`
 
 沿样条路径对相机或对象进行动画。提供两个具体子类：`CurveMovementCamera` 和 `CurveMovementObject`。
 
@@ -272,7 +270,7 @@ movement.addEventListener('complete', () => console.log('完成'));
 | `positionOffset`| `Vector3`                          | `(0,0,0)` | 叠加到每个位置上的世界坐标偏移量。   |
 | `direction`     | `1 \| -1`                          | `1`       | 当前行进方向。                       |
 
-### `tracking-controls`
+## `tracking-controls`
 
 使相机平滑跟随移动的 `Object3D` 目标。
 
@@ -296,7 +294,7 @@ tracking.enable();
 | `type`   | `'position' \| 'box3'` | `'position'` | 跟踪世界位置还是包围盒中心。                              |
 | `offset` | `Vector3`               | `(0,0,0)`    | 在移动相机前叠加到跟踪位置上的偏移量。                    |
 
-### `atmosphere`
+## `atmosphere`
 
 天空和大气渲染插件。目前为占位实现，`enable()` / `disable()` / `dispose()` 方法可用，但尚未实现具体功能。
 
@@ -307,7 +305,7 @@ const atmosphere = new Atmosphere(viewer);
 atmosphere.enable();
 ```
 
-### `object-controls`
+## `object-controls`
 
 对场景中的 3D 对象进行交互式移动、旋转、缩放操作。继承自 Three.js `TransformControls`，集成了 u-space `Viewer` 生命周期管理。
 
@@ -375,7 +373,7 @@ controls.addEventListener('dragging-changed', ({ value }) => {
 
 > 由于 `ObjectControls` 直接继承 `TransformControls`，所有原生属性（`translationSnap`、`rotationSnap`、`scaleSnap`、`showX/Y/Z` 等）和事件均可直接使用，参考 [Three.js TransformControls 文档](https://threejs.org/docs/#examples/en/controls/TransformControls)。
 
-### `topology-drawer`
+## `topology-drawer`
 
 在 3D 场景中交互式绘制拓扑路径图。点击场景中的任意对象表面放置节点，自动连接成路径；点击空白处则落回不可见的地面平面。事件检测通过 `viewer.interactionManager` 实现（`scene.addEventListener` 冒泡）。
 

package/docs/api-viewer.md

@@ -100,6 +100,52 @@ const camera = viewer.createOrthographicCamera();
 viewer.setCamera(camera);
 ```
 
+## 调试工具
+
+### Info
+
+`viewer.info` 是一个轻量的渲染统计叠加层，显示当前帧的 GPU 诊断数据，适合开发调试阶段使用。
+
+```typescript
+viewer.info.enable();  // 在画面左下角显示统计信息
+viewer.info.disable(); // 隐藏统计信息
+```
+
+启用后将在 `viewer.el` 左下角叠加以下数据：
+
+| 指标           | 说明                          |
+| :------------- | :---------------------------- |
+| `draw calls`   | 当前帧的绘制调用次数          |
+| `frame calls`  | 当前帧的帧调用次数            |
+| `triangles`    | 当前帧渲染的三角面数量        |
+| `points`       | 当前帧渲染的点数量            |
+| `lines`        | 当前帧渲染的线段数量          |
+| `timestamp`    | GPU 渲染耗时（ms，WebGPU 专属）|
+
+> `timestamp` 指标仅在 WebGPU 后端可用，WebGL 回退模式下显示 `0`。
+
+### ViewerHelper
+
+`viewer.viewerHelper` 是一个方向指示器 gizmo（基于 Three.js `ViewHelper`），显示当前相机朝向的 XYZ 轴，渲染为画面角落的叠加层。
+
+```typescript
+viewer.viewerHelper.enable();  // 显示方向 gizmo
+viewer.viewerHelper.disable(); // 隐藏方向 gizmo
+```
+
+**属性：**
+
+| 属性           | 类型        | 说明                                      |
+| :------------- | :---------- | :---------------------------------------- |
+| `location`     | `object`    | gizmo 在画面中的位置，支持 `top`、`bottom`、`left`、`right` 偏移（像素）。默认右下角。 |
+
+```typescript
+// 调整位置到左下角
+viewer.viewerHelper.location.left = 12;
+viewer.viewerHelper.location.bottom = 12;
+viewer.viewerHelper.location.right = null;
+```
+
 ### `dispose()`
 
 清理查看器，从 DOM 中移除 canvas，移除事件监听，并释放渲染器和环境贴图，以防止内存泄漏。
@@ -112,8 +158,10 @@ viewer.dispose();
 
 Viewer 继承自 `EventDispatcher`，会触发以下事件：
 
-- `beforeControlsUpdate`：在 `CameraControls` 更新之前触发，提供 `{ time: number }`。
-- `afterControlsUpdate`：在 `CameraControls` 更新之后触发，提供 `{ time: number }`。
-- `beforeRender`：在 `renderer.render` 调用之前立即触发，提供 `{ time: number }`。
-- `afterRender`：在 `renderer.render` 完成之后立即触发，提供 `{ time: number }`。
+- `beforeControlsUpdate`：在 `CameraControls` 更新之前触发，提供 `{ time: number; delta: number }`。
+- `afterControlsUpdate`：在 `CameraControls` 更新之后触发，提供 `{ time: number; delta: number }`。
+- `beforeRender`：在 `renderer.render` 调用之前立即触发，提供 `{ time: number; delta: number }`。
+- `afterRender`：在 `renderer.render` 完成之后立即触发，提供 `{ time: number; delta: number }`。
 - `cameraChange`：调用 `setCamera` 时触发，提供 `{ camera: Camera }`。
+
+其中 `delta` 为上一帧到当前帧的时间间隔（秒），可用于动画更新等场景。

package/docs/examples-guide.md

@@ -46,3 +46,17 @@
 - 流式传输结构化场景布局，解析场景描述（`SceneLoader`、`TopologiesLoader`）。
 - 使用相机动画（`VisionsLoader` 和 `VisionsParser`）在场景中编排预定义的飞行路径。
 - 获取复杂的节点材质，并自定义 WebGPU 专属的 TSL（Three Shading Language）节点，如 `TSLEffects.fluid()`。
+
+## 5. `test_model_animation.html`：模型内置动画
+
+[在线演示](https://u-space-phi.vercel.app/examples/test_model_animation.html)
+
+该示例演示了如何加载含内置动画的 glTF 模型，并通过 `Model` 类的动画 API 控制播放。
+
+### 核心要点：
+
+- 使用 `Model.loadAsync()` 加载带动画的 `.glb` 文件，动画片段自动初始化。
+- 使用 `viewer.frameloop = 'always'` 开启持续渲染以驱动动画。
+- 监听 `beforeRender` 事件，通过 `model.updateAnimation(e.delta)` 推进动画时间。
+- 使用 `model.playAnimation(name)` 按名称播放单个动画，`model.playAllAnimations()` 播放全部。
+- 使用 `model.stopAnimation()` 停止动画播放。

package/docs/getting-started.md

@@ -93,8 +93,7 @@ pnpm install three camera-controls
 `u-space` 内置了 `InteractionManager`，可以轻松为 3D 对象添加事件监听。
 
 ```javascript
-// 启用指针移动事件
-viewer.interactionManager.targetObjects = [];
+// 启用指针移动事件（pointerenter / pointerleave 需要此开关）
 viewer.interactionManager.pointerMoveEventsEnabled = true;
 
 // 添加点击事件

package/docs/index.md

@@ -48,3 +48,5 @@ features:
 | [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) | 在场景任意表面交互式绘制拓扑路径图 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-space",
-  "version": "0.0.2",
+  "version": "0.0.5",
   "type": "module",
   "types": "dist/src/index.d.ts",
   "module": "dist/index.js",
@@ -29,7 +29,7 @@
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
     "docs:deploy": "pnpm docs:build && vercel --prod",
-    "release": "npm publish --access=public"
+    "release": "npm version patch && npm publish --access=public"
   },
   "files": [
     "dist",