# stlkit 与相关项目的对比

stlkit 面向模型文件的打印前复核：读取 STL / OBJ / 3MF / PLY，检查网格、估算采样厚度、提供修复和报告。它是 MoonBit 实现，无 FFI；库、CLI 和浏览器使用同一份核心代码。

## 与 trimesh

[trimesh](https://trimesh.org/) 是 Python 的网格处理库。两者在格式读取、拓扑分析、质量属性、射线查询和修复方面有共同能力；stlkit 提供 MoonBit 接口及直接可用的 CLI / 网页报告。

| 能力 | trimesh | stlkit |
| --- | --- | --- |
| 主要实现 | Python / NumPy，部分操作依赖可选组件 | MoonBit；3MF 依赖 MoonBit ZIP / XML 库 |
| 文件读取 | STL、OBJ、3MF、PLY 及其他格式 | STL、OBJ、3MF、PLY 的文档声明范围 |
| 网格表示 | 顶点与面索引 | 三角形列表；按容差重建顶点关系 |
| 拓扑与质量属性 | 水密性、绕向、连通块、欧拉数、质量属性等 | 边界边、非流形边、退化面、绕向、连通块、欧拉数、质量属性 |
| 定向包围盒 | 提供定向包围盒相关查询 | PCA 包围盒，不保证最小体积 |
| 厚度 | `trimesh.proximity.thickness()`，支持 `max_sphere` / `ray` | 确定性表面采样与内法线射线估计；报告采样最小值和命中数 |
| 修复 | 提供网格修复工具 | 退化 / 重复面删除、简单环补洞、绕向和法线修正，再次复核 |
| 网格运算 | 布尔、体素、平滑、细分等 | 未实现 |
| 分块扫描 | 常规网格处理保留模型数据 | 二进制 STL 分块入口；仍保留顶点表与边表 |
| 使用方式 | Python 库与应用集成 | MoonBit 库、CLI、浏览器网页 |

trimesh 提供壁厚查询，官方接口和算法说明见 [trimesh.proximity.thickness](https://trimesh.org/trimesh.proximity.html#trimesh.proximity.thickness)。本项目的射线采样估计不等同于最大切球法，也不保证得到全局最薄处。

### 参考关系

参考了 trimesh 的 API 和能力组织：连通零件数、欧拉数、质量属性、定向包围盒、射线 / 最近点和 PLY 读写。stlkit 是独立的 MoonBit 实现；来源说明见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

## 与 MoonBit 相关项目

下面说明相关方向和本项目的侧重点，不作“生态唯一”“其他库完全不重叠”或未核实的性能断言。具体能力需结合各包版本、文档和源码判断。

| 项目 / 方向 | 侧重点 | stlkit 的侧重点 |
| --- | --- | --- |
| `mizchi/three` 等 three.js 接口 | 三维场景、渲染和模型加载接口 | MoonBit 文件处理与网格复核，同时提供静态 SVG 预览 |
| `mizchi/mesh3d` 等网格原语 | 渲染管线中的顶点 / 网格组织，部分含 OBJ 读取 | 格式解析、拓扑计数、修复及打印前报告 |
| glTF / GLB 资产工具 | 场景、材质、动画和渲染资产分析 | STL / OBJ / 3MF / PLY 模型的网格与制造前风险 |
| 网格优化和几何工具 | 渲染性能、压缩、简化或通用几何算法 | 读取后复核、修复和报告的工作流程 |
| PicoGK 等体素 / 建模工具 | 几何生成或体素建模 | 检查已有三角网格文件 |

共享几何算法或模型读取能力不意味着定位相同，也不意味着完全没有交集。stlkit 的价值是把这些网格复核能力提供给 MoonBit 使用者，并让 CLI 与浏览器复用相同结论。

## 能力与证据边界

- 检查通过只说明当前覆盖项未发现问题；没有覆盖全部网格自相交、非流形顶点、支撑与材料工艺条件。
- 简单环补洞和 PCA 包围盒有算法边界；修复后仍需复核。
- 分块扫描降低完整文件与三角形数组的存储需求，但顶点与边数据仍随规模增长。
- CLI 内存字段是数据量估算，不是进程内存测量。旧文档的固定内存节省比例和跨项目提速数字已撤下。
- 正确性通过可复现反例与跨后端测试验证；运行命令见 [README.md](README.md#验证与开发)。

项目 Apache-2.0 许可证与第三方样例 BSD-2-Clause 许可证分别说明，完整第三方条款随仓库保留。


## 声明面法线边界

STLKIT 仅统计已保留声明面法线与三角形绕向相反的情况（点积 < 0），不提供完整法线正确性校验；不查单位长度、垂直性或精确一致性。OBJ 三个顶点法线不完全相同时，面法线置零并跳过该项。完整语义及案例见 README 和 normal_scope_wbtest.mbt。