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 あるので、1つのカタログで十分な場合は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) | 汎用的な現代的なルックとして最適。アニメーションでも安定。 |
| リソグラフポスター | --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)。
- 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が期待通りであること。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、ブランドプリセット、バッチエクスポート)用のコピー可能なレシピ。