u-space 0.0.0-alpha.2 → 0.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/api-animations.md +23 -23
- package/docs/api-effects.md +41 -41
- package/docs/api-interactions.md +45 -45
- package/docs/api-managers.md +24 -24
- package/docs/api-objects.md +85 -85
- package/docs/api-plugins.md +113 -113
- package/docs/api-viewer.md +45 -45
- package/docs/examples-guide.md +31 -31
- package/docs/getting-started.md +36 -36
- package/package.json +4 -3
package/docs/api-plugins.md
CHANGED
|
@@ -1,44 +1,44 @@
|
|
|
1
1
|
# Plugins API
|
|
2
2
|
|
|
3
|
-
`u-space`
|
|
3
|
+
`u-space` 架构包含一套丰富的插件，提供从 GIS 瓦片加载到键盘控制和场景管理等高级功能。所有插件从 `u-space/plugins/*` 命名空间导入。
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## 可用插件
|
|
6
6
|
|
|
7
7
|
### `keyboard-controls`
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
为激活相机提供 WASD 或方向键的平移和旋转控制。
|
|
10
10
|
|
|
11
11
|
```typescript
|
|
12
12
|
import { KeyboardControls, ACTION } from 'u-space/plugins/keyboard-controls';
|
|
13
13
|
|
|
14
14
|
const keyboardControls = new KeyboardControls(viewer);
|
|
15
15
|
|
|
16
|
-
//
|
|
16
|
+
// 可选：自定义移动速度
|
|
17
17
|
keyboardControls.moveDistanceDelta = 0.5;
|
|
18
18
|
keyboardControls.rotateAngleDelta = (Math.PI / 180) * 2;
|
|
19
19
|
|
|
20
|
-
//
|
|
20
|
+
// 激活监听
|
|
21
21
|
keyboardControls.enable();
|
|
22
|
-
//
|
|
22
|
+
// 之后：
|
|
23
23
|
keyboardControls.disable();
|
|
24
24
|
```
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
**默认按键绑定**（`keyboardControls.keys`）：
|
|
27
27
|
|
|
28
|
-
|
|
|
29
|
-
|
|
|
30
|
-
| `W`
|
|
31
|
-
| `S`
|
|
32
|
-
| `A`
|
|
33
|
-
| `D`
|
|
34
|
-
| `Q`
|
|
35
|
-
| `E`
|
|
36
|
-
| `ArrowLeft` |
|
|
37
|
-
| `ArrowRight` |
|
|
38
|
-
| `ArrowUp` |
|
|
39
|
-
| `ArrowDown` |
|
|
28
|
+
| 按键 | 动作 |
|
|
29
|
+
| :----------- | :------- |
|
|
30
|
+
| `W` | 向前移动 |
|
|
31
|
+
| `S` | 向后移动 |
|
|
32
|
+
| `A` | 向左移动 |
|
|
33
|
+
| `D` | 向右移动 |
|
|
34
|
+
| `Q` | 向上移动 |
|
|
35
|
+
| `E` | 向下移动 |
|
|
36
|
+
| `ArrowLeft` | 向左旋转 |
|
|
37
|
+
| `ArrowRight` | 向右旋转 |
|
|
38
|
+
| `ArrowUp` | 向上旋转 |
|
|
39
|
+
| `ArrowDown` | 向下旋转 |
|
|
40
40
|
|
|
41
|
-
|
|
41
|
+
通过 `ACTION` 常量重新绑定任意按键：
|
|
42
42
|
|
|
43
43
|
```typescript
|
|
44
44
|
import { ACTION } from 'u-space/plugins/keyboard-controls';
|
|
@@ -47,100 +47,100 @@ keyboardControls.keys['Space'] = ACTION.MOVE_UP;
|
|
|
47
47
|
|
|
48
48
|
### `minimap`
|
|
49
49
|
|
|
50
|
-
|
|
50
|
+
生成一个 2D 小地图叠加层，在 3D 场景中跟踪目标对象。渲染到注入 `viewer.el` 的 `<canvas>` 元素中。
|
|
51
51
|
|
|
52
52
|
```typescript
|
|
53
53
|
import { Minimap } from 'u-space/plugins/minimap';
|
|
54
54
|
|
|
55
55
|
const minimap = new Minimap(viewer);
|
|
56
|
-
minimap.target = myCharacterModel; // Object3D
|
|
57
|
-
minimap.setSize(300, 300); //
|
|
56
|
+
minimap.target = myCharacterModel; // 要跟踪并显示的 Object3D
|
|
57
|
+
minimap.setSize(300, 300); // 宽高（像素）
|
|
58
58
|
|
|
59
|
-
//
|
|
59
|
+
// 可选：设置小地图场景样式
|
|
60
60
|
minimap.scene.background = new THREE.Color(0x111111);
|
|
61
61
|
|
|
62
62
|
minimap.enable();
|
|
63
|
-
//
|
|
63
|
+
// 之后：
|
|
64
64
|
minimap.disable();
|
|
65
65
|
minimap.dispose();
|
|
66
66
|
```
|
|
67
67
|
|
|
68
|
-
|
|
68
|
+
**属性：**
|
|
69
69
|
|
|
70
|
-
|
|
|
71
|
-
| :------------ | :-------------------- |
|
|
72
|
-
| `target` | `Object3D \| null` |
|
|
73
|
-
| `scene` | `Scene` |
|
|
74
|
-
| `camera` | `OrthographicCamera` |
|
|
75
|
-
| `marker` | `Object3D` |
|
|
76
|
-
| `needsUpdate` | `boolean` |
|
|
70
|
+
| 属性 | 类型 | 说明 |
|
|
71
|
+
| :------------ | :-------------------- | :--------------------------------------- |
|
|
72
|
+
| `target` | `Object3D \| null` | 小地图居中显示的对象。 |
|
|
73
|
+
| `scene` | `Scene` | 小地图内部的 Three.js 场景。 |
|
|
74
|
+
| `camera` | `OrthographicCamera` | 正交俯视相机。 |
|
|
75
|
+
| `marker` | `Object3D` | 显示主相机位置/朝向的箭头网格。 |
|
|
76
|
+
| `needsUpdate` | `boolean` | 设置为 `true` 可强制重新渲染小地图。 |
|
|
77
77
|
|
|
78
|
-
|
|
78
|
+
**方法：**
|
|
79
79
|
|
|
80
|
-
- `setSize(width, height)` —
|
|
81
|
-
- `enable()` —
|
|
82
|
-
- `disable()` —
|
|
83
|
-
- `dispose()` —
|
|
80
|
+
- `setSize(width, height)` — 调整小地图画布和相机视锥大小。
|
|
81
|
+
- `enable()` — 将画布附加到 `viewer.el` 并开始渲染。
|
|
82
|
+
- `disable()` — 移除画布并停止渲染。
|
|
83
|
+
- `dispose()` — 禁用并清理所有资源。
|
|
84
84
|
|
|
85
85
|
### `tiles`
|
|
86
86
|
|
|
87
|
-
|
|
87
|
+
提供与 `3d-tiles-renderer` 和地理空间数据的集成。主要导出 `ArcgisTilesRenderer`，可流式加载 ArcGIS Online 3D 瓦片并将地球重新定向到指定地理位置。
|
|
88
88
|
|
|
89
89
|
```typescript
|
|
90
90
|
import { ArcgisTilesRenderer } from 'u-space/plugins/tiles';
|
|
91
91
|
|
|
92
92
|
const arcgisTilesRenderer = new ArcgisTilesRenderer(viewer);
|
|
93
93
|
|
|
94
|
-
//
|
|
94
|
+
// 设置原点为经度、纬度、高度
|
|
95
95
|
arcgisTilesRenderer.invalidate(120.002269, 30.284849, 4);
|
|
96
96
|
|
|
97
|
-
//
|
|
97
|
+
// 瓦片持续流式加载，使用 always 模式
|
|
98
98
|
viewer.frameloop = 'always';
|
|
99
99
|
|
|
100
100
|
arcgisTilesRenderer.enable();
|
|
101
101
|
```
|
|
102
102
|
|
|
103
|
-
|
|
103
|
+
**方法：**
|
|
104
104
|
|
|
105
|
-
|
|
|
106
|
-
|
|
|
107
|
-
| `invalidate(lon, lat, alt)`
|
|
108
|
-
| `enable()`
|
|
109
|
-
| `disable()`
|
|
110
|
-
| `dispose()`
|
|
105
|
+
| 方法 | 说明 |
|
|
106
|
+
| :-------------------------- | :--------------------------------------------------------------------------------------------- |
|
|
107
|
+
| `invalidate(lon, lat, alt)` | 将瓦片原点设置为指定的 WGS84 坐标（度）。可多次调用。返回一个取消订阅的函数。 |
|
|
108
|
+
| `enable()` | 将瓦片添加到场景并启动更新循环。 |
|
|
109
|
+
| `disable()` | 从场景中移除瓦片并暂停更新循环。 |
|
|
110
|
+
| `dispose()` | 禁用并完全释放瓦片渲染器。 |
|
|
111
111
|
|
|
112
112
|
### `u-manager`
|
|
113
113
|
|
|
114
|
-
`u-manager`
|
|
114
|
+
`u-manager` 是一套全面的加载器和解析器，用于从服务器路径流式传输、解密并显示结构化场景数据。支持场景、拓扑、动画、属性和相机视点。
|
|
115
115
|
|
|
116
|
-
|
|
116
|
+
所有加载器均继承自 Three.js 的 `Loader`，并提供 `setPath(path)` 方法，在调用 `loadAsync()` 前配置基础数据目录。
|
|
117
117
|
|
|
118
118
|
#### `SceneLoader`
|
|
119
119
|
|
|
120
|
-
|
|
120
|
+
从服务端场景包加载完整场景树（模型、组、形状、拉伸区域），并自动将所有已加载对象按 `id` 和 `sid` 注册到 `viewer.objectManager`。
|
|
121
121
|
|
|
122
122
|
```typescript
|
|
123
123
|
import { SceneLoader } from 'u-space/plugins/u-manager';
|
|
124
124
|
|
|
125
125
|
const sceneLoader = new SceneLoader(viewer);
|
|
126
126
|
sceneLoader.setPath('./scenes/my-scene');
|
|
127
|
-
sceneLoader.setKey('YOUR_LICENSE_KEY'); //
|
|
127
|
+
sceneLoader.setKey('YOUR_LICENSE_KEY'); // 官方授权场景必需
|
|
128
128
|
const group = await sceneLoader.loadAsync();
|
|
129
129
|
viewer.scene.add(group);
|
|
130
130
|
```
|
|
131
131
|
|
|
132
|
-
|
|
132
|
+
**方法：**
|
|
133
133
|
|
|
134
|
-
|
|
|
135
|
-
|
|
|
136
|
-
| `setKey(key)`
|
|
137
|
-
| `loadAsync()`
|
|
138
|
-
| `clearCache()`
|
|
139
|
-
| `dispose()`
|
|
134
|
+
| 方法 | 说明 |
|
|
135
|
+
| :--------------- | :------------------------------------------------------------ |
|
|
136
|
+
| `setKey(key)` | 设置授权场景的 RSA 解密密钥。 |
|
|
137
|
+
| `loadAsync()` | 加载并解析场景，返回包含完整层级的 `Group`。 |
|
|
138
|
+
| `clearCache()` | 从 `objectManager` 中移除此加载器注册的所有 ID。 |
|
|
139
|
+
| `dispose()` | 清除缓存并释放水印叠加层。 |
|
|
140
140
|
|
|
141
141
|
#### `TopologiesLoader` / `TopologyParser`
|
|
142
142
|
|
|
143
|
-
|
|
143
|
+
加载拓扑图数据并将其转换为 `Topology` 对象。
|
|
144
144
|
|
|
145
145
|
```typescript
|
|
146
146
|
import { TopologiesLoader } from 'u-space/plugins/u-manager';
|
|
@@ -153,7 +153,7 @@ viewer.scene.add(...topologies);
|
|
|
153
153
|
|
|
154
154
|
#### `VisionsLoader` / `VisionsParser`
|
|
155
155
|
|
|
156
|
-
|
|
156
|
+
加载命名相机视点，并将相机飞行到指定视点。
|
|
157
157
|
|
|
158
158
|
```typescript
|
|
159
159
|
import { VisionsLoader, VisionsParser } from 'u-space/plugins/u-manager';
|
|
@@ -161,30 +161,30 @@ import { VisionsLoader, VisionsParser } from 'u-space/plugins/u-manager';
|
|
|
161
161
|
const visionsLoader = new VisionsLoader();
|
|
162
162
|
visionsLoader.setPath('./scenes/my-scene');
|
|
163
163
|
const visionsData = await visionsLoader.loadAsync();
|
|
164
|
-
// visionsData
|
|
164
|
+
// visionsData 是 Record<string, IVisions[]>
|
|
165
165
|
|
|
166
166
|
const visionsParser = new VisionsParser(viewer);
|
|
167
167
|
|
|
168
|
-
//
|
|
168
|
+
// 飞行到指定视点
|
|
169
169
|
await visionsParser.flyTo(visionsData['HOME'][0]);
|
|
170
170
|
|
|
171
|
-
//
|
|
171
|
+
// 飞行到主（默认）视点
|
|
172
172
|
await visionsParser.flyToPrimary(visionsData['HOME']);
|
|
173
173
|
```
|
|
174
174
|
|
|
175
|
-
**`IVisions`
|
|
175
|
+
**`IVisions` 字段：**
|
|
176
176
|
|
|
177
|
-
|
|
|
178
|
-
| :--------- | :------------ |
|
|
179
|
-
| `camera` | `'P' \| 'O'` |
|
|
180
|
-
| `position` | `IVector3` |
|
|
181
|
-
| `target` | `IVector3` |
|
|
182
|
-
| `zoom` | `number` |
|
|
183
|
-
| `primary` | `boolean` |
|
|
177
|
+
| 字段 | 类型 | 说明 |
|
|
178
|
+
| :--------- | :------------ | :------------------------------ |
|
|
179
|
+
| `camera` | `'P' \| 'O'` | 相机类型：透视或正交。 |
|
|
180
|
+
| `position` | `IVector3` | 相机世界位置。 |
|
|
181
|
+
| `target` | `IVector3` | 相机朝向目标点。 |
|
|
182
|
+
| `zoom` | `number` | 相机缩放级别。 |
|
|
183
|
+
| `primary` | `boolean` | 是否为默认视点。 |
|
|
184
184
|
|
|
185
185
|
#### `AnimationsLoader` / `AnimationsParser`
|
|
186
186
|
|
|
187
|
-
|
|
187
|
+
加载关键帧动画数据，并通过 `tweenAnimation` 驱动 `Object3D` 的变换。
|
|
188
188
|
|
|
189
189
|
```typescript
|
|
190
190
|
import { AnimationsLoader, AnimationsParser } from 'u-space/plugins/u-manager';
|
|
@@ -193,24 +193,24 @@ const animLoader = new AnimationsLoader();
|
|
|
193
193
|
animLoader.setPath('./scenes/my-scene');
|
|
194
194
|
const animationsData = await animLoader.loadAsync(); // IAnimations[]
|
|
195
195
|
|
|
196
|
-
//
|
|
196
|
+
// 查找特定对象的动画
|
|
197
197
|
const data = animationsData.find((a) => a.modelId === myModel.userData.id);
|
|
198
198
|
|
|
199
199
|
const parser = new AnimationsParser(viewer, myModel);
|
|
200
|
-
parser.initTransform(); //
|
|
200
|
+
parser.initTransform(); // 保存初始位置/旋转/缩放
|
|
201
201
|
|
|
202
|
-
await parser.play(data.keyframes); //
|
|
202
|
+
await parser.play(data.keyframes); // 播放动画序列
|
|
203
203
|
|
|
204
|
-
//
|
|
204
|
+
// 中途停止
|
|
205
205
|
parser.stop();
|
|
206
206
|
|
|
207
|
-
//
|
|
207
|
+
// 重置到初始变换
|
|
208
208
|
parser.reset();
|
|
209
209
|
```
|
|
210
210
|
|
|
211
211
|
#### `PropertiesLoader`
|
|
212
212
|
|
|
213
|
-
|
|
213
|
+
加载与模型关联的结构化属性元数据（如 BIM 属性）。
|
|
214
214
|
|
|
215
215
|
```typescript
|
|
216
216
|
import { PropertiesLoader } from 'u-space/plugins/u-manager';
|
|
@@ -219,23 +219,23 @@ const propsLoader = new PropertiesLoader();
|
|
|
219
219
|
propsLoader.setPath('./scenes/my-scene');
|
|
220
220
|
const properties = await propsLoader.loadAsync(); // IProperties[]
|
|
221
221
|
|
|
222
|
-
//
|
|
222
|
+
// 查找模型的属性
|
|
223
223
|
const modelProps = properties.filter(p => p.modelId === myModel.userData.id);
|
|
224
224
|
```
|
|
225
225
|
|
|
226
|
-
**`IProperties`
|
|
226
|
+
**`IProperties` 字段：**
|
|
227
227
|
|
|
228
|
-
|
|
|
229
|
-
| :-------- |
|
|
230
|
-
| `modelId` | `string`
|
|
231
|
-
| `group` | `string`
|
|
232
|
-
| `key` | `string`
|
|
233
|
-
| `value` | `string \| null
|
|
234
|
-
| `label` | `string \| null
|
|
228
|
+
| 字段 | 类型 | 说明 |
|
|
229
|
+
| :-------- | :--------------- | :----------------------- |
|
|
230
|
+
| `modelId` | `string` | 关联模型的 ID。 |
|
|
231
|
+
| `group` | `string` | 属性分组/类别名称。 |
|
|
232
|
+
| `key` | `string` | 属性键名。 |
|
|
233
|
+
| `value` | `string \| null` | 属性值。 |
|
|
234
|
+
| `label` | `string \| null` | 属性的显示标签。 |
|
|
235
235
|
|
|
236
236
|
### `curve-movement`
|
|
237
237
|
|
|
238
|
-
|
|
238
|
+
沿样条路径对相机或对象进行动画。提供两个具体子类：`CurveMovementCamera` 和 `CurveMovementObject`。
|
|
239
239
|
|
|
240
240
|
```typescript
|
|
241
241
|
import { CurveMovementObject } from 'u-space/plugins/curve-movement';
|
|
@@ -247,58 +247,58 @@ movement.setFromPoints([
|
|
|
247
247
|
new Vector3(10, 2, 0),
|
|
248
248
|
new Vector3(20, 0, 10),
|
|
249
249
|
]);
|
|
250
|
-
movement.speed = 0.05; //
|
|
250
|
+
movement.speed = 0.05; // 每秒进度
|
|
251
251
|
movement.loop = 'repeat'; // 'once' | 'repeat' | 'pingpong'
|
|
252
252
|
movement.autoLookAt = true;
|
|
253
253
|
|
|
254
254
|
movement.play();
|
|
255
255
|
// movement.pause() / movement.resume() / movement.stop()
|
|
256
256
|
|
|
257
|
-
//
|
|
257
|
+
// 监听事件
|
|
258
258
|
movement.addEventListener('update', ({ progress }) => console.log(progress));
|
|
259
|
-
movement.addEventListener('complete', () => console.log('
|
|
259
|
+
movement.addEventListener('complete', () => console.log('完成'));
|
|
260
260
|
```
|
|
261
261
|
|
|
262
|
-
**`CurveMovement`
|
|
262
|
+
**`CurveMovement` 属性：**
|
|
263
263
|
|
|
264
|
-
|
|
|
265
|
-
| :-------------- |
|
|
266
|
-
| `path` | `Curve<Vector3> \| null`
|
|
267
|
-
| `progress` | `number`
|
|
268
|
-
| `speed` | `number`
|
|
269
|
-
| `loop` | `'once' \| 'repeat' \| 'pingpong'
|
|
270
|
-
| `autoLookAt` | `boolean`
|
|
271
|
-
| `lookAtOffset` | `number`
|
|
272
|
-
| `positionOffset`| `Vector3`
|
|
273
|
-
| `direction` | `1 \| -1`
|
|
264
|
+
| 属性 | 类型 | 默认值 | 说明 |
|
|
265
|
+
| :-------------- | :--------------------------------- | :-------- | :----------------------------------- |
|
|
266
|
+
| `path` | `Curve<Vector3> \| null` | `null` | 样条路径。 |
|
|
267
|
+
| `progress` | `number` | `0` | 当前归一化进度（0–1）。 |
|
|
268
|
+
| `speed` | `number` | `0.1` | 每秒进度单位。 |
|
|
269
|
+
| `loop` | `'once' \| 'repeat' \| 'pingpong'` | `'once'` | 循环行为。 |
|
|
270
|
+
| `autoLookAt` | `boolean` | `true` | 朝向路径切线方向。 |
|
|
271
|
+
| `lookAtOffset` | `number` | `0` | Y 轴旋转偏移量（弧度）。 |
|
|
272
|
+
| `positionOffset`| `Vector3` | `(0,0,0)` | 叠加到每个位置上的世界坐标偏移量。 |
|
|
273
|
+
| `direction` | `1 \| -1` | `1` | 当前行进方向。 |
|
|
274
274
|
|
|
275
275
|
### `tracking-controls`
|
|
276
276
|
|
|
277
|
-
|
|
277
|
+
使相机平滑跟随移动的 `Object3D` 目标。
|
|
278
278
|
|
|
279
279
|
```typescript
|
|
280
280
|
import { TrackingControls } from 'u-space/plugins/tracking-controls';
|
|
281
281
|
|
|
282
282
|
const tracking = new TrackingControls(viewer);
|
|
283
283
|
tracking.target = myMovingObject;
|
|
284
|
-
tracking.type = 'box3'; // 'position'
|
|
285
|
-
tracking.offset.set(0, 5, 0); //
|
|
284
|
+
tracking.type = 'box3'; // 'position'（世界原点）或 'box3'（包围盒中心）
|
|
285
|
+
tracking.offset.set(0, 5, 0); // 相机目标偏移量
|
|
286
286
|
|
|
287
287
|
tracking.enable();
|
|
288
288
|
// tracking.disable();
|
|
289
289
|
```
|
|
290
290
|
|
|
291
|
-
|
|
291
|
+
**属性：**
|
|
292
292
|
|
|
293
|
-
|
|
|
294
|
-
| :------- | :---------------------- | :----------- |
|
|
295
|
-
| `target` | `Object3D \| null` | `null` |
|
|
296
|
-
| `type` | `'position' \| 'box3'` | `'position'` |
|
|
297
|
-
| `offset` | `Vector3` | `(0,0,0)` |
|
|
293
|
+
| 属性 | 类型 | 默认值 | 说明 |
|
|
294
|
+
| :------- | :---------------------- | :----------- | :-------------------------------------------------------- |
|
|
295
|
+
| `target` | `Object3D \| null` | `null` | 要跟踪的对象。 |
|
|
296
|
+
| `type` | `'position' \| 'box3'` | `'position'` | 跟踪世界位置还是包围盒中心。 |
|
|
297
|
+
| `offset` | `Vector3` | `(0,0,0)` | 在移动相机前叠加到跟踪位置上的偏移量。 |
|
|
298
298
|
|
|
299
299
|
### `atmosphere`
|
|
300
300
|
|
|
301
|
-
|
|
301
|
+
天空和大气渲染插件。目前为占位实现，`enable()` / `disable()` / `dispose()` 方法可用，但尚未实现具体功能。
|
|
302
302
|
|
|
303
303
|
```typescript
|
|
304
304
|
import { Atmosphere } from 'u-space/plugins/atmosphere';
|
package/docs/api-viewer.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# Viewer API
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
`Viewer` 是 `u-space` 的核心类，它将 WebGPU 渲染器、场景、相机、控制器以及各种管理器封装为一个易用的接口。
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## 构造函数
|
|
6
6
|
|
|
7
7
|
```typescript
|
|
8
8
|
new Viewer(options: ViewerOptions)
|
|
@@ -10,37 +10,37 @@ new Viewer(options: ViewerOptions)
|
|
|
10
10
|
|
|
11
11
|
### `ViewerOptions`
|
|
12
12
|
|
|
13
|
-
|
|
|
14
|
-
| :---------------- | :------------------------- |
|
|
15
|
-
| `el` | `HTMLElement` |
|
|
16
|
-
| `rendererOptions` | `WebGPURendererParameters` |
|
|
17
|
-
|
|
18
|
-
##
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
|
23
|
-
| :------------------- | :------------------------------------------ |
|
|
24
|
-
| `el` | `HTMLElement` |
|
|
25
|
-
| `renderer` | `WebGPURenderer` |
|
|
26
|
-
| `scene` | `Scene` |
|
|
27
|
-
| `camera` | `PerspectiveCamera` \| `OrthographicCamera` |
|
|
28
|
-
| `controls` | `CameraControls` |
|
|
29
|
-
| `renderPipeline` | `RenderPipeline` |
|
|
30
|
-
| `timer` | `Timer` | Three.js `Timer`
|
|
31
|
-
| `roomEnvironment` | `RoomEnvironment` |
|
|
32
|
-
| `info` | `Info` |
|
|
33
|
-
| `viewerHelper` | `ViewerHelper` |
|
|
34
|
-
| `interactionManager` | `InteractionManager` |
|
|
35
|
-
| `objectManager` | `ObjectManager` |
|
|
36
|
-
| `frameloop` | `'always'` \| `'demand'` |
|
|
37
|
-
| `frameCount` | `number` |
|
|
38
|
-
|
|
39
|
-
##
|
|
13
|
+
| 属性 | 类型 | 必填 | 说明 |
|
|
14
|
+
| :---------------- | :------------------------- | :--- | :------------------------------------------------------------------------------------------------------------- |
|
|
15
|
+
| `el` | `HTMLElement` | 是 | WebGPURenderer 的 canvas 将被注入到此 DOM 元素中。 |
|
|
16
|
+
| `rendererOptions` | `WebGPURendererParameters` | 否 | 直接传递给底层 `WebGPURenderer` 的选项。默认使用 WebGPU 的高性能配置。 |
|
|
17
|
+
|
|
18
|
+
## 属性
|
|
19
|
+
|
|
20
|
+
`Viewer` 实例暴露了若干核心 Three.js 和 `u-space` 组件。
|
|
21
|
+
|
|
22
|
+
| 属性 | 类型 | 说明 |
|
|
23
|
+
| :------------------- | :------------------------------------------ | :---------------------------------------------------------------------------------------------------------------- |
|
|
24
|
+
| `el` | `HTMLElement` | 容器元素。 |
|
|
25
|
+
| `renderer` | `WebGPURenderer` | 底层 WebGPU 渲染器实例。 |
|
|
26
|
+
| `scene` | `Scene` | 主 Three.js 场景，背景默认为 `0x000000`。 |
|
|
27
|
+
| `camera` | `PerspectiveCamera` \| `OrthographicCamera` | 当前激活的相机。 |
|
|
28
|
+
| `controls` | `CameraControls` | 相机控制器（基于 `camera-controls` 库）。 |
|
|
29
|
+
| `renderPipeline` | `RenderPipeline` | 管理后处理通道和最终渲染调用。 |
|
|
30
|
+
| `timer` | `Timer` | Three.js `Timer` 实例，用于每帧精确的 delta time 跟踪。 |
|
|
31
|
+
| `roomEnvironment` | `RoomEnvironment` | 为场景提供默认的类室内 IBL 环境贴图。 |
|
|
32
|
+
| `info` | `Info` | 以叠加层的形式渲染渲染器诊断信息（绘制调用次数、三角面数量等）。 |
|
|
33
|
+
| `viewerHelper` | `ViewerHelper` | 提供实用辅助工具（如坐标轴、网格显示），用于开发/调试。 |
|
|
34
|
+
| `interactionManager` | `InteractionManager` | 管理对象的指针事件和射线检测。 |
|
|
35
|
+
| `objectManager` | `ObjectManager` | 用于按 ID 或名称注册和检索对象的工具。 |
|
|
36
|
+
| `frameloop` | `'always'` \| `'demand'` | 设置渲染模式。默认为 `'demand'`（仅在需要时渲染）。设置为 `'always'` 可开启持续渲染。 |
|
|
37
|
+
| `frameCount` | `number` | 待渲染帧的内部计数器，调用 `render()` 时递增。 |
|
|
38
|
+
|
|
39
|
+
## 方法
|
|
40
40
|
|
|
41
41
|
### `init()`
|
|
42
42
|
|
|
43
|
-
|
|
43
|
+
异步初始化渲染器。如果需要确保渲染器（如环境设置或插件）完全就绪，必须调用此方法。
|
|
44
44
|
|
|
45
45
|
```typescript
|
|
46
46
|
await viewer.init();
|
|
@@ -48,18 +48,18 @@ await viewer.init();
|
|
|
48
48
|
|
|
49
49
|
### `render(frame?: number)`
|
|
50
50
|
|
|
51
|
-
|
|
51
|
+
请求渲染一帧。在 `'demand'` 模式下，每当场景发生视觉变化时必须调用此方法来更新画布。`frame` 指定渲染的帧数（默认 `1`）。返回一个在帧渲染完成后 resolve 的 `Promise<void>`。
|
|
52
52
|
|
|
53
53
|
```typescript
|
|
54
54
|
viewer.render();
|
|
55
55
|
|
|
56
|
-
//
|
|
56
|
+
// 等待帧渲染完成
|
|
57
57
|
await viewer.render();
|
|
58
58
|
```
|
|
59
59
|
|
|
60
60
|
### `setCamera(camera: PerspectiveCamera | OrthographicCamera)`
|
|
61
61
|
|
|
62
|
-
|
|
62
|
+
为查看器设置自定义相机，并自动更新控制器和交互管理器以使用该相机。
|
|
63
63
|
|
|
64
64
|
```typescript
|
|
65
65
|
const customCamera = new PerspectiveCamera(75, width / height, 0.1, 1000);
|
|
@@ -68,7 +68,7 @@ viewer.setCamera(customCamera);
|
|
|
68
68
|
|
|
69
69
|
### `setCameraByType(type: 'perspective' | 'orthographic')`
|
|
70
70
|
|
|
71
|
-
|
|
71
|
+
便捷方法，在保持查看器上下文的同时切换相机类型。
|
|
72
72
|
|
|
73
73
|
```typescript
|
|
74
74
|
viewer.setCameraByType('orthographic');
|
|
@@ -76,7 +76,7 @@ viewer.setCameraByType('orthographic');
|
|
|
76
76
|
|
|
77
77
|
### `createScene()`
|
|
78
78
|
|
|
79
|
-
|
|
79
|
+
创建并返回一个黑色背景的新 `Scene`。由构造函数内部调用，也可用于重置/替换场景。
|
|
80
80
|
|
|
81
81
|
```typescript
|
|
82
82
|
viewer.scene = viewer.createScene();
|
|
@@ -84,7 +84,7 @@ viewer.scene = viewer.createScene();
|
|
|
84
84
|
|
|
85
85
|
### `createPerspectiveCamera()`
|
|
86
86
|
|
|
87
|
-
|
|
87
|
+
使用合理的默认值创建 `PerspectiveCamera`（视角 50°，近裁 `0.1`，远裁 `1e5`，位置在 `(5, 5, 5)`）。
|
|
88
88
|
|
|
89
89
|
```typescript
|
|
90
90
|
const camera = viewer.createPerspectiveCamera();
|
|
@@ -93,7 +93,7 @@ viewer.setCamera(camera);
|
|
|
93
93
|
|
|
94
94
|
### `createOrthographicCamera()`
|
|
95
95
|
|
|
96
|
-
|
|
96
|
+
创建与容器元素等大的 `OrthographicCamera`，近裁 `0.1`，远裁 `1e5`，位置在 `(5, 5, 5)`。
|
|
97
97
|
|
|
98
98
|
```typescript
|
|
99
99
|
const camera = viewer.createOrthographicCamera();
|
|
@@ -102,18 +102,18 @@ viewer.setCamera(camera);
|
|
|
102
102
|
|
|
103
103
|
### `dispose()`
|
|
104
104
|
|
|
105
|
-
|
|
105
|
+
清理查看器，从 DOM 中移除 canvas，移除事件监听，并释放渲染器和环境贴图，以防止内存泄漏。
|
|
106
106
|
|
|
107
107
|
```typescript
|
|
108
108
|
viewer.dispose();
|
|
109
109
|
```
|
|
110
110
|
|
|
111
|
-
##
|
|
111
|
+
## 事件
|
|
112
112
|
|
|
113
|
-
|
|
113
|
+
Viewer 继承自 `EventDispatcher`，会触发以下事件：
|
|
114
114
|
|
|
115
|
-
- `beforeControlsUpdate
|
|
116
|
-
- `afterControlsUpdate
|
|
117
|
-
- `beforeRender
|
|
118
|
-
- `afterRender
|
|
119
|
-
- `cameraChange
|
|
115
|
+
- `beforeControlsUpdate`：在 `CameraControls` 更新之前触发，提供 `{ time: number }`。
|
|
116
|
+
- `afterControlsUpdate`：在 `CameraControls` 更新之后触发，提供 `{ time: number }`。
|
|
117
|
+
- `beforeRender`：在 `renderer.render` 调用之前立即触发，提供 `{ time: number }`。
|
|
118
|
+
- `afterRender`：在 `renderer.render` 完成之后立即触发，提供 `{ time: number }`。
|
|
119
|
+
- `cameraChange`：调用 `setCamera` 时触发，提供 `{ camera: Camera }`。
|