mooncsg

    Pure MoonBit 3D solid modeling kernel: signed distance primitives, exact CSG booleans, marching tetrahedra meshing, STL/OBJ export, no FFI.

    csg
    sdf
    3d
    modeling
    mesh
    Download zip
    Author
    Version
    0.1.5
    License
    Apache-2.0
    Last updated
    27 minutes ago
    Downloads
    43

    No dependencies

    #mooncsg

    纯 MoonBit 的 3D 实体建模内核:有符号距离场(SDF)原语、CSG 布尔、 marching tetrahedra 网格化、OBJ / STL 导出。没有 FFI,没有第三方几何库。

    目标是让「程序化生成一个能直接进切片软件的实体」这件事只依赖一份 可读的 MoonBit 代码——几何在数学上闭合(水密、朝向一致、体积可对数), 而不是「看起来像」。闭合不是无条件承诺:mesh_checked 先判定输入是否 满足条件,不满足就拒绝,范围见下文「可打印保证的范围」。

    在线演示:https://mihujiang.github.io/mooncsg/  实测数字:见 ACCEPTANCE.md

    演示站点由 .github/workflows/pages.yml 部署,仓库的 Pages Source 已设为 “GitHub Actions”,改到 examples/web/** 或 *.mbt 的 push 会自动重建并部署。 首次启用必须手点一次这个开关:GITHUB_TOKEN 没有 admin 权限, configure-pages 的 enablement: true 会 403。

    #现状

    已覆盖 M0–M6:

    • vec.mbt:Vec3 / Mat3 / Aabb
    • sdf.mbt:球、盒、半空间、圆柱、圆台、胶囊、环面;平移/旋转/缩放; 并/交/差/平滑并;包围盒
    • marching.mbt:规则体素 + 6 四面体分解 + 边键焊接 + 梯度投影; mesh_checked 的采样域前置检查与拒绝语义(mesh / mesh_unchecked 不检查)
    • mesh.mbt:散度体积、面积、水密判定、欧拉示性数 / 亏格(只对单个闭合壳 有定义,多壳返回 -1)、FNV-1a 指纹
    • export.mbt:OBJ、ASCII STL、二进制 STL,以及二进制 STL 回读
    • examples/web:交互 demo(调参 → 网格 → canvas 2D 软件投影 + 体积/面积/拓扑), 页面里带 ?selftest=1 的验收路径
    • examples/bench:网格化耗时基线(native / js / wasm-gc 同一份代码)
    • tools/oracle.py:独立解析基准(只用标准库),--cases 给出对拍用例
    • tools/volume_check.mjs:把 oracle 的解析体积和 cmd/main --stats 的实测值逐组比阈值
    • tools/guard_check.mjs:CLI 边界语义门禁(正常输入必须闭合,半空间 / 裁剪 / 空域必须被拒)
    • tools/wasm_check.mjs:在 Node 里实例化同一份 wasm 跑验收
    • tools/scene_check.mjs:在 Node 里校验交互 demo 的 wasm 接口(建网格/读坐标/读指标)
    • tools/serve.mjs:本地静态服务,node tools/serve.mjs → http://127.0.0.1:8000/
    • tools/acceptance.mjs:一条命令跑全部验收项并打表
    • tools/publish.mjs:发布 + 发布后回拉验证(见下)

    #安装

    已发布到 mooncakes(weopqrst/mooncsg@0.1.3):

    moon add weopqrst/mooncsg

    效果等同在 moon.mod 里写:

    import {
    "weopqrst/mooncsg@0.1.3",
    }

    再在调用方包的 moon.pkg 里加 "weopqrst/mooncsg",即可用 @mooncsg. 前缀调用。

    #快速开始

    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.mjs

    交互 demo 的形状与参数:球(半径)、立方体(边长)、圆台(底半径 + 高)、 胶囊(半径 + 圆柱段长)、环面(管半径 + 环半径),外加「减去偏移球」的挖切; 拖拽旋转、滚轮缩放、双击复位。分辨率滑杆控制的是请求值,指标区显示的是 实际格点数(超过 MAX_GRID_SLOTS 会被自动收窄,见下)。

    examples/demo 的输出(40³ 盒减球 r=12,res = 64):

    triangles: 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

    体积相对误差 0.07%。

    #性能基线

    moon run examples/bench --release 走 moonbitlang/core/bench 的单调时钟 (native 绑 clock_gettime,wasm 绑 time_unstable.instant_now,微秒), 先跑一次预热,再取三次的最小值。机器:Intel Core Ultra 9 275HX / Windows 11 / Node 24(wasm-gc 与 js 都跑在 V8 上)。

    「实际格点」一列是 grid_shape() 报的值:resolution 只是请求值,超过 MAX_GRID_SLOTS(16.7M 个采样点)会被按 1.25 倍步长收窄。所以请求 256 的 立方包围盒实际跑的是 205³——表里照实写。

    用例三角形实际格点wasm-gcjs
    球 r=10,请求 322628032³13.9 ms35.2 ms
    球 r=10,请求 6410468864³68.3 ms175.0 ms
    立方体 40³ 挖球 r=24,请求 4810728048³90.7 ms233.5 ms
    环面 R=8 r=3,请求 483617248×48×1520.6 ms45.3 ms
    球 r=25,请求 128443736128³404.5 ms981.1 ms
    球 r=25,请求 2561135968205³(被收窄)1419.9 ms3270.0 ms

    后两行用 moon run examples/bench --release -- big 才跑(默认不跑,js 后端 那两档要几秒,塞进 CI 会把 bench 这条 step 拖成分钟级)。

    两点说明:

    • wasm-gc 比 js 后端快 2.2–2.6 倍,这是同一份 MoonBit 源码换后端的结果, 不是两份实现——wasm-gc 直接吃 f64 运算,js 后端还要过一层 BigInt/boxing 的 边界检查。
    • native 数字本地没有:这台 Windows 机器没装 MSVC Build Tools,native 后端 整体不可用(tools/acceptance.mjs 会把它判成 SKIP 而不是 FAIL)。CI 的 ubuntu runner 上 moon test --target native 会跑,所以 native 的正确性有 持续覆盖,只是没有本地耗时对照。本表不编 native 的数。

    #可打印保证的范围

    「水密」不是形容词,而是可判定的输入条件加可验证的输出性质。 mesh_checked 是唯一给出保证的入口,其余情况一律拒绝:

    前置条件(逐条检查)不满足时的处置
    采样域各轴长度 > 0、坐标有限DegenerateBounds
    采样点场值处处有限(无 NaN / Inf)NonFiniteField(点)
    实体严格位于采样域内部:6 个面上的采样点全部 f > 0SurfaceClipped(点, 场值)
    采样域内确实存在内部点NoSurface

    通过检查的输出保证:每条无向边恰好被 2 个三角形共享(is_watertight())、 open_edges() == 0、体积为正、朝向朝外。

    为什么第 3 条是充要条件、不是保守估计:三角形只在相邻四面体之间按 「格点索引对」配对焊接,曲面上的每个顶点都落在一条两端格点异号的边上。 若某条边的两端都贴着采样域边界,曲面就是从边界穿出去的——那个顶点在域内 找不到对侧三角形,边界处必然留开口。反过来,边界全正意味着曲面整块在 内部,每个顶点都能在域内找到对侧三角形,于是「闭合」是构造保证,不是 概率。

    #具体到几类输入

    输入输出 / 拒绝条件
    球 / 盒 / 圆柱 / 圆台 / 胶囊 / 环面(有界原语)默认采样域 bounds().expand(0.5) ⇒ 通过,闭合
    原语的布尔组合(并 / 交 / 差 / 平滑并)同上;包围盒由运算各自收紧,平滑并额外外扩 k/2
    半空间 planebounds() == 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

    实测(node tools/guard_check.mjs,CI 里的第 13 项门禁):

    场景退出码关键输出
    球 r=10,自动采样域0watertight: true、open_edges: 0
    半空间,无域1没有有限包围盒,提示用 --bounds
    半空间 + 有界域1采样域被实体穿过:边界点 (-10,-10,-10) 场值 -10
    域小于实体(裁一半)1采样域被实体穿过:场值 -0.015
    同一输入加 --clip0watertight: false、open_edges: 402
    域离实体很远1采样域内没有曲面

    #明确不保证的

    • 薄壳:壁厚小于 2 个体素时两侧可能落进同一格点,整片壳被漏掉——报 NoSurface 或体积明显偏小。加密 --res,或把壁厚做大。
    • 非精确 SDF(|∇f| 明显偏离 1):拓扑仍闭合,但体积与法线有偏差。
    • 自交实体(环面管半径 ≥ 母线半径、subtract 挖成非流形):输出闭合, 但不是合法实体,切片器会拒绝。
    • 多壳:is_watertight 对多个不相交壳仍为真(每条边 2 面),但 genus() 返回 -1 表示「单壳亏格不可用」。

    #验收口径

    每条断言都能把当前代码判为失败,不是「跑通了就算」:

    判据测试
    球/盒各 1000 个随机点、圆柱 / 平面 / 圆台 / 胶囊的解析距离误差 < 1e-12,环面按参数化构造点对拍sdf_test.mbt
    布尔与 min / max / 取负逐点一致sdf_test.mbt
    球体积误差 < 0.5%(128 分辨率)、盒 < 1%(40 分辨率)mesh_test.mbt
    环面亏格 = 1、欧拉示性数 = 0mesh_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 == 0marching_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-6export_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

    tools/oracle.py 用 Python 标准库手算解析值,tools/volume_check.mjs 把它和 cmd/main --stats 的实测体积逐组比阈值——只跑 oracle.py 没意义(它打印完就 exit 0),所以 CI 里跑的是后者,超差直接红。

    #设计要点

    f == 0 一律算外部。 边界点归外部,插值参数再夹到 t ∈ [1e-6, 1-1e-6] (按边长比例,与体素尺寸无关),避免零面积三角形;否则同一格点会在相邻 体素里被两边都算一次,网格出现重面。

    焊接不靠 eps 量化。 交点的键是「两个格点索引的 min/max」:同一条 几何边无论从哪个四面体、哪个方向被访问都得到同一个键,位置也统一按 min -> max 方向插值。于是焊接是精确的,而 O(1) 查表不依赖哈希遍历顺序。

    绕向用顶点梯度,不用格点当参考。 格点可能恰好贴着等值面,参考方向会 被浮点噪声决定;顶点就在面上,梯度就是外法线。逐面判定后仍保留 「体积为负则整体翻转」的兜底。

    四面体对角固定。 立方体只沿 (0,0,0)-(1,1,1) 拆 6 个四面体。 换一种拆分,同一 SDF 同一分辨率会得到不同三角数,体积就不可比。

    网格化是确定性的。 固定遍历顺序、固定四面体表、固定排序(自写归并), 不使用哈希迭代顺序决定输出顺序。这份确定性是可验证的:Mesh::hash() 把 顶点位模式与索引序列压成 FNV-1a 64 位指纹,测试用常量断言,native / js / wasm-gc 三个后端必须算出同一个数。

    #已知限制

    • 体积与面积是结果度量,不是约束求解;没有做保体积简化(decimation)。
    • 半空间没有有限包围盒,单独网格化必须先给 --bounds;给了也会因「曲面从域边界 穿出」被拒绝——半空间只有和别的形状做布尔(例如与盒求交)才构成有界实体。
    • 只有均匀缩放;非均匀缩放会让 SDF 不再是距离场(需要除以梯度模)。
    • 二进制 STL 的坐标是 f32,这是格式限制;要更高精度请用 OBJ。
    • 回读只做了二进制 STL(OBJ 回读需要文本数字解析,暂缓)。
    • 没有 BVH / 距离查询加速,eval 直接遍历树;雏版靠分辨率控制成本。
    • resolution 上限 512,且总格点另有 MAX_GRID_SLOTS(16.7M)收紧: 512 的立方包围盒实际按约 253³ 采样(场数组约 134 MB),再大就该分块 或换稀疏/自适应表示,而不是继续加分辨率。

    #许可

    Apache-2.0。

    更细的取舍说明(每个文件「为什么长这样」、验收策略、AI 参与与验证流程)见 docs/ARCHITECTURE.md,版本变更见 CHANGELOG.md。

    Aabb

    pub(all) struct Aabb {
    min : Vec3
    max : Vec3
    }

    轴对齐包围盒。min 逐分量小于等于 max 才是有效盒。

    Aabb::center

    fn Aabb::center(self : Aabb) -> Vec3

    Aabb::contains

    fn Aabb::contains(self : Aabb, p : Vec3) -> Bool

    Aabb::diagonal

    fn Aabb::diagonal(self : Aabb) -> Double

    Aabb::expand

    fn Aabb::expand(self : Aabb, r : Double) -> Aabb

    各方向等比外扩 r,网格化时用来给采样留一圈边界。

    Aabb::from_center_half

    fn Aabb::from_center_half(center : Vec3, half : Vec3) -> Aabb

    Aabb::intersect

    fn Aabb::intersect(self : Aabb, o : Aabb) -> Aabb

    Aabb::is_empty

    fn Aabb::is_empty(self : Aabb) -> Bool

    空盒用「min > max」表示,不额外加标志位。

    Aabb::new

    fn Aabb::new(min : Vec3, max : Vec3) -> Aabb

    Aabb::size

    fn Aabb::size(self : Aabb) -> Vec3

    Aabb::union

    fn Aabb::union(self : Aabb, o : Aabb) -> Aabb

    Mat3

    pub(all) struct Mat3 {
    c0 : Vec3
    c1 : Vec3
    c2 : Vec3
    }

    3×3 矩阵,按列存:c0/c1/c2 是三个基向量。

    按列存是为了 mul_vec 写成一次线性组合——这也是后面做旋转 与梯度变换时唯一需要的方向。

    Mat3::from_columns

    fn Mat3::from_columns(c0 : Vec3, c1 : Vec3, c2 : Vec3) -> Mat3

    Mat3::identity

    fn Mat3::identity() -> Mat3

    Mat3::mul_vec

    fn Mat3::mul_vec(self : Mat3, v : Vec3) -> Vec3

    Mat3::transpose

    fn Mat3::transpose(self : Mat3) -> Mat3

    转置:旋转的逆。SDF 变换里要用它把世界坐标拉回局部坐标。

    Mesh

    pub(all) struct Mesh {
    positions : Array[Vec3]
    indices : Array[Int]
    }

    三角网格:位置数组 + 索引数组(每 3 个索引一个三角形)。

    顶点是焊接过的——同一个几何位置只出现一次,否则「每条边恰好 2 面」 这个水密判据会被重复顶点破坏。索引用 Int,Int 在 wasm-gc 是 32 位, 顶点数上限 2^31 对建模场景足够。

    Mesh::area

    fn Mesh::area(self : Mesh) -> Double

    Mesh::bounds

    fn Mesh::bounds(self : Mesh) -> Aabb

    Mesh::edge_count

    fn Mesh::edge_count(self : Mesh) -> Int

    唯一边数。

    Mesh::edge_keys

    fn Mesh::edge_keys(self : Mesh) -> Array[Int64]

    每条边编码成 min * V + max 后的升序数组。V 是顶点数, 所以编码无歧义;V 不会超过 2^31,乘积在 Int64 内。

    Mesh::empty

    fn Mesh::empty() -> Mesh

    Mesh::euler

    fn Mesh::euler(self : Mesh) -> Int

    欧拉示性数 V - E + F。单个闭合曲面上等于 2 - 2g;k 个不相交的 闭合壳则是 2k - 2Σgᵢ(示性数对壳可加)。

    Mesh::flipped

    fn Mesh::flipped(self : Mesh) -> Mesh

    翻转全部三角形。朝向统一翻,不逐面判断——逐面判断在凹面上会被 数值梯度的噪声带偏。

    Mesh::from_stl_binary

    fn Mesh::from_stl_binary(data : Bytes) -> Mesh?

    二进制 STL 回读。

    STL 没有索引,同一个顶点会在每个相邻三角形里重复出现。这里按 f32 位模式做精确去重(不是 eps 距离):同一位置写出去时位模式 相同,读回来也相同,所以能还原原始顶点数。这个等价关系只在 「导出后未经过任何编辑」时成立,正好是往返测试要的性质。

    实现上按 UInt64 哈希分桶、桶内比坐标:早期版本给每个顶点拼一个 String 当键,十几万面的 STL 要构造几十万个字符串,回读时间和 内存都被这一项主导。

    Mesh::genus

    fn Mesh::genus(self : Mesh) -> Int

    亏格 g = (2 - χ) / 2。

    只对单个闭合壳是真正的亏格。多壳时返回值是 1 - k + Σgᵢ:k 个球 给出 1 - k,看起来像负数——所以这里把「不闭合 / 多壳」一并返回 -1 (χ 为奇数说明不闭合,或顶点只被部分面共享),意义是「这个数为不了」, 不区分具体原因。要逐壳统计得先做连通分量拆分,本雏版不做。

    Mesh::hash

    fn Mesh::hash(self : Mesh) -> UInt64

    网格内容的 64 位指纹:顶点坐标的位模式(按存储顺序)+ 索引序列。

    「同输入两次网格化逐位相同」只能证明同后端内确定;把指纹写成测试 常量之后,wasm-gc / js / native 任意后端算出的值都必须是同一个, 这才叫跨后端确定性。顶点与索引的顺序本身是确定性的产物,所以指纹 也顺带覆盖了遍历顺序。

    Mesh::is_empty

    fn Mesh::is_empty(self : Mesh) -> Bool

    Mesh::is_watertight

    fn Mesh::is_watertight(self : Mesh) -> Bool

    水密:每条无向边恰好被 2 个三角形共享。

    Mesh::new

    fn Mesh::new(positions : Array[Vec3], indices : Array[Int]) -> Mesh

    Mesh::open_edges

    fn Mesh::open_edges(self : Mesh) -> Int

    开口边数:只被 1 个(或 3 个以上)三角形共享的边。

    is_watertight() 只回答「是否全闭合」,这里回答「开口有多大」。用在 --clip 这种故意裁剪的场景:裁剪出来的网格不该被当成可打印实体,但 开口的数量要说得出来,而不是只给一个 false。

    Mesh::to_obj

    fn Mesh::to_obj(self : Mesh, name : String) -> String

    文本格式导出。先做 OBJ 与 ASCII STL:两者都不需要二进制打包, 结果可以直接用 diff 比对,也就顺势成了回归测试的一部分。 二进制 STL 见文件末尾:它需要位打包,但也带来一个好处—— 可以写回读,用「导出再导入」检验网格是不是真的没丢东西。

    Mesh::to_stl

    fn Mesh::to_stl(self : Mesh, name : String) -> String

    ASCII STL。STL 不带顶点索引,每个三角形重复三个顶点, 所以文件通常比 OBJ 大——换来的是所有切片软件/查看器都认。

    Mesh::to_stl_binary

    fn Mesh::to_stl_binary(self : Mesh) -> Bytes

    二进制 STL:80 字节头 + uint32 三角形数 + 每三角形 50 字节 (法线 12 字节 + 三顶点 36 字节 + 属性 2 字节)。全部小端。

    头 80 字节留空。很多工具往里塞模型名,但格式本身不规定, 空着头反而省掉一次「名字超过 80 字节怎么办」的讨论。 顶点坐标按 f32 存储,这是格式本身的限制。往返测试因此用 「相对误差 < 1e-6」而不是逐位相等:f32 只有 24 位有效数字。

    Mesh::triangle

    fn Mesh::triangle(self : Mesh, i : Int) -> (Vec3, Vec3, Vec3)

    第 i 个三角形的三个顶点。

    Mesh::triangle_count

    fn Mesh::triangle_count(self : Mesh) -> Int

    Mesh::vertex_count

    fn Mesh::vertex_count(self : Mesh) -> Int

    Mesh::volume

    fn Mesh::volume(self : Mesh) -> Double

    散度定理求体积:V = Σ a · (b × c) / 6。

    朝向正确时结果为正,所以这个数同时充当朝向自检——不需要再单独 遍历面判法线。

    MeshError

    pub(all) enum MeshError {
    Unbounded
    DegenerateBounds
    NonFiniteField(Vec3)
    SurfaceClipped(Vec3, Double)
    NoSurface
    }

    网格化的拒绝原因。

    mesh_checked 只在「采样域严格包住实体、场值处处有限」时返回网格, 其余情况明确拒绝。原因很直接:marching tetrahedra 只能在采样域内部 把曲面闭合起来,曲面一旦碰到采样域边界,那里的面必然被截断成开口。 那种网格体积偏小、切片软件会当成「有漏的实体」。宁可报错,也不返回 一个看起来能用、实际不可打印的网格。

    MeshError::describe

    fn MeshError::describe(self : MeshError) -> String

    拒绝原因的可读描述。CLI、测试、文档共用这一份,免得三处口径不一致。

    MeshOptions

    pub(all) struct MeshOptions {
    resolution : Int
    project : Bool
    iterations : Int
    }

    网格化选项。

    MeshOptions::new

    fn MeshOptions::new(resolution : Int) -> MeshOptions

    Sdf

    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)
    }

    有符号距离场(SDF)。

    约定:实体内部为负、外部为正、边界为 0。所有原语与布尔都保持这个约定, 因为它们只由 min / max / - 组合,而这三个运算保号。

    树是公开的(pub(all)):调用方可以直接构造,也可以把自己的节点 写进 eval 之外的分析(例如 bounds)。递归节点不做共享引用, 同一棵子树被复用两次就是两份拷贝——几何树很小,不做引用计数。

    Sdf::at

    fn Sdf::at(self : Sdf, center : Vec3) -> Sdf

    Sdf::bounds

    fn Sdf::bounds(self : Sdf) -> Aabb?

    保守包围盒:只做「不会漏掉实体」的放大,不求紧。 半空间没有有限包围盒,参与 Union 时整体返回 None, 参与 Intersect 时由另一侧决定,做刀具时被忽略。

    Sdf::box

    fn Sdf::box(half : Vec3) -> Sdf

    Sdf::capsule

    fn Sdf::capsule(radius : Double, half_height : Double) -> Sdf

    Sdf::cone

    fn Sdf::cone(r1 : Double, r2 : Double, half_height : Double) -> Sdf

    圆台:r1 是 z = -half_height 处的半径,r2 是 z = +half_height 处的半径。

    Sdf::cylinder

    fn Sdf::cylinder(radius : Double, half_height : Double) -> Sdf

    Sdf::eval

    fn Sdf::eval(self : Sdf, p : Vec3) -> Double

    求有符号距离。这是整个内核唯一的「真相来源」:网格化、体积、法线 全部由它派生,所以每个原语都直接照抄解析公式,不做近似。

    Sdf::gradient

    fn Sdf::gradient(self : Sdf, p : Vec3) -> Vec3

    数值梯度(中心差分)指向距离增大方向,也就是实体外部。

    步长随坐标尺度放大,避免在远处把差分吃掉;这里只用 + - * / sqrt, 不引入三角函数,保证同一输入的梯度在任何后端一致。

    Sdf::intersect

    fn Sdf::intersect(self : Sdf, o : Sdf) -> Sdf

    Sdf::is_inside

    fn Sdf::is_inside(self : Sdf, p : Vec3) -> Bool

    内部/外部判定。f >= 0 一律算外部:f == 0 的抖动会让网格化漏面或重面, 所以边界点统一归到外部,由采样偏置处理(见 ARCHITECTURE)。

    Sdf::plane

    fn Sdf::plane(normal : Vec3, offset : Double) -> Sdf

    法线在这里归一化:Plane 的距离公式要求 |normal| = 1, 否则返回值会被整体缩放。

    Sdf::scale

    fn Sdf::scale(self : Sdf, s : Double) -> Sdf

    Sdf::smooth_union

    fn Sdf::smooth_union(self : Sdf, o : Sdf, k : Double) -> Sdf

    Sdf::sphere

    fn Sdf::sphere(radius : Double) -> Sdf

    Sdf::subtract

    fn Sdf::subtract(self : Sdf, o : Sdf) -> Sdf

    Sdf::torus

    fn Sdf::torus(big : Double, small : Double) -> Sdf

    环面:big 是母线(环心到管心)半径,small 是管半径。

    Sdf::union

    fn Sdf::union(self : Sdf, o : Sdf) -> Sdf

    Vec3

    pub(all) struct Vec3 {
    x : Double
    y : Double
    z : Double
    }

    三维向量。几何内核只做静态求值,所有分量用 Double: 这里的正确性标准是「与解析公式逐点一致」,不是跨后端逐位一致 (后者是 moonroll 的定点数要解决的问题)。

    Vec3::abs

    fn Vec3::abs(self : Vec3) -> Vec3

    Vec3::add

    fn Vec3::add(self : Vec3, o : Vec3) -> Vec3

    Vec3::cross

    fn Vec3::cross(self : Vec3, o : Vec3) -> Vec3

    Vec3::div

    fn Vec3::div(self : Vec3, s : Double) -> Vec3

    Vec3::dot

    fn Vec3::dot(self : Vec3, o : Vec3) -> Double

    Vec3::length

    fn Vec3::length(self : Vec3) -> Double

    Vec3::length_sq

    fn Vec3::length_sq(self : Vec3) -> Double

    Vec3::lerp

    fn Vec3::lerp(self : Vec3, o : Vec3, t : Double) -> Vec3

    Vec3::max

    fn Vec3::max(self : Vec3, o : Vec3) -> Vec3

    Vec3::max_zero

    fn Vec3::max_zero(self : Vec3) -> Vec3

    逐分量 max(v, 0),SDF 盒公式里反复用到。

    Vec3::min

    fn Vec3::min(self : Vec3, o : Vec3) -> Vec3

    Vec3::mul

    fn Vec3::mul(self : Vec3, s : Double) -> Vec3

    Vec3::mul_vec

    fn Vec3::mul_vec(self : Vec3, o : Vec3) -> Vec3

    逐分量乘。

    Vec3::neg

    fn Vec3::neg(self : Vec3) -> Vec3

    Vec3::new

    fn Vec3::new(x : Double, y : Double, z : Double) -> Vec3

    Vec3::normalize

    fn Vec3::normalize(self : Vec3) -> Vec3

    零向量归一化返回零向量:调用方不该靠 panic 处理退化输入。

    Vec3::splat

    fn Vec3::splat(v : Double) -> Vec3

    Vec3::sub

    fn Vec3::sub(self : Vec3, o : Vec3) -> Vec3

    Vec3::zero

    fn Vec3::zero() -> Vec3

    grid_shape

    fn grid_shape(bounds : Aabb, resolution : Int) -> (Int, Int, Int)

    请求 resolution 后实际会用的格点数 (nx, ny, nz)。

    只跟包围盒尺寸和 resolution 有关。想报告「真实的采样密度」时用它, 而不是回显请求值——超过 MAX_GRID_SLOTS 时两者不一样。

    mesh

    fn mesh(sdf : Sdf, bounds : Aabb, opts : MeshOptions) -> Mesh

    mesh_unchecked 的旧名字,保留给 0.1.x 的调用方。

    它不做前置检查;要「保证闭合可切片」请用 mesh_checked。

    mesh_checked

    fn mesh_checked(sdf : Sdf, bounds : Aabb, opts : MeshOptions) -> Result[Mesh, MeshError]

    带前置检查的网格化:要么返回一块闭合、可直接切片的网格,要么返回 拒绝原因,不存在「看起来能用、其实漏面」的第三种结果。

    通过检查时输出满足:每条无向边恰好被 2 个三角形共享(is_watertight), 朝向逐面由梯度决定、以体积符号兜底,空网格不会被当成成功返回。

    检查覆盖:

    • 采样域必须体积为正、坐标有限(DegenerateBounds);
    • 场值必须处处有限(NonFiniteField);
    • 实体必须严格位于采样域内部:6 个面上的采样点全部 f > 0 (SurfaceClipped)——半空间、被裁剪的实体、与域面相切的实体都在 这里被拒;
    • 采样域内必须真有曲面(NoSurface)。

    它不保证的(属于采样精度或输入合法性,不是拓扑问题):

    • 壁厚小于 2 个体素的薄壳:两个格点可能同号,整片壳被漏掉,结果是空 网格(NoSurface)或体积明显偏小;
    • |∇f| 明显偏离 1 的非精确 SDF:体积与法线有偏差,拓扑仍闭合;
    • 自交实体(如管半径大于母线半径的环面):输出闭合但不可打印。

    mesh_unchecked

    fn mesh_unchecked(sdf : Sdf, bounds : Aabb, opts : MeshOptions) -> Mesh

    生成三角网格,不校验采样域与实体的关系。

    采样域小于实体、实体贴住域边界、场值含 NaN 时它照样返回网格——那种 网格会开口或含垃圾三角形。只在「前提已经确认成立」时用它(比如故意 要给半空间做裁剪网格)。要保证闭合请用 mesh_checked。

    resolution 的口径见 plan_grid:先夹到 [2, 512],再按总格点收紧。