rebelle

Rebelle 控制

Rebelle 可模拟真实颜料——水会流动，颜料会颗粒化，厚涂会捕捉光线—— 它的两个可脚本化版本都采用相同的 JSON 事件词汇：

版本	驱动方式	适用场景
/Applications/Rebelle 8.app（Pro）	WebSocket 服务，实时运行	在用户正在查看的应用中绘画、探索、创作一次性作品；以及在没有 Motion IO 时制作动画
/Applications/Rebelle 8 Motion IO.app	-batch-json 文件，近似无头运行	可复现的渲染、动画帧序列、数据图层输入/输出

先检查安装了哪些版本（ls -d /Applications/Rebelle*）——通常只有 Pro。 Pro 二进制文件接受 -batch-json，随后却会静默忽略它（空白画布、无帧，已在 8.3.4 上验证），因此路径 B 仅适用于 Motion IO。

除非任务需要数据图层、16 位输出或无头渲染，否则优先使用实时模式：往返只需几秒，而不是一分钟；你可以随时查看画布，动画也可以实时制作（见路径 B 的最后一段）。

• references/json-events.md — 完整的事件词汇（两种路径都适用）。编写简单笔画之外的内容前请阅读。
• references/websocket.md — 实时协议、未公开的 cmd API，以及实时模式不支持的功能。
• references/batch.md — Motion IO 命令行、数据图层、帧→视频、许可。
• references/assets.md — 查找画笔预设和纸张名称（名称错误时会静默失败）。
• scripts/rebelle_ws.py — 无依赖的 WebSocket 客户端（库 + CLI）。
• scripts/rebelle_events.py — 构建事件文件；封装批处理帧规则和笔画几何辅助函数。
• scripts/rebelle-batch.sh — 运行批处理，并在其实际完成后返回。

路径 A — 通过 WebSocket 实时操作

只有启动 Rebelle 时带上该标志，它才会监听；每个任务开始前无需重启——先检查，再询问：

python3 scripts/rebelle_ws.py --ping     # prints e.g. "Rebelle 8 Pro here"

如果没有响应，请先询问用户再启动：新实例会打开一个空白文档，绘画会直接写入当前打开的作品，且不会进行撤销分组。

"/Applications/Rebelle 8.app/Contents/MacOS/Rebelle 8" \
  -websocket-server-enable \
  -websocket-allowed-ip-addresses "::ffff:127.0.0.1,127.0.0.1" &

允许列表会与套接字的字面地址匹配，而本地客户端会以 IPv6 映射地址 ::ffff:127.0.0.1 连接——只列出普通的 127.0.0.1 会导致自身连接被拒绝（Rebelle 的输出中会出现 ... refused）。

然后从 Python 驱动它——辅助模块是此技能 scripts/ 目录中的普通模块，因此请将该目录添加到路径中（或从该目录运行）：

import sys; sys.path.insert(0, "<this skill>/scripts")
from rebelle_ws import Rebelle
from rebelle_events import catmull_rom, taper

with Rebelle() as r:
    r.event({"event_type": "NEW_ARTWORK", "width": 1200, "height": 800, "units": "px"})
    r.event({"event_type": "SET_BRUSH", "tool": "WATERCOLOR", "preset": "Watercolor/Round",
             "size": 55, "water": 70, "opacity": 90, "paint_type": "PAINT",
             "color": {"r": 30, "g": 90, "b": 200}})
    r.stroke(catmull_rom([(150, 450), (400, 250), (800, 600), (1050, 320)]),
             pressure=taper(0.95))
    r.event({"event_type": "SIMULATION", "repeats": 20})   # let the water spread
    r.sync()                                   # wait until Rebelle is really finished
    r.export("/tmp/check.png")                 # then Read the PNG

sync() 会发送一个 BOOKMARK 并等待回显。没有其他事件会确认操作，因此不调用它，就可能导出仍在绘制笔画的画布。

NEW_ARTWORK 是唯一绝不能与其他操作竞速的事件：画布重新初始化期间， Rebelle 会丢弃下一条消息——通常是你的 SET_BRUSH；没有画笔的笔画会让刚启动的应用崩溃（bad_optional_access，8.3.4）。调用 Rebelle.event() 后会阻塞，直到收到书签（ready()），因此请通过它发送事件，而不要直接调用 send_text()；手动编写的客户端也必须采用相同的轮询方式。

实时模式下会拒绝 SAVE/LOAD 事件——唯一可用的导出方式是 export()（cmd: export_canvas），它会写出用户所见的合成画布。

路径 B — 使用 Motion IO 批量渲染

python3 build_painting.py                  # writes events.json via rebelle_events.Doc
bash scripts/rebelle-batch.sh events.json out/

在 macOS 上，Motion IO 不会自行退出，只会在标准输出中以 batch frame end: i/n 报告进度，因此务必通过 rebelle-batch.sh 运行——它会等待 i == n，显示 ERROR: 行，然后停止应用。

一帧 = 一张输出图像 + 一次隐式流体模拟步进。因此，动画制作很自然：画一些内容，结束该帧，然后重复。

from rebelle_events import Doc, catmull_rom, taper

d = Doc(1200, 800, paper={"preset": "Handmade/HM01 Handmade", "deckled_edges": True})
d.set_brush("WATERCOLOR", "Watercolor/Round", size=55, water=70, opacity=90,
            paint_type="PAINT", color=(30, 90, 200))
d.stroke(catmull_rom([(150, 450), (400, 250), (800, 600), (1050, 320)]), pressure=taper())
d.frame()                    # one animation frame ends here
d.simulation(15, frames=20)  # 20 frames of the paint spreading and drying
d.write("events.json")

让批处理正常工作的帧规则

Doc 已经应用了这些规则；手写 JSON 也必须遵守，否则运行会永远卡住或悄无声息地 丢失工作。读取第一帧时，Motion IO 仍在完成启动流程，只有以下帧结构能正常通过：

1. 帧 0 是预热帧，必须加载画笔。 在此帧中执行 SET_BRUSH 就足以让启动完成。 只有 BOOKMARK 的帧——或空帧——会在处理任何帧之前造成死锁。
2. NEW_ARTWORK 必须放在帧 1，不能放在帧 0。 放在帧 0 会被无声丢弃， 最终悄悄使用 Rebelle 的默认 A4 画布（2339×1654，200 dpi）。
3. NEW_ARTWORK 所在帧中必须还有后续内容（另一个 SET_BRUSH 即可）。 在 NEW_ARTWORK 后立即结束的帧会造成死锁。
4. 不要在 NEW_ARTWORK 所在帧绘画——画布重新初始化时会擦掉绘画内容。请从 下一帧开始绘画（Doc.first_content_frame 是实际内容开始的帧； 将它传给 ffmpeg -start_number）。

如果必须完全跳过 NEW_ARTWORK，-input artwork.reb 会打开已有作品， 这是修正画布尺寸最稳妥的方法——但用户必须先保存一份作品。

没有 Motion IO？直接实时渲染同一个 Doc。 rebelle_ws.py --send events.json --frames-out out/ 会通过 WebSocket 逐帧重放，并按批处理编号导出 frame_0000.png…，因此 batch.md 中的 first_content_frame 和 ffmpeg 配方无需改动。实时运行时，流体模拟按实际时间运行，而不是每帧推进一步， 因此湿画区域需要明确添加 SIMULATION 重复操作，不要依赖帧数。

画出绘画质感

• 坐标单位是画布像素，y 轴从左上角向下递增，也可以超出画布范围——让笔触从 画布外开始和结束，即可绘制从边缘到边缘的水洗效果。
• POINTER_MOVE 会绘制前一段笔触，因此笔触必须在最后一次移动的位置以释放操作结束。 stroke()/stroke_events() 会处理这一点；手写事件经常会因此丢失最后一段笔触。
• 按预设校准画笔宽度。 size（UI 滑块）和 size_px 都无法预测实际绘画宽度： 在 8.3.4 中，Round 画笔的 size_px 为 200 时宽度约为 150 px，Mop 约为 50 px， Flat 约为 200 px；而 Round 画笔的 size_px 为 50 时宽度仅约为 6 px。每个预设先画一条 测试笔触，导出并测量，然后再调整尺寸——在确定构图之前完成。
• 路径采样要密集。 Rebelle 会在点与点之间插值，所以四个点只能形成平滑但普通的曲线； 使用每段约 16 个点的 catmull_rom()，才能充分展现画笔纹理、间距和压力效果。
• 改变压力。 恒定的 0.9 看起来像机器绘制。taper() 会让两端变细， ramp() 会逐渐加深——这本身就足以让绘图和笔触产生大部分差异。
• 湿媒介需要模拟时间。 水只会在模拟步中扩散：先绘画，再花若干帧（或使用 {"event_type":"SIMULATION","repeats":N}）让颜料晕开；在绘制不应渗入下层的图层之前， 使用 DRY/FAST_DRY。
• 像真实绘画一样逐层叠加颜色：先画浅色水洗层，执行 DRY，再在上面叠加 深色罩染层。SET_ENGINE_PARAMS 可控制吸收性、滴流和颗粒效果。
• 根据模拟效果而非名称选择画笔：WATERCOLOR 用于水洗和晕染， INK_PEN 用于可重新湿润的线条，OIL_AND_ACRYLIC 用于厚涂和画布上的颜色混合， PENCIL/PASTEL 用于干性纹理，AIRBRUSH 用于柔和渐变。

始终查看结果

Rebelle 几乎不会返回任何信息，而错误的纸张或预设会生成看似合理、实则完全错误的图像。每完成一个有意义的步骤后，都要导出并读取 PNG，就像查看画布一样：实时操作时使用 r.export(path)，批量操作时读取最后渲染的帧。把它当作一幅画来评判——覆盖范围、颜色，以及水彩效果是否生效——然后迭代。用户需要完成的作品时，再以完整尺寸导出（使用 rgba_canvas，或使用带 scaling 的 SAVE 导出 NanoPixel 尺寸的图像）。

使用前值得了解的注意事项

• 预设名称错误 → 明确报错；纸张名称错误 → 没有提示。 先根据文件系统确认两者的名称（assets.md）；官方快速入门中的 "Default/HM01 Handmade" 在 Rebelle 8 中本身就是错误的。
• SET_BRUSH 不带 preset 时不会绘画，并会记录 Preset for brush was not set。
• 一次只能运行一个 Rebelle。 同时运行 GUI 版本和 Motion IO 会惹上麻烦；启动另一个之前，先停止其中一个。
• 强制停止应用会在 ~/Library/Application Support/Escape Motions/Rebelle 8/ 中留下 Data/Sessions/<pid>/ 文件夹。这不会造成问题，但每个文件夹大小可达数十 MB，并会不断累积——应该告知用户，而不是擅自删除。
• 颜色是 8 位 RGB 对象（{"r":…,"g":…,"b":…}），尽管引擎使用 16 位混色；只有 Motion IO 导出的 .exr 文件支持 16 位输出。
• 文档领先于实际构建版本。 8.3 文档称可通过 WebSockets 使用 SAVE/LOAD；已发布的 8.3.x 构建版本（已检查 8.3.0 和 8.3.4）却会拒绝这些命令。应相信自己查看过的导出结果，而不是文档中的行为描述。
• 动画许可附带条件——在协助商业制作之前，请查看 batch.md 末尾的说明。

安全

路径 B 不会打开任何内容——Motion IO 读取文件并渲染。路径 A 则会：使用 -websocket-server-enable 启动 Rebelle，会将其变成一个可执行其事件词汇中代码的服务器。要求用户重新启动应用之前，请先说明这一点。

• 服务器监听 127.0.0.1:8265（REBELLE_WS_PORT），并会将收到的所有事件 JSON 应用到用户当前打开的作品上；export() 则会以用户的权限写入文件。没有身份验证：任何本地进程以及共享机器上的其他用户都能在用户的画布上绘画。
• -websocket-allowed-ip-addresses 是唯一的访问控制方式，且它匹配的是套接字对端地址。请将其限制为回环地址（::ffff:127.0.0.1,127.0.0.1）——绝不要添加局域网地址，否则画布会暴露到网络中。请注意，用户自己浏览器中的网页也是回环对端，而且 WebSocket 连接不受 CORS 限制，因此不要指望允许列表能将其排除在外。
• 要停止服务，请退出 Rebelle，然后在不带此标志的情况下重新启动。该标志只对本次启动生效，因此正常启动的 Rebelle 不会监听任何连接。