Pure MoonBit 3D solid modeling kernel: signed distance primitives, exact CSG booleans, marching tetrahedra meshing, STL/OBJ export, no FFI.
演示站点由 .github/workflows/pages.yml 部署,仓库的 Pages Source 已设为 “GitHub Actions”,改到 examples/web/** 或 *.mbt 的 push 会自动重建并部署。 首次启用必须手点一次这个开关:GITHUB_TOKEN 没有 admin 权限, configure-pages 的 enablement: true 会 403。
moon add weopqrst/mooncsgimport {
"weopqrst/mooncsg@0.1.3",
}moon test # 50 个 test 块 / 225 个用例(native / js / wasm-gc 都要跑)
moon run examples/demo # 盒减球,打印体积/面积/拓扑
moon run examples/bench --release # 网格化耗时基线
moon check --deny-warn
moon fmt --check
# 边界语义的两端:能保证的与必须拒绝的
moon run cmd/main -- sphere 10 --res 32 > s.stl # exit 0:闭合可切片
moon run cmd/main -- plane 0 0 1 0 --stats # exit 1:半空间没有有限包围盒
moon run cmd/main -- sphere 10 --bounds -10.5,-10.5,-10.5,2,10.5,10.5 --stats
# exit 1:采样域被实体穿出
moon run cmd/main -- sphere 10 --bounds -10.5,-10.5,-10.5,2,10.5,10.5 --clip --stats
# exit 0:明确声明 watertight=false
# 交互 demo(调参 + canvas 投影)
node tools/build_web.mjs # 编译 wasm 并复制到 examples/web/
node tools/serve.mjs # 打开 http://127.0.0.1:8000/
node tools/wasm_check.mjs # 不开浏览器,在 Node 里跑同一份 wasm 的验收项
node tools/scene_check.mjs # 在 Node 里跑 demo 用到的场景接口
node tools/guard_check.mjs # 边界语义门禁:正常输入闭合,半空间/裁剪/空域必须被拒
# 一次跑完全部验收项(13 项:check/fmt/三后端测试/package/demo/bench/web/边界语义/体积对拍)
node tools/acceptance.mjstriangles: 126484
vertices: 63242
volume: 17058.878927955866
area: 6336.3007417442195
watertight: true
euler: 0 (genus 1)
obj bytes: 4577832
stl bytes: 26192644
预期体积(解析):24000 - 2*pi*10*(144 - 100/3) = 17046.6| 用例 | 三角形 | 实际格点 | wasm-gc | js |
|---|---|---|---|---|
| 球 r=10,请求 32 | 26280 | 32³ | 13.9 ms | 35.2 ms |
| 球 r=10,请求 64 | 104688 | 64³ | 68.3 ms | 175.0 ms |
| 立方体 40³ 挖球 r=24,请求 48 | 107280 | 48³ | 90.7 ms | 233.5 ms |
| 环面 R=8 r=3,请求 48 | 36172 | 48×48×15 | 20.6 ms | 45.3 ms |
| 球 r=25,请求 128 | 443736 | 128³ | 404.5 ms | 981.1 ms |
| 球 r=25,请求 256 | 1135968 | 205³(被收窄) | 1419.9 ms | 3270.0 ms |
| 前置条件(逐条检查) | 不满足时的处置 |
|---|---|
| 采样域各轴长度 > 0、坐标有限 | DegenerateBounds |
| 采样点场值处处有限(无 NaN / Inf) | NonFiniteField(点) |
| 实体严格位于采样域内部:6 个面上的采样点全部 f > 0 | SurfaceClipped(点, 场值) |
| 采样域内确实存在内部点 | NoSurface |
| 输入 | 输出 / 拒绝条件 |
|---|---|
| 球 / 盒 / 圆柱 / 圆台 / 胶囊 / 环面(有界原语) | 默认采样域 bounds().expand(0.5) ⇒ 通过,闭合 |
| 原语的布尔组合(并 / 交 / 差 / 平滑并) | 同上;包围盒由运算各自收紧,平滑并额外外扩 k/2 |
| 半空间 plane | bounds() == None ⇒ 拒绝 Unbounded;CLI 要求用 --bounds 给出有界域 |
| 半空间 + 有界域 | 域边界上必然出现 f <= 0 ⇒ 拒绝 SurfaceClipped——半空间在有限域内闭不了 |
| 实体与域面相切(球心落在域面上) | 边界采样 f == 0 ⇒ 拒绝(判据 f <= 0 含相等) |
| 采样域小于实体(被裁剪) | 默认拒绝;显式要裁剪网格时用 --clip(或 mesh_unchecked),此时 watertight=false、open_edges 给出开口边数 |
| 域与实体完全不重叠 | 拒绝 NoSurface,不把空网格当成功 |
| 退化参数(scale(0)、NaN 半径) | 采样到 Inf/NaN ⇒ 拒绝 NonFiniteField |
| 场景 | 退出码 | 关键输出 |
|---|---|---|
| 球 r=10,自动采样域 | 0 | watertight: true、open_edges: 0 |
| 半空间,无域 | 1 | 没有有限包围盒,提示用 --bounds |
| 半空间 + 有界域 | 1 | 采样域被实体穿过:边界点 (-10,-10,-10) 场值 -10 |
| 域小于实体(裁一半) | 1 | 采样域被实体穿过:场值 -0.015 |
| 同一输入加 --clip | 0 | watertight: false、open_edges: 402 |
| 域离实体很远 | 1 | 采样域内没有曲面 |
| 判据 | 测试 |
|---|---|
| 球/盒各 1000 个随机点、圆柱 / 平面 / 圆台 / 胶囊的解析距离误差 < 1e-12,环面按参数化构造点对拍 | sdf_test.mbt |
| 布尔与 min / max / 取负逐点一致 | sdf_test.mbt |
| 球体积误差 < 0.5%(128 分辨率)、盒 < 1%(40 分辨率) | mesh_test.mbt |
| 环面亏格 = 1、欧拉示性数 = 0 | mesh_test.mbt |
| 盒挖两个贯通孔后亏格 = 2、欧拉示性数 = -2、体积误差 < 0.5% | mesh_test.mbt |
| 盒减球体积与球带公式误差 < 1% | mesh_test.mbt |
| 完全被挖空时输出空网格 | mesh_test.mbt |
| 相切球、零厚度板、空交集、贴面格点、退化包围盒、超低分辨率都不崩 | mesh_test.mbt |
| 等值面正好落在格点上时仍水密、体积误差 < 1% | mesh_test.mbt |
| 每条无向边恰好 2 个面(水密) | mesh_test.mbt |
| mesh_checked 对相切 / 裁剪 / 空域 / 退化域 / 非有限场值分别返回对应错误 | marching_test.mbt |
| 60 个随机实体在 bounds().expand(0.5) 下全部闭合、open_edges == 0 | marching_test.mbt |
| 同输入两次网格化逐位相同 | mesh_test.mbt |
| 网格指纹等于常量 7885752854646016839(js / wasm-gc 本地跑,native 在 CI 跑,三后端同值) | mesh_test.mbt |
| 分辨率或朝向变化时指纹必然改变(指纹确实覆盖几何与拓扑) | mesh_test.mbt |
| OBJ/ASCII STL 行数与索引范围、字节级确定性 | export_test.mbt |
| 二进制 STL 往返后三角数/顶点数/欧拉示性数不变、体积相对误差 < 1e-6 | export_test.mbt |
| 截断的二进制 STL 返回 None 而不是越界 | export_test.mbt |
| wasm 验收壳 4/4 通过(Node 与浏览器同一份 wasm) | tools/wasm_check.mjs |
| CLI 边界语义:正常输入 exit 0 且闭合;半空间 / 裁剪 / 空域 exit ≠ 0;--clip 声明开口 | tools/guard_check.mjs |
| 全部验收项一条命令跑完(13 项,含边界语义与体积对拍) | tools/acceptance.mjs |
pub(all) struct MeshOptions {
resolution : Int
project : Bool
iterations : Int
}pub(all) enum Sdf {
Sphere(Vec3, Double)
Box(Vec3, Vec3)
Plane(Vec3, Double)
Cylinder(Vec3, Double, Double)
Torus(Vec3, Double, Double)
Cone(Vec3, Double, Double, Double)
Capsule(Vec3, Double, Double)
Translate(Sdf, Vec3)
Rotate(Sdf, Mat3)
Scale(Sdf, Double)
Union(Sdf, Sdf)
Intersect(Sdf, Sdf)
Subtract(Sdf, Sdf)
SmoothUnion(Sdf, Sdf, Double)
}pub(all) struct Vec3 {
x : Double
y : Double
z : Double
}Install
Download zipPure MoonBit 3D solid modeling kernel: signed distance primitives, exact CSG booleans, marching tetrahedra meshing, STL/OBJ export, no FFI.