#stlkit

#为什么需要它

#能做什么

解析    STL（ASCII + 二进制）、OBJ（含多边形面与负数编号）、
        3MF（含装配体与单位换算）、PLY（ASCII + 两种字节序的二进制）
校验    水密性、非流形边、退化面、法线朝向、绕向一致性
分析    体积、表面积、包围盒、定向包围盒、尺寸、三角形数、去重顶点数、
        壁厚（从表面往里打射线量对面有多远）、
        零件数（几块互不相连的几何）、欧拉示性数、
        重心与转动惯量（密度取 1）
预览    等轴测 SVG 图（自带背面剔除与明暗）
修复    删退化面、去重复面、补洞、重算法线；可导出成 STL / OBJ / PLY
流式    分块扫描超大模型，内存不随模型大小增长
形态    库 + 命令行 + 网页

#用法

#网页

#命令行

# 出一份体检报告
moon run cmd/main examples/cube.stl

# 顺便导出预览图
moon run cmd/main examples/cube.stl --svg cube.svg

# 跑基准测试，对比三种解析方式的耗时与内存
moon run cmd/main big.stl --bench

# 不带参数打印帮助
moon run cmd/main

examples/broken.stl
  格式      ASCII STL
  三角形    11 个
  顶点      33 个（去重后 8 个）
  包围盒    1 × 1 × 1 mm
  体积      1 mm³
  表面积    5.5 mm²

  ✗ 不是水密网格 —— 有 3 条边只被一个面共用
    网格上有破洞，切片软件分不清哪里是实心哪里是空的，直接打印会失败

  结论：直接打印会失败，需要先修复

#库

let data = @fs.read_file_to_bytes("model.stl")
let mesh = match @stlkit.parse_mesh(data) {
  Ok(mesh) => mesh
  Err(msg) => { println("读不了：\{msg}"); return }
}
let check = @stlkit.validate_default(mesh)
if check.is_watertight() {
  println("可以打印，体积 \{mesh.volume()} mm³")
} else {
  println("有 \{check.boundary_edge_count} 条边界边，需要先修复")
}

#3MF：现代切片软件用的格式

1. 它是个 ZIP 包（OPC 容器），模型数据装在里面一个叫 3D/3dmodel.model 的 XML 里
2. 顶点是共享的，三角形存的是顶点表下标，和 OBJ 一样

#实测：拿官方样例验算

#官方一致性测试：13 个全过

• 只输出被引用的对象（Chapter3.4.3a）：文件里有 2 个对象，但 <build> 只引用 了 1 个。工具输出 12 个三角形而不是 24 个——没偷懒把 resources 全倒出来
• 两条不同路径给出同一个结果：Chapter3.2c（1 个对象 + 2 个 item）和 Chapter4.2（2 个对象 + 2 个 component）用 3MF 里两种完全不同的机制描述同一几何， 结果逐位相同（60 个三角形、14000.003 mm³）。这两条路径在实现里是分开的 （一个是 build 层的重复引用，一个是对象层的嵌套引用，后者还要做矩阵合成）， 能对上说明两边都对
• 无关内容不干扰解析：Chapter2.3a（可忽略标记）和 Chapter3.4.1c （未定义的 metadata 名）往文件里塞了一堆和几何无关的东西，解析器不能被带偏

#装配体

<object id="2" type="model">
  <components>
    <component objectid="1" transform="1 0 0 0 1 0 0 0 1 10 0 0"/>
  </components>
</object>

m00 m01 m02
m10 m11 m12
m20 m21 m22
m30 m31 m32      ← 平移在这里，不是前三个

#官方样例自己就有缺陷

  ✗ 有 53 个面的绕向和其他面相反（顶点顺序写反了）
  ✗ 有 24 条边被三个以上的面共用（非流形边）
  ✗ 有 24 个退化三角形（三个点共线，没有面积）

#超大模型：流式解析

#问题出在内存，不是速度

#做法

1. 没凑够一个完整记录的零头——块的大小随便给，不要求对齐到 50 字节
2. 顶点去重表——只存「量化坐标 → 编号」，8 字节一个键，不存三角形
3. 边表——每条边压成一个 UInt64（两个端点编号各占 32 位）

#实测

$ moon run cmd/main huge.stl --bench
  全量解析（保留网格，能校验能修复）
    耗时      18087.6 ms
    内存      文件 95.37 MB + 网格 198.36 MB = 293.73 MB

  流式扫描（不保留网格，文件整块读）
    耗时      2048.4 ms
    内存      文件 95.37 MB + 顶点边表 45.85 MB = 141.22 MB

  流式扫描（不保留网格，文件分块读）
    耗时      3334.3 ms
    内存      缓冲 256 KB + 顶点边表 45.85 MB = 46.1 MB

  省内存      247.63 MB（84.3%）
  提速        5.4 倍

#两条路径必须给出同样的结论

#两条路怎么选

#实现上的几个决定

#开发

moon test            # 跑测试
moon run cmd/main    # 不带参数会打印帮助
bash web/build.sh    # 重新编译网页用的 JS

#测试

Total tests: 239, passed: 239, failed: 0.

• 拿走 1 个三角形要报 3 条边界边，拿走一整个面要报 4 条
• 三个面共用一条边要报非流形
• 翻转法线要被抓到，但法线填零不算错（那是「没填」不是「填错了」）
• 容差两侧各测一次：差 1e-9 的要焊成一个点，差 0.001 的不能
• OBJ 走的是完全不同的代码路径（查顶点表、扇形三角化），但算出来的体积必须和 STL 版一致
• 流式扫描的每个字段都和全量校验逐项对照，分块扫描还要用 1、3、7、13、49、51、83、85 字节这些不对齐的块大小各跑一遍——实现里只要假设了「每次喂进来的都是完整记录」，这些尺寸立刻算出垃圾
• 3MF 的测试样本在内存里现拼（用 fzip 的 zip_sync 把几段 XML 打成 ZIP），想改哪一处就改哪一处。除了正常路径，还专门盯了几个易错点：英寸/厘米/米的换算（不换算体积差 16387 倍）、矩阵平移在最后三个数而不是前三个、组件变换和 build 变换的叠加顺序、以及对象互相引用成环时不能栈溢出

#依赖

#项目结构

• vec3.mbt — 三维向量与点乘/叉乘/单位化
• mesh.mbt — Triangle / Aabb / Mesh，以及体积、表面积、包围盒
• stl.mbt — STL 解析（两种形态）与格式判断
• obj.mbt — OBJ 解析（共享顶点表、多边形三角化、负数编号）
• three_mf.mbt — 3MF 解析（ZIP + XML、装配体、单位换算）
• validate.mbt — 顶点焊接与四项校验
• winding.mbt — 绕向一致性检查与统一
• repair.mbt — 补洞、删退化/重复面、统一绕向、重算法线
• writer.mbt — 导出二进制 / ASCII STL 与 OBJ
• preview.mbt — SVG 等轴测渲染
• stream.mbt — 流式扫描（不建网格、分块读取，内存不随模型增长）
• cmd/main/ — 命令行
• web/ — 网页版（含编译产物 dist/web.js）
• examples/ — 演示与测试用的模型：完好、破洞、绕向反了、圆环，STL 与 OBJ 各一份

#修复

moon run cmd/main examples/broken.stl --fix fixed.stl

  修复前 边界边 3  非流形边 0  退化面 0
  修复后 边界边 0  非流形边 0  退化面 0

  已存到 fixed.stl（684 字节），现在可以切片打印了

#绕向：水密检查查不出的那种坏

$ moon run cmd/main examples/flipped.stl
  体积      0.667 mm³        ← 错！应该是 1

  ✗ 有 1 个面的绕向和其他面相反（顶点顺序写反了）
    这些面朝里了：水密性检查看不出问题，但体积会算错，切片软件也可能把实心区域填反
  ⚠ 有 1 个三角形的法线朝向和顶点顺序不一致

$ moon run cmd/main examples/flipped.stl --fix fixed.stl
修复：
  翻转 1 个绕向反了的面（体积从 0.667 修正为 1）
  已存到 fixed.stl（684 字节），现在可以切片打印了

1. 相邻面的方向必须跟当前面比，不能跟边的规范顺序比。拿规范顺序比会得到「所有面都和规范顺序一致」这种恒真的结论，规则直接失效。
2. 同一条边的两个面都要留着。绕向反了的那条边上，两个面走的是同一个方向——只存「谁走了这个方向」的话，后写入的会覆盖先写入的，查找时还会返回自己。

#参考

• 零件数（count_parts）对应它的 mesh.split()——按面的邻接数连通块
• 欧拉示性数（ValidationReport::euler_number）对应它的 mesh.euler_number
• 水密性、绕向一致性的判据也是同一套拓扑定义

• 3MF 的格式定义来自 3MF Consortium 的规范； examples/conformance/ 下收的 13 个一致性测试文件也来自他们的 3mf-samples 仓库（BSD 2-Clause）

#许可证