CommunityBildgithub.com

Dith

Nutzt die Dith-CLI, um Fotos und Logos zu ditheren, prozedurale Texturen zu generieren und retro- oder druckfertige Animationen aus wiederholbaren Rezepten zu exportieren.

Was ist Dith?

Dith ist eine deterministische Dithering-CLI, die speziell für KI-Agenten entwickelt wurde. Sie zeichnet sich durch maschinenlesbare JSON-Ausgaben, pixelgenaue Ergebnisse und vollständige Reproduzierbarkeit aus. Der Workflow umfasst die Analyse von Bildern (Metadaten, Farbpaletten), das Auswählen von Looks aus über 20 Voreinstellungen (von 1-Bit Mac-Klassik bis zu Stahlstich) und die Ausgabe in Formaten wie PNG, WebP, SVG oder Terminal-Text. Besonders hervorzuheben ist die Animationsfunktion mit prozeduralen Schleifen, Neudithering von GIFs/APNGs und zeitlichen Parametern wie Sweeps und Flimmersteuerung. Dith unterstützt Batch-Verarbeitung, Rezepte für agentenbasierte Workflows und eine detaillierte Fehlerberichterstattung. Es kann über `cargo run` oder ein global installiertes Binary ausgeführt werden und eignet sich ideal für Aufgaben wie Marken-Assets, Retro-Spielegrafiken, Druckvorbereitung und generative Kunst.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lassejlv/dith/tree/HEAD/skills/dith

Installed? Explore more Bild skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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

  1. Überprüfe die Binärdatei mit dith --version.
    • Innerhalb des Dith-Quellcodes (ohne globale Installation) führe es mit cargo run --release -- <args> aus (oder mbx run -- <args>, wenn mbx verfü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.
  2. 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 capabilities für das vollständige Manifest der Befehle, Parameterbereiche und das Standardrezept (ca. 40 KB, daher list bevorzugen, wenn ein Katalog ausreicht)

Kernworkflow

  1. Die Quelle verstehen. Führe für ein vorhandenes Bild dith inspect <image> --json aus. Es gibt Abmessungen, Transparenz, Luminanzperzentile (p5/p50/p95), dynamic_range, dominante Farben und Voreinstellungsempfehlungen mit ausführungsbereiten Befehlen aus.
  2. 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
  3. Komplexe Flagsets zuerst validieren mit --dry-run --json. Dies fängt fehlerhafte Werte ab und zeigt die geplanten output_dimensions an, ohne Dateien zu schreiben.
  4. Rendern mit apply, generate, animate oder batch, immer mit --json. Einzeldateibefehle überschreiben vorhandene Ausgaben standardmäßig. Füge --no-clobber hinzu, wenn vorhandene Dateien nicht berührt werden dürfen; bei batch gilt dies für jede Datei.
  5. Vor der Erfolgsmeldung verifizieren. Siehe Ergebnis verifizieren.
  6. Reproduzierbar machen, wenn der Look wiederverwendet werden soll. Übergib --emit-recipe (fügt dem Report ein recipe-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.

ZielStarte mitHinweise
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-duoZweifarb- und Zweitrommel-Überdruck-Looks auf warmem Papier.
Comic / Zine-Halfton--preset halftone-zineKombiniere mit --format svg --svg-shape circle für Vektorpunkte.
Game Boy / Pixelkunst--preset gameboy, pico8Geordneter Bayer plus klobige --pixel-size.
CRT / Terminal-Glow--preset crt-amber, phosphorDunkle Bilder eignen sich am besten dafür.
Kupferstich / Holzschnitt--preset woodcut, --algorithm crosshatchLinienraster; mit --pattern-scale einstellen.
Blaupause / technisch--preset blueprintPreußischblau und Kreide-Zweifarb.
Die eigenen Farben des Fotos behalten--preset lo-fi-photo oder --auto-palette NExtrahiert 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-levels oder --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).
  • Größe zuerst. Begrenze mit --max-dim (oder --width/--height plus --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 N verkleinert, dithert und skaliert dann nächstgelegen hoch, sodass die Ausgabeabmessungen unverändert bleiben.
  • Geordnete Rastergröße. --pattern-scale 2..4 vergrößert Bayer-, Halbton-, Linien- und Blue-Noise-Zellen für kräftigere, grafischere Texturen.
  • Farbraum. Behalte den Standard oklab bei. Verwende srgb nur, um veraltete Hardware-Mathematik nachzuahmen; linear ist physikalisch lineares Licht.
  • Determinismus. Stochastische Algorithmen (blue-noise, random, ign), --noise und --auto-palette verwenden --seed (Standard 42). Ändere den Seed für Variationen und behalte ihn für Reproduzierbarkeit bei.
  • Transparenz. Logos und Icons mit Alpha: --alpha-mode preserve behält den Alphakanal, threshold ergibt eine scharfe 1-Bit-Maske, dither ergibt einen gepunkteten Verblassungseffekt und flatten --background "#hex" überlagert auf eine Farbe.
  • Teile von Voreinstellungen deaktivieren. Die meisten monochromen Voreinstellungen aktivieren --grayscale und --auto-levels. Verwende --no-grayscale, --no-auto-levels und --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) oder dot (eingelassene Punkte). --svg-skip-bg entfernt die dominante Hintergrundfarbe für Überlagerungen. SVG wächst mit der Pixelanzahl, und Kreise sind viel größer als Rechtecke, daher --max-dim bei etwa 120–320 halten.
  • Terminal-Text: --format braille|ascii mit --text-width N. -o ist 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 Feld motion von dith list generators --json beschreibt 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 boil ist 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, random und threshold. 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 Feld temporally_stable von dith list algorithms --json gibt an, welcher Algorithmus stabil ist. boil erzeugt absichtlich einen handgezeichneten Schimmereffekt; setze --boil-rate 2 für eine Animation „auf Zweien“. grain randomisiert die Punktierung in jedem Frame neu.
  • Nahtlose Schleifen. Prozedurale Muster sind von Natur aus schleifenfähig. Verwende für Sweeps --sweep-mode pulse oder --ping-pong.
  • Sweeps animieren einen Parameter über die Zeit: --sweep-bias, --sweep-brightness, --sweep-contrast, --sweep-gamma, --sweep-strength, --sweep-pixel-size, jeweils als START..ENDE geschrieben. Forme sie mit --easing und pausiere an Keyframes mit --hold-start und --hold-end.
  • Palette. Eine gemeinsame globale Palette ist Standard und hält die Farben stabil. Verwende --per-frame-palette nur für Material, dessen Farben sich stark ändern.
  • Timing. Frames sind auf 2..=240 begrenzt. --duration S ist 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|50 exaktes 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 (auch 500KB, 1.5MiB oder Bytes). Dith verkleinert die Frame-Abmessungen, behält aber Frame-Anzahl und fps bei, bis die Datei passt, und meldet size_fit_scale (1,0 = unverändert). Wenn size_fit_scale klein 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).
  • Prozedurale Farben. Ohne --stops verwenden 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> und compare/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". batch kann stattdessen "partial_failure" mit Exit-Code 1 zurückgeben; überprüfe failed und jedes items[].error.
  • output_dimensions für Bilder oder frame_count, frame_dimensions und total_duration_ms für Animationen entsprechen der Absicht.
  • bytes_written > 0; es ist 0 bei --dry-run.
  • palette_colors und color_usage sind wie erwartet. Wenn eine Farbe mehr als etwa 95 % der Pixel abdeckt, ist das Bild nahezu leer: Passe --bias, --gamma oder --contrast an 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_PRESET und ähnliche Codes (valid_values listet die Optionen auf) und OUTPUT_EXISTS (--no-clobber traf 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. batch beendet 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).

Verwandte Skills