Community影像github.com

Dith

使用 dith CLI 對照片和標誌進行抖色、生成程序化紋理,並從可重現的配方中導出循環的復古或印刷動畫。

Dith 是什麼?

Dith 是一個專為 AI 代理設計的確定性抖色 CLI 工具。其核心設計原則是可重複性與機器可讀性:每個命令都支援 `--json` 輸出,產生調色板精確的結果,並返回結構化報告。相同的輸入和標誌始終產生位元組完全相同的檔案,非常適合自動化工作流程和需要一致輸出結果的場景。 Dith 支援多種平台(終端機、腳本、CI/CD 系統),並提供完整的命令集來檢查影像、比較抖色效果、產生程序化紋理,以及建立循環動畫。其工作流程從 `dith inspect` 開始,分析影像並提出預設建議,接著透過 `dith apply` 或 `dith animate` 進行渲染,最後使用 `--json` 報告驗證結果。 Dith 的優勢在於其豐富的樣式選項,包括經典 Mac 風格、編輯印刷、電影點畫、Risograph、Game Boy、CRT 等預設,並支援 SVG、WebP、ASCII 藝術等多種輸出格式。動畫功能支援無縫循環、參數掃描,並可透過 `--max-size` 控制檔案大小。所有隨機過程都使用固定的 `--seed`(預設 42)確保確定性,讓您每次都能獲得完全相同的結果。

相容平台~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 是一個為代理設計的確定性抖色 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 通道的標誌和圖示:--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 是可選的,文字會輸出到標準輸出。
  • 標準輸入/標準輸出:傳遞 - 作為輸入或 -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*、halftone、line 螢幕)、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 會自動進行增量編碼:第一個影格之後的每個影格僅儲存變化的部分。因此,具有靜態區域的鎖定逐像素演算法,其檔案大小遠小於幾乎每個像素都變化的誤差擴散或 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 並檢視該 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:針對常見任務(網頁主圖、頭像、標誌 SVG、社交卡片、CSS 精靈表、Reveal GIF、品牌預設、批次匯出)的即用配方。

相關技能