# BIM Engine SDK API 文档

本文档为 BIM Engine SDK 的完整 API 参考，适合大模型阅读和理解引擎的功能结构。

## 目录

1. [核心引擎类](#1-核心引擎类)
2. [基础模块](#2-基础模块)
3. [功能管理器](#3-功能管理器)
4. [状态管理](#4-状态管理)

---

## 1. 核心引擎类

### EngineKernelV2

引擎核心组件，负责整合和管理所有模块。

**文件路径**: `src/core/v2/EngineKernel.ts`

#### 构造函数

```typescript
constructor(options: any)
```

**参数**:
- `options.containerId`: string - 容器元素的 ID

**功能**:
- 初始化所有基础模块（场景、相机、渲染器、控制器等）
- 初始化所有功能管理器（测量、剖切、模型树等）
- 设置渲染循环
- 添加性能监视器

#### 公共属性

```typescript
// 基础对象
public scene: THREE.Scene | null                    // 三维场景
public camera: THREE.Camera | null                  // 当前使用的相机
public renderer: THREE.WebGLRenderer | null         // 渲染器
public controls: any                                // 控制器（轨道控制或第一人称）

// 基础模块
public sceneModule: SceneModule                     // 场景模块
public cameraModule: CameraModule                   // 相机模块
public deviceModule: DeviceModule                   // 设备模块
public renderModule: RenderModule                   // 渲染模块
public controlModule: ControlModule                 // 控制模块
public composerModule: ComposerModule               // 合成器模块
public loaderModule: LoaderModule                   // 加载器模块
public lightModule: LightModule                     // 光照模块
public interactionModule: InteractionModule         // 交互模块
public modelToolModule: ModelToolModule             // 模型工具模块

// 功能管理器
public viewCube: ViewCube                           // 视图立方体
public rangeScale: RangeScale                       // 范围缩放
public setting: Setting                             // 设置
public measure: Measure                             // 测量
public clipping: Clipping                           // 剖切
public modelTree: ModelTree                         // 模型树
public engineInfo: EngineInfo                       // 引擎信息统计
public modelProperties: ModelProperties             // 模型属性
public modelMapperBatch: ModelMapperBatch           // 模型批量映射
public modelEdge: ModelEdge                         // 模型边线

// 状态管理
public engineStatus: EngineStatus                   // 引擎状态
public events: EventModule                          // 事件模块

// 业务数据
public models: any[]                                // 已加载的模型数组
public reactBoundingClientRect: { left: number; top: number }  // 容器的边界矩形
```

#### 公共方法

##### pauseRendering()

```typescript
public pauseRendering(): void
```

**功能**: 暂停渲染循环
- 停止动画帧请求
- 禁用控制器
- 用于性能优化或后台运行

##### resumeRendering()

```typescript
public resumeRendering(): void
```

**功能**: 恢复渲染循环
- 重新启动动画帧请求
- 恢复控制器状态

##### isRenderingPausedState()

```typescript
public isRenderingPausedState(): boolean
```

**功能**: 检查渲染是否暂停

**返回值**: boolean - true 表示已暂停

##### dispose()

```typescript
public dispose(): void
```

**功能**: 销毁引擎，释放所有资源
- 停止渲染循环
- 清理所有模块
- 释放几何体、材质、纹理
- 移除 DOM 元素
- 清理事件监听器

**注意**: 调用此方法后引擎不可再使用

---

## 2. 基础模块

### 2.1 SceneModule - 场景模块

**文件路径**: `src/core/v2/modules/sceneModule.ts`

#### 公共属性

```typescript
public scene: THREE.Scene | null  // 三维场景对象
```

**功能**:
- 创建并管理 THREE.Scene
- 初始化边线组（groupEdge）用于存储模型边线

---

### 2.2 CameraModule - 相机模块

**文件路径**: `src/core/v2/modules/cameraModule.ts`

#### 公共属性

```typescript
public perspectiveCamera: THREE.PerspectiveCamera    // 透视相机
public orthographicCamera: THREE.OrthographicCamera  // 正交相机
```

#### 公共方法

##### switchCurrentCamera()

```typescript
public switchCurrentCamera(): void
```

**功能**: 切换当前相机类型（透视 ↔ 正交）

##### switchToPerspectiveCamera()

```typescript
public switchToPerspectiveCamera(): void
```

**功能**: 切换到透视相机
- 保持当前位置和目标点
- 更新控制器
- 重新初始化合成器

##### switchToOrthographicCamera()

```typescript
public switchToOrthographicCamera(): void
```

**功能**: 切换到正交相机
- 保持当前位置和目标点
- 更新控制器
- 重新初始化合成器

##### getCameraType()

```typescript
public getCameraType(): CameraType
```

**功能**: 获取当前相机类型

**返回值**:
- `CameraType.PERSPECTIVE` - 透视相机
- `CameraType.ORTHOGRAPHIC` - 正交相机

##### getCameraPose()

```typescript
public getCameraPose(): ICameraPose
```

**功能**: 获取当前相机姿态（位置、旋转、目标点、缩放等）

**返回值**: ICameraPose 对象
```typescript
interface ICameraPose {
    type: CameraType;
    position: { x: number; y: number; z: number };
    rotation: { x: number; y: number; z: number };
    quaternion: { x: number; y: number; z: number; w: number };
    target?: { x: number; y: number; z: number };
    zoom?: number;
}
```

##### restoreCameraPose()

```typescript
public restoreCameraPose(pose: ICameraPose): void
```

**功能**: 通过相机姿态还原相机位置
- 自动切换相机类型
- 恢复位置、旋转、目标点
- 恢复正交相机的缩放值

**参数**:
- `pose`: ICameraPose - 相机姿态对象

---

### 2.3 DeviceModule - 设备模块

**文件路径**: `src/core/v2/modules/deviceModule.ts`

#### 公共属性

```typescript
public deviceType: string  // 设备类型（默认 'PC'）
```

#### 公共方法

##### getDeviceType()

```typescript
public getDeviceType(): string
```

**功能**: 获取设备类型

**返回值**: 'PC' 或其他设备标识

##### getContainerSize()

```typescript
public getContainerSize(): { width: number; height: number }
```

**功能**: 获取容器尺寸

**返回值**: 容器的宽度和高度

---

### 2.4 RenderModule - 渲染模块

**文件路径**: `src/core/v2/modules/renderModule.ts`

#### 公共属性

```typescript
public renderer: THREE.WebGLRenderer | null  // WebGL 渲染器
```

#### 公共方法

##### createRenderer()

```typescript
public createRenderer(): THREE.WebGLRenderer
```

**功能**: 创建并配置 WebGL 渲染器
- 启用抗锯齿
- 启用阴影映射（PCFSoftShadowMap）
- 启用本地裁剪（用于剖切平面）
- 配置色彩空间和色调映射

**返回值**: 配置好的渲染器实例

##### disposeRenderer()

```typescript
public disposeRenderer(): void
```

**功能**: 释放渲染器资源

---

### 2.5 ControlModule - 控制模块

**文件路径**: `src/core/v2/modules/controlModule.ts`

#### 公共属性

```typescript
public orbitControls: any          // 轨道控制器
public firstPersonControls: any    // 第一人称控制器
public isActive: boolean           // 控制器是否激活
```

#### 公共方法

##### init()

```typescript
public init(): void
```

**功能**: 初始化控制器
- 创建轨道控制器和第一人称控制器
- 创建旋转中心指示器 UI

##### active()

```typescript
public active(): void
```

**功能**: 激活控制器

##### disActive()

```typescript
public disActive(): void
```

**功能**: 禁用控制器

##### switchFirstPersonMode()

```typescript
public switchFirstPersonMode(): void
```

**功能**: 切换到第一人称漫游模式
- 禁用轨道控制器
- 启用第一人称控制器

##### switchDefaultMode()

```typescript
public switchDefaultMode(): void
```

**功能**: 切换到默认模式（轨道控制）
- 禁用第一人称控制器
- 启用轨道控制器

##### update()

```typescript
public update(): void
```

**功能**: 更新控制器状态
- 更新旋转中心指示器位置
- 在渲染循环中调用

---

### 2.6 ComposerModule - 合成器模块

**文件路径**: `src/core/v2/modules/composerModule.ts`

#### 公共属性

```typescript
public composer: any  // 效果合成器
```

#### 公共方法

##### init()

```typescript
public init(): void
```

**功能**: 初始化后处理管线
- RenderPass - 基础渲染
- GTAOPass - 环境光遮蔽（默认禁用）
- UnrealBloomPass - 辉光效果（默认禁用）
- SaturationPass - 饱和度和对比度调整
- OutputPass - 色调映射和颜色校正
- FXAAPass - 抗锯齿

##### resize()

```typescript
public resize(): void
```

**功能**: 调整合成器大小
- 更新所有 pass 的分辨率
- 更新 FXAA 的分辨率参数

---

### 2.7 LoaderModule - 加载器模块

**文件路径**: `src/core/v2/modules/loaderModule.ts`

#### 公共方法

##### loadModels()

```typescript
async loadModels(urls: string[], options?: LoadModelOptions): Promise<void>
```

**功能**: 加载多个模型
- 支持轻量化模型格式
- 支持 GLTF/GLB 格式
- 异步加载

**参数**:
- `urls`: string[] - 模型 URL 数组
- `options`: LoadModelOptions - 加载选项（可选）

---

### 2.8 EventModule - 事件模块

**文件路径**: `src/core/v2/modules/eventModule.ts`

#### 公共方法

##### on()

```typescript
on<T = any>(event: EventType, callback: (data: T) => void): void
```

**功能**: 注册事件监听器

**参数**:
- `event`: EventType - 事件类型
- `callback`: 回调函数

##### off()

```typescript
off<T = any>(event: EventType, callback: (data: T) => void): void
```

**功能**: 移除事件监听器

**参数**:
- `event`: EventType - 事件类型
- `callback`: 要移除的回调函数

##### trigger()

```typescript
trigger(event: EventType, data?: any): void
```

**功能**: 触发事件

**参数**:
- `event`: EventType - 事件类型
- `data`: 传递给监听器的数据

**常用事件类型**:
- `EventType.Click` - 点击事件
- `EventType.ViewportResize` - 视口大小改变
- `EventType.EngineFree` - 引擎空闲
- `EventType.EngineBusy` - 引擎繁忙

---

### 2.9 LightModule - 光照模块

**文件路径**: `src/core/v2/modules/lightModule.ts`

#### 公共方法

##### init()

```typescript
public init(): void
```

**功能**: 初始化场景基本光照
- 添加定向光（DirectionalLight）
  - 强度: 2
  - 位置: (10, 20, 10)
  - 阴影贴图: 4096x4096（高质量）
- 添加环境光（AmbientLight）
  - 强度: 1

---

### 2.10 InteractionModule - 交互模块

**文件路径**: `src/core/v2/modules/interactionModule.ts`

#### 公共方法

##### init()

```typescript
public init(): void
```

**功能**: 初始化交互行为处理器

##### active()

```typescript
public active(): void
```

**功能**: 激活交互功能

##### disActive()

```typescript
public disActive(): void
```

**功能**: 禁用交互功能

##### handleMouseClick()

```typescript
public handleMouseClick(event: any): void
```

**功能**: 处理鼠标单击事件
- 射线检测点击的模型
- 高亮选中的模型
- 设置旋转中心
- 支持 Ctrl 多选

##### handleMouseDoubleClick()

```typescript
public handleMouseDoubleClick(event: any): void
```

**功能**: 处理鼠标双击事件
- 双击模型后缩放到该模型
- 计算模型包围盒并调整相机视角

##### handleMouseClickInstance()

```typescript
public handleMouseClickInstance(raycaster: any): any
```

**功能**: 判断点击实例化网格节点

**参数**:
- `raycaster`: 射线投射器

**返回值**: 相交结果数组

---

### 2.11 ModelToolModule - 模型工具模块

**文件路径**: `src/core/v2/modules/modelToolModule.ts`

#### 公共方法

##### highlightModel()

```typescript
public highlightModel(models: any): void
```

**功能**: 设置模型高亮显示

**参数**:
- `models`: 模型数组，格式: `[{url: string, ids: string[]}]`

##### unhighlightModel()

```typescript
public unhighlightModel(models: any): void
```

**功能**: 取消模型高亮

**参数**:
- `models`: 模型数组

##### unhighlightAllModels()

```typescript
public unhighlightAllModels(): void
```

**功能**: 取消所有模型高亮

##### hideModel()

```typescript
public hideModel(models: any): void
```

**功能**: 隐藏模型

**参数**:
- `models`: 模型数组，格式: `[{url: string, ids: string[]}]`

##### showModel()

```typescript
public showModel(models: any): void
```

**功能**: 显示模型

**参数**:
- `models`: 模型数组

##### isolateModel()

```typescript
public isolateModel(models: any): void
```

**功能**: 隔离模型（只显示指定模型，隐藏其他）

**参数**:
- `models`: 要显示的模型数组

##### showAllModels()

```typescript
public showAllModels(): void
```

**功能**: 显示所有模型

##### getModelsBox()

```typescript
public getModelsBox(models: any): THREE.Box3
```

**功能**: 获取模型的包围盒

**参数**:
- `models`: 模型数组

**返回值**: THREE.Box3 包围盒对象

---

## 3. 功能管理器

### 3.1 ViewCube - 视图立方体

**文件路径**: `src/core/v2/managers/viewCube/index.ts`

#### 公共属性

```typescript
public cubeTool: any  // 视图立方体工具
```

#### 公共方法

##### init()

```typescript
public init(): void
```

**功能**: 初始化视图立方体
- 创建 3D 小立方体辅助视图
- 支持六个面和边角视图切换

##### CameraGoHome()

```typescript
public CameraGoHome(): void
```

**功能**: 相机回归正位（默认视角）

##### zoomToModel()

```typescript
public zoomToModel(box: THREE.Box3): void
```

**功能**: 缩放到指定模型包围盒

**参数**:
- `box`: THREE.Box3 - 目标包围盒

---

### 3.2 RangeScale - 范围缩放工具

**文件路径**: `src/core/v2/managers/rangeScale/index.ts`

#### 公共方法

##### init()

```typescript
public init(): void
```

**功能**: 初始化范围缩放工具
- 创建绘制框 UI 元素
- 初始化坐标转换工具

##### active()

```typescript
public active(): void
```

**功能**: 激活范围缩放工具
- 禁用控制器
- 启用框选功能
- 鼠标变为十字光标

**使用方式**:
1. 激活工具
2. 鼠标拖拽绘制矩形区域
3. 松开鼠标自动缩放到该区域
4. 按 ESC 键退出

##### disActive()

```typescript
public disActive(): void
```

**功能**: 停用范围缩放工具
- 恢复控制器
- 移除事件监听

---

### 3.3 Setting - 设置管理器

**文件路径**: `src/core/v2/managers/setting/index.ts`

#### 公共方法

##### setStatsVisible()

```typescript
public setStatsVisible(visible: boolean): void
```

**功能**: 显示/隐藏性能监视器

**参数**:
- `visible`: true 显示，false 隐藏

##### setAmbientLightIntensity()

```typescript
public setAmbientLightIntensity(intensity: number): void
```

**功能**: 设置环境光照强度

**参数**:
- `intensity`: 光照强度，范围 0-5

##### setAmbientLightColor()

```typescript
public setAmbientLightColor(color: number | string): void
```

**功能**: 设置环境光照颜色

**参数**:
- `color`: 颜色（0xffffff 或 '#ffffff'）

##### setDirectionalLightIntensity()

```typescript
public setDirectionalLightIntensity(intensity: number): void
```

**功能**: 设置定向光源强度

**参数**:
- `intensity`: 光照强度，范围 0-5

##### setDirectionalLightColor()

```typescript
public setDirectionalLightColor(color: number | string): void
```

**功能**: 设置定向光源颜色

**参数**:
- `color`: 颜色

##### setShadowQuality()

```typescript
public setShadowQuality(quality: 'low' | 'medium' | 'high' | 'ultra'): void
```

**功能**: 设置阴影精细度

**参数**:
- `quality`: 质量等级
  - 'low': 1024
  - 'medium': 2048
  - 'high': 4096
  - 'ultra': 8192

##### setDirectionalLightShadow()

```typescript
public setDirectionalLightShadow(enabled: boolean): void
```

**功能**: 开启/关闭定向光阴影

**参数**:
- `enabled`: true 开启，false 关闭

##### setGTAOEnabled()

```typescript
public setGTAOEnabled(enabled: boolean): void
```

**功能**: 开启/关闭 GTAO 环境光遮蔽

**参数**:
- `enabled`: true 开启，false 关闭

##### setSceneSaturation()

```typescript
public setSceneSaturation(saturation: number): void
```

**功能**: 设置场景饱和度

**参数**:
- `saturation`: 饱和度值，1.0 为正常，推荐范围 0.5-2.0

##### setSceneContrast()

```typescript
public setSceneContrast(contrast: number): void
```

**功能**: 设置场景对比度

**参数**:
- `contrast`: 对比度值，1.0 为正常，推荐范围 0.5-2.0

##### setGroundEnabled()

```typescript
public setGroundEnabled(enabled: boolean, options?: {
    size?: number;
    color?: number | string;
    opacity?: number;
}): void
```

**功能**: 开启/关闭地面

**参数**:
- `enabled`: true 开启，false 关闭
- `options`: 地面配置选项
  - `size`: 地面大小（默认 100）
  - `color`: 地面颜色（默认 0x808080）
  - `opacity`: 透明度（默认 0.3）

##### setHDRBackground()

```typescript
public setHDRBackground(hdrTexture: THREE.Texture | null): void
```

**功能**: 设置 HDR 背景

**参数**:
- `hdrTexture`: HDR 环境贴图，null 则移除

---

### 3.4 Measure - 测量工具

**文件路径**: `src/core/v2/managers/measure/index.ts`

#### 公共方法

##### active()

```typescript
public active(): void
```

**功能**: 激活测量工具

##### disActive()

```typescript
public disActive(): void
```

**功能**: 停用测量工具
- 清除所有测量
- 恢复点选功能

##### clearAllPoints()

```typescript
public clearAllPoints(): void
```

**功能**: 清空所有测量点

##### clearAll()

```typescript
public clearAll(): void
```

**功能**: 清除所有测量标注

##### update()

```typescript
update(): void
```

**功能**: 更新测量标注
- 在渲染循环中调用
- 更新屏幕坐标

**测量类型**:
- 距离测量（DistanceMeasure）
- 净高测量（ClearHeightMeasure）
- 净距测量（ClearDistanceMeasure）
- 标高测量（ElevationMeasure）
- 点测量（PointMeasure）
- 角度测量（AngleMeasure）
- 面积测量（AreaMeasure）
- 坡度测量（SlopeMeasure）

---

### 3.5 Clipping - 剖切管理器

**文件路径**: `src/core/v2/managers/clipping/index.ts`

#### 公共属性

```typescript
public sectionPlaneX: any  // X 轴剖切平面
public sectionPlaneY: any  // Y 轴剖切平面
public sectionPlaneZ: any  // Z 轴剖切平面
public sectionBox: any     // 剖切盒
```

#### 公共方法

##### init()

```typescript
public init(): void
```

**功能**: 初始化剖切管理器
- 创建 6 个剖切平面（前、后、左、右、顶、底）
- 初始化 X/Y/Z 轴剖切工具
- 初始化剖切盒工具

##### disActive()

```typescript
public disActive(): void
```

**功能**: 停用所有剖切工具

---

### 3.6 ModelTree - 模型树

**文件路径**: `src/core/v2/managers/modelTree/index.ts`

#### 公共方法

##### getTreeData()

```typescript
public getTreeData(): any[]
```

**功能**: 获取模型树数据

**返回值**: 模型树数组
```typescript
[{
    name: string,        // 模型名称
    children: any[]      // 模型层级树
}]
```

---

### 3.7 EngineInfo - 引擎信息统计

**文件路径**: `src/core/v2/managers/engineInfo/index.ts`

#### 公共方法

##### getEngineInfo()

```typescript
public getEngineInfo(): {
    totalVertices: number;
    totalTriangles: number;
    meshCount: number;
}
```

**功能**: 获取引擎统计信息
- 统计所有网格的顶点数
- 统计所有网格的三角面数
- 统计网格数量

**返回值**:
- `totalVertices`: 总顶点数
- `totalTriangles`: 总三角面数
- `meshCount`: 网格数量

---

### 3.8 ModelProperties - 模型属性

**文件路径**: `src/core/v2/managers/modelProperties/index.ts`

#### 公共方法

##### getModelProperties()

```typescript
public getModelProperties(url: string, id: string, callback: (properties: any) => void): void
```

**功能**: 查询构件属性
- 异步加载属性数据（如果未加载）
- 从压缩的 JSON 中解析属性

**参数**:
- `url`: 模型 URL
- `id`: 构件 ID
- `callback`: 回调函数，接收属性对象

**返回值格式**:
```typescript
{
    properties: [{
        name: string,      // 分类名称
        children: [{
            name: string,  // 属性名
            value: any     // 属性值
        }]
    }],
    materials: []
}
```

---

### 3.9 ModelMapperBatch - 模型批量映射

**文件路径**: `src/core/v2/managers/modelMapperBatch/index.ts`

#### 公共方法

##### getModelTypes()

```typescript
public getModelTypes(): any[]
```

**功能**: 获取模型中所有的构件类型

##### getModelMajors()

```typescript
public getModelMajors(): any[]
```

**功能**: 获取模型中所有的专业

##### getModelLevels()

```typescript
public getModelLevels(): any[]
```

**功能**: 获取模型中所有的楼层

##### getModelMapper()

```typescript
public getModelMapper(url: string, id: number): any
```

**功能**: 获取指定构件的映射信息

**参数**:
- `url`: 模型 URL
- `id`: 构件 ID

**返回值**: Mapper 对象（包含类型、专业、楼层等信息）

##### getModelSWithType()

```typescript
public getModelSWithType(type: string, callback: any): any[]
```

**功能**: 获取同类型的所有构件

**参数**:
- `type`: 构件类型名称
- `callback`: 回调函数

**返回值**: `[{url: string, ids: number[]}]`

##### getModelSWithLevel()

```typescript
public getModelSWithLevel(level: string, callback: any): any[]
```

**功能**: 获取同楼层的所有构件

**参数**:
- `level`: 楼层名称
- `callback`: 回调函数

**返回值**: `[{url: string, ids: number[]}]`

##### getModelsWithMajor()

```typescript
public getModelsWithMajor(major: string, callback: any): any[]
```

**功能**: 获取同专业的所有构件

**参数**:
- `major`: 专业名称
- `callback`: 回调函数

**返回值**: `[{url: string, ids: number[]}]`

---

### 3.10 ModelEdge - 模型边线管理器

**文件路径**: `src/core/v2/managers/modelEdge/index.ts`

#### 公共方法

##### active()

```typescript
public active(): void
```

**功能**: 启动边线显示
- 显示所有模型的边线
- 用于技术制图风格渲染

##### disActive()

```typescript
public disActive(): void
```

**功能**: 关闭边线显示

##### getModelEdge()

```typescript
public getModelEdge(url: string, id: Number): any
```

**功能**: 获取指定模型的边线数据

**参数**:
- `url`: 模型 URL
- `id`: 构件 ID

**返回值**: 边线数据 `[startIndex, endIndex, points]`

##### hideModelEdge()

```typescript
public hideModelEdge(url: string, id: Number): void
```

**功能**: 隐藏指定构件的边线

**参数**:
- `url`: 模型 URL
- `id`: 构件 ID

##### showModelEdge()

```typescript
public showModelEdge(url: string, id: Number): void
```

**功能**: 显示指定构件的边线

**参数**:
- `url`: 模型 URL
- `id`: 构件 ID

---

## 4. 状态管理

### 4.1 EngineStatus - 引擎状态

**文件路径**: `src/core/v2/status/engineStatus.ts`

#### 公共属性

```typescript
public isFree: boolean              // 引擎是否空闲
public highlightModels: any[]       // 高亮的模型数组
public hideModels: any[]            // 隐藏的模型数组
public models: any[]                // 已加载的模型数组
```

#### 公共方法

##### init()

```typescript
public init(): void
```

**功能**: 初始化引擎状态监听
- 监听 `EventType.EngineFree` 事件
- 监听 `EventType.EngineBusy` 事件

##### updateFree()

```typescript
public updateFree(status: boolean): void
```

**功能**: 更新引擎空闲状态

**参数**:
- `status`: true 表示空闲，false 表示繁忙

##### closeAllFunction()

```typescript
public closeAllFunction(): void
```

**功能**: 关闭所有功能

---

### 4.2 HandelBehaved - 行为处理器

**文件路径**: `src/core/v2/status/handelBehaved.ts`

这是一个工厂函数，返回行为处理器对象。

#### 公共方法

##### init()

```typescript
init(self: any, options: any): void
```

**功能**: 初始化行为处理器

**参数**:
- `self`: 当前激活的行为对象
- `options`: 行为配置选项
  - `showCatch`: boolean - 是否显示捕捉点

##### active()

```typescript
active(): void
```

**功能**: 开启事务（激活事件监听）
- 监听鼠标事件（mousedown, mouseup, mousemove）
- 监听键盘事件（keydown, keyup）

##### disActive()

```typescript
disActive(): void
```

**功能**: 关闭事务（禁用事件监听）

**支持的键盘事件**:
- Delete / Backspace - 删除
- Escape - 取消
- Enter - 确认
- Space - 空格
- Ctrl / Control - 控制键
- Shift - 切换键
- Alt - 辅助键
- Meta / Command - 命令键

**支持的鼠标事件**:
- handleMouseDown - 鼠标按下
- handleMouseMove - 鼠标移动
- handleMouseUp - 鼠标弹起
- handleMouseClick - 鼠标单击
- handleMouseDoubleClick - 鼠标双击

**捕捉功能**:
- 点捕捉（距离 < 5 像素）
- 线捕捉（距离 < 5 像素）
- 面捕捉（默认）

---

## 使用示例

### 初始化引擎

```typescript
import { EngineKernelV2 } from './src/core/v2/EngineKernel';

const engine = new EngineKernelV2({
    containerId: 'canvas-container',
    antialias: true
});
```

### 加载模型

```typescript
await engine.loaderModule.loadModels([
    'https://example.com/model1.light',
    'https://example.com/model2.light'
]);
```

### 高亮模型

```typescript
engine.modelToolModule.highlightModel([
    { url: 'model1.light', ids: ['wall-001', 'wall-002'] }
]);
```

### 切换相机

```typescript
// 切换到正交相机
engine.cameraModule.switchToOrthographicCamera();

// 或切换当前相机类型
engine.cameraModule.switchCurrentCamera();
```

### 保存和恢复相机姿态

```typescript
// 保存当前相机姿态
const pose = engine.cameraModule.getCameraPose();

// 恢复相机姿态
engine.cameraModule.restoreCameraPose(pose);
```

### 设置光照和渲染质量

```typescript
// 设置环境光强度
engine.setting.setAmbientLightIntensity(1.5);

// 设置阴影质量
engine.setting.setShadowQuality('ultra');

// 开启 GTAO
engine.setting.setGTAOEnabled(true);

// 调整饱和度和对比度
engine.setting.setSceneSaturation(1.3);
engine.setting.setSceneContrast(1.1);
```

### 获取模型属性

```typescript
engine.modelProperties.getModelProperties('model.light', 'wall-001', (data) => {
    console.log('属性:', data.properties);
});
```

### 按类型筛选构件

```typescript
engine.modelMapperBatch.getModelSWithType('墙', (models) => {
    // 高亮所有墙体
    engine.modelToolModule.highlightModel(models);
});
```

### 监听事件

```typescript
// 监听点击事件
engine.events.on(EventType.Click, (hit) => {
    console.log('点击了:', hit.object.name);
});

// 监听视口大小改变
engine.events.on(EventType.ViewportResize, ({ width, height }) => {
    console.log('视口大小:', width, height);
});
```

### 暂停和恢复渲染

```typescript
// 暂停渲染（节省性能）
engine.pauseRendering();

// 恢复渲染
engine.resumeRendering();

// 检查渲染状态
if (engine.isRenderingPausedState()) {
    console.log('渲染已暂停');
}
```

### 销毁引擎

```typescript
// 释放所有资源
engine.dispose();
```

---

## 总结

BIM Engine SDK 提供了完整的 3D BIM 模型渲染和交互能力，主要特性包括：

- **完整的相机系统**: 支持透视和正交相机，可保存和恢复相机姿态
- **强大的模型操作**: 高亮、隐藏、隔离、批量筛选
- **丰富的测量工具**: 距离、净高、净距、标高、角度、面积、坡度
- **灵活的剖切功能**: 支持 X/Y/Z 轴剖切和剖切盒
- **可配置的渲染质量**: 阴影、环境光遮蔽、饱和度、对比度
- **事件驱动架构**: 支持自定义事件监听和触发
- **性能优化**: 支持暂停/恢复渲染，八叉树加速
- **完善的资源管理**: 自动释放几何体、材质、纹理等资源

适用场景：
- BIM 模型在线浏览
- 建筑设计审查
- 施工模拟
- 运维管理
- AI 辅助设计