主引擎 API 文档

1 概述

1.1 产品简介

MinBIM® BIM轻量化引擎是一款基于 WebGL 技术的 BIM 模型轻量化可视化引擎，支持多格式建筑模型加载、渲染、交互、测量、属性查看及导出，可嵌入 Web 系统，实现 BIM 数据的三维展示与交互。

主要特性：

• 支持 IFC、RVT、SKP、FBX、NWD、3DM、RVM、GLTF/GLB、OBJ 等多种源格式的轻量化转换与展示；
• 保持 BIM 几何、材质、属性与结构树数据；
• 支持多模型加载、实例化渲染、BVH 射线加速与按需渲染；
• 内置拾取、测量、剖切、拆解、截图和导出功能；
• 提供独立特效库与 GIS 扩展，可按需引入；
• 提供 UMD 与 ES Module 产物，便于二次开发与系统集成。

1.2 适读对象

• 二次开发工程师；
• Web 前端开发人员；
• BIM 平台系统集成商；
• 技术支持与测试工程师。

1.3 技术要求

1.4 运行环境

前端： HTML5 + JavaScript + WebGL 2.0 + Web Worker。

后端： 转换模块负责将源模型转换为 MinBIM 轻量化数据。

浏览器： 推荐使用最新版 Chrome 或 Edge；Firefox 需满足同等 WebGL 2.0 与 Worker 能力。

显卡： 推荐支持 WebGL 2.0 的独立显卡。

1.5 系统架构

• 前端渲染层（MinBIM Viewer）：负责模型展示与交互。
• 后端转换层（MinBIM Converter）：执行模型格式转换。
• 数据层（BIM Files Storage）：存储源文件与转换后的轻量化数据。
• 扩展层（MinBIMEffects / MinBIMGIS）：按需提供场景特效、地理图层与分析能力。

公开全局对象及产物：

对应 ES Module 产物为 dist/minbim.module.min.js、dist/minbim-effect.module.min.js、dist/minbim-gis.module.min.js。扩展包的 UMD 版本必须在主包之后加载。

独立接口文档：MinBIM 特效库接口文档（v1.0）、MinBIM GIS 扩展接口文档（v1.0）。

1.6 快速上手

<link rel="stylesheet" href="public/css/style.css">
<link rel="stylesheet" href="public/css/main.css">
<div id="viewer" style="width:100%;height:100vh"></div>

<script src="dist/minbim.min.js"></script>
<script>
const viewer = new MinBIM.Viewer('viewer');
viewer.init({
    config: { assetsDir: 'public' }
});

const loader = new MinBIM.Loader(viewer);
loader.load('model/example')
    .then((model) => viewer.focus(model))
    .catch((error) => console.error('模型加载失败：', error));
</script>

basePath 指向包含 manifest.mb 及关联数据文件的目录，不需要在末尾写 manifest.mb。

2 后端服务接口

示例：

main.exe D:\input.ifc D:\output\
check.exe D:\output\

3 核心类接口

主包公开出口：

MinBIM.VERSION  // '1.5.1'
MinBIM.Viewer
MinBIM.Loader
MinBIM.Exporter
MinBIM.Tool
MinBIM.Widget
MinBIM.THREE    // Three.js 命名空间
MinBIM.TWEEN    // 补间动画命名空间

3.1 Viewer 视窗类

3.1.1 属性（Properties）

3.1.2 方法（Methods）

3.1.2.1 constructor(containerId)

功能说明： 构建 Viewer 实例。容器必须已存在。

参数说明：

返回结果： Viewer

const viewer = new MinBIM.Viewer('viewer');

3.1.2.2 init(options)

功能说明： 初始化场景、相机、渲染管线、控制器和挂件。

参数说明：

viewCube 配置：

toolbar 配置：

tree 配置：

dynamicCenter 配置：

config 配置：

返回结果： void

viewer.init({
    quality: true,
    ground: true,
    tree: false,
    dynamicCenter: { icon: 'public/images/center.png' },
    config: { assetsDir: 'public' }
});

3.1.2.3 focus(object, cb, ratio)

功能说明： 平滑聚焦指定 Three.js 对象。

返回结果： void

viewer.focus(viewer.models, () => console.log('聚焦完成'));

3.1.2.4 getView()

功能说明： 获取当前相机位置和控制目标点。

返回结果： { position: {x,y,z}, target: {x,y,z} }

const view = viewer.getView();

3.1.2.5 restoreView(view, duration, cb)

功能说明： 从当前视角平滑过渡到指定视角。

返回结果： Tween；可调用 stop() 打断，打断时不执行完成回调。

const tween = viewer.restoreView(viewer.getView(), 1000);
// tween.stop();

3.1.2.6 setCamera(isOrthCamera)

功能说明： 在透视投影与正交投影相机之间切换，并保持当前构图。

返回结果： void

viewer.setCamera(true);

3.1.2.7 setQuality(enabled)

功能说明： 开关 SAO 质量效果；仅在 init({ quality:true }) 创建的质量管线中生效。

返回结果： void

3.1.2.8 getQuality()

功能说明： 获取当前 SAO 开关状态；非质量模式返回 false。

返回结果： Boolean

viewer.setQuality(false);
console.log(viewer.getQuality()); // false

3.1.2.9 dispose()

功能说明： 销毁 Viewer，释放模型、扩展、渲染资源及事件监听。

返回结果： void

viewer.dispose();

3.2 Loader 加载器类

3.2.1 属性（Properties）

无独立配置属性；加载回调由构造函数设置。

3.2.2 方法（Methods）

3.2.2.1 constructor(viewer, showLoading, onProgress, onComplete, onError)

功能说明： 构建 Loader 实例。

返回结果： Loader

const loader = new MinBIM.Loader(
    viewer,
    true,
    (progress) => console.log(progress),
    () => console.log('加载完成'),
    (error) => console.error(error)
);

3.2.2.2 load(basePath, ghost, options)

功能说明： 异步加载一个模型批次的清单、材质、几何、属性和节点数据。

options.resolveUrl(url, kind, refresh)：

钩子可返回 String 或 Promise<String>；返回空值时使用原 URL。清单、材质、几何、属性和节点请求在 401/403 时会以 refresh=true 重签并重试一次。贴图 URL 也经过该钩子；跨域 CDN 需配置 CORS。

返回结果： Promise<Group>，解析为本次加载的独立批次组。viewer.models 是多模型累计根，返回组可整体落位或移除：

const model = await loader.load('model/example');
model.position.set(10, 0, 0);
viewer.focus(model);
viewer.renderRequested = true;

// 需要时移除本批次：model.removeFromParent(); viewer.renderRequested = true;

CDN 签名示例：

const model = await loader.load('https://cdn.example.com/bim/project', false, {
    resolveUrl: async (url, kind, refresh) => {
        const response = await fetch(`/api/sign?url=${encodeURIComponent(url)}&refresh=${refresh}`);
        const { signedUrl } = await response.json();
        return signedUrl;
    }
});

多模型可分别保存返回的 Group。getFileInfo()、getNode()、getProperty() 基于全局数据存储，多次加载时以最近写入的数据为准。

3.2.2.3 getFileInfo()

功能说明： 获取当前模型文件信息。

返回结果： Object

3.2.2.4 getNode()

功能说明： 获取模型节点树；非 BIM 类模型可能没有节点数据。

返回结果： Array<Object>，节点常用字段为 id、guid、name、children。

3.2.2.5 getProperty(id)

功能说明： 获取指定构件属性，或不传参数获取当前属性数据。

返回结果： 传入 id 时返回对应属性对象（未找到为 undefined）；不传时返回 Array<Object>。

const allProperties = loader.getProperty();
const property = loader.getProperty('0eaC0nL3XAOfFxRXK_2iAr');

3.3 Picker 拾取器类

Viewer.init() 自动创建拾取器，通过 viewer.picker 使用。

3.3.1 属性（Properties）

3.3.2 方法（Methods）

3.3.2.1 enable() / disable()

功能说明： 启用或禁用鼠标拾取。重复调用时应避免无意义地重复注册监听。

返回结果： void

viewer.picker.disable();
viewer.picker.enable();

3.3.2.2 setSelected(ids, crossMaterial)

功能说明： 手动选中构件并聚焦高亮对象。

返回结果： void

viewer.picker.setSelected(['0eaC0nL3XAOfFxRXK_2iAr']);

3.3.2.3 clearSelection()

功能说明： 清除高亮及选中状态。

返回结果： void

3.3.2.4 dispose()

功能说明： 禁用拾取并清除高亮；通常由 viewer.dispose() 统一调用。

返回结果： void

3.3.3 事件（Events）

viewer.picker.addEventListener('selected', (event) => {
    console.log('选中构件：', event.id);
});
viewer.picker.addEventListener('unselected', () => {
    console.log('未拾取到构件');
});

3.4 Exporter 导出器类

3.4.1 属性（Properties）

无公开属性。

3.4.2 方法（Methods）

3.4.2.1 export(type, input, options)

功能说明： 将 Scene、Group 或其他 Object3D 导出为 glTF/GLB。

options：

返回结果： Promise<String>，解析为含扩展名的实际文件名。

const exporter = new MinBIM.Exporter();
const filename = await exporter.export('glb', viewer.models, {
    filename: 'Download',
    autoDownload: true
});

3.4.2.2 screenshot(viewer, type, filename)

功能说明： 导出当前三维场景截图并自动下载。

返回结果： String，返回传入的文件名。

exporter.screenshot(viewer, 'jpg', 'Download');

4 工具类接口

4.1 Measure 测量工具类

4.1.1 属性（Properties）

4.1.2 方法（Methods）

4.1.2.1 constructor(viewer)

const measure = new MinBIM.Tool.Measure(viewer);

4.1.2.2 init(options)

功能说明： 初始化测量面板与射线拾取。

当前内置面板创建后会将 unit0/unit 置为 'm'、precision 置为 2、measureMode 置为 'distance'。需要代码指定状态时，请在 init() 后设置 measure.settings 或 measure.measureMode。

返回结果： void

measure.init();
measure.measureMode = 'distance';
measure.settings.precision = 2;

4.1.2.3 open()

功能说明： 启动测量，暂时禁用默认 Picker。

返回结果： void

measure.open();

4.1.2.4 close()

功能说明： 关闭测量并清除测量标注，恢复默认 Picker。

返回结果： void

4.1.2.5 destroy()

功能说明： 关闭并销毁工具实例。

返回结果： void

4.2 Clipping 剖切工具类

4.2.1 属性（Properties）

4.2.2 方法（Methods）

4.2.2.1 constructor(viewer)

const clipping = new MinBIM.Tool.Clipping(viewer);

4.2.2.2 init(options)

返回结果： void

clipping.init({ sliderMin: 0, sliderMax: 100, sliderStep: 1 });

4.2.2.3 open()

功能说明： 创建剖切盒并启用模型剖切。

返回结果： void

4.2.2.4 close()

功能说明： 清除剖切辅助对象并还原模型材质。

返回结果： void

4.2.2.5 destroy()

功能说明： 关闭并销毁工具实例。

返回结果： void

4.3 Explode 拆解工具类

4.3.1 属性（Properties）

4.3.2 方法（Methods）

4.3.2.1 constructor(viewer)

const explode = new MinBIM.Tool.Explode(viewer);

4.3.2.2 init()

功能说明： 初始化拆解工具并缓存模型原始位置。当前不接收参数。

返回结果： void

explode.init();

4.3.2.3 open()

功能说明： 打开拆解工具，倍率重置为 1.0。

返回结果： void

4.3.2.4 close()

功能说明： 关闭工具并还原模型和实例矩阵。

返回结果： void

4.3.2.5 destroy()

功能说明： 关闭并销毁工具实例。

返回结果： void

4.4 Visibility 构件显隐工具类

4.4.1 属性（Properties）

4.4.2 方法（Methods）

4.4.2.1 constructor(viewer)

const visibility = new MinBIM.Tool.Visibility(viewer);

4.4.2.2 show(guids)

功能说明： 显示指定构件；对 ghost 批次表示将指定构件实体化。

返回结果： void

4.4.2.3 showAll()

功能说明： 清除全部隐藏、半透明和实体化状态；ghost 批次回到全 ghost 状态。

返回结果： void

4.4.2.4 hide(guids)

功能说明： 隐藏指定构件。

返回结果： void

4.4.2.5 setTransparent(guids, opacity)

功能说明： 将指定构件设为半透明。

返回结果： void

visibility.hide(['guid-a']);
visibility.setTransparent(['guid-b'], 0.35);
visibility.show(['guid-a', 'guid-b']);

4.5 Settings 场景设置类

4.5.1 属性（Properties）

无独立公开配置属性。

4.5.2 方法（Methods）

4.5.2.1 constructor(viewer) / init()

功能说明： 构建设置工具；init() 创建内置设置面板。调用独立场景设置方法前应完成 viewer.init()。

const settings = new MinBIM.Tool.Settings(viewer);
settings.init(); // 需要使用 settings.domElement 时调用

4.5.2.2 skybox(name)

功能说明： 设置天空盒。

返回结果： void

4.5.2.3 camera(type)

功能说明： 设置相机投影类型。

返回结果： void

4.5.2.4 axes(show)

功能说明： 显示或隐藏辅助坐标轴。

返回结果： void

4.5.2.5 up(type)

功能说明： 设置模型向上轴向并重新聚焦。

返回结果： void

多模型场景优先使用各模型 manifest.mb 中的 up 信息；该方法操作的是 viewer.models 总根。

4.5.2.6 edge(show)

功能说明： 显示或隐藏模型构件边线；首次开启时按需创建边线几何。

返回结果： void

4.5.2.7 quality(high)

功能说明： 设置高质量（SAO）或性能优先模式，等价于 viewer.setQuality(high)。

返回结果： void

settings.skybox('day');
settings.camera('orthographic');
settings.axes(true);
settings.edge(true);
settings.quality(false);

4.6 mainview(viewer) 回默认主视角

功能说明： 以 viewer.models 为目标调用 focus()。

返回结果： void

MinBIM.Tool.mainview(viewer);

4.7 fullscreen(on, viewer) 全屏显示控制

返回结果： void

MinBIM.Tool.fullscreen(true, viewer);
MinBIM.Tool.fullscreen(false);

5 组件类接口

5.1 Modal 模态框类

5.1.1 属性（Properties）

5.1.2 方法（Methods）

5.1.2.1 constructor(options)

返回结果： Modal

const modal = new MinBIM.Widget.Modal({
    container: viewer.container,
    title: '标题',
    content: '内容',
    onToggle: (visible) => console.log(visible)
});

5.1.2.2 show()

显示模态框并触发 onToggle(true)。

5.1.2.3 close()

隐藏模态框并触发 onToggle(false)。

5.1.2.4 toggle()

切换显示状态。

5.1.2.5 updateContent(content)

5.1.2.6 destroy()

关闭模态框、移除 DOM 并释放引用。

以上方法均返回 void。

modal.show();
modal.updateContent('<p>新内容</p>');
modal.toggle();
modal.destroy();

6 版本历史

v1.5.1（2026年10月18日）

• 支持多模型独立批次加载，Loader.load() 返回本批次 Group。
• 增加 CDN 签名 URL 钩子与 401/403 重签重试。
• restoreView() 返回可打断的 Tween。
• 增加动态旋转中心与构件半透明等能力。
• 修正旧文档中工具启停方法、公开组件和默认值等不一致内容。

v1.4.1（2026年9月10日）

• 添加非叶子节点的等选功能。
• Visibility 显隐参数由 uuid 调整为 guid。
• 修复层级树选择与构件属性同步问题。

v1.4.0（2026年7月14日）

• 升级轻量化数据加载支持。
• 将 toggleGraphics 调整为 setQuality() / getQuality()。
• 场景交互期间暂时关闭 SAO。

v1.3.4（2026年5月23日）

• 优化 SAO 和地面伪阴影。
• 数据加载由同步改为异步。

v1.3.3（2026年2月3日）

• 修复实例对象独立 ID 问题。
• 完善测距 XYZ 轴向值显示。
• 应用 BVH 加速射线检测。

v1.3.2（2025年12月26日）

• 修复法向量自动计算中的硬边问题。
• 支持多构件同时选中。
• 增强场景视觉效果。

v1.3.1（2025年12月12日）

• 修复双击卡顿和爆炸错位问题。

v1.3.0（2025年11月6日）

• 修复渲染异常、节点重复加载和交互失效问题。
• 开放 Viewer、Loader、Picker、Exporter 及工具类 API。
• 完成接口文档标准化。

v1.2.1（2025年10月10日）

• 修复已知问题与部分纹理 UV 问题。
• 优化导出提示与错误处理。

v1.2.0（2025年8月10日）

• 引入面数减化、实例化渲染、节点合并与索引压缩。
• 优化模型分块解析和加载缓存。
• 集成自动转换及结果检查流程。

v1.1.3（2025年6月15日）

• 新增拾取事件监听。
• 完善模型层级树与节点定位。

v1.1.2（2025年6月2日）

• 支持透视与正交视图切换。
• 新增模型层级树与节点定位。
• 优化复杂场景性能。

v1.1.0（2025年5月7日）

• 增加 property、node 数据。
• 引入自定义 .mb 数据格式。
• 优化分段解析、异步调度与光照自适应。

v1.0.5（2025年4月15日）

• 新增工具栏、测量、剖切、拆解与场景设置。
• 优化聚焦计算与界面交互。
• 添加模型底部地面组件。

v1.0.3（2025年3月15日）

• 发布首个公开版本，完成核心渲染、相机、光照与初版 API 架构。

7 版权声明

本文档及其中内容为 魔兜（济南）数字科技有限公司 所有，公开用于产品评估及授权项目开发，未经许可不得转载或用于其他商业用途。