u-space 0.0.0-alpha.2 → 0.0.2

package/docs/api-interactions.md

@@ -1,63 +1,63 @@
 # Interactions API
 
-The `InteractionManager` provides a unified way to handle user input (mouse, touch, pointer) over 3D scenes. It resolves the raycasting from screen space to world space and dispatches corresponding events directly directly to the intersected 3D objects.
+`InteractionManager` 提供了一种统一的方式来处理 3D 场景中的用户输入（鼠标、触摸、指针）。它将屏幕空间的射线检测转换为世界空间坐标，并将对应事件直接分发到被命中的 3D 对象上。
 
-The `InteractionManager` is automatically instantiated within the `Viewer` at `viewer.interactionManager`.
+`InteractionManager` 在 `Viewer` 内部自动实例化，可通过 `viewer.interactionManager` 访问。
 
-## Enabling Interaction Events
+## 启用交互事件
 
-By default, pointer move events might be disabled for performance reasons. You need to enable them if you want hover and drag effects. This should be explicitly set for interactive applications.
+出于性能考虑，指针移动事件默认可能处于禁用状态。如需悬停和拖拽效果，必须显式开启。
 
 ```typescript
-// Enable events on mouse move (like pointerenter and pointerleave)
+// 启用鼠标移动事件（如 pointerenter 和 pointerleave）
 viewer.interactionManager.pointerMoveEventsEnabled = true;
 ```
 
-### Targeting Objects
+### 目标对象
 
-You can limit which objects the raycaster checks.
+可以限制射线检测所针对的对象范围。默认值为 `scene.children`（即整个场景的直接子级，含递归嵌套）。
 
 ```typescript
-// Default behavior: checks the entire scene
-viewer.interactionManager.targetObjects = [];
+// 仅检测指定对象
+viewer.interactionManager.targetObjects = [myBox, myModel];
 
-// Check only specific objects
-// viewer.interactionManager.targetObjects = [myBox, myModel];
+// 恢复默认：检测整个场景
+viewer.interactionManager.targetObjects = viewer.scene.children;
 ```
 
-## Adding Event Listeners
+## 添加事件监听
 
-Because `u-space` objects (and `BaseMesh`, `BaseGroup` by extension) support custom events, you can attach listeners natively just like a DOM element.
+由于 `u-space` 对象（以及继承自 `BaseMesh`、`BaseGroup` 的对象）支持自定义事件，你可以像操作 DOM 元素一样原生地绑定监听器。
 
 ```typescript
 const myBox = new Mesh(geometry, material);
 viewer.scene.add(myBox);
 
-// Example listener attached directly to the 'Mesh' or 'Model'
+// 直接在 Mesh 或 Model 上绑定监听器
 myBox.addEventListener('click', (eventData) => {
-  // The underlying pointer event and raycast intersection information
+  // 底层指针事件和射线检测数据
   const intersect = eventData.event.intersect;
 
-  console.log('Clicked at position:', intersect.point);
+  console.log('点击位置：', intersect.point);
 });
 ```
 
-## Supported Events
+## 支持的事件类型
 
-The following event types can be listened to on interactive objects:
+以下事件类型可在可交互对象上监听：
 
-- `click`: Fired when the pointer clicks on an object (filtered: ignored after long press or large move).
-- `dblclick`: Fired when the object is double-clicked rapidly.
-- `contextmenu`: Fired on right-click (prevents default browser context menu).
-- `pointerdown`: Fired when a pointer button is depressed over an object.
-- `pointerup`: Fired when a pointer button is released over an object.
-- `pointermove`: Fired while the pointer moves over an object. Requires `pointerMoveEventsEnabled = true`.
-- `pointerenter`: Fired when the cursor enters the boundaries of an object. Requires `pointerMoveEventsEnabled = true`.
-- `pointerleave`: Fired when the cursor leaves the boundaries of an object. Requires `pointerMoveEventsEnabled = true`.
+- `click`：指针点击对象时触发（过滤：长按或大幅移动后忽略）。
+- `dblclick`：快速双击对象时触发。
+- `rightclick`：右键短按松开时触发（长按或拖拽不触发；浏览器原生上下文菜单已被阻止）。与原生 `contextmenu` 的区别在于，此事件在 `pointerup` 时派发，因此可以正确过滤相机拖拽等操作。
+- `pointerdown`：指针按键在对象上按下时触发。
+- `pointerup`：指针按键在对象上释放时触发。
+- `pointermove`：指针在对象上移动时触发，需要 `pointerMoveEventsEnabled = true`。
+- `pointerenter`：光标进入对象范围时触发，需要 `pointerMoveEventsEnabled = true`。
+- `pointerleave`：光标离开对象范围时触发，需要 `pointerMoveEventsEnabled = true`。
 
-### Event Propagation
+### 事件冒泡
 
-Events bubble up the parent chain. To stop an event from continuing, call `stopPropagation()` on the event payload:
+事件会沿父级链向上冒泡。若要阻止事件继续传播，可调用事件载荷上的 `stopPropagation()`：
 
 ```typescript
 myObject.addEventListener('click', (e) => {
@@ -67,42 +67,42 @@ myObject.addEventListener('click', (e) => {
 
 ## `InteractionEvent`
 
-The event object passed to all listener callbacks under the `event` key.
+传递给所有监听回调的事件对象，位于 `event` 键下。
 
-### Properties
+### 属性
 
-| Property        | Type                                       | Description                                                                         |
-| :-------------- | :----------------------------------------- | :---------------------------------------------------------------------------------- |
-| `type`          | `InteractionEventType`                     | The event type string (e.g., `'click'`).                                            |
-| `target`        | `Object3D`                                 | The original 3D object that triggered the event (first intersection).               |
-| `currentTarget` | `Object3D`                                 | The current object in the bubbling chain.                                           |
-| `intersect`     | `Intersection \| null`                     | Three.js raycaster intersection data: `point`, `face`, `distance`, `uv`, etc.       |
-| `originalEvent` | `PointerEvent \| MouseEvent`               | The original DOM pointer/mouse event.                                               |
+| 属性            | 类型                                       | 说明                                                                        |
+| :-------------- | :----------------------------------------- | :-------------------------------------------------------------------------- |
+| `type`          | `InteractionEventType`                     | 事件类型字符串（如 `'click'`）。                                            |
+| `target`        | `Object3D`                                 | 触发事件的原始 3D 对象（第一个命中点）。                                    |
+| `currentTarget` | `Object3D`                                 | 冒泡链中当前处理事件的对象。                                                |
+| `intersect`     | `Intersection \| null`                     | Three.js 射线检测数据：`point`、`face`、`distance`、`uv` 等。               |
+| `originalEvent` | `PointerEvent \| MouseEvent`               | 原始 DOM 指针/鼠标事件。                                                    |
 
-### Methods
+### 方法
 
 #### `stopPropagation()`
 
-Stops the event from bubbling further up the parent hierarchy.
+阻止事件继续向上冒泡。
 
 ## `InteractionManager` API
 
-### Properties
+### 属性
 
-| Property                  | Type                          | Default | Description                                                        |
-| :------------------------ | :---------------------------- | :------ | :----------------------------------------------------------------- |
-| `targetObjects`           | `Object3D[] \| null`          | `null`  | Objects to raycast against. `null` means all scene children.       |
-| `pointerMoveEventsEnabled`| `boolean`                     | `false` | Enables `pointermove`, `pointerenter`, `pointerleave` events.      |
+| 属性                       | 类型                          | 默认值  | 说明                                                       |
+| :------------------------- | :---------------------------- | :------ | :--------------------------------------------------------- |
+| `targetObjects`            | `Object3D[]`                  | `scene.children` | 射线检测的目标对象列表，默认为场景的直接子级。  |
+| `pointerMoveEventsEnabled` | `boolean`                     | `false` | 启用 `pointermove`、`pointerenter`、`pointerleave` 事件。  |
 
-### Methods
+### 方法
 
 #### `setCamera(camera)`
 
-Updates the camera used for raycasting. Called automatically by `viewer.setCamera()`.
+更新用于射线检测的相机。由 `viewer.setCamera()` 自动调用。
 
 #### `dispose()`
 
-Removes all DOM event listeners and cleans up internal state.
+移除所有 DOM 事件监听，清理内部状态。
 
 ```typescript
 viewer.interactionManager.dispose();

package/docs/api-managers.md

@@ -1,35 +1,35 @@
 # Managers API
 
-`u-space` utilizes specialized managers for handling specific domain logic, such as `ObjectManager` for caching and registering 3D objects.
+`u-space` 使用专用管理器来处理特定领域的逻辑，例如用于缓存和注册 3D 对象的 `ObjectManager`。
 
 ## ObjectManager
 
-The `ObjectManager` provides a centralized dictionary/map layer to easily retrieve complex models or specific meshes by string IDs or string names without having to recursively traverse the Three.js scene graph.
+`ObjectManager` 提供了一个集中式字典/映射层，让你无需递归遍历 Three.js 场景图，就能通过字符串 ID 或字符串名称轻松检索复杂模型或特定网格。
 
-The default instance is available via `viewer.objectManager`.
+默认实例可通过 `viewer.objectManager` 访问。
 
-### Adding Objects
+### 添加对象
 
-When you add an object to the manager, you must provide a unique identifier.
+向管理器添加对象时，必须提供唯一标识符。
 
 ```typescript
 const myModel = new Model();
-// ... load logic
+// ... 加载逻辑
 
-// Add with a specific unique ID
+// 用指定的唯一 ID 添加
 viewer.objectManager.add('my-unique-car-id', myModel);
 
-// An object can be registered under multiple IDs
+// 一个对象可以注册多个 ID
 viewer.objectManager.add('player-vehicle', myModel);
 ```
 
-### Retrieving Objects
+### 检索对象
 
-The manager gives you fast access to your objects.
+管理器提供快速访问对象的方法。
 
 #### `getById(id: string)`
 
-Retrieves exactly one object (or `undefined`) matching the specific ID.
+精确检索与指定 ID 匹配的一个对象（或 `undefined`）。
 
 ```typescript
 const car = viewer.objectManager.getById('my-unique-car-id');
@@ -37,10 +37,10 @@ const car = viewer.objectManager.getById('my-unique-car-id');
 
 #### `getByName(name: string)`
 
-Because Three.js objects can share the same `.name` property, this method returns a `Set<Object3D>` encompassing all registered objects that match the requested name.
+由于 Three.js 对象可以共享同一个 `.name` 属性，此方法返回一个 `Set<Object3D>`，包含所有与指定名称匹配的已注册对象。
 
 ```typescript
-// Assuming myModel.name = 'sedan'
+// 假设 myModel.name = 'sedan'
 const sedans = viewer.objectManager.getByName('sedan');
 
 sedans.forEach((vehicle) => {
@@ -50,7 +50,7 @@ sedans.forEach((vehicle) => {
 
 #### `getByType(type: string)`
 
-Returns a `Set<Object3D>` of all registered objects whose `object.type` matches `type`.
+返回一个 `Set<Object3D>`，包含所有 `object.type` 与指定类型匹配的已注册对象。
 
 ```typescript
 const models = viewer.objectManager.getByType('Model');
@@ -58,17 +58,17 @@ const models = viewer.objectManager.getByType('Model');
 
 #### `getObjectIds(object: Object3D)`
 
-Returns a `Set<string>` of all IDs registered for a given object.
+返回给定对象已注册的所有 ID 的 `Set<string>`。
 
 ```typescript
 const ids = viewer.objectManager.getObjectIds(myModel);
 ```
 
-### Removing Objects
+### 移除对象
 
 #### `remove(object: Object3D)`
 
-Removes an object and all its associated IDs from all internal maps.
+从所有内部映射中移除该对象及其所有关联 ID。
 
 ```typescript
 viewer.objectManager.remove(myModel);
@@ -76,7 +76,7 @@ viewer.objectManager.remove(myModel);
 
 #### `removeById(id: string)`
 
-Removes the object registered under the given ID.
+移除注册在指定 ID 下的对象。
 
 ```typescript
 viewer.objectManager.removeById('my-unique-car-id');
@@ -84,7 +84,7 @@ viewer.objectManager.removeById('my-unique-car-id');
 
 #### `removeByName(name: string)`
 
-Removes all objects with the given `.name`.
+移除所有具有指定 `.name` 的对象。
 
 ```typescript
 viewer.objectManager.removeByName('sedan');
@@ -92,14 +92,14 @@ viewer.objectManager.removeByName('sedan');
 
 #### `removeByType(type: string)`
 
-Removes all objects with the given `.type`.
+移除所有具有指定 `.type` 的对象。
 
 ```typescript
 viewer.objectManager.removeByType('Model');
 ```
 
-### Utility Methods
+### 工具方法
 
-- `getAll()`: Returns a `Set<Object3D>` of all tracked objects.
-- `clear()`: Removes all objects from all internal maps.
-- `size`: Returns the total number of unique objects currently tracked by the manager.
+- `getAll()`：返回所有已跟踪对象的 `Set<Object3D>`。
+- `clear()`：从所有内部映射中移除所有对象。
+- `size`：返回当前管理器跟踪的唯一对象总数。

package/docs/api-objects.md

@@ -1,32 +1,32 @@
 # Objects API
 
-`u-space` provides several object wrappers that make manipulating and loading 3D assets easier, primarily extending Three.js's basic nodes.
+`u-space` 提供了若干对象封装类，主要扩展自 Three.js 的基础节点，使 3D 资产的操作和加载更加便捷。
 
-## Base Classes
+## 基础类
 
 ### `BaseMesh`
 
-Extends `THREE.Mesh`. All primitive mesh classes in `u-space` inherit from this.
+继承自 `THREE.Mesh`，`u-space` 中所有基础网格类都继承于此。
 
-**Key property:**
+**关键属性：**
 
-| Property                     | Type      | Default | Description                                                                     |
-| :--------------------------- | :-------- | :------ | :------------------------------------------------------------------------------ |
-| `ignoreInvisibleWhenRaycast` | `boolean` | `true`  | When `true`, invisible meshes are skipped during raycasting (no hit detection). |
+| 属性                         | 类型      | 默认值 | 说明                                                           |
+| :--------------------------- | :-------- | :----- | :------------------------------------------------------------- |
+| `ignoreInvisibleWhenRaycast` | `boolean` | `true` | 为 `true` 时，不可见的网格在射线检测时会被跳过（不参与碰撞）。 |
 
 ### `BaseGroup`
 
-Extends `THREE.Group`. `Model` and `Topology` inherit from this.
+继承自 `THREE.Group`，`Model` 和 `Topology` 均继承于此。
 
-**Key property:**
+**关键属性：**
 
-| Property                     | Type      | Default | Description                                                                      |
-| :--------------------------- | :-------- | :------ | :------------------------------------------------------------------------------- |
-| `ignoreInvisibleWhenRaycast` | `boolean` | `true`  | When `true`, invisible groups are skipped during raycasting (no hit detection).  |
+| 属性                         | 类型      | 默认值 | 说明                                                             |
+| :--------------------------- | :-------- | :----- | :--------------------------------------------------------------- |
+| `ignoreInvisibleWhenRaycast` | `boolean` | `true` | 为 `true` 时，不可见的组在射线检测时会被跳过（不参与碰撞）。     |
 
-## Models
+## 模型
 
-The `Model` class extends `BaseGroup` (which in turn extends `THREE.Group`) and simplifies the process of asynchronously loading external 3D models like `glb` and `gltf` files. It features built-in support for different caching layers.
+`Model` 类继承自 `BaseGroup`（进而继承自 `THREE.Group`），简化了异步加载 `glb`、`gltf` 等外部 3D 模型的流程，内置多层缓存支持。
 
 ```typescript
 import { Model } from 'u-space';
@@ -34,9 +34,9 @@ import { Model } from 'u-space';
 const myModel = new Model();
 ```
 
-### Loading Assets
+### 加载资产
 
-The `loadAsync` method handles loading the asset from a URL and adding it to the group.
+`loadAsync` 方法负责从 URL 加载资产并将其添加到组中。
 
 ```typescript
 await myModel.loadAsync(options: ModelLoadOptions)
@@ -44,38 +44,38 @@ await myModel.loadAsync(options: ModelLoadOptions)
 
 #### `ModelLoadOptions`
 
-| Property     | Type      | Description                                                                                                                      |
-| :----------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------- |
-| `url`        | `string`  | The URL of the `.gltf` or `.glb` file.                                                                                           |
-| `cache`      | `boolean` | (Optional) Enables in-memory caching. If a model has been loaded before, it retrieves it instantly from memory. Default `false`. |
-| `persistent` | `boolean` | (Optional) Enables persistent disk-level caching using the browser's Cache API. Good for larger models. Default `false`.         |
+| 属性         | 类型      | 说明                                                                                                               |
+| :----------- | :-------- | :----------------------------------------------------------------------------------------------------------------- |
+| `url`        | `string`  | `.gltf` 或 `.glb` 文件的 URL。                                                                                     |
+| `cache`      | `boolean` | （可选）启用内存缓存。若模型已加载过，则直接从内存中获取。默认 `false`。                                           |
+| `persistent` | `boolean` | （可选）使用浏览器 Cache API 启用持久化磁盘缓存，适合较大的模型。默认 `false`。                                    |
 
-#### Caching Example
+#### 缓存示例
 
 ```javascript
-// Load a model from network and persist it
+// 从网络加载并持久化
 const model1 = new Model();
 model1.loadAsync({ url: 'model.glb', persistent: true });
 
-// Sometime later, this will load from Cache API
+// 稍后，将从 Cache API 加载
 const model2 = new Model();
 model2.loadAsync({ url: 'model.glb', persistent: true });
 
-// This will load from fast Memory Cache
+// 从内存缓存快速加载
 const model3 = new Model();
 model3.loadAsync({ url: 'model.glb', cache: true, persistent: true });
 ```
 
-### Clearing Caches
+### 清除缓存
 
-You can manually clear the internal caches using static methods on the `Model` class:
+可通过 `Model` 类的静态方法手动清除内部缓存：
 
-- `Model.clearMemoryCache()`: Clears the transient runtime memory cache.
-- `await Model.clearPersistentCache()`: Completely clears the browser's persistent cache for `u-space` models.
+- `Model.clearMemoryCache()`：清除运行时内存缓存。
+- `await Model.clearPersistentCache()`：完全清除浏览器中 `u-space` 模型的持久化缓存。
 
-## Meshes
+## 网格
 
-`u-space` offers a variety of streamlined Mesh classes extending `BaseMesh`. All use `MeshStandardNodeMaterial` by default, accept a `{ geometryParameters, materialParameters }` constructor shape, and support interaction event dispatching.
+`u-space` 提供了多种精简的网格类，均继承自 `BaseMesh`。所有类默认使用 `MeshStandardNodeMaterial`，构造函数接受 `{ geometryParameters, materialParameters }` 参数，并支持交互事件分发。
 
 ### `SphereMesh`
 
@@ -90,14 +90,14 @@ const sphere = new SphereMesh({
 
 **`SphereMeshParameters`**
 
-| Property              | Type                                | Description                              |
-| :-------------------- | :---------------------------------- | :--------------------------------------- |
-| `geometryParameters`  | `SphereGeometry` constructor params | `radius`, `widthSegments`, `heightSegments`, etc. |
-| `materialParameters`  | `MeshStandardNodeMaterialParameters`| Standard material options (color, etc.). |
+| 属性                  | 类型                                 | 说明                                             |
+| :-------------------- | :----------------------------------- | :----------------------------------------------- |
+| `geometryParameters`  | `SphereGeometry` 构造函数参数        | `radius`、`widthSegments`、`heightSegments` 等。  |
+| `materialParameters`  | `MeshStandardNodeMaterialParameters` | 标准材质选项（颜色等）。                          |
 
 ### `PlaneMesh`
 
-A flat horizontal plane.
+水平平面网格。
 
 ```typescript
 import { PlaneMesh } from 'u-space';
@@ -110,7 +110,7 @@ const plane = new PlaneMesh({
 
 ### `CircleMesh`
 
-A flat circle.
+圆形平面网格。
 
 ```typescript
 import { CircleMesh } from 'u-space';
@@ -122,7 +122,7 @@ const circle = new CircleMesh({
 
 ### `TubeMesh`
 
-A tube along a given `Curve<Vector3>`.
+沿指定 `Curve<Vector3>` 曲线生成的管道网格。
 
 ```typescript
 import { TubeMesh } from 'u-space';
@@ -137,21 +137,21 @@ const tube = new TubeMesh({
 
 ### `ShapeMesh`
 
-A flat mesh built from a `THREE.Shape` or from 2D points.
+由 `THREE.Shape` 或 2D 点生成的平面网格。
 
 ```typescript
 import { ShapeMesh } from 'u-space';
 
-// From an explicit shape
+// 从显式 Shape 创建
 const mesh = new ShapeMesh({ geometryParameters: { shape: myShape } });
 
-// Static helper: from x/z point array
+// 静态辅助方法：从 x/z 点数组创建
 const mesh2 = ShapeMesh.createFromPoints([{ x: 0, z: 0 }, { x: 5, z: 0 }, { x: 5, z: 5 }]);
 ```
 
 ### `ExtrudeMesh`
 
-An extruded 3D solid from a `THREE.Shape` or from 2D points.
+由 `THREE.Shape` 或 2D 点拉伸生成的 3D 实体网格。
 
 ```typescript
 import { ExtrudeMesh } from 'u-space';
@@ -164,7 +164,7 @@ const solid = new ExtrudeMesh({
   materialParameters: { color: 0xff8800 },
 });
 
-// Static helper
+// 静态辅助方法
 const solid2 = ExtrudeMesh.createFromPoints(
   [{ x: 0, z: 0 }, { x: 5, z: 0 }, { x: 5, z: 5 }],
   { geometryParameters: { options: { depth: 2, bevelEnabled: false } } }
@@ -173,20 +173,20 @@ const solid2 = ExtrudeMesh.createFromPoints(
 
 ## Poi
 
-`Poi` is a canvas-rendered billboard (sprite) used for placing icons and labels in the 3D scene. It extends `BaseSprite`.
+`Poi` 是一个基于 canvas 渲染的公告板（精灵），用于在 3D 场景中放置图标和标签，继承自 `BaseSprite`。
 
 ```typescript
 import { Poi } from 'u-space';
 
 const poi = new Poi({
   img: '/icons/marker.png',
-  text: 'My Location',
+  text: '我的位置',
   fontSize: 28,
   color: '#ffffff',
   backgroundColor: 'rgba(0,0,0,0.6)',
   textPosition: 'right',
 });
-await poi.updateAsync(); // render the canvas texture
+await poi.updateAsync(); // 渲染 canvas 纹理
 
 poi.position.set(10, 5, 10);
 viewer.scene.add(poi);
@@ -194,37 +194,37 @@ viewer.scene.add(poi);
 
 ### `PoiParameters`
 
-| Property          | Type                                        | Default                  | Description                                       |
-| :---------------- | :------------------------------------------ | :----------------------- | :------------------------------------------------ |
-| `img`             | `string \| CanvasImageSource`               | `''`                     | Icon image URL or element.                        |
-| `text`            | `string`                                    | `''`                     | Label text.                                       |
-| `fontSize`        | `number`                                    | `32`                     | Font size in pixels.                              |
-| `fontFamily`      | `string`                                    | `'Arial'`                | Font family.                                      |
-| `color`           | `string`                                    | `'#ffffff'`              | Text color.                                       |
-| `iconSize`        | `number`                                    | `64`                     | Icon size in pixels.                              |
-| `padding`         | `number`                                    | `10`                     | Padding around content.                           |
-| `backgroundColor` | `string`                                    | `'rgba(0, 0, 0, 0.5)'`  | Background fill color.                            |
-| `borderRadius`    | `number`                                    | `8`                      | Background border radius.                         |
-| `textPosition`    | `'top' \| 'bottom' \| 'left' \| 'right'`   | `'right'`                | Text position relative to the icon.               |
-
-### Methods
+| 属性              | 类型                                        | 默认值                   | 说明                               |
+| :---------------- | :------------------------------------------ | :----------------------- | :--------------------------------- |
+| `img`             | `string \| CanvasImageSource`               | `''`                     | 图标图片 URL 或元素。              |
+| `text`            | `string`                                    | `''`                     | 标签文字。                         |
+| `fontSize`        | `number`                                    | `32`                     | 字体大小（像素）。                 |
+| `fontFamily`      | `string`                                    | `'Arial'`                | 字体族。                           |
+| `color`           | `string`                                    | `'#ffffff'`              | 文字颜色。                         |
+| `iconSize`        | `number`                                    | `64`                     | 图标大小（像素）。                 |
+| `padding`         | `number`                                    | `10`                     | 内容四周的内边距。                 |
+| `backgroundColor` | `string`                                    | `'rgba(0, 0, 0, 0.5)'`  | 背景填充颜色。                     |
+| `borderRadius`    | `number`                                    | `8`                      | 背景圆角半径。                     |
+| `textPosition`    | `'top' \| 'bottom' \| 'left' \| 'right'`   | `'right'`                | 文字相对图标的位置。               |
+
+### 方法
 
 #### `updateAsync(parameters?)`
 
-Re-renders the canvas texture with optional parameter overrides.
+使用可选的参数覆盖重新渲染 canvas 纹理。
 
 ```typescript
-await poi.updateAsync({ text: 'Updated label', color: '#ffff00' });
+await poi.updateAsync({ text: '更新后的标签', color: '#ffff00' });
 viewer.render();
 ```
 
 #### `dispose()`
 
-Disposes the canvas texture and material.
+释放 canvas 纹理和材质。
 
 ## Topology
 
-`Topology` is a graph data structure with built-in 3D visualization. It stores nodes (positions) and weighted edges, implements Dijkstra's shortest-path algorithm, and renders the graph as spheres and tubes.
+`Topology` 是一个带有内置 3D 可视化的图数据结构。它存储节点（位置）和带权重的边，实现了 Dijkstra 最短路径算法，并将图渲染为球体和管道。
 
 ```typescript
 import { Topology } from 'u-space';
@@ -243,54 +243,54 @@ topo.addNode('C', new Vector3(5, 0, 5));
 topo.addEdge('A', 'B');
 topo.addEdge('B', 'C');
 
-topo.renderGraph(); // Creates sphere + tube meshes
+topo.renderGraph(); // 创建球体 + 管道网格
 viewer.scene.add(topo);
 ```
 
 ### `TopologyParameters`
 
-| Property      | Type                 | Default     | Description                     |
-| :------------ | :------------------- | :---------- | :------------------------------ |
-| `nodeColor`   | `ColorRepresentation`| `0x0000ff`  | Color of node spheres.          |
-| `nodeRadius`  | `number`             | `0.5`       | Radius of node spheres.         |
-| `edgeColor`   | `ColorRepresentation`| `0x00ff00`  | Color of edge tubes.            |
-| `edgeRadius`  | `number`             | `0.1`       | Radius of edge tubes.           |
-| `pathColor`   | `ColorRepresentation`| `0xff00ff`  | Color used for path visualization. |
-| `pathRadius`  | `number`             | `0.2`       | Radius of path tubes.           |
+| 属性          | 类型                  | 默认值      | 说明                     |
+| :------------ | :-------------------- | :---------- | :----------------------- |
+| `nodeColor`   | `ColorRepresentation` | `0x0000ff`  | 节点球体颜色。           |
+| `nodeRadius`  | `number`              | `0.5`       | 节点球体半径。           |
+| `edgeColor`   | `ColorRepresentation` | `0x00ff00`  | 边管道颜色。             |
+| `edgeRadius`  | `number`              | `0.1`       | 边管道半径。             |
+| `pathColor`   | `ColorRepresentation` | `0xff00ff`  | 路径可视化颜色。         |
+| `pathRadius`  | `number`              | `0.2`       | 路径管道半径。           |
 
-### Methods
+### 方法
 
 #### `addNode(id, position)`
 
-Adds a node to the graph.
+向图中添加一个节点。
 
 #### `removeNode(id)`
 
-Removes a node and its associated edges.
+移除一个节点及其关联的边。
 
 #### `addEdge(from, to, weight?, bidirectional?)`
 
-Adds an edge between two nodes. `weight` defaults to Euclidean distance. `bidirectional` defaults to `true`.
+在两个节点之间添加一条边。`weight` 默认为欧氏距离，`bidirectional` 默认为 `true`（双向）。
 
 #### `removeEdge(from, to, bidirectional?)`
 
-Removes an edge between two nodes.
+移除两个节点之间的边。
 
 #### `getShortestPath(startId, endId): Vector3[]`
 
-Returns the shortest path as an array of world-space positions using Dijkstra's algorithm. Returns `[]` if no path exists.
+使用 Dijkstra 算法返回最短路径（世界坐标位置数组）。若不存在路径则返回 `[]`。
 
 #### `renderGraph()`
 
-Builds the sphere/tube scene graph from current nodes and edges. Call this after modifying the graph to refresh the visualization.
+根据当前节点和边构建球体/管道场景图。修改图后需调用此方法刷新可视化。
 
 #### `clearGraph()`
 
-Removes and disposes all graph meshes.
+移除并释放所有图网格。
 
 #### `renderPath(points, color?): TubeMesh`
 
-Renders a smoothed path (CatmullRomCurve3) through the given points as a tube mesh.
+将给定点通过 CatmullRomCurve3 平滑处理后渲染为管道网格。
 
 ```typescript
 const path = topo.getShortestPath('A', 'C');
@@ -300,12 +300,12 @@ viewer.render();
 
 #### `clearPaths()`
 
-Removes and disposes all path meshes.
+移除并释放所有路径网格。
 
 #### `getNeighbors(id): Map<string, number> | undefined`
 
-Returns the adjacency map for a node (neighbor ID → edge weight).
+返回节点的邻接表（邻居 ID → 边权重）。
 
 #### `dispose()`
 
-Clears graph and path meshes.
+清除图和路径网格。