Community图像github.com

Dith

使用 dith CLI 对照片和 Logo 进行半色调(抖动)处理,生成程序化纹理,并根据可重复配方导出自循环复古或印刷风格动画。

Dith 是什么?

Dith 是一个专为 AI 代理设计的确定性抖动(Dithering)命令行工具。它强调可重复性和机器可读性:每个命令都支持 `--json` 输出,并返回精确的报告。同样的输入和参数总能生成字节完全一致的文件,非常适合需要可再现结果的自动化工作流。 该工具支持多种平台,包括 Mac、Linux 等,并无缝集成到基于代理的 shell 中。其工作流程包括:通过 `dith inspect` 分析源图像,从预设样式指南(如经典Mac、社论印刷、胶片点刻、Risograph 等)中选择起点,使用 `--dry-run` 验证复杂参数,然后执行 `apply`、`generate`、`animate` 或 `batch` 命令。动画功能支持程序化图案、GIF/APNG 重抖动、帧序列以及带可调闪烁模式的静态图像。 Dith 的独特优势包括:字节级确定性(利用种子控制随机算法)、丰富的输出格式(PNG、WebP、SVG,甚至终端徽章),以及通过 `--emit-recipe` 或 `--save-preset` 实现的可重复性。它还能通过 `dith list` 和 `dith capabilities` 进行自省,方便代理动态查询可用的预设、算法、调色板和生成器,无需依赖硬编码目录。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lassejlv/dith/tree/HEAD/skills/dith

Installed? Explore more 图像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Dith 是做什么的?

dith 是一个确定性抖动(Dithering)CLI,专为代理构建。每个命令都支持 --json,输出精确匹配调色板,并返回机器可读的报告。相同的输入和标志始终产生字节完全相同的文件。

设置

  1. 使用 dith --version 检查二进制文件是否存在。
    • 在 dith 源码目录中(未全局安装),通过 cargo run --release -- <args> 运行(或当 mbx 可用时,使用 mbx run -- <args>)。
    • 如果 dith 缺失,告知用户并从 references/cli.md 提供安装命令。在安装前等待用户批准。
  2. 当确切集合重要时,不要依赖记忆中的目录。向二进制文件询问:
    • dith list presets|algorithms|palettes|generators|formats --json,可通过 --tag <substr> 或 --category <name> 进行筛选。
    • dith capabilities 获取完整的命令清单、参数范围以及默认配方(约 40 KB,因此当只需一个目录时,优先使用 list)。

核心工作流程

  1. 理解源文件。 对于现有图像,运行 dith inspect <image> --json。它会报告尺寸、透明度、亮度百分位数(p5/p50/p95)、dynamic_range、主色以及带有即用命令的预设推荐。
  2. 从样式指南中选择起点。 当方向未定时,先渲染一个联系表并查看: dith compare <image> -o sheet.png --presets mac-classic,editorial-print,risograph,film-stipple --json
  3. 首先验证复杂的标志集,使用 --dry-run --json。这能捕获错误值并在不写入文件的情况下显示计划的 output_dimensions。
  4. 渲染:使用 apply、generate、animate 或 batch,始终带上 --json。单文件命令默认会覆盖已有输出。当现有文件不得被触碰时,添加 --no-clobber;在 batch 中,它应用于每个文件。
  5. 在报告成功之前进行验证。 参见验证结果。
  6. 使外观可重现(当该外观将被重用时)。传递 --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)。
  • 程序化颜色。 没有 --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、品牌预设、批量导出)的即用配方。

相关技能