---
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`