Dith 是做什麼的?
dith 是一個為代理設計的確定性抖色 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 通道的標誌和圖示:
--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)。
- 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 並檢視該 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、品牌預設、批次匯出)的即用配方。