ljq/deep-engine-demo

Fork 0

plum 5d7f479765 feat(all): init commit

2026-04-19 18:46:28 +08:00

15 KiB

Raw Permalink Blame History

outline

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

onMounted(() => {
  const viewer = new Viewer("viewer", {
    initCameraState: initCameraState
  });

来源：packages/demo/src/views/GoldMineScene.vue

onMounted(() => {
  const viewer = new Viewer("viewer", {
    initCameraState: initCameraState
  });

函数示例

`Viewer.openInspector`

来源：packages/demo/src/hooks/useDebug.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

  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

                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

15 KiB Raw Permalink Blame History Unescape Escape

Viewer

接口：CameraState

字段

接口：SceneNode

字段

接口：ModelNameMapping

字段

接口：IViewerOptions

字段

类：Viewer

构造函数

new Viewer(container: string | HTMLDivElement, options: IViewerOptions = {})

属性

访问器

get camera(): THREE.PerspectiveCamera | THREE.OrthographicCamera

get cameraControls(): CameraControls

方法

initCameraControls(): void

initContainer(container: string | HTMLDivElement): void

getSize(): { width: number; height: number; }

getSizeVector2(): THREE.Vector2

initRenderer(): void

openInspector(): void

closeInspector(): void

handleResize(): void

animate(time: DOMHighResTimeStamp, frame?: XRFrame): void

dispose(): void

isReady(): boolean

getModelDisplayName(name: string): string

addModelNameMapping(mapping: ModelNameMapping): void

addModelNameMappings(mappings: ModelNameMapping[]): void

clearModelNameMappings(): void

serializeObject(obj: THREE.Object3D): SceneNode

sceneToTreeJSON(scene: THREE.Scene = this.scene): SceneNode

serializeObjectFiltered(obj: THREE.Object3D = this.scene, nameFilter?: string): SceneNode | null

serializeSceneFiltered(nameFilter?: string): SceneNode[]

sceneToTreeJSONFiltered(scene: THREE.Scene = this.scene, nameFilter?: string): SceneNode | null

getCameraState(): { position: THREE.Vector3; target: THREE.Vector3; }

setCameraState(cameraState: CameraState, enableTransition: boolean = true): Promise<void>

resetCamera(enableTransition: boolean = true): void

switchCameraType(type: 'perspective' | 'orthographic'): Promise<void>

exportSceneToJSON(): string

downloadSceneJSON(filename: string = 'scene.json'): void

getAllVolumeMesh(): VolumeMesh[]

setTestBackground(): void

构造示例

函数示例

Viewer.openInspector

Viewer.serializeSceneFiltered

Viewer.getCameraState

Demo 参考

SceneNode

Viewer

15 KiB

Raw Permalink Blame History

接口：`CameraState`

接口：`SceneNode`

接口：`ModelNameMapping`

接口：`IViewerOptions`

类：`Viewer`

`new Viewer(container: string | HTMLDivElement, options: IViewerOptions = {})`

`get camera(): THREE.PerspectiveCamera | THREE.OrthographicCamera`

`get cameraControls(): CameraControls`

`initCameraControls(): void`

`initContainer(container: string | HTMLDivElement): void`

`getSize(): { width: number; height: number; }`

`getSizeVector2(): THREE.Vector2`

`initRenderer(): void`

`openInspector(): void`

`closeInspector(): void`

`handleResize(): void`

`animate(time: DOMHighResTimeStamp, frame?: XRFrame): void`

`dispose(): void`

`isReady(): boolean`

`getModelDisplayName(name: string): string`

`addModelNameMapping(mapping: ModelNameMapping): void`

`addModelNameMappings(mappings: ModelNameMapping[]): void`

`clearModelNameMappings(): void`

`serializeObject(obj: THREE.Object3D): SceneNode`

`sceneToTreeJSON(scene: THREE.Scene = this.scene): SceneNode`

`serializeObjectFiltered(obj: THREE.Object3D = this.scene, nameFilter?: string): SceneNode | null`

`serializeSceneFiltered(nameFilter?: string): SceneNode[]`

`sceneToTreeJSONFiltered(scene: THREE.Scene = this.scene, nameFilter?: string): SceneNode | null`

`getCameraState(): { position: THREE.Vector3; target: THREE.Vector3; }`

`setCameraState(cameraState: CameraState, enableTransition: boolean = true): Promise<void>`

`resetCamera(enableTransition: boolean = true): void`

`switchCameraType(type: 'perspective' | 'orthographic'): Promise<void>`

`exportSceneToJSON(): string`

`downloadSceneJSON(filename: string = 'scene.json'): void`

`getAllVolumeMesh(): VolumeMesh[]`

`setTestBackground(): void`

`Viewer.openInspector`

`Viewer.serializeSceneFiltered`

`Viewer.getCameraState`

`SceneNode`

`Viewer`