feat(all): init commit

packages/docs/api/core/Viewer.md

@@ -0,0 +1,557 @@
+---
+outline: [2, 3]
+---
+
+# Viewer
+
+- 源文件：`packages/sdk/src/core/Viewer.ts`
+- 文档位置：`packages/docs/api/core/Viewer.md`
+
+## 接口：`CameraState`
+
+- 作用：相机状态接口
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `position` | `{ x: number; y: number; z: number; }` | 是 | 位置数据。 |
+| `target` | `{ x: number; y: number; z: number; }` | 是 | 目标点数据。 |
+
+## 接口：`SceneNode`
+
+- 作用：场景节点接口
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `uuid` | `string` | 是 | 对象的唯一标识。 |
+| `name` | `string` | 是 | 名称。 |
+| `displayName` | `string` | 是 | 显示名称 |
+| `hasMappedName` | `boolean` | 否 | 是否有映射名称 |
+| `parent` | `string \| null` | 是 | 父级对象标识。 |
+| `children` | `SceneNode[]` | 是 | 子节点列表。 |
+| `type` | `string` | 是 | 类型标识。 |
+| `visible` | `boolean` | 是 | 控制对象是否可见。 |
+| `opacity` | `number` | 是 | 控制对象或材质的透明度。 |
+| `isClippingGroup` | `boolean` | 是 | 用于标记 `isClippingGroup` 的启用状态。 |
+
+## 接口：`ModelNameMapping`
+
+- 作用：模型名称映射接口
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `name` | `string` | 是 | 名称。 |
+| `displayName` | `string` | 是 | 用于界面展示的名称。 |
+
+## 接口：`IViewerOptions`
+
+- 作用：视图配置选项
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `initCameraState` | `CameraState` | 否 | 初始相机状态配置。 |
+| `raycastEnabled` | `boolean` | 否 | 是否启用射线拾取。 |
+| `modelNameMappings` | `ModelNameMapping[]` | 否 | 模型名称映射 |
+| `clipping` | `IClippingManagerOptions` | 否 | 剖切配置 |
+
+## 类：`Viewer`
+
+- 作用：三维视图管理器 Deep Engine 的核心类，负责管理场景、相机、渲染器等
+
+### 构造函数
+
+#### `new Viewer(container: string | HTMLDivElement, options: IViewerOptions = {})`
+
+- 作用：创建 Viewer 实例。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `container` | `string \| HTMLDivElement` | 是 | 挂载容器，支持 DOM ID 或 DOM 元素。 |
+| `options` | `IViewerOptions` | 否 | 当前功能对应的配置项。 |
+
+- 出参：`Viewer`
+- 返回说明：返回当前类实例。
+
+### 属性
+
+| 属性名 | 可见性 | 类型 | 作用 |
+| --- | --- | --- | --- |
+| `events` | `public` | `EventManager` | 事件管理器 |
+| `resources` | `public` | `ResourceManager` | 资源管理器 |
+| `clipping` | `public` | `ClippingManager` | 剖切管理器 |
+| `container` | `public` | `HTMLElement \| null` | 当前渲染视图挂载的 DOM 容器。 |
+| `scene` | `public` | `THREE.Scene` | Three.js 主场景，承载业务模型与特效对象。 |
+| `sceneHelpers` | `public` | `THREE.Scene` | 辅助场景，通常用于调试辅助器和非业务对象。 |
+| `perspectiveCamera` | `public` | `THREE.PerspectiveCamera` | 透视相机实例。 |
+| `orthographicCamera` | `public` | `THREE.OrthographicCamera` | 正交相机实例。 |
+| `currentCameraType` | `public` | `'perspective' \| 'orthographic'` | 当前启用的相机类型。 |
+| `renderer` | `public` | `THREE.WebGPURenderer \| null` | WebGPU 渲染器实例。 |
+| `animationFrameId` | `public` | `number \| null` | 当前渲染循环对应的动画帧编号。 |
+| `isInitialized` | `public` | `boolean` | 标记 Viewer 是否已经完成初始化。 |
+| `pipelineManager` | `public` | `PipelineManager` | 渲染管线管理器。 |
+| `selection` | `public` | `SelectionManager` | 场景选择管理器。 |
+| `css2d` | `public` | `CSS2DRendererManager` | CSS2D 渲染管理器 |
+| `css3d` | `public` | `CSS3DRendererManager` | CSS3D 渲染管理器 |
+| `parametric` | `public` | `ParametricManager` | 参数化对象管理器 |
+| `inspector` | `public` | `Inspector` | Three Inspector 调试面板实例。 |
+| `ruptureEvents` | `public` | `RuptureEventManager` | 破裂事件管理器 |
+| `emitter` | `public` | `Emittery<ViewerEventMap, ViewerEventMap & OmnipresentEventData, ViewerEvents.INIT>` | Viewer 内部事件发射器。 |
+| `options` | `public` | `IViewerOptions` | Viewer 的初始化配置。 |
+| `modelNameMappings` | `public` | `Map<string, string>` | 模型名称映射，用于存储模型名称到显示名的映射 |
+| `rangeCullingManager` | `public` | `RangeCullingManager` | 范围剔除管理器。 |
+| `timer` | `public` | `THREE.Timer` | 用于计算帧间隔时间的计时器。 |
+
+### 访问器
+
+#### `get camera(): THREE.PerspectiveCamera | THREE.OrthographicCamera`
+
+- 作用：获取当前激活的相机
+
+- 入参：无
+
+- 出参：`THREE.PerspectiveCamera \| THREE.OrthographicCamera`
+- 返回说明：返回 `THREE.PerspectiveCamera | THREE.OrthographicCamera`。
+
+#### `get cameraControls(): CameraControls`
+
+- 作用：获取当前激活的相机控制器
+
+- 入参：无
+
+- 出参：`CameraControls`
+- 返回说明：返回 `CameraControls`。
+
+### 方法
+
+#### `initCameraControls(): void`
+
+- 作用：执行 init Camera Controls 初始化逻辑。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `initContainer(container: string | HTMLDivElement): void`
+
+- 作用：初始化容器
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `container` | `string \| HTMLDivElement` | 是 | 挂载容器，支持 DOM ID 或 DOM 元素。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `getSize(): { width: number; height: number; }`
+
+- 作用：获取容器的大小
+
+- 入参：无
+
+- 出参：`{ width: number; height: number; }`
+- 返回说明：返回 `{ width: number; height: number; }`。
+
+#### `getSizeVector2(): THREE.Vector2`
+
+- 作用：获取大小的 Vector2 对象
+
+- 入参：无
+
+- 出参：`THREE.Vector2`
+- 返回说明：返回 `THREE.Vector2`。
+
+#### `initRenderer(): void`
+
+- 作用：初始化视图
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `openInspector(): void`
+
+- 作用：打开 Inspector。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `closeInspector(): void`
+
+- 作用：关闭 Inspector。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `handleResize(): void`
+
+- 作用：处理窗口大小变化
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `animate(time: DOMHighResTimeStamp, frame?: XRFrame): void`
+
+- 作用：执行 animate 相关逻辑。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `time` | `DOMHighResTimeStamp` | 是 | 时间戳。 |
+| `frame` | `XRFrame` | 否 | 参数 `frame`，类型为 `XRFrame`。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `dispose(): void`
+
+- 作用：销毁视图
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `isReady(): boolean`
+
+- 作用：检查是否已初始化
+
+- 入参：无
+
+- 出参：`boolean`
+- 返回说明：是否已初始化
+
+#### `getModelDisplayName(name: string): string`
+
+- 作用：获取模型的显示名称
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `name` | `string` | 是 | - 模型原始名称 |
+
+- 出参：`string`
+- 返回说明：模型的显示名称，如果没有映射则返回原始名称
+
+#### `addModelNameMapping(mapping: ModelNameMapping): void`
+
+- 作用：添加模型名称映射
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `mapping` | `ModelNameMapping` | 是 | - 模型名称映射 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `addModelNameMappings(mappings: ModelNameMapping[]): void`
+
+- 作用：添加多个模型名称映射
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `mappings` | `ModelNameMapping[]` | 是 | - 模型名称映射数组 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `clearModelNameMappings(): void`
+
+- 作用：清除所有模型名称映射
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `serializeObject(obj: THREE.Object3D): SceneNode`
+
+- 作用：序列化 Object。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `obj` | `THREE.Object3D` | 是 | 参数 `obj`，类型为 `THREE.Object3D`。 |
+
+- 出参：`SceneNode`
+- 返回说明：返回 `SceneNode`。
+
+#### `sceneToTreeJSON(scene: THREE.Scene = this.scene): SceneNode`
+
+- 作用：执行 scene To Tree JSON 相关逻辑。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `scene` | `THREE.Scene` | 否 | 目标场景实例。 |
+
+- 出参：`SceneNode`
+- 返回说明：返回 `SceneNode`。
+
+#### `serializeObjectFiltered(obj: THREE.Object3D = this.scene, nameFilter?: string): SceneNode | null`
+
+- 作用：序列化场景对象，只返回 Object3D 和 Group 类型的对象
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `obj` | `THREE.Object3D` | 否 | - 要序列化的对象 |
+| `nameFilter` | `string` | 否 | - 可选的名称过滤器，支持模糊匹配 |
+
+- 出参：`SceneNode \| null`
+- 返回说明：序列化后的场景节点
+
+#### `serializeSceneFiltered(nameFilter?: string): SceneNode[]`
+
+- 作用：序列化场景对象，只返回 Object3D 和 Group 类型的对象，并支持名称过滤
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `nameFilter` | `string` | 否 | - 可选的名称过滤器，支持模糊匹配 |
+
+- 出参：`SceneNode[]`
+- 返回说明：序列化后的场景节点列表
+
+#### `sceneToTreeJSONFiltered(scene: THREE.Scene = this.scene, nameFilter?: string): SceneNode | null`
+
+- 作用：将场景转换为树状 JSON 结构，只包含 Object3D 和 Group 类型的对象
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `scene` | `THREE.Scene` | 否 | - 要转换的场景 |
+| `nameFilter` | `string` | 否 | - 可选的名称过滤器，支持模糊匹配 |
+
+- 出参：`SceneNode \| null`
+- 返回说明：序列化后的场景节点
+
+#### `getCameraState(): { position: THREE.Vector3; target: THREE.Vector3; }`
+
+- 作用：获取 Camera State。
+
+- 入参：无
+
+- 出参：`{ position: THREE.Vector3; target: THREE.Vector3; }`
+- 返回说明：返回 `{ position: THREE.Vector3; target: THREE.Vector3; }`。
+
+#### `setCameraState(cameraState: CameraState, enableTransition: boolean = true): Promise<void>`
+
+- 作用：设置 Camera State。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `cameraState` | `CameraState` | 是 | 参数 `cameraState`，类型为 `CameraState`。 |
+| `enableTransition` | `boolean` | 否 | 参数 `enableTransition`，类型为 `boolean`。 |
+
+- 出参：`Promise<void>`
+- 返回说明：返回 Promise，解析结果类型为 `void`。
+
+#### `resetCamera(enableTransition: boolean = true): void`
+
+- 作用：重置 Camera。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `enableTransition` | `boolean` | 否 | 参数 `enableTransition`，类型为 `boolean`。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `switchCameraType(type: 'perspective' | 'orthographic'): Promise<void>`
+
+- 作用：切换相机类型（透视相机和正交相机） 切换时保持视角不变
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `type` | `'perspective' \| 'orthographic'` | 是 | - 相机类型 'perspective' 或 'orthographic' |
+
+- 出参：`Promise<void>`
+- 返回说明：返回 Promise，解析结果类型为 `void`。
+
+#### `exportSceneToJSON(): string`
+
+- 作用：导出场景为JSON格式
+
+- 入参：无
+
+- 出参：`string`
+- 返回说明：场景的JSON字符串
+
+#### `downloadSceneJSON(filename: string = 'scene.json'): void`
+
+- 作用：导出场景为JSON文件并下载
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `filename` | `string` | 否 | - 下载的文件名 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `getAllVolumeMesh(): VolumeMesh[]`
+
+- 作用：获取 All Volume Mesh。
+
+- 入参：无
+
+- 出参：`VolumeMesh[]`
+- 返回说明：返回数组结果，元素类型为 `VolumeMesh`。
+
+#### `setTestBackground(): void`
+
+- 作用：设置 Test Background。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+## 构造示例
+
+- 来源：`packages/demo/src/views/GeothermalScene.vue`
+
+```ts
+onMounted(() => {
+  const viewer = new Viewer("viewer", {
+    initCameraState: initCameraState
+  });
+```
+
+- 来源：`packages/demo/src/views/GoldMineScene.vue`
+
+```ts
+onMounted(() => {
+  const viewer = new Viewer("viewer", {
+    initCameraState: initCameraState
+  });
+```
+
+## 函数示例
+
+### `Viewer.openInspector`
+
+- 来源：`packages/demo/src/hooks/useDebug.ts`
+
+```ts
+        bloom: Value;
+        bloomColor: Value;
+        renderOrder: Value;
+        color: Value;
+        metalness: Value;
+        roughness: Value;
+        depthTest: Value;
+        depthWrite: Value;
+        side: Value;
+    } = {} as any;
+
+    // 打开调试
+    viewer.openInspector();
+
+    // 添加 GUI 控件
+    const inspector = viewer.renderer!.inspector as Inspector;
+```
+
+### `Viewer.serializeSceneFiltered`
+
+- 来源：`packages/demo/src/components/SceneTree.vue`
+
+```ts
+  if (bus.viewer) {
+    treeData.value = bus.viewer.serializeSceneFiltered();
+    console.log(treeData.value)
+  }
+}
+const handleSearch = () => {
+  if (bus.viewer) {
+    const sceneData = bus.viewer.serializeSceneFiltered(searchKeyword.value);
+    treeData.value = sceneData
+  }
+};
+```
+
+### `Viewer.getCameraState`
+
+- 来源：`packages/demo/src/hooks/useDebug.ts`
+
+```ts
+                const transformInfo = {
+                    position: [selectedObject.position.x, selectedObject.position.y, selectedObject.position.z],
+                    rotation: [selectedObject.rotation.x, selectedObject.rotation.y, selectedObject.rotation.z],
+                    scale: [selectedObject.scale.x, selectedObject.scale.y, selectedObject.scale.z]
+                };
+                console.log('模型变换信息:', transformInfo);
+            }
+        },
+        printCameraState: () => {
+            const cameraState = viewer.getCameraState();
+            console.log('相机状态:', cameraState);
+        },
+        addTestBox: () => {
+            // 创建测试box
+            const geometry = new THREE.BoxGeometry(1, 1, 1);
+            const material = new THREE.MeshPhysicalMaterial({color: 0x00ff00});
+            const box = new THREE.Mesh(geometry, material);
+            box.position.set(0, 0, 0);
+            box.name = "Test Box";
+            viewer.scene.add(box);
+```
+
+## Demo 参考
+
+### `SceneNode`
+
+以下示例文件中可以看到该 API 的实际调用方式：
+
+- `packages/demo/src/components/SceneTree.vue`
+
+### `Viewer`
+
+以下示例文件中可以看到该 API 的实际调用方式：
+
+- `packages/demo/src/disasterFormationPanel/TunnelScene/RuptureEventPanel.vue`
+- `packages/demo/src/hooks/Bus.ts`
+- `packages/demo/src/panels/FracturingPanel.vue`
+- `packages/demo/src/panels/GeothermalScene/DirectionalReservoir.vue`
+- `packages/demo/src/panels/GoldMineScene/DevelopmentMiningPanel.vue`
+- `packages/demo/src/panels/GoldMineScene/DrillingPanel.vue`
+- `packages/demo/src/panels/GoldMineScene/ExplorationMiningPanel.vue`
+- `packages/demo/src/panels/GoldMineScene/VentilationFillingPanel.vue`
+

packages/docs/api/core/ViewerInstances.md

@@ -0,0 +1,87 @@
+---
+outline: [2, 3]
+---
+
+# ViewerInstances
+
+- 源文件：`packages/sdk/src/core/ViewerInstances.ts`
+- 文档位置：`packages/docs/api/core/ViewerInstances.md`
+
+## 类：`ViewerManager`
+
+- 作用：ViewerManager 类。
+
+### 属性
+
+| 属性名 | 可见性 | 类型 | 作用 |
+| --- | --- | --- | --- |
+| `viewers` | `public` | `Set<Viewer>` | 用于保存 `viewers` 对应的数据。 |
+| `defaultViewer` | `public` | `Viewer \| null` | 用于保存 `defaultViewer` 对应的数据。 |
+
+### 方法
+
+#### `register(viewer: Viewer, makeDefault = false): void`
+
+- 作用：执行 register 相关逻辑。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `viewer` | `Viewer` | 是 | 关联的 Viewer 实例。 |
+| `makeDefault` | `boolean` | 否 | 参数 `makeDefault`，类型为 `boolean`。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `unregister(viewer: Viewer): void`
+
+- 作用：执行 unregister 相关逻辑。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `viewer` | `Viewer` | 是 | 关联的 Viewer 实例。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `getDefault(): Viewer`
+
+- 作用：获取 Default。
+
+- 入参：无
+
+- 出参：`Viewer`
+- 返回说明：返回 `Viewer`。
+
+#### `setDefault(viewer: Viewer): void`
+
+- 作用：设置 Default。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `viewer` | `Viewer` | 是 | 关联的 Viewer 实例。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `getAll(): Viewer[]`
+
+- 作用：获取 All。
+
+- 入参：无
+
+- 出参：`Viewer[]`
+- 返回说明：返回数组结果，元素类型为 `Viewer`。
+
+## 构造示例
+
+- 当前 Demo 中没有直接展示 `ViewerManager` 的构造调用。
+
+## 函数示例
+
+- 当前 Demo 中没有直接展示 `ViewerManager` 的公开方法调用。