#moon_rough

#定位

#安装

moon add sayoi7799/moon_rough

import {
  "sayoi7799/moon_rough",
}

git clone https://github.com/sayoi7799/moon_rough.git

moon test --target js

moon run src/examples/gallery > gallery.svg

#用法

fn main {
  let gen = @moon_rough.generator()
  let rect = gen.rectangle(
    10.0, 10.0, 200.0, 100.0,
    options=@moon_rough.Options::new(
      seed=42,
      fill="#e66",
      fill_style=CrossHatch,
      roughness=1.5,
    ),
  )
  // 和后端无关的数据：OpSet 列表，每个 op 是 Move / LineTo / BCurveTo
  for set in rect.sets {
    println("\{set.kind.name()}: \{set.ops.length()} ops")
  }
  // 转成 SVG：每个 OpSet 一个 <path>，整个 Drawable 一个 <g>
  println(@moon_rough.svg_document(220.0, 120.0, @moon_rough.drawable_to_svg(rect)))
}

#API 对照

#给 diago 的流程图加手绘风格

let svg = @diago.compile(source)
let sketch = @diago_sketch.sketchify(svg, seed=7)

#Canvas 后端和浏览器演示页

// js 目标。ctx 是 JavaScript 传进来的 canvas.getContext("2d")
pub fn paint(ctx : @canvas.JsContext) -> Unit {
  let rc = @canvas.RoughCanvas::new(ctx, options=@moon_rough.Options::new(seed=42))
  ignore(
    rc.rectangle(
      10.0, 10.0, 200.0, 100.0,
      options=@moon_rough.Options::new(fill="#e76f51", fill_style=CrossHatch),
    ),
  )
}

• 绘制逻辑 draw(ctx, drawable) 按 canvas.js 逐句对应，写在 Canvas2D trait 上（save、restore、beginPath、moveTo、lineTo、bezierCurveTo、stroke、fill 和描边 / 填充 / 线宽 / 虚线属性），在所有目标上都能编译。
• JsContext 是它在 js 目标上的绑定（extern "js" 调用 CanvasRenderingContext2D）。Recorder 是另一个实现，只记录调用，测试用的就是它。
• wasm-gc 和 native 上没有真正的 canvas 绑定。 wasm-gc 需要宿主提供导入函数，目前没做；trait 让以后补一个实现很容易。
• 测试：预期值来自官方 rough.js。scripts/gen_fixtures.mjs 用一个会记录每次方法调用和属性赋值（并且禁止读取任何属性）的假 canvas 运行真正的 rough.canvas()，616 个 Drawable、40,147 次调用，顺序和每个数字（按位）都和 MoonBit 一致，三个后端都是。

node examples/web/build.mjs

node examples/web/serve.mjs

• 抖动线条：每一帧用 seed + 帧号 把同一幅图（矩形、椭圆、箭头、圆、一条路径，带五种填充）重画一遍，线条就像手绘动画一样抖动。
• 描线：只画 Drawable 的前 k 个 op，k 从 0 增长到全部，笔就一笔一笔写出图形。draw_prefix 在 src/examples/web_demo 里，不在发布包里。

#支持范围

#与 rough.js 的差异

1. Math.random() 可以注入。 rough.js 在三处用未加种子的 Math.random()：seed 为 0 时、dots 填充的点位置、hachure 的一个回退分支。所以 rough.js 的 dots 填充即使设了 seed 也不可复现。moon_rough 把这些调用交给 RandomSource：默认是固定种子（DEFAULT_FALLBACK_SEED）的 Park–Miller 序列，传 RandomSource::park_miller(n) 可以换种子（测试就是这样对照 dots 的）。注意默认序列每次运行起点相同，并不像 Math.random() 那样每次不同；需要每次不同时请自己提供 RandomSource::new(f)。
2. 不修改调用方的数据。 hachure-fill 会原地旋转传入的多边形再转回来，rough.js 用户传进 polygon() 的点会被改动最后几位。moon_rough 内部复制一份，并在内部照样保留这种改动（rough.js 后续步骤依赖它）。
3. rough.js 不会结束的输入，这里会结束：
   • 起止角相同的 arc（以及任何角度步长 ≤ 0 的循环）：跳过该循环；
   • dashOffset + dashGap = 0 的 dashed 填充、zigzagOffset = 0 的 zigzag-line 填充：不画这条线上的填充；
   • Z 后面跟数字（如 M 1 1 Z 5）：path-data-parser 会无限循环，这里 raise NumberAfterClose。
4. rough.js 抛异常的输入： 非法路径数据 raise PathError（InvalidCharacter(偏移) / ParamNotANumber / EndedShort）；带图案填充的空 polygon([]) 不画填充（hachure-fill 会抛 TypeError）；curve_to_bezier 少于 3 个点时 raise CurveTooShort。
5. 以 npm 实际加载的 bundle 为准。 generator.path() 的第三个 replace 在 bin/ 里是 '/(\s\s)/g'，在 bundled/rough.cjs.js 里是 "/(ss)/g"（都是字符串而非正则，正常路径下都不起作用）。这里照 Node 实际运行的 bundle 实现。
6. 类型收紧： seed 是 32 位 Int（rough.js 接受任意 number）；fixed_decimal_place_digits 限制在 0–100（JS 超出范围会抛 RangeError）；fill_style 是枚举，FillStyle::from_name 和 rough.js 一样，未知名称按 hachure 处理。
7. 未移植： DOM 版 RoughSVG（改为输出字符串）、OpSet 里生成器从不填写的 size / path 字段，以及 _curve 的 closePoint 分支（4.6.6 的所有调用方都传 null）。
8. roughness < -1 的 path： points-on-path 会用负的简化距离无限递归，这里同样不支持。

#怎么保证一致

• 随机数顺序。 rough.js 很多地方在一个表达式或参数列表里多次取随机数，JS 从左到右求值，差一次后面就全错。移植时每次取随机数都单独写成一条语句，按 JS 的求值顺序排列（例如 _bezierTo 里终点的随机数先于控制点，ellipse 的 _offset(0.1, _offset(0.4, 1, o), o) 内层先算）。fixture 生成器包装了 Math.imul（bundle 里只有 Random.next 用它）和 Math.random，记录每个用例取了多少个随机数，测试先比较次数，再比较数值。
• 对象共享语义。 rough.js 的随机数生成器懒创建在 options 对象上；{ ...o } 复制时，已存在的会被共享，还不存在的则各自新建；cloneOptionsAlterSeed 用 seed + 1 重新开始；不传 options 时，所有图形共用生成器的默认 options 对象，随机状态跨调用延续。MoonBit 里带 mut 字段的 struct 是引用类型，{ ..o, f: v } 复制的是指针，行为和 JS 相同。点也是可变的引用对象，JS 共享数组的地方 MoonBit 也共享（比如 simplify 对单点集合返回 [p, p]，hachure 会把它旋转两次）。
• 浮点函数。 native 后端上，core 的 sin / cos 调用 C 库，约 2.5% 的参数与 V8 差 1 ulp；js 后端调用宿主 Math，在 arm64 上也差 1 ulp。这种差别会翻转离散判断（循环终止、Math.round、ceil / floor 计数、toFixed(9)），使 op 数量都对不上。所以 jsmath 在 js 和 native 上改用 fdlibm 算法（与 V8 和 core 的 wasm 实现相同）。另外按 ECMAScript 规范精确实现了 toFixed、Math.round、Math.min/max（含 NaN 和 ±0 的处理），并验证了 Math.pow(x, 2) === x * x、% 与 JS 一致。

#测试

moon test --target js

moon test --target wasm-gc

moon test --target native

#误差报告

• 用 scripts/package-lock.json 锁定的 roughjs 4.6.6 重新生成 fixtures，和仓库里的比较，必须完全一致；
• 在 macOS（arm64）和 Windows 上跑同样的测试，暂时不阻塞，因为 clang 可能把 a * b + c 合并成 FMA，需要先看一轮结果；
• 用最新版 MoonBit 跑 check 和测试，提前发现兼容性问题，同样不阻塞。

#性能

• 只计时生成，不含画到 canvas 或转 SVG（最后两行除外，它们测的就是转 SVG）。输入在计时开始之前做好。
• 两边用同一个确定性的随机数生成器，生成同样的 10,000 个图形（9 种图形，无填充或 6 种填充样式，随机 roughness、bowing、角度、间距、seed）和同一条 300 段的复杂路径（绝对和相对命令、平滑曲线、圆弧、多个闭合子路径）。官方 rough.js 对这些输入生成的 op 数量和所有数值之和，和 moon_rough 的逐位相同（src/perf/checksum_test.mbt，预期值由 scripts/gen_fixtures.mjs 生成），所以比的是同样的工作。
• moon_rough 用 moon bench --release，每个基准是 10 批，每批至少 100 ms。Node 的脚本照同样的方法计时：预热后把批次调到至少 100 ms，取 10 批。dots 填充只测 500 个图形，因为每个图形有成百上千个点。
• dots 填充的点位置来自没有种子的 Math.random()，两边画出的点不同，所以它不在校验和里（校验和里它用同一个固定序列）；这一行只比时间。
• SVG 那两行：官方的 RoughSVG 需要 DOM，Node 里没有，所以 Node 一侧用 opsToPath 加字符串拼接写了一个输出相同字符串的版本（两边字符串的总长度相同，也在校验里）。

• 三角函数（dots 填充、椭圆、圆、圆弧）。 1000 次 sin 加 cos：20 µs / 169 µs / 24 µs / 101 µs。为了在所有环境下得到同样的结果，moon_rough 自带了 fdlibm 的实现，而不是调用宿主的 Math。在 js 目标上，生成的 JS 里 UInt64 是用 BigInt 实现的，fdlibm 每次取浮点数的高 32 位都要走一遍；每次调用还要分配一个小数组。10,000 个椭圆：33 ms / 49 ms / 14 ms / 52 ms。
• SVG 输出。 其中的 escape_attribute 逐字符处理整段路径数据（每个图形平均 16 KB），对全部 op set 做一遍：26 ms / 987 ms / 520 ms / 412 ms，在 js 上占 SVG 输出时间的约四成。保留两位小数的 to_fixed 为了和 JavaScript 的 toFixed 完全一致，用大整数精确实现：对 140 万个数 96 ms / 197 ms / 263 ms / 1.35 s，这是 native 上这一行慢 6.9 倍的主要原因。ops_to_path：0.97 s / 1.07 s / 1.48 s / 2.0 s。
• native 整体偏慢。 大多数项目比 rough.js 慢 1.2 到 2.4 倍。release 构建用 cl /O2 /MT，并且定义了 MOONBIT_ALLOCATOR_SYSTEM（用系统的 malloc），而代码里有大量小对象（点、op、数组）。这是我对原因的判断，没有换分配器验证过。

node scripts/bench.mjs

moon bench -p sayoi7799/moon_rough/perf --target wasm-gc --release

#重新生成 fixtures

cd scripts && npm ci && npm run gen

• 来源：scripts/package.json + package-lock.json 锁定 roughjs 4.6.6，以及 hachure-fill 0.5.2、path-data-parser 0.1.0、points-on-curve 0.2.0、points-on-path 0.2.1（通过 overrides 固定）。脚本启动时会检查这些版本。
• Drawable 用例用 Node 调用 require('roughjs')（即 bundled/rough.cjs.js）的 rough.generator() 生成，不需要浏览器；底层用例直接调用各依赖包和 roughjs/bin/math.js。
• Math.random 被替换成固定的 Park–Miller 序列（seed 1234567），测试注入同一序列。
• 只生成某几类：node gen_fixtures.mjs random jsmath path_data curve hachure core_shapes core_fills core_random core_edge svg。
• 输出确定，重新生成不会产生 diff。每个用例的数据上限为 6 万字符（极密的填充会产生几 MB 的 op），生成器会检查每种"图形 × 填充"组合仍被覆盖。

#移植来源和许可证