u-space 0.0.7 → 0.0.9

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

@@ -9,6 +9,9 @@ export interface FlyToBoxOptions {
 }
 export interface FlyToObjectOptions extends FlyToBoxOptions {
 }
+export interface FlyToOptions {
+    enableTransition?: boolean;
+}
 export interface CameraViewpointData {
     position: IVector3;
     target: IVector3;
@@ -22,5 +25,25 @@ export declare class CameraControls extends CameraControlsBase {
     absoluteRotations(): void;
     flyToBox(box: Box3, options?: FlyToBoxOptions): Promise<boolean>;
     flyToObject(object: Object3D, options?: FlyToObjectOptions): Promise<boolean>;
+    /**
+     * Fly camera to a specific position and look-at target.
+     */
+    flyTo(position: IVector3, target: IVector3, options?: FlyToOptions): Promise<void>;
+    /**
+     * Get the current camera viewpoint data (position, target, zoom).
+     */
+    getCameraViewpoint(): CameraViewpointData;
+    /**
+     * Lock camera controls (disable all user interaction).
+     */
+    lock(): void;
+    /**
+     * Unlock camera controls (re-enable user interaction).
+     */
+    unlock(): void;
+    /**
+     * Switch between 2D top-down and 3D perspective views.
+     */
+    setViewMode(mode: '2d' | '3d', enableTransition?: boolean): Promise<void>;
     setCameraViewpoint(viewpoint: CameraViewpointData, enableTransition?: boolean): Promise<[void, void]>;
 }

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

@@ -1,4 +1,4 @@
-import { EventDispatcher, WebGPURenderer, Scene, PerspectiveCamera, Timer, OrthographicCamera } from 'three/webgpu';
+import { EventDispatcher, WebGPURenderer, Scene, PerspectiveCamera, Timer, OrthographicCamera, type ColorRepresentation, type Texture } from 'three/webgpu';
 import { InteractionManager } from '../interactions';
 import { ObjectManager } from '../managers';
 import { RenderPipeline } from './RenderPipeline';
@@ -12,6 +12,21 @@ export interface ViewerOptions {
     el: HTMLElement;
     rendererOptions?: ViewerRendererOptions;
 }
+export interface ScreenshotOptions {
+    width?: number;
+    height?: number;
+    type?: 'image/png' | 'image/jpeg' | 'image/webp';
+    quality?: number;
+}
+export interface FogOptions {
+    color?: ColorRepresentation;
+    near?: number;
+    far?: number;
+}
+export interface FogExp2Options {
+    color?: ColorRepresentation;
+    density?: number;
+}
 export interface ViewerEventMap {
     beforeControlsUpdate: {
         time: number;
@@ -60,6 +75,42 @@ declare class Viewer extends EventDispatcher<ViewerEventMap> {
     createScene(): Scene;
     createPerspectiveCamera(): PerspectiveCamera;
     createOrthographicCamera(): OrthographicCamera;
+    /**
+     * Manually trigger a resize update.
+     */
+    resize(width?: number, height?: number): void;
+    /**
+     * Capture a screenshot of the current render.
+     */
+    screenshot(options?: ScreenshotOptions): Promise<string>;
+    /**
+     * Set the scene background color, texture, or null.
+     */
+    setBackground(background: ColorRepresentation | Texture | null): void;
+    /**
+     * Set the scene environment map for reflections / IBL.
+     */
+    setEnvironment(envMap: Texture | null): void;
+    /**
+     * Enable shadow rendering.
+     */
+    enableShadow(): void;
+    /**
+     * Disable shadow rendering.
+     */
+    disableShadow(): void;
+    /**
+     * Enable linear fog.
+     */
+    enableFog(options?: FogOptions): void;
+    /**
+     * Enable exponential fog.
+     */
+    enableFogExp2(options?: FogExp2Options): void;
+    /**
+     * Disable fog.
+     */
+    disableFog(): void;
     dispose(): void;
 }
 export { Viewer };

package/docs/api-camera-controls.md

@@ -0,0 +1,146 @@
+# CameraControls API
+
+`CameraControls` 是 `u-space` 对 [`camera-controls`](https://github.com/yomotsu/camera-controls) 库的扩展封装，提供相机飞行、视角切换等高级功能。通过 `viewer.controls` 访问。
+
+## 默认配置
+
+| 属性          | 默认值 | 说明                           |
+| :------------ | :----- | :----------------------------- |
+| `minDistance`  | `0.2`  | 相机最小缩放距离。             |
+| `smoothTime`  | `0.2`  | 平滑过渡时间（秒）。           |
+| `dollySpeed`  | `0.2`  | 滚轮缩放速度。                 |
+
+> 更多基础属性和方法请参考 [camera-controls 文档](https://github.com/yomotsu/camera-controls)。
+
+## 方法
+
+### `flyToBox(box, options?)`
+
+将相机飞行到指定的 `Box3` 包围盒。
+
+```typescript
+import { Box3 } from 'three/webgpu';
+
+const box = new Box3().setFromObject(myModel);
+await viewer.controls.flyToBox(box, {
+  viewpoint: 'frontTop',
+  enableTransition: true,
+  padding: 0.1,
+});
+```
+
+#### `FlyToBoxOptions`
+
+| 属性               | 类型      | 默认值       | 说明                                              |
+| :----------------- | :-------- | :----------- | :------------------------------------------------ |
+| `viewpoint`        | `string`  | `'frontTop'` | 预设视角方向，见下方视角列表。设为 `'current'` 保持当前朝向。 |
+| `enableTransition` | `boolean` | `true`       | 是否启用平滑过渡动画。                            |
+| `padding`          | `number`  | `0.1`        | 包围盒四周的留白比例。                            |
+| `cover`            | `boolean` | `false`      | 是否以覆盖模式适配（类似 CSS `object-fit: cover`）。 |
+
+**预设视角：**
+
+`top` | `bottom` | `front` | `back` | `left` | `right` | `frontTop` | `backTop` | `leftTop` | `rightTop` | `leftFrontTop` | `rightFrontTop` | `leftBackTop` | `rightBackTop` | `current`
+
+### `flyToObject(object, options?)`
+
+将相机飞行到指定对象的包围盒。参数同 `flyToBox`。
+
+```typescript
+await viewer.controls.flyToObject(myModel, { viewpoint: 'rightFrontTop' });
+```
+
+### `setCameraViewpoint(viewpoint, enableTransition?)`
+
+将相机平滑过渡到指定的位置、目标和缩放。
+
+```typescript
+await viewer.controls.setCameraViewpoint({
+  position: { x: 10, y: 5, z: 10 },
+  target: { x: 0, y: 0, z: 0 },
+  zoom: 1.0,
+});
+
+// 禁用过渡动画，立即跳转
+await viewer.controls.setCameraViewpoint(viewpoint, false);
+```
+
+**参数：**
+
+| 参数               | 类型                   | 默认值  | 说明                                |
+| :----------------- | :--------------------- | :------ | :---------------------------------- |
+| `viewpoint`        | `CameraViewpointData`  | —       | 包含 `position`、`target`、`zoom`。 |
+| `enableTransition` | `boolean`              | `true`  | 是否启用平滑过渡动画。             |
+
+#### `CameraViewpointData`
+
+| 属性       | 类型       | 说明                 |
+| :--------- | :--------- | :------------------- |
+| `position` | `IVector3` | 相机位置。           |
+| `target`   | `IVector3` | 相机注视目标位置。   |
+| `zoom`     | `number`   | 相机缩放值。         |
+
+### `flyTo(position, target, options?)`
+
+将相机飞行到指定的位置和注视目标。
+
+```typescript
+await viewer.controls.flyTo(
+  { x: 10, y: 8, z: 10 },
+  { x: 0, y: 0, z: 0 },
+  { enableTransition: true },
+);
+```
+
+**参数：**
+
+| 参数               | 类型       | 默认值 | 说明                    |
+| :----------------- | :--------- | :----- | :---------------------- |
+| `position`         | `IVector3` | —      | 相机目标位置。          |
+| `target`           | `IVector3` | —      | 相机注视目标。          |
+| `enableTransition` | `boolean`  | `true` | 是否启用平滑过渡动画。 |
+
+### `getCameraViewpoint()`
+
+获取当前相机的视角数据，返回 `CameraViewpointData`。与 `setCameraViewpoint` 对应，方便保存/恢复视角。
+
+```typescript
+const viewpoint = viewer.controls.getCameraViewpoint();
+console.log(viewpoint.position, viewpoint.target, viewpoint.zoom);
+
+// 稍后恢复
+await viewer.controls.setCameraViewpoint(viewpoint);
+```
+
+### `lock()` / `unlock()`
+
+锁定或解锁相机控制（禁用/启用所有用户交互）。
+
+```typescript
+viewer.controls.lock();   // 禁止用户操作相机
+viewer.controls.unlock(); // 恢复用户操作
+```
+
+### `setViewMode(mode, enableTransition?)`
+
+在 2D 俯视图和 3D 透视图之间切换。2D 模式会将相机旋转到正上方，并锁定极角。
+
+```typescript
+await viewer.controls.setViewMode('2d'); // 切换到 2D 俯视模式
+await viewer.controls.setViewMode('3d'); // 切换回 3D 模式
+```
+
+**参数：**
+
+| 参数               | 类型              | 默认值 | 说明                    |
+| :----------------- | :---------------- | :----- | :---------------------- |
+| `mode`             | `'2d'` \| `'3d'` | —      | 视图模式。              |
+| `enableTransition` | `boolean`         | `true` | 是否启用平滑过渡动画。 |
+
+### `absoluteRotations()`
+
+将方位角（azimuth）归一化到 `[-π, π]` 范围内，避免相机在飞行过渡时产生多余旋转。在 `flyToBox` 内部自动调用。
+
+```typescript
+viewer.controls.absoluteRotations();
+```

package/docs/api-effects.md

@@ -9,7 +9,7 @@
 特性：
 - **效果可叠加**：高亮和呼吸效果可同时作用于同一对象，呼吸在高亮结果之上混合
 - **共享材质安全**：按材质跟踪引用计数，多个 Mesh 共享材质时互不干扰
-- **完整还原**：移除效果时自动恢复材质原始的 `colorNode`、`opacityNode` 和 `transparent` 状态
+- **完整还原**：移除效果时自动恢复材质原始的 `colorNode`、`opacityNode`、`transparent` 和 `depthWrite` 状态
 
 ### `MaterialEffects.highlightColor(object, options?)`
 
@@ -18,13 +18,24 @@
 ```typescript
 import { MaterialEffects } from 'u-space';
 
-// 以 50% 透明度高亮为红色
+// 以 50% 透明度高亮为红色（叠加模式）
 MaterialEffects.highlightColor(myModel, {
   color: 0xff0000,
   opacity: 0.5,
   overwrite: false, // false = 叠加（相乘），true = 完全替换颜色
 });
 
+// 半透明效果
+MaterialEffects.highlightColor(myModel, { opacity: 0.3 });
+
+// X 光效果（替换颜色 + 关闭深度写入）
+MaterialEffects.highlightColor(myModel, {
+  color: 0x0088ff,
+  opacity: 0.25,
+  overwrite: true,
+  depthWrite: false,
+});
+
 // 支持数组
 MaterialEffects.highlightColor([model1, model2], { color: 0x00ff00 });
 ```
@@ -33,9 +44,10 @@ MaterialEffects.highlightColor([model1, model2], { color: 0x00ff00 });
 
 | 属性        | 类型                  | 默认值      | 说明                                                                         |
 | :---------- | :-------------------- | :---------- | :--------------------------------------------------------------------------- |
-| `color`     | `ColorRepresentation` | `0xff0000`  | 高亮颜色。                                                                   |
-| `opacity`   | `number`              | `0.5`       | 高亮时材质的透明度。                                                         |
-| `overwrite` | `boolean`             | `false`     | `false` = 与原始颜色相乘（叠加）；`true` = 完全替换颜色。                    |
+| `color`      | `ColorRepresentation` | `0xff0000`  | 高亮颜色。                                                                   |
+| `opacity`    | `number`              | `0.5`       | 高亮时材质的透明度。                                                         |
+| `overwrite`  | `boolean`             | `false`     | `false` = 与原始颜色相乘（叠加）；`true` = 完全替换颜色。                    |
+| `depthWrite` | `boolean`             | —           | 可选。设为 `false` 可产生 X 光透视效果。不设置时保持原始值。                  |
 
 ### `MaterialEffects.removeHighlightColor(object)`
 
@@ -74,6 +86,36 @@ viewer.frameloop = 'always';
 MaterialEffects.removeBreatheColor(myModel);
 ```
 
+### `MaterialEffects.wireframe(object, enabled?)`
+
+开启或关闭线框渲染模式。
+
+```typescript
+MaterialEffects.wireframe(myModel);           // 开启线框
+MaterialEffects.wireframe(myModel, false);    // 关闭线框
+MaterialEffects.removeWireframe(myModel);     // 等同于 wireframe(obj, false)
+```
+
+### `MaterialEffects.fadeIn(object, options?)` / `MaterialEffects.fadeOut(object, options?)`
+
+淡入/淡出动画效果。返回 `Promise`，在动画完成后 resolve。淡出后对象材质保持透明状态。
+
+```typescript
+// 淡出
+await MaterialEffects.fadeOut(myModel, { duration: 1000 });
+
+// 淡入
+await MaterialEffects.fadeIn(myModel, { duration: 500 });
+```
+
+> 动画期间需要持续渲染，建议配合 `viewer.frameloop = 'always'` 使用。
+
+#### `FadeOptions`
+
+| 属性       | 类型     | 默认值 | 说明                |
+| :--------- | :------- | :----- | :------------------ |
+| `duration` | `number` | `500`  | 动画时长（毫秒）。 |
+
 ---
 
 ## `TSLEffects`

package/docs/api-interactions.md

@@ -6,7 +6,7 @@
 
 ## 启用交互事件
 
-出于性能考虑，指针移动事件默认可能处于禁用状态。如需悬停和拖拽效果，必须显式开启。
+出于性能考虑，指针移动事件默认处于禁用状态。如需悬停和拖拽效果，必须显式开启。
 
 ```typescript
 // 启用鼠标移动事件（如 pointerenter 和 pointerleave）
@@ -46,9 +46,9 @@ myBox.addEventListener('click', (eventData) => {
 
 以下事件类型可在可交互对象上监听：
 
-- `click`：指针点击对象时触发（过滤：长按或大幅移动后忽略）。
+- `click`：指针点击对象时触发。内置智能过滤：长按（>500ms）或移动距离过大时忽略，双击时不重复触发。
 - `dblclick`：快速双击对象时触发。
-- `rightclick`：右键短按松开时触发（长按或拖拽不触发；浏览器原生上下文菜单已被阻止）。与原生 `contextmenu` 的区别在于，此事件在 `pointerup` 时派发，因此可以正确过滤相机拖拽等操作。
+- `rightclick`：右键短按松开时触发（长按或拖拽不触发；浏览器原生上下文菜单已被阻止）。在 `pointerup` 时派发，因此可以正确过滤相机拖拽等操作。
 - `pointerdown`：指针按键在对象上按下时触发。
 - `pointerup`：指针按键在对象上释放时触发。
 - `pointermove`：指针在对象上移动时触发，需要 `pointerMoveEventsEnabled = true`。
@@ -89,13 +89,40 @@ myObject.addEventListener('click', (e) => {
 
 ### 属性
 
-| 属性                       | 类型                          | 默认值  | 说明                                                       |
-| :------------------------- | :---------------------------- | :------ | :--------------------------------------------------------- |
-| `targetObjects`            | `Object3D[]`                  | `scene.children` | 射线检测的目标对象列表，默认为场景的直接子级。  |
-| `pointerMoveEventsEnabled` | `boolean`                     | `false` | 启用 `pointermove`、`pointerenter`、`pointerleave` 事件。  |
+| 属性                       | 类型                          | 默认值            | 说明                                                       |
+| :------------------------- | :---------------------------- | :---------------- | :--------------------------------------------------------- |
+| `targetObjects`            | `Object3D[]`                  | `scene.children`  | 射线检测的目标对象列表，默认为场景的直接子级。             |
+| `pointerMoveEventsEnabled` | `boolean`                     | `false`           | 启用 `pointermove`、`pointerenter`、`pointerleave` 事件。  |
 
 ### 方法
 
+#### `enable()` / `disable()`
+
+全局启用或禁用所有交互事件。禁用后不再触发任何交互事件。
+
+```typescript
+viewer.interactionManager.disable(); // 暂停交互
+viewer.interactionManager.enable();  // 恢复交互
+```
+
+#### `setInteractable(object, interactable)`
+
+控制单个对象是否可交互。设为 `false` 后该对象及其所有子对象不再参与射线检测。
+
+```typescript
+viewer.interactionManager.setInteractable(myModel, false); // 禁止交互
+viewer.interactionManager.setInteractable(myModel, true);  // 恢复交互
+```
+
+#### `addIgnore(object)` / `removeIgnore(object)`
+
+`setInteractable` 的别名。`addIgnore(obj)` 等同于 `setInteractable(obj, false)`，`removeIgnore(obj)` 等同于 `setInteractable(obj, true)`。
+
+```typescript
+viewer.interactionManager.addIgnore(helperObject);    // 忽略辅助对象
+viewer.interactionManager.removeIgnore(helperObject);  // 恢复
+```
+
 #### `setCamera(camera)`
 
 更新用于射线检测的相机。由 `viewer.setCamera()` 自动调用。
@@ -107,3 +134,76 @@ myObject.addEventListener('click', (e) => {
 ```typescript
 viewer.interactionManager.dispose();
 ```
+
+---
+
+## Selection
+
+`Selection` 提供对象选择能力，包括单选、多选、toggle 和框选（rubber-band）。
+
+```typescript
+import { Selection } from 'u-space';
+
+const selection = new Selection(viewer.renderer.domElement, viewer.scene, viewer.camera);
+```
+
+### 基础选择
+
+```typescript
+selection.select(myObject);           // 选中
+selection.select([obj1, obj2]);       // 多选
+selection.deselect(myObject);         // 取消选择
+selection.toggle(myObject);           // 切换选择状态
+selection.clear();                    // 清空选择
+selection.isSelected(myObject);       // 检查是否已选
+```
+
+### 属性
+
+| 属性            | 类型            | 说明                                |
+| :-------------- | :-------------- | :---------------------------------- |
+| `selected`      | `Set<Object3D>` | 当前已选对象集合。                  |
+| `selectedArray` | `Object3D[]`    | 当前已选对象数组。                  |
+| `targetObjects` | `Object3D[]`    | 框选时的候选对象（默认为场景子级）。 |
+
+### 框选
+
+启用后可用鼠标拖动矩形区域选择多个对象。框选覆盖层会渲染在容器元素上。
+
+```typescript
+selection.enableBoxSelection({ deep: true });   // 开启框选
+selection.disableBoxSelection();                 // 关闭框选
+```
+
+#### `BoxSelectionOptions`
+
+| 属性        | 类型      | 默认值 | 说明                            |
+| :---------- | :-------- | :----- | :------------------------------ |
+| `className` | `string`  | —      | 框选矩形的 CSS 类名。          |
+| `deep`      | `boolean` | `true` | 是否递归检测子对象。            |
+
+### 事件
+
+```typescript
+selection.addEventListener('select', (e) => {
+  console.log('新选中:', e.objects);
+});
+
+selection.addEventListener('deselect', (e) => {
+  console.log('取消选中:', e.objects);
+});
+
+selection.addEventListener('change', (e) => {
+  console.log('当前选中:', e.selected.size, '个对象');
+});
+```
+
+### 方法
+
+#### `setCamera(camera)`
+
+更新用于框选投影计算的相机。切换相机时需调用。
+
+#### `dispose()`
+
+关闭框选、移除事件监听、清空选择集。

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();      // 清理
+```