CommunityImagegithub.com

Dith

Utilise l'interface en ligne de commande `dith` pour tramer des photos et logos, générer des textures procédurales, et exporter des animations rétro ou imprimables en boucle à partir de recettes reproductibles.

Qu'est-ce que Dith ?

Dith est un outil CLI de tramage déterministe conçu pour les agents IA. Il prend en charge une variété de formats d'entrée (images, GIF, APNG, WebP) et de sortie (PNG, WebP, SVG, texte terminal, trames numérotées). Le flux de travail central consiste à inspecter une image source, choisir un style prédéfini (comme mac-classic, editorial-print, risograph ou halftone-zine), valider les options avec `--dry-run`, puis appliquer le tramage via `apply`, `generate`, `animate` ou `batch`. Chaque commande accepte `--json` pour un rapport lisible par machine, garantissant la vérification du succès (statut `ok`, dimensions, nombre de couleurs). Dith assure la reproductibilité via des graines aléatoires fixes, l'option `--emit-recipe` ou `--save-preset`. Il gère également la transparence, la correction tonale avant tramage, et l'animation avec des boucles transparentes, des balayages animés et des algorithmes temporellement stables pour éviter le scintillement. L'outil est optimisé pour les environnements sans tête, mais peut aussi ouvrir un visualiseur plein écran interactif (Kitty protocol) si l'utilisateur le demande.

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

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait Dith ?

dith est un CLI de tramage déterministe conçu pour les agents. Chaque commande accepte --json, produit une sortie exacte en palette et renvoie un rapport lisible par machine. Les mêmes entrées et options produisent toujours des fichiers identiques octet pour octet.

Configuration

  1. Vérifiez la présence du binaire avec dith --version.
    • Depuis le répertoire source de dith sans installation globale, exécutez-le via cargo run --release -- <args> (ou mbx run -- <args> lorsque mbx est disponible).
    • Si dith est manquant, informez l'utilisateur et proposez une commande d'installation depuis references/cli.md. Attendez son approbation avant d'installer quoi que ce soit.
  2. Ne vous fiez pas aux catalogues mémorisés lorsque l'ensemble exact est important. Interrogez le binaire :
    • dith list presets|algorithms|palettes|generators|formats --json, filtrable avec --tag <substr> ou --category <name>
    • dith capabilities pour le manifeste complet des commandes, plages de paramètres et la recette par défaut (environ 40 Ko, donc préférez list quand un catalogue unique suffit)

Flux de travail principal

  1. Comprendre la source. Pour une image existante, exécutez dith inspect <image> --json. Il rapporte les dimensions, la transparence, les centiles de luminance (p5/p50/p95), la dynamic_range, les couleurs dominantes et des recommandations de préréglages avec des commandes prêtes à exécuter.
  2. Choisir un point de départ dans le guide de style ci-dessous. Lorsque la direction est ouverte, générez une planche de contact et observez-la avant de vous engager : dith compare <image> -o sheet.png --presets mac-classic,editorial-print,risograph,film-stipple --json
  3. Valider d'abord les ensembles d'options complexes avec --dry-run --json. Cela détecte les valeurs erronées et montre les output_dimensions prévues sans écrire de fichiers.
  4. Rendre avec apply, generate, animate ou batch, toujours avec --json. Les commandes mono-fichier écrasent les sorties existantes par défaut. Ajoutez --no-clobber lorsque les fichiers existants ne doivent pas être touchés ; dans batch, cela s'applique à chaque fichier.
  5. Vérifier avant de signaler le succès. Voir Vérifier le résultat.
  6. Rendre le résultat reproductible lorsque le rendu sera réutilisé. Passez --emit-recipe (ajoute un objet recipe au rapport) ou --save-preset <name> (écrit .dith/presets/<name>.json).

Choisir un style

Partez d'un préréglage, puis surchargez les options individuelles. Les options explicites l'emportent toujours sur le préréglage.

ObjectifCommencer parNotes
Mac classique 1-bit / portrait éditorial--preset mac-classic (atkinson)Atkinson ne diffuse que 2/8 de l'erreur, les hautes lumières restent aérées. Ajoutez --sharpen 0.4 sur les photos douces.
Impression monochrome raffinée / journal--preset editorial-print (ostromoukhov)Les dégradés les plus lisses de la famille de diffusion d'erreur.
Stipple cinématographique, sans artefacts de grille--preset film-stipple (blue-noise)Meilleur rendu général moderne ; également stable en animation.
Affiche Risographie--preset risograph, risograph-red, risograph-duoAspects bichromie et double-cylindre sur papier chaud.
Tramage de bande dessinée / fanzine--preset halftone-zineAssociez à --format svg --svg-shape circle pour des points vectoriels.
Game Boy / pixel art--preset gameboy, pico8Bayer ordonné plus --pixel-size épais.
Lueur CRT / terminal--preset crt-amber, phosphorLes images sombres conviennent le mieux.
Gravure / bois--preset woodcut, --algorithm crosshatchTramage linéaire ; ajustez avec --pattern-scale.
Plan technique / blueprint--preset blueprintBichromie bleu de Prusse et craie.
Conserver les couleurs d'origine de la photo--preset lo-fi-photo ou --auto-palette NExtrait N couleurs Oklab (2–64) de l'image.
Couleurs de marque exactes--colors "#0f172a,#2563eb,#f5efe6"Combinez avec n'importe quel algorithme ou préréglage.
Dégradés héroïques neon / UI sombre--preset vapor-mesh avec generate mesh

references/catalog.md contient tous les préréglages, palettes, algorithmes et générateurs avec quand utiliser chacun.

Règles de conception

  • Ton avant le tramage. Le tramage amplifie une entrée plate ou boueuse.
    • Faible dynamic_range (inférieure à environ 0,5) ou un écart p5–p95 étroit : ajoutez --auto-levels ou --contrast 0.1..0.3.
    • Photo douce passant en 1-bit ou Atkinson : --sharpen 0.3..0.6.
    • Demi-teintes sombres : --gamma 0.7..0.9 (les valeurs inférieures à 1 éclaircissent). Entrée claire et délavée : --gamma 1.2..1.5.
    • Ajuster la densité globale : --bias (négatif assombrit, positif éclaircit, plage ±0,5).
  • Taille d'abord. Limitez avec --max-dim (ou --width/--height plus --fit contain|cover|stretch). Les motifs de tramage sont par pixel, donc une image tramée ne doit jamais être redimensionnée par la suite. Rendez plutôt à la taille d'affichage finale.
  • Pixels épais. --pixel-size N sous-échantillonne, trame, puis suréchantillonne au plus proche voisin, donc les dimensions de sortie restent inchangées.
  • Taille de trame ordonnée. --pattern-scale 2..4 agrandit les cellules Bayer, demi-teintes, linéaires et blue-noise pour des textures plus audacieuses et graphiques.
  • Espace colorimétrique. Gardez le oklab par défaut. Utilisez srgb uniquement pour imiter les calculs matériels anciens ; linear est la lumière linéaire physique.
  • Déterminisme. Les algorithmes stochastiques (blue-noise, random, ign), --noise et --auto-palette utilisent --seed (par défaut 42). Changez la seed pour des variations et gardez-la fixe pour la reproductibilité.
  • Transparence. Logos et icônes avec alpha : --alpha-mode preserve conserve le canal alpha, threshold donne un masque 1-bit net, dither donne une atténuation pointillée, et flatten --background "#hex" compose sur une couleur.
  • Désactiver des parties du préréglage. La plupart des préréglages monochromes activent --grayscale et --auto-levels. Utilisez --no-grayscale, --no-auto-levels et --no-serpentine pour désactiver ce qu'un préréglage a activé.

Formats de sortie

Le format est déduit de l'extension -o ; passez --format pour le surcharger.

  • PNG (par défaut) : sans perte et exact au pixel près. Presque toujours le bon choix.
  • WebP : compact pour le web. JPEG détruit les motifs de tramage, ne l'utilisez donc jamais pour une sortie tramée sauf si l'utilisateur insiste.
  • SVG : --svg-shape rect (rectangles fusionnés par longueur de plage, les plus petits), circle (points demi-teintes) ou dot (points encastrés). --svg-skip-bg supprime la couleur de fond dominante pour les superpositions. La taille du SVG croît avec le nombre de pixels, et les cercles sont beaucoup plus grands que les rectangles, donc gardez --max-dim autour de 120–320.
  • Texte de terminal : --format braille|ascii avec --text-width N. -o est facultatif et le texte va sur stdout.
  • Entrée/sortie standard : passez - comme entrée ou comme -o -.

Animation

dith animate prend l'un des quatre types d'entrée :

  • un nom de motif (sphere, waves, mesh, plasma, ...) pour une boucle procédurale transparente. Chaque motif se déplace différemment (la sphère reste immobile tandis que sa lumière orbite, par exemple) ; le champ motion de dith list generators --json le décrit. Pour vérifier le mouvement à moindre coût avant un rendu complet, exportez une petite feuille de sprites (--anim-format spritesheet --sheet-cols <frames> --canvas-width 160 --canvas-height 120) et regardez-la.
  • un GIF animé, APNG ou WebP pour les retramer
  • plusieurs fichiers image comme séquence d'images
  • une seule image statique, qui reçoit un bouillonnement de film (--temporal boil est la valeur par défaut pour ce cas)

La sortie se fait en .gif (palette exacte, le plus petit), .apng (RGBA complet), une feuille de sprites .png via --anim-format spritesheet --sheet-cols N, ou des images PNG numérotées via --frames-dir DIR.

  • Scintillement. --temporal locked (par défaut) fixe l'écran et la seed entre les images, mais ne rend les régions statiques parfaitement stables qu'avec les algorithmes par pixel : trames ordonnées (bayer*, halftone, trames linéaires), blue-noise, ign, random et threshold. La diffusion d'erreur (floyd-steinberg, atkinson, stucki, riemersma, ...) transmet chaque changement aux pixels voisins, donc tout ce qui bouge fait scintiller le stipple en dessous et à droite. Atkinson scintille le moins. Le champ temporally_stable de dith list algorithms --json indique lequel est quoi. boil donne un scintillement dessiné à la main intentionnellement ; définissez --boil-rate 2 pour animer "à deux temps". grain randomise à nouveau le stipple à chaque image.
  • Boucles transparentes. Les motifs procéduraux bouclent par construction. Pour les balayages, utilisez --sweep-mode pulse ou --ping-pong.
  • Balayages animent un paramètre dans le temps : --sweep-bias, --sweep-brightness, --sweep-contrast, --sweep-gamma, --sweep-strength, --sweep-pixel-size, chacun écrit START..END. Façonnez-les avec --easing, et faites des pauses sur les images clés avec --hold-start et --hold-end.
  • Palette. Une palette globale partagée est la valeur par défaut et maintient les couleurs stables. Utilisez --per-frame-palette uniquement pour les séquences dont les couleurs changent beaucoup.
  • Temporisation. Les images sont limitées à 2..=240. --duration S est une alternative à --frames (images = S × fps) ; passer les deux est une erreur. Les délais GIF sont stockés par pas de 10 ms, donc --fps 10|20|25|50 donne un timing GIF exact (15 fps devient 70 ms par image). L'APNG est exact.
  • Taille. La taille du fichier croît avec images × pixels, et le bruit de tramage se compresse à peine.
    • Les GIF sont encodés par delta automatiquement : chaque image après la première ne stocke que ce qui a changé. Les algorithmes par pixel verrouillés avec des zones statiques sont donc beaucoup plus petits que la diffusion d'erreur ou boil/grain, où presque chaque pixel change à chaque image.
    • Pour atteindre un budget, passez --max-size 2MB (également 500KB, 1.5MiB ou en octets). Dith réduit les dimensions de l'image, en conservant le nombre d'images et le fps, jusqu'à ce que le fichier tienne, et rapporte size_fit_scale (1,0 = inchangé). Si size_fit_scale revient petit (inférieur à environ 0,5), le résultat peut être trop petit pour être utilisé. Réduisez plutôt la taille d'une autre manière : moins d'images, un algorithme ordonné verrouillé ou moins de couleurs de palette.
    • Gardez les toiles procédurales modestes (les valeurs par défaut sont 480×360).
  • Couleurs procédurales. Sans --stops, les motifs utilisent un simple dégradé quasi noir → quasi blanc. Passez --stops pour choisir délibérément les tons sources ; cela donne généralement un meilleur résultat, surtout avec une palette colorée.
  • Préréglages sur sources procédurales. Les préréglages sont optimisés pour les photos. Pour generate, animate <pattern> et compare/preview --pattern, dith ignore leurs auto-niveaux, contraste et accentuation, car ceux-ci transforment des dégradés propres en zones plates. Passez ces options explicitement pour les appliquer quand même.

Vérifier le résultat

Lisez le rapport JSON plutôt que de supposer le succès :

  • "status": "ok". batch peut renvoyer "partial_failure" avec le code de sortie 1 ; vérifiez failed et chaque items[].error.
  • output_dimensions pour les images, ou frame_count, frame_dimensions et total_duration_ms pour les animations, correspondent à l'intention.
  • bytes_written > 0 ; c'est 0 sur --dry-run.
  • palette_colors et color_usage sont comme attendu. Si une couleur couvre plus d'environ 95 % des pixels, l'image est presque vide : ajustez --bias, --gamma ou --contrast, ou essayez --invert.

Lorsque l'esthétique compte, regardez la sortie. Ouvrez les fichiers PNG avec un outil de visualisation d'image si vous en avez un ; sinon, ajoutez --preview pour obtenir une vignette Braille dans preview_braille. Pour les animations, exportez une feuille de sprites ou --frames-dir et visualisez les images PNG. Pour les SVG, rendez un PNG avec les mêmes options et visualisez-le.

Erreurs

Avec --json, les erreurs vont sur stderr sous forme de {"status":"error","code","message","suggestion","valid_values"?}.

  • Code 2 : entrée invalide de votre part. Les codes incluent CLI_USAGE_ERROR, INVALID_ARGUMENT (une valeur hors plage ; le message inclut la plage), UNKNOWN_PRESET et codes similaires (valid_values liste les options), et OUTPUT_EXISTS (--no-clobber a rencontré un fichier existant). Corrigez les options et réessayez.
  • Code 1 : échec d'exécution ou d'E/S (RUNTIME_ERROR), comme une entrée manquante ou un fichier indécodable. batch se termine également avec le code 1 lorsque un élément échoue.

Interactif vs sans tête

--view, preview (plein écran par défaut) et compare --view sont des visualiseurs interactifs (protocole Kitty) destinés à un humain derrière un terminal. Dans les shells d'agents non interactifs, rendez vers des fichiers, utilisez --preview ou --format braille, ou passez --inline (par exemple dith preview img.png --inline --mode braille --cols 60). N'utilisez le visualiseur plein écran que lorsque l'utilisateur souhaite explicitement regarder dans son propre terminal.

Références

  • references/cli.md : chaque sous-commande et option, avec plages, valeurs par défaut et champs du rapport JSON.
  • references/catalog.md : préréglages, palettes, algorithmes et générateurs, et quand choisir chacun.
  • references/recipes.md : recettes prêtes à copier pour les tâches courantes (héros web, avatar, logo SVG, carte sociale, feuille de sprites CSS, GIF de révélation, préréglage de marque, exportation par lot).

Skills associés