bim_xg/bim_engine
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

提交代码

Browse Source
This commit is contained in:
yuding
2026-03-16 16:13:36 +08:00
parent 507112fcf9
commit dd4600bb5b
35 changed files with 31811 additions and 9696 deletions
Download Patch File Download Diff File Expand all files Collapse all files

807
docs/快速开始.md
View File

@@ -20,83 +20,129 @@ yarn add iflow-engine
pnpm add iflow-engine
```
## 基础使用
## 引擎概览
### 1. 创建 HTML 容器
SDK 提供三个独立引擎类，按需引入，互不依赖：
```html
<div id="bim-container" style="width: 100%; height: 100vh;"></div>
| 类名 | 用途 | 定位 |
|---|---|---|
| `BimEngine` | 3D BIM 模型可视化 | 完整功能（工具栏、测量、剖切、漫游等 UI 组件） |
| `BimEngine2d` | 2D CAD/DWG 图纸查看 | 轻量级，无 UI 管理器 |
| `BimEngine720` | 720° 全景图查看 | 轻量级，无 UI 管理器 |
```typescript
// ESM 按需导入
import { BimEngine } from 'iflow-engine'; // 3D
import { BimEngine2d } from 'iflow-engine'; // 2D
import { BimEngine720 } from 'iflow-engine'; // 720°
// 也可以一次导入全部
import { BimEngine, BimEngine2d, BimEngine720 } from 'iflow-engine';
```
### 2. 初始化引擎
```html
<!-- UMD 方式（原生 HTML） -->
<script src="./lib/iflow-engine.umd.js"></script>
<script>
const { BimEngine, BimEngine2d, BimEngine720 } = IflowEngine;
</script>
```
> **注意**：三个引擎类共用同一个容器时，需先销毁当前实例再创建新实例。详见 [多引擎切换](#多引擎切换)。
---
## 一、3D 引擎（BimEngine）
完整的 BIM 3D 可视化引擎，包含工具栏、测量、剖切、漫游等全部 UI 功能。
### 基本用法
```typescript
import { BimEngine } from 'iflow-engine';
// 创建引擎实例
const engine = new BimEngine('bim-container', {
locale: 'zh-CN', // 语言：'zh-CN' | 'en-US'
theme: 'light' // 主题：'light' | 'dark'
const engine = new BimEngine('container', {
locale: 'zh-CN', // 'zh-CN' | 'en-US'
theme: 'dark' // 'dark' | 'light'
});
```
### 3. 加载模型
```typescript
// 初始化 3D 引擎
engine.engine?.initialize();
// 初始化 3D 渲染引擎
engine.engine?.initialize({
backgroundColor: 0x333333,
showViewCube: true
});
// 加载模型
engine.engine?.loadModel('https://example.com/model.gltf', {
autoFit: true // 自动适配视角
engine.engine?.loadModel(['https://example.com/model/'], {
position: [0, 0, 0],
rotation: [0, 0, 0],
scale: [1, 1, 1]
});
```
## 完整示例
### 构造参数
### Vue 3
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `container` | `HTMLElement \| string` | ✅ | DOM 元素或元素 ID |
| `options.locale` | `'zh-CN' \| 'en-US'` | | 界面语言，默认 `'zh-CN'` |
| `options.theme` | `'dark' \| 'light'` | | 主题，默认 `'dark'` |
### 管理器
BimEngine 构造时自动初始化以下管理器：
```typescript
engine.engine // EngineManager - 3D 引擎（加载模型、控制渲染）
engine.toolbar // ToolbarManager - 底部工具栏
engine.buttonGroup // ButtonGroupManager - 按钮组
engine.dialog // DialogManager - 弹窗管理
engine.rightKey // RightKeyManager - 右键菜单
engine.constructTreeBtn // ConstructTreeManagerBtn - 构件树
engine.measure // MeasureDialogManager - 测量工具
engine.sectionPlane // SectionPlaneDialogManager - 拾取面剖切
engine.sectionAxis // SectionAxisDialogManager - 轴向剖切
engine.sectionBox // SectionBoxDialogManager - 剖切盒
engine.walkControl // WalkControlManager - 漫游控制
engine.componentDetail // ComponentDetailManager - 构件详情
engine.aiChat // AiChatManager - AI 对话
engine.setting // SettingDialogManager - 设置
```
### Vue 3 示例
```vue
<template>
<div ref="containerRef" class="bim-container"></div>
<div ref="containerRef" style="width: 100vw; height: 100vh;" />
</template>
<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { BimEngine } from 'iflow-engine';
const containerRef = ref<HTMLElement | null>(null);
const containerRef = ref<HTMLElement>();
let engine: BimEngine | null = null;
onMounted(() => {
if (containerRef.value) {
engine = new BimEngine(containerRef.value, {
locale: 'zh-CN',
theme: 'light'
});
if (!containerRef.value) return;
// 初始化 3D 引擎
engine.engine?.initialize();
engine = new BimEngine(containerRef.value, {
locale: 'zh-CN',
theme: 'dark'
});
// 加载模型
engine.engine?.loadModel('/models/building.gltf');
}
engine.engine?.initialize({ backgroundColor: 0x333333 });
engine.engine?.loadModel(['https://example.com/model/']);
});
onUnmounted(() => {
engine?.destroy();
engine = null;
});
</script>
<style scoped>
.bim-container {
width: 100%;
height: 100vh;
}
</style>
```
### React
### React 示例
```tsx
import { useRef, useEffect } from 'react';
@@ -104,285 +150,514 @@ import { BimEngine } from 'iflow-engine';
export function BimViewer() {
const containerRef = useRef<HTMLDivElement>(null);
const engineRef = useRef<BimEngine | null>(null);
useEffect(() => {
if (containerRef.current && !engineRef.current) {
engineRef.current = new BimEngine(containerRef.current, {
locale: 'zh-CN',
theme: 'light'
});
if (!containerRef.current) return;
// 初始化 3D 引擎
engineRef.current.engine?.initialize();
const engine = new BimEngine(containerRef.current, {
locale: 'zh-CN',
theme: 'dark'
});
// 加载模型
engineRef.current.engine?.loadModel('/models/building.gltf');
}
engine.engine?.initialize({ backgroundColor: 0x333333 });
engine.engine?.loadModel(['https://example.com/model/']);
return () => {
engineRef.current?.destroy();
engineRef.current = null;
};
return () => engine.destroy();
}, []);
return <div ref={containerRef} style={{ width: '100vw', height: '100vh' }} />;
}
```
---
## 二、2D 图纸引擎（BimEngine2d）
轻量级 2D CAD/DWG 图纸查看引擎，无 UI 管理器，构造时自动初始化。
### 基本用法
```typescript
import { BimEngine2d } from 'iflow-engine';
const engine2d = new BimEngine2d('container', {
locale: 'zh-CN',
theme: 'dark',
backgroundColor: 0xf0f0f0,
gridEnabled: true,
axesEnabled: true
});
// 加载图纸
await engine2d.loadDrawing('https://example.com/drawing-id');
// 销毁
engine2d.destroy();
```
### 构造参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `container` | `HTMLElement \| string` | ✅ | DOM 元素或元素 ID |
| `options.locale` | `'zh-CN' \| 'en-US'` | | 界面语言 |
| `options.theme` | `'dark' \| 'light'` | | 主题 |
| `options.backgroundColor` | `number` | | 背景色，如 `0xffffff` |
| `options.gridEnabled` | `boolean` | | 是否显示网格 |
| `options.axesEnabled` | `boolean` | | 是否显示坐标轴 |
| `options.selectionColor` | `number` | | 选中构件颜色 |
| `options.highlightColor` | `number` | | 高亮构件颜色 |
| `options.enablePerformanceMonitoring` | `boolean` | | 是否启用性能监控 |
### API
```typescript
// 图纸操作
await engine2d.loadDrawing(url, options?) // 加载图纸
engine2d.getLayers() // 获取所有图层 → Drawing2dLayer[]
engine2d.setLayerVisible(name, visible) // 设置图层可见性
// 视图控制
engine2d.resetView() // 重置视图
engine2d.fitToView() // 适应全部内容
engine2d.setZoom(zoom) // 设置缩放级别
engine2d.getZoom() // 获取当前缩放级别
// 主题
engine2d.setTheme('dark' | 'light')
// 事件
const unsub = engine2d.on('event-name', (payload) => { ... })
unsub() // 取消订阅
engine2d.onRawEvent(event, handler) // 底层引擎事件
engine2d.offRawEvent(event, handler)
// 生命周期
engine2d.destroy() // 销毁引擎
```
### Vue 3 示例
```vue
<template>
<div ref="containerRef" style="width: 100%; height: 100vh;" />
</template>
<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { BimEngine2d } from 'iflow-engine';
const containerRef = ref<HTMLElement>();
let engine2d: BimEngine2d | null = null;
onMounted(async () => {
if (!containerRef.value) return;
engine2d = new BimEngine2d(containerRef.value, {
theme: 'light',
gridEnabled: true
});
await engine2d.loadDrawing('https://example.com/drawing-id');
});
onUnmounted(() => {
engine2d?.destroy();
engine2d = null;
});
</script>
```
### React 示例
```tsx
import { useRef, useEffect } from 'react';
import { BimEngine2d } from 'iflow-engine';
export function DrawingViewer() {
const containerRef = useRef<HTMLDivElement>(null);
useEffect(() => {
if (!containerRef.current) return;
const engine2d = new BimEngine2d(containerRef.current, {
theme: 'light',
gridEnabled: true
});
engine2d.loadDrawing('https://example.com/drawing-id');
return () => engine2d.destroy();
}, []);
return <div ref={containerRef} style={{ width: '100%', height: '100vh' }} />;
}
```
### 原生 HTML
---
## 三、720° 全景引擎（BimEngine720）
轻量级 720° 全景图查看引擎，支持鼠标/触摸旋转和缩放，构造时自动初始化。
### 基本用法
```typescript
import { BimEngine720 } from 'iflow-engine';
const engine720 = new BimEngine720('container', {
fov: 75,
enableZoom: true,
enableRotate: true,
sphereRadius: 500
});
// 加载全景图
await engine720.loadPanorama('https://example.com/panorama.png');
// 销毁
engine720.destroy();
```
### 构造参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `container` | `HTMLElement \| string` | ✅ | DOM 元素或元素 ID |
| `options.locale` | `'zh-CN' \| 'en-US'` | | 界面语言 |
| `options.theme` | `'dark' \| 'light'` | | 主题 |
| `options.fov` | `number` | | 视场角，默认 `75` |
| `options.enableZoom` | `boolean` | | 是否启用缩放，默认 `true` |
| `options.enableRotate` | `boolean` | | 是否启用旋转，默认 `true` |
| `options.sphereRadius` | `number` | | 球体半径，默认 `500` |
| `options.rotateSpeed` | `number` | | 旋转速度 |
| `options.zoomSpeed` | `number` | | 缩放速度 |
| `options.enableDamping` | `boolean` | | 是否启用阻尼（惯性效果） |
| `options.dampingFactor` | `number` | | 阻尼因子 |
| `options.minFov` | `number` | | 最小视场角 |
| `options.maxFov` | `number` | | 最大视场角 |
### API
```typescript
// 全景操作
await engine720.loadPanorama(url, options?) // 加载全景图
await engine720.preloadPanoramas(urls) // 预加载多个全景图
// 视角控制
engine720.setFov(fov) // 设置视场角
engine720.getFov() // 获取当前视场角
engine720.lookAt(phi, theta, animated?) // 设置相机朝向
engine720.resetView() // 重置视图
// 主题
engine720.setTheme('dark' | 'light')
// 事件
const unsub = engine720.on('event-name', (payload) => { ... })
unsub() // 取消订阅
engine720.onRawEvent(event, handler) // 底层引擎事件
engine720.offRawEvent(event, handler)
// 生命周期
engine720.destroy() // 销毁引擎
```
### Vue 3 示例
```vue
<template>
<div ref="containerRef" style="width: 100%; height: 100vh;" />
</template>
<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { BimEngine720 } from 'iflow-engine';
const containerRef = ref<HTMLElement>();
let engine720: BimEngine720 | null = null;
onMounted(async () => {
if (!containerRef.value) return;
engine720 = new BimEngine720(containerRef.value, {
fov: 75,
enableZoom: true,
enableRotate: true,
sphereRadius: 500
});
await engine720.loadPanorama('https://example.com/panorama.png');
});
onUnmounted(() => {
engine720?.destroy();
engine720 = null;
});
</script>
```
### React 示例
```tsx
import { useRef, useEffect } from 'react';
import { BimEngine720 } from 'iflow-engine';
export function PanoramaViewer() {
const containerRef = useRef<HTMLDivElement>(null);
useEffect(() => {
if (!containerRef.current) return;
const engine720 = new BimEngine720(containerRef.current, {
fov: 75,
enableZoom: true,
enableRotate: true,
sphereRadius: 500
});
engine720.loadPanorama('https://example.com/panorama.png');
return () => engine720.destroy();
}, []);
return <div ref={containerRef} style={{ width: '100%', height: '100vh' }} />;
}
```
---
## 多引擎切换
三个引擎类可以共用同一个容器，但同一时刻只能有一个实例。切换时需先销毁当前实例：
```typescript
import { BimEngine, BimEngine2d, BimEngine720 } from 'iflow-engine';
let current: BimEngine | BimEngine2d | BimEngine720 | null = null;
function destroyCurrent() {
current?.destroy();
current = null;
}
// 切换到 3D
function switchTo3D() {
destroyCurrent();
const engine = new BimEngine('container', { theme: 'dark' });
engine.engine?.initialize({ backgroundColor: 0x333333 });
engine.engine?.loadModel(['https://example.com/model/']);
current = engine;
}
// 切换到 2D
function switchTo2D() {
destroyCurrent();
const engine2d = new BimEngine2d('container', { theme: 'dark' });
engine2d.loadDrawing('https://example.com/drawing-id');
current = engine2d;
}
// 切换到 720°
function switchTo720() {
destroyCurrent();
const engine720 = new BimEngine720('container', {
fov: 75,
enableZoom: true,
enableRotate: true,
sphereRadius: 500
});
engine720.loadPanorama('https://example.com/panorama.png');
current = engine720;
}
```
---
## 原生 HTML 完整示例
```html
<!DOCTYPE html>
<html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>iflow-engine Demo</title>
<style>
#bim-container {
width: 100%;
height: 100vh;
}
body { margin: 0; font-family: sans-serif; }
#container { width: 100vw; height: 100vh; }
.btn-group { position: fixed; top: 10px; left: 10px; z-index: 100; }
.btn-group button { padding: 8px 16px; margin-right: 8px; cursor: pointer; }
</style>
</head>
<body>
<div id="bim-container"></div>
<div class="btn-group">
<button onclick="switchTo3D()">3D 引擎</button>
<button onclick="switchTo2D()">2D 图纸</button>
<button onclick="switchTo720()">720° 全景</button>
</div>
<div id="container"></div>
<script type="module">
import { BimEngine } from './lib/iflow-engine.es.js';
<script src="./lib/iflow-engine.umd.js"></script>
<script>
var BimEngine = IflowEngine.BimEngine;
var BimEngine2d = IflowEngine.BimEngine2d;
var BimEngine720 = IflowEngine.BimEngine720;
const engine = new BimEngine('bim-container', {
locale: 'zh-CN',
theme: 'light'
});
var current = null;
// 初始化 3D 引擎
engine.engine?.initialize();
function destroyCurrent() {
if (current) { current.destroy(); current = null; }
}
// 加载模型
engine.engine?.loadModel('./models/building.gltf');
function switchTo3D() {
destroyCurrent();
var engine = new BimEngine('container', { locale: 'zh-CN', theme: 'dark' });
engine.engine.initialize({ backgroundColor: 0x333333, showViewCube: true });
engine.engine.loadModel(['https://example.com/model/']);
current = engine;
}
function switchTo2D() {
destroyCurrent();
var engine2d = new BimEngine2d('container', { theme: 'dark', gridEnabled: true });
engine2d.loadDrawing('https://example.com/drawing-id');
current = engine2d;
}
function switchTo720() {
destroyCurrent();
var engine720 = new BimEngine720('container', {
fov: 75, enableZoom: true, enableRotate: true, sphereRadius: 500
});
engine720.loadPanorama('https://example.com/panorama.png');
current = engine720;
}
// 默认加载 3D
switchTo3D();
</script>
</body>
</html>
```
## 主题切换
```typescript
// 切换到暗色主题
engine.setTheme('dark');
// 切换到亮色主题
engine.setTheme('light');
// 自定义主题
engine.setCustomTheme({
name: 'custom',
primary: '#ff6b6b',
primaryHover: '#ff5252',
primaryActive: '#ff4757',
// ... 其他属性
});
```
## 语言切换
```typescript
// 切换到英文
engine.setLocale('en-US');
// 切换到中文
engine.setLocale('zh-CN');
```
## 工具栏操作
```typescript
// 显示/隐藏工具栏
engine.toolbar?.show();
engine.toolbar?.hide();
// 添加自定义按钮
engine.toolbar?.addButton({
id: 'custom-btn',
type: 'button',
label: '自定义',
icon: '<svg>...</svg>',
onClick: () => {
console.log('Custom button clicked');
}
});
// 设置按钮激活状态
engine.toolbar?.setBtnActive('measure', true);
```
## 测量功能
```typescript
// 显示测量面板
engine.measure?.show();
// 切换测量模式
engine.measure?.switchMode('distance'); // 距离
engine.measure?.switchMode('angle'); // 角度
engine.measure?.switchMode('volume'); // 体积
engine.measure?.switchMode('elevation'); // 标高
engine.measure?.switchMode('slope'); // 坡度
// 获取测量配置
const config = engine.measure?.getConfig();
console.log(config); // { unit: 'mm', precision: 2 }
// 设置测量配置
engine.measure?.setConfig({ unit: 'cm', precision: 1 });
// 清除所有测量结果
engine.measure?.clearAll();
```
## 剖切功能
### 平面剖切
```typescript
// 显示剖切面板
engine.sectionPlane?.show();
// 隐藏剖切面板
engine.sectionPlane?.hide();
```
### 轴向剖切
```typescript
// 显示轴向剖切
engine.sectionAxis?.show();
// 设置剖切轴向
engine.sectionAxis?.setActiveAxis('x'); // X 轴
engine.sectionAxis?.setActiveAxis('y'); // Y 轴
engine.sectionAxis?.setActiveAxis('z'); // Z 轴
```
### 剖切盒
```typescript
// 显示剖切盒
engine.sectionBox?.show();
// 获取剖切范围
const range = engine.sectionBox?.getRange();
console.log(range); // { minX, maxX, minY, maxY, minZ, maxZ }
// 设置剖切范围
engine.sectionBox?.setRange({ minX: 0, maxX: 100 });
// 反向剖切
engine.sectionBox?.setReversedState(true);
```
## 漫游功能
```typescript
// 显示漫游控制面板
engine.walkControl?.show();
// 隐藏漫游控制面板
engine.walkControl?.hide();
```
## 事件监听
```typescript
// 监听模型加载完成
const unsubscribe = engine.on('engine:model-loaded', (payload) => {
console.log('Model loaded:', payload.url);
});
// 监听对象点击
engine.on('engine:object-clicked', (payload) => {
console.log('Object clicked:', payload.objectId, payload.position);
});
// 监听主题变更
engine.on('sys:theme-changed', (payload) => {
console.log('Theme changed:', payload.theme);
});
// 取消监听
unsubscribe();
```
## 销毁引擎
```typescript
// 在组件卸载或页面关闭时销毁
engine.destroy();
```
---
## TypeScript 类型
SDK 提供完整的 TypeScript 类型支持：
SDK 导出所有相关类型，开箱即用：
```typescript
import type {
// 主入口
BimEngine,
// 配置类型
// 3D 引擎
EngineOptions,
ModelLoadOptions,
// 2D 引擎
Engine2dOptions,
DrawingLoadOptions,
Drawing2dLayer,
// 720 引擎
Engine720Options,
PanoramaLoadOptions,
PanoramaAnnotation,
// 通用
ThemeConfig,
ThemeType,
EngineEvents,
// UI 组件（仅 BimEngine 3D 使用）
DialogOptions,
DialogPosition,
ButtonConfig,
ButtonGroupOptions,
TreeOptions,
TreeNodeConfig,
TreeNodeCheckState,
CollapseOptions,
CollapseItemConfig,
DescriptionOptions,
DescriptionItem,
// 主题类型
ThemeConfig,
ThemeType,
// 事件类型
EngineEvents,
} from 'iflow-engine';
```
## 常见问题
---
### 1. 模型加载失败
## 主题与语言
- 检查模型 URL 是否正确
- 确保模型格式受支持（GLTF/GLB/IFC）
- 检查 CORS 配置
三个引擎类均支持主题切换和语言设置：
### 2. 工具栏不显示
```typescript
// 构造时设置
const engine = new BimEngine('container', { theme: 'dark', locale: 'zh-CN' });
const engine2d = new BimEngine2d('container', { theme: 'light' });
const engine720 = new BimEngine720('container', { theme: 'dark' });
- 确保容器有足够的尺寸
- 检查是否调用了 `engine.initialize()`
// 运行时切换主题
engine.setTheme('light');
engine2d.setTheme('dark');
engine720.setTheme('light');
### 3. 主题不生效
// 运行时切换语言（仅 3D 引擎支持）
engine.setLocale('en-US');
- 确保在引擎初始化后再设置主题
- 检查自定义主题配置是否完整
### 4. 内存泄漏
- 确保在组件卸载时调用 `engine.destroy()`
- 取消不再需要的事件监听
## 下一步
- 查看 [架构文档](架构设计.md) 了解设计原理
- 查看 [模块文档](MODULES/模块索引.md) 了解详细 API
- 查看 [demo](../demo/) 获取更多示例
// 自定义主题（仅 3D 引擎支持）
engine.setCustomTheme({
name: 'custom',
primary: '#1890ff',
primaryHover: '#40a9ff',
// ...
});
```
---
**文档生成时间**: 2026-01-23
**文档版本**: 1.0.0
## 常见问题
### 1. 如何只引入需要的引擎？
直接按需 import，构建工具会自动 tree-shaking 未使用的代码：
```typescript
// 只用 2D，不会打包 3D 和 720 的代码
import { BimEngine2d } from 'iflow-engine';
```
### 2. 多个引擎能同时存在吗？
可以，但需要**不同的容器**。同一个容器同时只能挂载一个引擎实例：
```typescript
const engine3d = new BimEngine('container-3d', { theme: 'dark' });
const engine2d = new BimEngine2d('container-2d', { theme: 'dark' });
const engine720 = new BimEngine720('container-720', { theme: 'dark' });
```
### 3. 切换引擎时页面闪烁
确保先调用 `destroy()` 再创建新实例。`destroy()` 会清空容器内容。
### 4. 模型/图纸加载失败
- 检查 URL 是否可访问
- 检查浏览器控制台是否有 CORS 错误
- 确保使用 HTTP 服务器运行（不能直接打开 HTML 文件）
### 5. 页面关闭时如何释放资源？
务必调用 `destroy()` 释放 WebGL 上下文和事件监听：
```typescript
window.addEventListener('beforeunload', () => {
engine?.destroy();
});
```
---
## 下一步
- [架构设计](架构设计.md) — 了解 Manager 模式和分层架构
- [引擎 API 对接](引擎API对接.md) — 底层引擎 API 详细说明
- [API 调用链](API调用链.md) — 调用关系与数据流
- [demo/](../demo/) — 完整可运行示例
---
**文档版本**: 2.0.0 | **更新日期**: 2026-03-10