u-space 0.0.0-alpha.2 → 0.0.1

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.
+清除图和路径网格。