LTplus-AG/ifc-lite · 上手攻略

  • 仓库：LTplus-AG/ifc-lite
  • 链接：https://github.com/LTplus-AG/ifc-lite
  • 分类：engineering / BIM（IFC 工具链）
  • 作者：spark
  • 更新：2026-10-17

三证 checklist - [x] GitHub URL 已 fetch（README 直接读取，2026-10-17） - [ ] 顶会 venue+年份：仓库 README 全部以产品/官网 ifclite.com、ifclite.dev、npm/crates 包为锚点，没有挂任何学术 venue（IFC 是 ISO 16739 工业标准，本文为开源工具链攻略，无 arXiv 引用） - [x] README 子模块 anchor：Get Started / Parse / View / Query / Validate / Edit / Export / CLI / Choose your setup / Performance / Examples 均已 fetch - 注：卡片标 MPL-2.0，与 LICENSE 标注一致；版本以 npm @ifc-lite/parser 与 crates ifc-lite-core 当前 badge 为准（版本号浮动 ⚠️，具体版本请以发布页查实时）

是什么

IFClite 是一个"客户端优先"的 IFC（Industry Foundation Classes，ISO 16739）开源工具链：

  • Rust 核心（ifc-lite-core crate）做 STEP 解析与几何，编译成 WASM；
  • WebGPU 渲染器前端实时展示（@ifc-lite/renderer）；
  • TypeScript SDK（@ifc-lite/sdk）按模块拆分 30+ npm 包，按需取用；
  • CLI（ifc-lite）覆盖 inspect / query / schedule / validate / export / create / diff / clash-check / merge / convert / script；
  • MCP server（ifc-lite mcp）让 LLM agent 直接查询 / 编辑 BIM 数据。

支持 IFC2X3、IFC4、IFC4X3、IFC5（IFCX）。几何用"精确算术 CSG 内核"逐 element 与 IfcOpenShell 对齐，benchmark corpus 上 99.9%+ 一致。

解决什么问题

BIM（建筑信息模型）从业者面对的标准痛点：

  • IFC 工具链生态分裂：解析器、几何内核、查看器、校验器、导出器散落在 IfcOpenShell、BIMserver、web-ifc 等不同仓库，集成成本高；
  • 服务端依赖：大多数 BIM 工具要上传文件到 server，移动 / 离线场景没法用；
  • 几何不精确：布尔运算浮点误差累积 → 开口、孔洞与 IfcOpenShell 不一致；
  • AI / agent 接入门槛：让 LLM 操作 BIM 数据要写大量胶水。

IFClite 直接给一套 客户端优先 + 精确几何 + 全栈 SDK + MCP 的答案：浏览器里看大模型、CLI 里跑批处理、给 agent 一个 stdio server。

快速安装

按使用场景三条路：

1. 数据自动化（headless SDK 或 CLI）

npm install @ifc-lite/sdk

# 或只要 CLI
npm install -g @ifc-lite/cli
ifc-lite info model.ifc

最简读取 + 查询：

import { readFile } from 'node:fs/promises';
import { openModel } from '@ifc-lite/sdk/headless';

const model = await openModel(await readFile('model.ifc'));
try {
  if (model.report.completeness !== 'complete') {
    throw new Error('Incomplete or unknown record coverage');
  }
  console.log(model.bim.query().byType('IfcDoor').count());
} finally {
  model.close();
}

终端一行：npx @ifc-lite/cli info model.ifc --json。

2. 渲染集成（脚手架）

npx create-ifc-lite my-viewer --template react
cd my-viewer && npm install && npm run dev

模板可选 basic、threejs、babylonjs、server、server-native。得到的是带拖放加载、轨道 / 平移 / 缩放的 WebGPU IFC 查看器。

3. 在已有项目里追加 IFC 能力

npm install @ifc-lite/parser @ifc-lite/geometry @ifc-lite/renderer

其它按需：@ifc-lite/query、@ifc-lite/mutations、@ifc-lite/ids、@ifc-lite/export、@ifc-lite/clash、@ifc-lite/diff、@ifc-lite/bcf、@ifc-lite/lens、@ifc-lite/lists、@ifc-lite/sdk、@ifc-lite/mcp（完整清单见 README "Pick your packages" 表）。

4. 开发 / 贡献（WASM 重编）

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install wasm-pack    # 或 curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

git clone https://github.com/LTplus-AG/ifc-lite.git
cd ifc-lite
pnpm install && pnpm build && pnpm dev     # 起查看器 localhost:3000

pnpm fixtures        # 下 IFC 测试模型（hash 校验，幂等）
pnpm fixtures:check  # CI 友好：缺/过期即 exit 1

rust-toolchain.toml 锁定 nightly 通道 + wasm32-unknown-unknown 目标。

核心用法

1. 解析 IFC

import { IfcParser } from '@ifc-lite/parser';

const parser = new IfcParser();
const buffer = await fetch('model.ifc').then(r => r.arrayBuffer());
const t0 = performance.now();
const store = await parser.parseColumnar(buffer, {
  onProgress: ({ phase, percent }) => console.log(`${phase}: ${percent}%`),
});

console.log(`${store.entityCount} entities, schema ${store.schemaVersion}`);
console.log(`Parsed in ${(performance.now() - t0).toFixed(0)}ms`);

2. 3D 渲染

import { IfcParser } from '@ifc-lite/parser';
import { GeometryProcessor } from '@ifc-lite/geometry';
import { Renderer } from '@ifc-lite/renderer';

const parser = new IfcParser();
const geometry = new GeometryProcessor();
const renderer = new Renderer(canvas);

await Promise.all([geometry.init(), renderer.init()]);

const arrayBuffer = await file.arrayBuffer();
const store = await parser.parseColumnar(arrayBuffer);
const meshes = [];
for await (const event of geometry.processAdaptive(new Uint8Array(arrayBuffer))) {
  if (event.type === 'batch') meshes.push(...event.meshes);
}
renderer.loadGeometry(meshes);
renderer.requestRender();

// 在 canvas 像素坐标 (x, y) 上做命中拾取
const hit = await renderer.pick(120, 240);
if (hit) console.log(`Picked expressId ${hit.expressId}`);

Three.js / Babylon.js 走同一套 parser + geometry，把 meshes 喂给你的引擎即可。

3. 查询

import { IfcQuery } from '@ifc-lite/query';

const query = new IfcQuery(store);

const walls = query
  .ofType('IfcWall', 'IfcWallStandardCase')
  .whereProperty('Pset_WallCommon', 'IsExternal', '=', true)
  .whereProperty('Pset_WallCommon', 'LoadBearing', '=', true)
  .execute();

for (const wall of walls) {
  console.log(wall.name, wall.globalId);
}

// 复杂查询走 SQL（DuckDB-WASM）
const result = await query.sql(`
  SELECT type, COUNT(*) AS n FROM entities GROUP BY type ORDER BY n DESC LIMIT 10
`);

4. IDS 校验

import { parseIDS, validateIDS, createTranslationService } from '@ifc-lite/ids';
import { createDataAccessor } from '@ifc-lite/ids/bridge';

const idsSpec = parseIDS(idsXmlContent);
const accessor = createDataAccessor(store);
const modelInfo = {
  modelId: 'my-model',
  schemaVersion: store.schemaVersion,
  entityCount: store.entityCount,
};
const translator = createTranslationService('en');
const report = await validateIDS(idsSpec, accessor, modelInfo, { translator });

for (const spec of report.specificationResults) {
  console.log(`${spec.specification.name}: ${spec.passRate}% passed`);
}

5. 编辑属性（带 undo）

import { MutablePropertyView } from '@ifc-lite/mutations';
import { PropertyValueType } from '@ifc-lite/data';

const view = new MutablePropertyView(store.properties, 'my-model');
view.setProperty(
  wallExpressId,
  'Pset_WallCommon',
  'FireRating',
  'REI 120',
  PropertyValueType.Label,
);

console.log(view.getMutations());   // 变更历史，可作 undo / export 之用

6. 导出

import { exportToStep, ParquetExporter, Ifc5Exporter } from '@ifc-lite/export';
import { GeometryProcessor } from '@ifc-lite/geometry';

const stepText = exportToStep(store, { schema: 'IFC4', applyMutations: true });

const gp = new GeometryProcessor();
await gp.init();
const glb    = gp.exportGlbFromMeshes(meshes);                // Uint8Array（不重新 mesh）
const csv    = gp.exportCsv(bytes, 'entities', ',', true);
const jsonld = gp.exportJsonld(bytes);
const parquet = await new ParquetExporter(store).exportTable('entities');
const ifcx   = new Ifc5Exporter(store, geometryResult).export({ includeGeometry: true });

7. CLI 全套

ifc-lite info model.ifc                                  # schema / entities / storeys
ifc-lite query model.ifc --type IfcWall --json
ifc-lite schedule model.ifc --preset door                # 门表，csv/json/md/html
ifc-lite ids model.ifc requirements.ids                  # IDS 校验
ifc-lite clash model.ifc --matrix --bcf clashes.bcfzip   # 碰撞检测 → BCF
ifc-lite diff model-v1.ifc model-v2.ifc                  # 模型对比
ifc-lite merge arch.ifc struct.ifc mep.ifc --out fed.ifc # 模型联邦
ifc-lite convert model.ifc --schema IFC4 --out out.ifc   # schema 转换
ifc-lite view model.ifc                                  # 3D 查看器 + REST API
ifc-lite eval model.ifc "bim.query().byType('IfcWall').count()"
ifc-lite mcp model.ifc                                   # 起 MCP server（stdio 或 HTTP）
ifc-lite ask model.ifc "how many walls?"                 # 自然语言问答

典型适用场景

  • 浏览器 / 离线 BIM 查看器：客户端渲染 + 离线友好，模型不外发；
  • CI / ETL：CLI + --json 把 IFC 做成 DuckDB / Polars 可查的 Parquet；
  • BIM 数据自动化：把模型里"所有外墙 Load-bearing 部件 + FireRating 缺失清单"做成可调度任务；
  • AI agent 接入 BIM：ifc-lite mcp 给 agent 一个稳定的 BIM 接口，省掉胶水；
  • BIM 协作 / BCF / diff / merge：版本对比、模型联邦、碰撞检测全在 CLI 里；
  • Python 数据科学：官方 ifclite-geom wheel（pip install ifclite-geom）让几何内核跑在 numpy 进程内。

坑与注意

  1. 精确几何 ≠ 最快几何：IFClite 走的是"exact-arithmetic boolean kernel"，99.9%+ 与 IfcOpenShell 一致；近似布尔引擎在某些 boolean-heavy 模型上更快——这是 README 明说的"trade is deliberate"。如果你更在意速度而非位级一致，先看 benchmarks。
  2. 流式渲染 vs 完整解析：浏览器版是流式的（首屏三角形先出来、文件还在解析）；CLI / server 是 native 多线程，吞吐更高；选哪个看使用场景。
  3. IDS 校验需要翻译器：createTranslationService('en') 会校验多语言规则；切换语言要传对应 locale。
  4. Schema 差异：IFC2X3、IFC4、IFC4X3、IFC5 字段覆盖不同，写跨 schema 查询时留意版本分支。
  5. WASM 体积：约 2.6 MB gzip，按需懒加载；首屏要手动触发 init()。
  6. 依赖 Rust nightly + WASM target：贡献者必须装 Rust nightly，README 已用 rust-toolchain.toml 锁住。
  7. fixtures 走 GitHub Release：CI 跑 pnpm fixtures:check 验证 hash；本地若网络受限先缓存到 tests/models/manifest.json 覆盖范围。
  8. CLI 子命令的 --json 才有可机读输出：默认人类格式，要走管线务必带 --json。
  9. MCP server 模式选择：ifc-lite mcp model.ifc 默认 stdio，HTTP 模式需要查 docs；接 Claude / Codex 时按各自 transport 接。

与同类对比

工具 形态 客户端 / 服务端 几何内核 浏览器 3D MCP / Agent
IFClite（本） npm + Rust + CLI + MCP 客户端优先 + native 服务端 精确算术 CSG WebGPU ✅
web-ifc WASM 解析器 浏览器 近似布尔 取决于上层 ❌
IfcOpenShell Python/C++ 库 服务端 精确几何 无 ❌
BIMserver / BIMSie 协作 server 服务端 — 视前端 ❌
Autodesk Forge / APS SaaS 服务端 闭源 自家 viewer ❌

相对 web-ifc：IFClite 把"解析 + 几何 + 渲染 + CLI + MCP"打通了，单一团队能完整交付；近似 boolean 速度上仍可能输给 web-ifc。相对 IfcOpenShell：IFClite 在浏览器侧做到了"不外发文件"的客户端体验，这是 IfcOpenShell 不覆盖的场景。相对 Autodesk APS：IFClite 是 MPL-2.0 开源、自带 MCP，没有 vendor lock-in。

一句话推荐结论

如果你的团队要在浏览器里交付 IFC 模型、或者想给 LLM agent 一个稳定的 BIM 数据接口、又不想把模型推到 SaaS——IFClite 是当前生态里把"客户端优先 + 精确几何 + 全栈 npm/Rust/CLI + MCP"最完整打通的开源选项；先 npx create-ifc-lite my-viewer --template react 跑一次看效果，再决定要不要上 CLI / MCP。

补充引用：IFC 标准本身是 ISO 16739（buildingSMART 维护），buildingSMART 官网。