Dith 是做什么的?
dith 是一个确定性抖动(Dithering)CLI,专为代理构建。每个命令都支持 --json,输出精确匹配调色板,并返回机器可读的报告。相同的输入和标志始终产生字节完全相同的文件。
设置
- 使用
dith --version检查二进制文件是否存在。- 在 dith 源码目录中(未全局安装),通过
cargo run --release -- <args>运行(或当mbx可用时,使用mbx run -- <args>)。 - 如果 dith 缺失,告知用户并从 references/cli.md 提供安装命令。在安装前等待用户批准。
- 在 dith 源码目录中(未全局安装),通过
- 当确切集合重要时,不要依赖记忆中的目录。向二进制文件询问:
dith list presets|algorithms|palettes|generators|formats --json,可通过--tag <substr>或--category <name>进行筛选。dith capabilities获取完整的命令清单、参数范围以及默认配方(约 40 KB,因此当只需一个目录时,优先使用list)。
核心工作流程
- 理解源文件。 对于现有图像,运行
dith inspect <image> --json。它会报告尺寸、透明度、亮度百分位数(p5/p50/p95)、dynamic_range、主色以及带有即用命令的预设推荐。 - 从样式指南中选择起点。 当方向未定时,先渲染一个联系表并查看:
dith compare <image> -o sheet.png --presets mac-classic,editorial-print,risograph,film-stipple --json - 首先验证复杂的标志集,使用
--dry-run --json。这能捕获错误值并在不写入文件的情况下显示计划的output_dimensions。 - 渲染:使用
apply、generate、animate或batch,始终带上--json。单文件命令默认会覆盖已有输出。当现有文件不得被触碰时,添加--no-clobber;在batch中,它应用于每个文件。 - 在报告成功之前进行验证。 参见验证结果。
- 使外观可重现(当该外观将被重用时)。传递
--emit-recipe(向报告中添加recipe对象)或--save-preset <name>(写入.dith/presets/<name>.json)。
选择外观
从预设开始,然后覆盖单个标志。显式标志始终优先于预设。
| 目标 | 起点 | 备注 |
|---|---|---|
| 经典 1 位 Mac / 社论肖像 | --preset mac-classic (atkinson) | Atkinson 丢弃 2/8 的误差,因此高光保持通透。在柔和照片上添加 --sharpen 0.4。 |
| 精致的单色印刷 / 报纸 | --preset editorial-print (ostromoukhov) | 误差扩散系列中最平滑的渐变。 |
| 胶片点刻,无网格伪影 | --preset film-stipple (blue-noise) | 最佳的通用现代外观;在动画中也很稳定。 |
| Risograph 海报 | --preset risograph, risograph-red, risograph-duo | 在温暖纸张上的双色调和双滚筒套印效果。 |
| 漫画 / 小杂志半色调 | --preset halftone-zine | 配合 --format svg --svg-shape circle 实现矢量网点。 |
| Game Boy / 像素艺术 | --preset gameboy, pico8 | 有序 Bayer 加上厚实的 --pixel-size。 |
| CRT / 终端辉光 | --preset crt-amber, phosphor | 暗键图像最适合此效果。 |
| 雕刻 / 木刻 | --preset woodcut, --algorithm crosshatch | 线屏;用 --pattern-scale 调整。 |
| 蓝图 / 技术图纸 | --preset blueprint | 普鲁士蓝和粉笔双色调。 |
| 保留照片自身的颜色 | --preset lo-fi-photo 或 --auto-palette N | 从图像中提取 N 种 Oklab 颜色(2–64)。 |
| 精确的品牌色 | --colors "#0f172a,#2563eb,#f5efe6" | 可与任何算法或预设组合。 |
| 霓虹英雄渐变 / 深色 UI | --preset vapor-mesh 结合 generate mesh |
references/catalog.md 包含每个预设、调色板、算法和生成器,以及何时使用它们。
工艺规则
- 抖动前先调整色调。 抖动会放大平坦或浑浊的输入。
- 低
dynamic_range(约低于 0.5)或狭窄的 p5–p95 范围:添加--auto-levels或--contrast 0.1..0.3。 - 柔和照片转为 1 位或 Atkinson:
--sharpen 0.3..0.6。 - 暗部中间调:
--gamma 0.7..0.9(低于 1 的值会提亮)。明亮、过曝的输入:--gamma 1.2..1.5。 - 调整整体密度:
--bias(负值更暗,正值更亮,范围 ±0.5)。
- 低
- 先确定尺寸。 使用
--max-dim(或--width/--height加上--fit contain|cover|stretch)限制大小。抖动模式是逐像素的,因此抖动的图像之后绝不能调整大小。应改为在最终显示尺寸下渲染。 - 粗像素。
--pixel-size N会降采样、抖动,然后最近邻上采样,因此输出尺寸不变。 - 有序屏幕尺寸。
--pattern-scale 2..4可放大 Bayer、半色调、线和蓝噪声单元,以获得更大胆、更具图形感的纹理。 - 色彩空间。 保持默认的
oklab。仅为了模拟旧硬件的数学计算而使用srgb;linear是物理上的线性光。 - 确定性。 随机算法(
blue-noise、random、ign)、--noise和--auto-palette使用--seed(默认为 42)。更改种子以获得变体,并保持固定以实现可重复性。 - 透明度。 带有 alpha 通道的 Logo 和图标:
--alpha-mode preserve保留 alpha 通道,threshold提供清晰的 1 位蒙版,dither提供点刻淡化效果,flatten --background "#hex"合成到背景色上。 - 关闭预设的某些部分。 大多数单色预设会开启
--grayscale和--auto-levels。使用--no-grayscale、--no-auto-levels和--no-serpentine来禁用预设开启的内容。
输出格式
格式从 -o 扩展名推断;传递 --format 可覆盖。
- PNG(默认):无损且像素精确。几乎所有情况下的正确选择。
- WebP:面向网页的紧凑格式。JPEG 会破坏抖动模式,因此除非用户坚持,否则切勿将其用于抖动输出。
- SVG:
--svg-shape rect(游程合并矩形,最小)、circle(半色调网点)或dot(内嵌网点)。--svg-skip-bg会丢弃主背景色以便叠加。SVG 随像素数增长,圆形比矩形大得多,因此将--max-dim保持在 120–320 左右。 - 终端文本:
--format braille|ascii配合--text-width N。-o可选,文本输出到 stdout。 - 标准输入/输出:传递
-作为输入或-o -。
动画
dith animate 接受四种类型的输入之一:
- 图案名称(
sphere、waves、mesh、plasma等),用于无缝程序循环。每个图案运动方式不同(例如球体静止而光照围绕其旋转);dith list generators --json的motion字段描述了这一点。在完整渲染前,导出一个小型精灵表(--anim-format spritesheet --sheet-cols <frames> --canvas-width 160 --canvas-height 120)并查看,可廉价检查运动效果。 - 动画 GIF、APNG 或 WebP,用于重新抖动
- 多个图像文件作为帧序列
- 单个静态图像,此时会获得胶片沸腾效果(对于这种情况,
--temporal boil是默认设置)
输出为 .gif(精确调色板,最小)、.apng(全 RGBA)、通过 --anim-format spritesheet --sheet-cols N 生成的精灵表 .png,或通过 --frames-dir DIR 生成的编号 PNG 帧。
- 闪烁。
--temporal locked(默认)固定帧间的屏幕和种子,但它仅在使用逐像素算法时使静态区域稳固:有序屏幕(bayer*、半色调、线屏)、blue-noise、ign、random和threshold。误差扩散(floyd-steinberg、atkinson、stucki、riemersma等)会将每个变化传递给相邻像素,因此任何移动都会导致点刻在移动区域下方和右侧闪烁。Atkinson 闪烁最少。dith list algorithms --json的temporally_stable字段说明了哪些算法是稳定的。boil有意产生手绘般的闪烁;设置--boil-rate 2以“两帧动一次”的方式动画。grain每帧重新随机化点刻。 - 无缝循环。 程序化图案通过构造实现循环。对于扫描效果,使用
--sweep-mode pulse或--ping-pong。 - 扫描随时间变化参数:
--sweep-bias、--sweep-brightness、--sweep-contrast、--sweep-gamma、--sweep-strength、--sweep-pixel-size,每个都写为START..END。使用--easing塑造它们,并通过--hold-start和--hold-end在关键帧上暂停。 - 调色板。 默认使用共享的全局调色板,保持颜色稳定。仅当镜头颜色变化很大时,才使用
--per-frame-palette。 - 时间控制。 帧数上限为 2..=240。
--duration S是--frames的替代方案(帧数 = S × fps);同时传递两者是错误的。GIF 延迟以 10 毫秒为步长存储,因此--fps 10|20|25|50能提供精确的 GIF 时间(15 fps 变为每帧 70 毫秒)。APNG 是精确的。 - 大小。 文件大小随帧数 × 像素数增长,且抖动噪声几乎不压缩。
- GIF 会自动进行增量编码:第一帧后的每一帧仅存储变化部分。因此,锁定逐像素算法且具有静态区域的 GIF 远比误差扩散或
boil/grain小得多,后者几乎每帧每个像素都会变化。 - 要达到预算限制,传递
--max-size 2MB(也可以是500KB、1.5MiB或字节数)。Dith 会缩小帧尺寸,保持帧数和 fps,直到文件合适,并报告size_fit_scale(1.0 表示未改动)。如果size_fit_scale返回的值很小(约低于 0.5),结果可能太小而无法使用。改用其他方式降低大小:更少的帧、锁定的有序算法或更少的调色板颜色。 - 保持程序化画布适中(默认为 480×360)。
- GIF 会自动进行增量编码:第一帧后的每一帧仅存储变化部分。因此,锁定逐像素算法且具有静态区域的 GIF 远比误差扩散或
- 程序化颜色。 没有
--stops时,图案使用简单的近黑 → 近白渐变。传递--stops来有意识地选择源色调;这通常看起来更好,尤其是使用彩色调色板时。 - 程序化源上的预设。 预设针对照片调整。对于
generate、animate <pattern>以及compare/preview --pattern,dith 会跳过其自动色阶、对比度和锐化,因为这些会裁剪平滑渐变导致平坦色块。显式传递这些标志以强制应用它们。
验证结果
阅读 JSON 报告,而非假设成功:
"status": "ok"。batch可能返回"partial_failure"并带退出码 1;检查failed和每个items[].error。output_dimensions(对于图像)或frame_count、frame_dimensions和total_duration_ms(对于动画)与意图匹配。bytes_written > 0;在--dry-run时为0。palette_colors和color_usage符合预期。如果一种颜色覆盖超过约 95% 的像素,图像几乎空白:调整--bias、--gamma或--contrast,或尝试--invert。
当审美重要时,查看输出。如果有图像查看工具,打开 PNG 文件;否则添加 --preview 以在 preview_braille 中获得盲文缩略图。对于动画,导出精灵表或 --frames-dir 并查看 PNG 帧。对于 SVG,使用相同的标志渲染 PNG 并查看。
错误
使用 --json 时,错误输出到 stderr,格式为 {"status":"error","code","message","suggestion","valid_values"?}。
- 退出码 2:来自您的无效输入。代码包括
CLI_USAGE_ERROR、INVALID_ARGUMENT(超出范围的值;消息中包含范围)、UNKNOWN_PRESET及类似代码(valid_values列出选项)以及OUTPUT_EXISTS(--no-clobber遇到现有文件)。修正标志后重试。 - 退出码 1:运行时或 I/O 故障(
RUNTIME_ERROR),例如输入缺失或文件无法解码。batch在任何项目失败时也退出码 1。
交互式 vs 非交互式
--view、preview(默认全屏)和 compare --view 是交互式的 Kitty 协议查看器,专为终端前的人类设计。在非交互式代理 shell 中,渲染到文件,使用 --preview 或 --format braille,或传递 --inline(例如 dith preview img.png --inline --mode braille --cols 60)。仅当用户明确希望在自己的终端中观看时,才使用全屏查看器。
参考
- references/cli.md:每个子命令和标志,包括范围、默认值和 JSON 报告字段。
- references/catalog.md:预设、调色板、算法和生成器,以及何时选择每一个。
- references/recipes.md:针对常见任务(网页主图、头像、Logo SVG、社交卡片、CSS 精灵表、展示 GIF、品牌预设、批量导出)的即用配方。