# moonbit-ifc

[![CI](https://github.com/chiooo09/moonbit-ifc/actions/workflows/check.yml/badge.svg)](https://github.com/chiooo09/moonbit-ifc/actions/workflows/check.yml) [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

`moonbit-ifc` 是一个纯 MoonBit 实现的 IFC STEP 物理文件解析与 BIM 构件提取库。它面向 IFC2x3 / IFC4 常用实体，提供从 ISO 10303-21 文件读取、实体关系查询，到几何摘要、三角网格分析和 WebBIM 导出的完整数据路径。

项目不依赖 C/C++ 动态库或外部 EXPRESS 解释器，可用于 MoonBit Native、JavaScript、WebAssembly 和 Wasm GC 应用。当前版本：`0.1.3`。

## 项目定位

项目定位为 BIM 数据基础设施，而不是完整的 EXPRESS 编译器或工业级 BRep 几何内核。核心设计目标是：

- 用无损的 `Entity` / `Value` 模型保留未知 IFC 实体和扩展值；
- 用轻量索引和关系映射提供可复用的产品、空间和属性视图；
- 用纯 MoonBit 数据结构连接服务端解析、WebAssembly 预处理和前端 WebBIM；
- 在保持模块边界清晰的前提下，为更完整的 IFC Schema 和几何适配器留下扩展点。

## 核心能力

### STEP 与 IFC 解析

- 解析 ISO 10303-21 文件头、`HEADER`、`DATA` 和文件尾；
- 支持 `$`、`*`、整数、实数、字符串、枚举、二进制文本、实体引用、Typed value 和任意层级列表；
- 识别 IFC2x3、IFC4、IFC4X1 和 IFC4X3，并保留未知 Schema 信息；
- 提供实体 ID、类型、引用关系和属性索引，并报告缺失引用与结构错误。

### 语义提取

- 提取项目、场地、建筑、楼层、空间、墙、门、窗、梁、柱、板、屋顶、楼梯、坡道和开口等产品；
- 解析 `IfcRelAggregates`、`IfcRelContainedInSpatialStructure` 和 `IfcRelDefinesByProperties`；
- 构建空间树，支持路径、层级、容器、叶节点、包围盒和统计指标查询；
- 提取 `IfcPropertySet` / `IfcPropertySingleValue`，支持属性名、字符串和数值查询；
- 提供常用 IFC 实体的轻量 Schema profile 检查。

### 几何与拓扑

- 提供 `IfcExtrudedAreaSolid`、`IfcFacetedBrep`、`IfcTriangulatedFaceSet`、`IfcPolygonalFaceSet` 和 `IfcCsgSolid` 的统一几何入口；
- 对常见矩形和圆形拉伸体生成三角网格；
- 计算表面积、体积、法线、包围盒、边界边、非流形边、退化三角形和连通分量；
- 支持点焊接、退化面清理、三角面数量限制、拓扑审计和平面剖切。

### 查询、编辑与导出

- `ModelCatalog` 提供按类型、名称、属性和空间容器筛选、排序与分页；
- `ModelPatch` 支持实体新增、删除、替换、属性修改、补丁回放和反向补丁；
- STEP 记录流扫描器可在构造完整模型前统计记录、引用、偏移、行号和输入健康度；
- 空间索引支持包围盒查询、射线拾取、碰撞检测、可见性选择和渲染 LOD；
- 工程量提取支持几何测量、属性公式、单位语义转换、材料盘点和空间排程；
- 导出 OBJ、PLY、JSON Lines、剖切结果和 WebBIM 场景数据；
- 输出确定性的 JSON、CSV、STEP 和 WebBIM 资源 manifest，并提供修订缓存失效计划；
- 提供模型质量审计、GUID 检查、关系图分析和交付门禁报告。

## 快速开始

### 安装

```bash
moon add chiooo09/moonbit-ifc
```

在 `moon.pkg` 中导入：

```moonbit
import {
  "chiooo09/moonbit-ifc" @ifc,
}
```

### 解析模型

```moonbit
let model = @ifc.parse(step_text)
let index = model.index()

for product in model.products() {
  println("\{product.ifc_type} #\{product.id}")
}

let json = @ifc.model_to_json(model)
```

解析函数使用 checked error。应用可以让 `raise` 向上传递，也可以在文件边界用 `try ... catch` 转换为自己的诊断类型。

## CLI

仓库包含两个可直接运行的命令：

```bash
# 运行内置 IFC4 示例，查看模型摘要、质量检查和产品列表
moon run --target native cmd/inspect

# 运行解析、流扫描和组合管线基准
moon run --target native cmd/bench
```

`cmd/bench` 使用确定性生成的 ISO 10303-21 输入，不依赖外部模型文件。基准输出同时提供 Markdown 表格和 JSON，便于记录或接入其他分析工具。

## 架构

| 层次 | 主要文件 | 职责 |
| --- | --- | --- |
| 输入层 | `scanner.mbt`, `parser.mbt`, `value.mbt` | STEP 游标、词法读取、递归值和实体解析 |
| 模型层 | `types.mbt`, `index.mbt`, `schema.mbt` | 公开数据模型、索引、Schema 识别与能力报告 |
| 语义层 | `product.mbt`, `properties.mbt`, `spatial.mbt`, `spatial_analysis.mbt` | 产品、属性、空间关系和空间统计 |
| 几何层 | `geometry.mbt`, `topology.mbt`, `mesh.mbt`, `mesh_analysis.mbt`, `placement.mbt` | 表示链、拓扑、网格、质量指标和放置变换 |
| 工具层 | `catalog.mbt`, `stream.mbt`, `boundary.mbt`, `edit.mbt` | 目录查询、流式预检、边界诊断和模型补丁 |
| 输出层 | `json.mbt`, `exchange.mbt`, `export.mbt`, `export_advanced.mbt`, `webbim.mbt` | JSON、CSV、STEP、OBJ、PLY 和 WebBIM 导出 |
| 分析层 | `spatial_index.mbt`, `clash_detection.mbt`, `quantity_takeoff.mbt`, `section_analysis.mbt`, `topology_audit.mbt` | 空间、碰撞、工程量、剖切和拓扑分析 |
| 交付层 | `quality_audit.mbt`, `asset_manifest.mbt`, `delivery_diff.mbt`, `delivery_report.mbt` | 质量门禁、资源清单、修订影响和交付报告 |
| 工程层 | `benchmark.mbt`, `cmd/inspect`, `cmd/bench` | 基准、示例和可运行命令 |

## 设计边界

项目当前不承诺 NURBS 曲面 tessellation、复杂 CSG 求值或全部 IFC 实体的强约束验证。Schema profile 只覆盖常见实体；未知扩展以通用模型保留。拉伸体、三角面集和 BRep 入口适合导入、检查和 WebBIM 预处理，不能替代工业级几何内核。

## 基准

基准使用当前实现生成的有效 STEP 文档，分别包含 8、64 和 256 个 IFC 墙体产品；每个产品包含放置、表示、拉伸体和矩形轮廓。测量使用 `@env.now()` 的墙钟时间，详细输入、工具链和复现实测结果见 [`docs/benchmarks.md`](docs/benchmarks.md)。

本地一次实测的代表性结果如下：

| 场景 | 输入字符数 | 实体数 | 迭代次数 | 用时 |
| --- | ---: | ---: | ---: | ---: |
| 8 墙体解析 | 3,179 | 56 | 8 | 10 ms |
| 64 墙体解析 | 20,981 | 392 | 3 | 27 ms |
| 256 墙体解析 | 84,331 | 1,544 | 1 | 31 ms |
| 64 墙体组合管线 | 20,981 | 392 | 3 | 139 ms |

当前实现由 76 个按职责组织的 `.mbt` 文件组成，共 24,117 行文件内容；其中 20,390 行为非空、非注释的实现内容。统计不包含测试文件、fixture、Markdown 和构建产物。

## 测试

测试覆盖解析、实体索引、语义关系、属性、空间树、单位、几何、拓扑、网格质量、流式扫描、Schema、模型补丁、交付门禁和基准边界，共 40 项测试。

```bash
moon check --target all --deny-warn
moon test --target all --deny-warn
moon build --target all --deny-warn
```

项目已在 Native、JavaScript、WebAssembly 和 Wasm GC 目标上验证。边界测试包括空输入、截断文件、异常偏移、缺失引用、退化三角形、非流形边、分页边界和补丁回放。

## CI

GitHub Actions 工作流位于 [`.github/workflows/check.yml`](.github/workflows/check.yml)，在 Ubuntu、macOS 和 Windows 上使用 stable MoonBit 工具链执行：

- `moon check --target all --deny-warn`；
- `moon test --target all --deny-warn`；
- `moon build --target all --deny-warn`；
- Native CLI 示例运行；
- `moon fmt --check`；
- `moon info` 与生成接口差异检查。

## 许可证与来源

项目代码使用 [Apache License 2.0](LICENSE)。格式参考、IFC Schema 资料、fixture 来源和适用范围记录在 [`docs/sources.md`](docs/sources.md) 与 [`docs/scope.md`](docs/scope.md)。仓库不包含私有工程数据、闭源 SDK 或第三方实现的复制源码。