Was macht Dith?
dith ist ein deterministisches Dithering-CLI, das für Agenten entwickelt wurde. Jeder Befehl akzeptiert --json, schreibt palettenexakte Ausgaben und gibt einen maschinenlesbaren Report zurück. Dieselben Eingaben und Flags erzeugen stets byteidentische Dateien.
Einrichtung
- Überprüfe die Binärdatei mit
dith --version.- Innerhalb des Dith-Quellcodes (ohne globale Installation) führe es mit
cargo run --release -- <args>aus (odermbx run -- <args>, wennmbxverfügbar ist). - Wenn dith fehlt, informiere den Benutzer und biete einen Installationsbefehl aus references/cli.md an. Warte auf seine Zustimmung, bevor du etwas installierst.
- Innerhalb des Dith-Quellcodes (ohne globale Installation) führe es mit
- Verlasse dich nicht auf auswendig gelernte Kataloge, wenn die genaue Menge wichtig ist. Frage die Binärdatei:
dith list presets|algorithms|palettes|generators|formats --json, filterbar mit--tag <substr>oder--category <name>dith capabilitiesfür das vollständige Manifest der Befehle, Parameterbereiche und das Standardrezept (ca. 40 KB, daherlistbevorzugen, wenn ein Katalog ausreicht)
Kernworkflow
- Die Quelle verstehen. Führe für ein vorhandenes Bild
dith inspect <image> --jsonaus. Es gibt Abmessungen, Transparenz, Luminanzperzentile (p5/p50/p95),dynamic_range, dominante Farben und Voreinstellungsempfehlungen mit ausführungsbereiten Befehlen aus. - Einen Startpunkt wählen aus der Stilübersicht unten. Wenn die Richtung offen ist, erstelle ein Kontaktblatt und betrachte es, bevor du dich festlegst:
dith compare <image> -o sheet.png --presets mac-classic,editorial-print,risograph,film-stipple --json - Komplexe Flagsets zuerst validieren mit
--dry-run --json. Dies fängt fehlerhafte Werte ab und zeigt die geplantenoutput_dimensionsan, ohne Dateien zu schreiben. - Rendern mit
apply,generate,animateoderbatch, immer mit--json. Einzeldateibefehle überschreiben vorhandene Ausgaben standardmäßig. Füge--no-clobberhinzu, wenn vorhandene Dateien nicht berührt werden dürfen; beibatchgilt dies für jede Datei. - Vor der Erfolgsmeldung verifizieren. Siehe Ergebnis verifizieren.
- Reproduzierbar machen, wenn der Look wiederverwendet werden soll. Übergib
--emit-recipe(fügt dem Report einrecipe-Objekt hinzu) oder--save-preset <name>(schreibt.dith/presets/<name>.json).
Look auswählen
Beginne mit einer Voreinstellung und überschreibe einzelne Flags. Explizite Flags gewinnen immer über die Voreinstellung.
| Ziel | Starte mit | Hinweise |
|---|---|---|
| Klassischer 1-Bit Mac / redaktionelles Porträt | --preset mac-classic (atkinson) | Atkinson gibt 2/8 des Fehlers ab, daher bleiben Lichter luftig. Ergänze --sharpen 0.4 bei weichen Fotos. |
| Raffinierter monochromer Druck / Zeitung | --preset editorial-print (ostromoukhov) | Glatteste Farbverläufe der Fehlerdiffusionsfamilie. |
| Filmische Punktierung, keine Gitterartefakte | --preset film-stipple (blue-noise) | Bester allgemeiner moderner Look; auch stabil in Animationen. |
| Risograph-Poster | --preset risograph, risograph-red, risograph-duo | Zweifarb- und Zweitrommel-Überdruck-Looks auf warmem Papier. |
| Comic / Zine-Halfton | --preset halftone-zine | Kombiniere mit --format svg --svg-shape circle für Vektorpunkte. |
| Game Boy / Pixelkunst | --preset gameboy, pico8 | Geordneter Bayer plus klobige --pixel-size. |
| CRT / Terminal-Glow | --preset crt-amber, phosphor | Dunkle Bilder eignen sich am besten dafür. |
| Kupferstich / Holzschnitt | --preset woodcut, --algorithm crosshatch | Linienraster; mit --pattern-scale einstellen. |
| Blaupause / technisch | --preset blueprint | Preußischblau und Kreide-Zweifarb. |
| Die eigenen Farben des Fotos behalten | --preset lo-fi-photo oder --auto-palette N | Extrahiert N Oklab-Farben (2–64) aus dem Bild. |
| Exakte Markenfarben | --colors "#0f172a,#2563eb,#f5efe6" | Mit jedem Algorithmus oder jeder Voreinstellung kombinierbar. |
| Neon-Helden-Verläufe / dunkles UI | --preset vapor-mesh mit generate mesh |
references/catalog.md enthält jede Voreinstellung, Palette, jeden Algorithmus und Generator mit Hinweisen zur Verwendung.
Gestaltungsregeln
- Ton vor dem Dithern. Dithern verstärkt flache oder matschige Eingaben.
- Niedriger
dynamic_range(unter ca. 0,5) oder eine enge p5–p95-Spanne: Ergänze--auto-levelsoder--contrast 0.1..0.3. - Weiches Foto, das zu 1-Bit oder Atkinson wird:
--sharpen 0.3..0.6. - Dunkle Mitteltöne:
--gamma 0.7..0.9(Werte unter 1 hellen auf). Helle, verwaschene Eingabe:--gamma 1.2..1.5. - Gesamtdichte anpassen:
--bias(negativ ist dunkler, positiv ist heller, Bereich ±0,5).
- Niedriger
- Größe zuerst. Begrenze mit
--max-dim(oder--width/--heightplus--fit contain|cover|stretch). Dither-Muster sind pixelgenau, daher darf ein gedithertes Bild niemals nachträglich skaliert werden. Stattdessen in der endgültigen Anzeigegröße rendern. - Klobige Pixel.
--pixel-size Nverkleinert, dithert und skaliert dann nächstgelegen hoch, sodass die Ausgabeabmessungen unverändert bleiben. - Geordnete Rastergröße.
--pattern-scale 2..4vergrößert Bayer-, Halbton-, Linien- und Blue-Noise-Zellen für kräftigere, grafischere Texturen. - Farbraum. Behalte den Standard
oklabbei. Verwendesrgbnur, um veraltete Hardware-Mathematik nachzuahmen;linearist physikalisch lineares Licht. - Determinismus. Stochastische Algorithmen (
blue-noise,random,ign),--noiseund--auto-paletteverwenden--seed(Standard 42). Ändere den Seed für Variationen und behalte ihn für Reproduzierbarkeit bei. - Transparenz. Logos und Icons mit Alpha:
--alpha-mode preservebehält den Alphakanal,thresholdergibt eine scharfe 1-Bit-Maske,ditherergibt einen gepunkteten Verblassungseffekt undflatten --background "#hex"überlagert auf eine Farbe. - Teile von Voreinstellungen deaktivieren. Die meisten monochromen Voreinstellungen aktivieren
--grayscaleund--auto-levels. Verwende--no-grayscale,--no-auto-levelsund--no-serpentine, um das zu deaktivieren, was eine Voreinstellung aktiviert hat.
Ausgabeformate
Das Format wird aus der -o-Erweiterung abgeleitet; übergib --format, um es zu überschreiben.
- PNG (Standard): verlustfrei und pixelexakt. Fast immer die richtige Wahl.
- WebP: kompakt für das Web. JPEG zerstört Dither-Muster, daher niemals für geditherte Ausgaben verwenden, es sei denn, der Benutzer besteht darauf.
- SVG:
--svg-shape rect(laufzeitkomprimierte Rechtecke, am kleinsten),circle(Halbtonpunkte) oderdot(eingelassene Punkte).--svg-skip-bgentfernt die dominante Hintergrundfarbe für Überlagerungen. SVG wächst mit der Pixelanzahl, und Kreise sind viel größer als Rechtecke, daher--max-dimbei etwa 120–320 halten. - Terminal-Text:
--format braille|asciimit--text-width N.-oist optional und der Text wird auf stdout ausgegeben. - Stdin/stdout: übergib
-als Eingabe oder als-o -.
Animation
dith animate akzeptiert eine von vier Arten von Eingaben:
- einen Musternamen (
sphere,waves,mesh,plasma, ...) für eine nahtlose prozedurale Schleife. Jedes Muster bewegt sich anders (die Kugel bleibt z. B. still, während ihr Licht umkreist); das Feldmotionvondith list generators --jsonbeschreibt es. Um die Bewegung vor einem vollständigen Rendern günstig zu prüfen, exportiere ein kleines Spritesheet (--anim-format spritesheet --sheet-cols <frames> --canvas-width 160 --canvas-height 120) und betrachte es. - einem animierten GIF, APNG oder WebP zum Neudithern
- mehreren Bilddateien als Bildsequenz
- einem einzelnen statischen Bild, das einen Filmkorn-Effekt erhält (
--temporal boilist der Standard für diesen Fall)
Die Ausgabe erfolgt als .gif (exakte Palette, am kleinsten), .apng (volles RGBA), ein Spritesheet .png über --anim-format spritesheet --sheet-cols N oder nummerierte PNG-Frames über --frames-dir DIR.
- Flimmern.
--temporal locked(Standard) fixiert den Bildschirm und Seed framesübergreifend, funktioniert aber nur bei pixelgenauen Algorithmen für statische Regionen: geordnete Raster (bayer*,halftone, Linienraster),blue-noise,ign,randomundthreshold. Fehlerdiffusion (floyd-steinberg,atkinson,stucki,riemersma, ...) gibt jede Änderung an benachbarte Pixel weiter, sodass alles, was sich bewegt, die Punktierung darunter und rechts davon zum Schimmern bringt. Atkinson schimmert am wenigsten. Das Feldtemporally_stablevondith list algorithms --jsongibt an, welcher Algorithmus stabil ist.boilerzeugt absichtlich einen handgezeichneten Schimmereffekt; setze--boil-rate 2für eine Animation „auf Zweien“.grainrandomisiert die Punktierung in jedem Frame neu. - Nahtlose Schleifen. Prozedurale Muster sind von Natur aus schleifenfähig. Verwende für Sweeps
--sweep-mode pulseoder--ping-pong. - Sweeps animieren einen Parameter über die Zeit:
--sweep-bias,--sweep-brightness,--sweep-contrast,--sweep-gamma,--sweep-strength,--sweep-pixel-size, jeweils alsSTART..ENDEgeschrieben. Forme sie mit--easingund pausiere an Keyframes mit--hold-startund--hold-end. - Palette. Eine gemeinsame globale Palette ist Standard und hält die Farben stabil. Verwende
--per-frame-palettenur für Material, dessen Farben sich stark ändern. - Timing. Frames sind auf 2..=240 begrenzt.
--duration Sist eine Alternative zu--frames(Frames = S × fps); die Angabe beider ist ein Fehler. GIF-Verzögerungen werden in 10-ms-Schritten gespeichert, daher ergibt--fps 10|20|25|50exaktes GIF-Timing (15 fps werden zu 70 ms pro Frame). APNG ist exakt. - Größe. Die Dateigröße wächst mit Frames × Pixel, und Dither-Rauschen komprimiert kaum.
- GIFs werden automatisch delta-kodiert: Jeder Frame nach dem ersten speichert nur, was sich geändert hat. Gesperrte pixelgenaue Algorithmen mit statischen Bereichen sind daher viel kleiner als Fehlerdiffusion oder
boil/grain, bei denen sich fast jedes Pixel pro Frame ändert. - Um ein Budget einzuhalten, übergib
--max-size 2MB(auch500KB,1.5MiBoder Bytes). Dith verkleinert die Frame-Abmessungen, behält aber Frame-Anzahl und fps bei, bis die Datei passt, und meldetsize_fit_scale(1,0 = unverändert). Wennsize_fit_scaleklein zurückkommt (unter ca. 0,5), ist das Ergebnis möglicherweise zu klein, um verwendet zu werden. Verkleinere die Größe stattdessen auf andere Weise: weniger Frames, ein gesperrter geordneter Algorithmus oder weniger Palettenfarben. - Halte prozedurale Leinwände bescheiden (Standard ist 480×360).
- GIFs werden automatisch delta-kodiert: Jeder Frame nach dem ersten speichert nur, was sich geändert hat. Gesperrte pixelgenaue Algorithmen mit statischen Bereichen sind daher viel kleiner als Fehlerdiffusion oder
- Prozedurale Farben. Ohne
--stopsverwenden Muster eine einfache Rampe von fast Schwarz zu fast Weiß. Übergib--stops, um die Quelltöne bewusst zu wählen; das sieht meist besser aus, insbesondere mit einer farbigen Palette. - Voreinstellungen auf prozeduralen Quellen. Voreinstellungen sind für Fotos optimiert. Für
generate,animate <pattern>undcompare/preview --patternüberspringt dith deren Auto-Levels, Kontrast und Schärfung, da diese saubere Farbverläufe in flache Flecken klippen. Übergib diese Flags explizit, um sie trotzdem anzuwenden.
Ergebnis verifizieren
Lies den JSON-Report, anstatt von Erfolg auszugehen:
"status": "ok".batchkann stattdessen"partial_failure"mit Exit-Code 1 zurückgeben; überprüfefailedund jedesitems[].error.output_dimensionsfür Bilder oderframe_count,frame_dimensionsundtotal_duration_msfür Animationen entsprechen der Absicht.bytes_written > 0; es ist0bei--dry-run.palette_colorsundcolor_usagesind wie erwartet. Wenn eine Farbe mehr als etwa 95 % der Pixel abdeckt, ist das Bild nahezu leer: Passe--bias,--gammaoder--contrastan oder versuche--invert.
Wenn die Ästhetik wichtig ist, betrachte die Ausgabe. Öffne PNG-Dateien mit einem Bildbetrachtungswerkzeug, falls vorhanden; andernfalls füge --preview hinzu, um eine Braille-Miniaturansicht in preview_braille zu erhalten. Für Animationen exportiere ein Spritesheet oder --frames-dir und betrachte die PNG-Frames. Für SVGs rendere ein PNG mit denselben Flags und betrachte es.
Fehler
Mit --json gehen Fehler auf stderr als {"status":"error","code","message","suggestion","valid_values"?}.
- Exit 2: ungültige Eingabe von dir. Codes umfassen
CLI_USAGE_ERROR,INVALID_ARGUMENT(ein außerhalb des Bereichs liegender Wert; die Nachricht enthält den Bereich),UNKNOWN_PRESETund ähnliche Codes (valid_valueslistet die Optionen auf) undOUTPUT_EXISTS(--no-clobbertraf auf eine vorhandene Datei). Korrigiere die Flags und versuche es erneut. - Exit 1: Laufzeit- oder E/A-Fehler (
RUNTIME_ERROR), z. B. eine fehlende Eingabe oder eine nicht dekodierbare Datei.batchbeendet sich ebenfalls mit Exit 1, wenn ein Element fehlschlägt.
Interaktiv vs. headless
--view, preview (standardmäßig Vollbild) und compare --view sind interaktive Kitty-Protokoll-Viewer, die für einen Menschen an einem Terminal gedacht sind. In nicht-interaktiven Agenten-Shells rendere in Dateien, verwende --preview oder --format braille oder übergib --inline (z. B. dith preview img.png --inline --mode braille --cols 60). Verwende den Vollbild-Viewer nur, wenn der Benutzer explizit zusehen möchte.
Referenzen
- references/cli.md: jeder Unterbefehl und jedes Flag, mit Bereichen, Standardwerten und JSON-Report-Feldern.
- references/catalog.md: Voreinstellungen, Paletten, Algorithmen und Generatoren und wann welches zu wählen ist.
- references/recipes.md: kopierfertige Rezepte für häufige Aufgaben (Web-Held, Avatar, Logo-SVG, Social Card, CSS-Spritesheet, Enthüllungs-GIF, Marken-Voreinstellung, Batch-Export).