Community画像github.com

Dith

dith CLIを使用して写真やロゴをディザリングし、プロシージャルテクスチャを生成し、再現可能なレシピからレトロ調や印刷用のループアニメーションをエクスポートします。

Dith とは?

Dithは、AIエージェント向けに設計された決定論的ディザリングCLIツールです。すべてのコマンドは `--json` フラグに対応し、パレット通りの出力と機械可読なレポートを生成します。同一の入力とフラグは常にバイト単位で同一のファイルを生成するため、再現性が保証されます。このスキルは、写真やロゴのディザリング、プロシージャルテクスチャの生成、アニメーションの作成など、幅広いクリエイティブワークフローをサポートします。主な機能として、画像の分析(`dith inspect`)、スタイルの比較(`dith compare`)、ディザリングの適用(`dith apply`)、テクスチャ生成(`dith generate`)、アニメーション作成(`dith animate`)、バッチ処理(`dith batch`)などがあります。出力形式はPNG、WebP、SVG、ターミナルテキスト(点字やASCII)に対応し、アニメーションはGIF、APNG、スプライトシート、フレーム画像として出力可能です。各コマンドは `--json` フラグで詳細なレポートを返し、`--dry-run` で事前検証が可能です。また、`--emit-recipe` や `--save-preset` により、同じルックを後で再利用するためのレシピやプリセットを保存できます。このツールはClaude Code、Cursor、CodexなどのAIエージェント環境で特に有用であり、エージェントが画像処理の結果をプログラム的に検証し、再現可能なワークフローを構築することを可能にします。

対応~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に質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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 あるので、1つのカタログで十分な場合は 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)汎用的な現代的なルックとして最適。アニメーションでも安定。
リソグラフポスター--preset risograph、risograph-red、risograph-duo温かみのある紙の上でのデュオトーンおよび2ドラムの重ね刷りルック。
コミック / ジーンのハーフトーン--preset halftone-zine--format svg --svg-shape circle と組み合わせてベクタードットに。
ゲームボーイ / ピクセルアート--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色(2~64)のOklab色を抽出。
正確なブランドカラー--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-mode preserve はアルファチャンネルを保持し、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はピクセル数に応じて大きくなり、circleはrectよりはるかに大きいため、--max-dim を約120~320に保ちます。
  • ターミナルテキスト:--format braille|ascii と --text-width N。-o はオプションで、テキストは標準出力に出力されます。
  • 標準入出力:入力または -o - として - を渡します。

アニメーション

dith animate は4種類の入力のいずれかを取ります:

  • シームレスなプロシージャルループ用のパターン名(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 で「2フレームに1回」のアニメーションを設定します。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 でキーフレームで一時停止します。
  • パレット。 デフォルトでは1つの共有グローバルパレットが使用され、色を安定に保ちます。色が大きく変化する映像にのみ --per-frame-palette を使用します。
  • タイミング。 フレーム数は2~240に制限されています。--duration S は --frames の代替です(フレーム数 = S × fps)。両方を渡すとエラーになります。GIF遅延は10ms単位で保存されるため、--fps 10|20|25|50 は正確なGIFタイミングを与えます(15fpsはフレームあたり70msになります)。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 が期待通りであること。1つの色がピクセルの約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プロトコルビューアです。非インタラクティブなエージェントシェルでは、ファイルにレンダリングし、--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スプライトシート、リビールGIF、ブランドプリセット、バッチエクスポート)用のコピー可能なレシピ。

関連スキル