bim_xg/bim_engine

Fork 0

Files

yuding dd4600bb5b 提交代码

2026-03-16 16:13:36 +08:00

6.2 KiB

Raw Blame History

iflow-engine SDK 架构设计

概述

iflow-engine 提供三个独立引擎类，均可单独导入：

类	定位	内部结构
`BimEngine`	3D 完整引擎	ManagerRegistry + 15 Managers + 20+ UI 组件
`BimEngine2d`	2D 图纸引擎	ManagerRegistry(仅事件) + Engine2d 组件
`BimEngine720`	720° 全景引擎	ManagerRegistry(仅事件) + Engine720 组件

三个类互不依赖，各自创建独立的 ManagerRegistry 实例。BimEngine2d 和 BimEngine720 跳过 Manager 层，直接使用底层组件。

2026-03 的核心调整：

新增 BimEngine2d、BimEngine720 独立类，按需导入
BimEngine 变为纯 3D 引擎，不再包含 2D/720 代码
EngineManager 从“大量透传”收敛为“少量公共 API + 生命周期编排”
内部 Manager 统一通过 BaseManager.engineComponent 直接访问 Engine 组件
Engine.getEngine() 已移除，改为 onRawEvent()/offRawEvent() 订阅底层事件

分层结构

┌───────────────────────────────────────────────────────────────────┐
│ 用户 API 入口                                                        │
│  BimEngine (3D)       BimEngine2d (2D)       BimEngine720 (720°)   │
└────┬──────────────────┬────────────────────┬────────────────────┘
     │                  │                    │
     ▼                  ▼                    ▼
 ManagerRegistry    ManagerRegistry      ManagerRegistry
 + 15 Managers     (仅事件总线)          (仅事件总线)
 + 20+ UI 组件     + Engine2d 组件      + Engine720 组件
     │                  │                    │
     └──────┬───────────┴────────┬───────────┘
            │                │
            ▼                ▼
  Services (Theme/Locale)   Core (EventEmitter/BaseManager)
            │
            ▼
  iflow-engine-base (createEngine / createEngine2d / createEngine720)

ManagerRegistry 设计

ManagerRegistry 是 实例模式：每个 BimEngine 都创建独立 registry，支持多实例隔离。

✅ 无全局共享状态污染
✅ 多画布/多引擎实例可并行
✅ 事件总线隔离

关键文件：src/core/manager-registry.ts

Engine 访问策略（最新）

1) 外部 SDK 用户

通过 bimEngine.engine（EngineManager）调用稳定公共 API：

initialize(options?)
isInitialized()
loadModel(urls, options?)
pauseRendering()
resumeRendering()
destroy()

2) 内部 Manager（BaseManager 子类）

通过 BaseManager 新增 getter：

protected get engineComponent(): Engine | null

直接调用 Engine 组件方法，例如：

this.engineComponent?.activeSection('box');
this.engineComponent?.setWalkSpeed(speed);

3) 非 Manager 组件

通过 registry 获取组件实例：

registry.engine3d?.getEngineComponent()?.toggleMiniMap();

EngineManager 职责边界

EngineManager 现在聚焦在“入口能力 + 组装能力”：

创建并持有 Engine 组件实例
初始化并持有 RightKeyManager
注册右键菜单项并编排右键行为
对外暴露少量稳定 API

不再承担：

对 Engine 全量方法的 1:1 透传

关键文件：src/managers/engine-manager.ts

原始引擎事件订阅策略

为避免暴露底层 raw engine 实例，Engine 组件提供：

onRawEvent(event, handler)
offRawEvent(event, handler)

例如测量与剖切盒事件：

this.engineComponent?.onRawEvent('measure-changed', handler);
this.engineComponent?.offRawEvent('measure-changed', handler);

关键文件：src/components/engine/index.ts

典型调用链

Button onClick
  -> registry.engine3d?.getEngineComponent()?.CameraGoHome()
  -> Engine.CameraGoHome()
  -> rawEngine.viewCube.CameraGoHome()

Section Box

SectionBoxDialogManager (BaseDialogManager)
  -> this.engineComponent?.activeSection('box')
  -> Engine.activeSection('box')
  -> rawEngine.clipping.active('box')

设计收益

降低中间层重复代码：EngineManager 大幅瘦身
减少三层转发链：Manager 可直接访问 Engine 组件
对外 API 稳定：仍保留 bimEngine.engine 作为入口
保持封装边界：不暴露 raw engine，仅开放受控事件桥接

后续建议

当前已完成“Manager 瘦身”阶段。若后续继续演进，可考虑将 Engine 组件按领域继续拆分（measure/section/walk/model/scene），进一步降低单类复杂度。

2D / 720 独立引擎设计

设计决策

不采用“一个 BimEngine 懒加载三种引擎”的方案，而是创建三个独立类。理由：

按需导入：只用 2D 的用户不需要打包 3D 的 UI 组件
职责清晰：3D 需要完整的 Manager 层，2D/720 只需轻量封装
生命周期独立：各自 destroy() 不影响其他实例
共享服务：themeManager 和 localeManager 依然是全局单例，主题切换对所有实例生效

BimEngine2d 结构

BimEngine2d
  ├─ ManagerRegistry (仅事件总线)
  └─ Engine2d 组件
       └─ createEngine2d() (iflow-engine-base)

构造时自动初始化，无需 initialize() 调用
直接暴露 loadDrawing()、getLayers()、setLayerVisible() 等 API
不创建任何 UI 组件（toolbar、dialog 等）

BimEngine720 结构

BimEngine720
  ├─ ManagerRegistry (仅事件总线)
  └─ Engine720 组件
       └─ createEngine720() (iflow-engine-base)

构造时自动初始化，配置 fov、zoom、rotate 等参数
直接暴露 loadPanorama()、setFov()、lookAt() 等 API
不创建任何 UI 组件

多引擎切换模式

同一容器同时只能有一个引擎实例。切换时：
1. current.destroy()   // 销毁当前
2. new BimEngineXxx()  // 创建新实例

文档更新时间: 2026-03-10

6.2 KiB Raw Blame History Unescape Escape