Art ASCII
scripts/ascii.py génère des images fixes et scripts/animate.py des animations (voir "Animation"). Les deux nécessitent seulement Python 3.9+ et Pillow (plus ffmpeg pour la vidéo). Avec uv installé, uv run télécharge Pillow automatiquement.
uv run scripts/ascii.py IMAGE [options] # ou : python3 scripts/ascii.py (nécessite pillow)
Les chemins ci-dessous sont relatifs au dossier de ce skill.
Étapes
- Obtenez le chemin de l'image. Pour une URL, téléchargez-la d'abord avec
curl -L -o /tmp/in.img URL. - Choisissez la sortie. Utilisez la sortie standard pour afficher l'art dans le chat. Utilisez
-o fichier.pngou-o fichier.htmllorsque l'utilisateur veut un fichier à partager. - Exécutez, puis lisez le résultat. Pour un PNG, ouvrez l'image et regardez-la.
- Si le sujet est difficile à voir, ajustez les paramètres et réexécutez (voir "Correction des résultats faibles").
Options
| Option | Effet |
|---|---|
-w 100 | Largeur en caractères (1–1000). Utilisez 60–80 pour le chat, 120–200 pour PNG/HTML, 120+ pour les captures d'écran de texte. |
-c standard | Rampe de caractères : standard, detailed, blocks, terminal, minimal, binary, dots, ou votre propre chaîne du plus dense au plus vide, comme -c "#*. ". |
-o out.png | Sortie par extension : .txt, .html, .png, .jpg, .webp. Sans -o, imprime le texte brut sur stdout. |
--bg black | Arrière-plan : black (par défaut), white, none (PNG/HTML transparent), ou toute couleur. Sur fond sombre, les pixels clairs reçoivent des glyphes denses. Sur fond clair, ce sont les pixels sombres. |
--fg matrix | Une couleur d'encre : matrix, amber, cyan, magenta, mint, ou toute couleur CSS ou hexadécimale. Sans cela, PNG/HTML utilisent les couleurs de la photo. |
--color | Codes d'échappement ANSI truecolor dans la sortie texte (stdout ou .txt). Utilise --fg s'il est donné, sinon les couleurs de la photo. |
--invert | Inverse le clair et le foncé. |
--contrast 1.0 --brightness 1.0 | Facteurs s'ajoutant à l'étirement automatique du contraste. 1.0 signifie aucun changement. |
--dither | Tramage Floyd-Steinberg. Bon pour les dégradés lisses et les rampes courtes comme blocks ou minimal. |
--mode ramp | ramp (par défaut) : un glyphe par pixel, choisi par luminosité. shape : comme ramp, mais les contours sont dessinés avec des symboles de même forme (`/ \ |
--sharpen | Accentue les contours avant la réduction. Aide pour les visages et les détails fins, surtout en mode braille. |
--aspect 0.5 | Largeur du caractère divisée par sa hauteur. Augmentez si l'art semble écrasé. |
--font-size 12 | Taille du glyphe en px pour PNG/HTML. |
--glow 0.8 | Lueur douce autour des glyphes (0-1) dans les PNG, HTML et animations, comme la lumière sur un vieil écran. Meilleur sur fond sombre. |
Correction des résultats faibles
Le script étire déjà chaque image sur toute sa plage tonale, donc la plupart des images sont correctes sans réglage.
- Photos :
-c blocks --ditherdonne les visages et animaux les plus reconnaissables. - Sujet sombre (chien noir, scène nocturne) disparaît sur fond noir : utilisez
--bg white. Augmenter--brightness 1.5aide aussi. Augmenter le contraste aggrave les scènes sombres. - Logo sombre sur fond blanc apparaît comme un bloc solide : ajoutez
--bg white(ou--invertpour la sortie terminal). - Vous voulez plus de détail à la même largeur :
--mode braille --dither --sharpenpour un style line-art,--mode halfblockpour une photo couleur. - Trop de bruit : utilisez moins de colonnes ou une rampe plus courte (
-c minimal). - Bandes dans les dégradés : ajoutez
--dither. - Sortie chat : n'utilisez jamais
--color, car les codes d'échappement apparaissent comme des déchets. Encadrez le texte dans un bloc de code. - SVG n'est pas pris en charge. Convertissez-le d'abord en PNG (
rsvg-convert -w 800 logo.svg -o logo.png).
Modes en bref
brailleignore-c. Utilisez-le avec--ditherpour les photos et sans pour les logos. Les couleurs suivent la photo, ou--fg.halfblockignore-c,--ditheret--fg, car les couleurs sont l'image. Le texte brut (sans--color) n'a pas de couleurs, donc chaque cellule devient un bloc d'ombre█▓▒░selon la luminosité.--bg nonene le rend pas transparent : les pixels transparents deviennent noirs.- Les terminaux dessinent les points braille petits, donc le braille y paraît plus sombre que dans un PNG.
Affiche de tuiles
--mode tiles crée une affiche : une grille de tuiles carrées dans quelques couleurs calmes, chacune avec un glyphe, sur une page charbon. Là où l'image est proche de la couleur de la page, les cellules ne sont pas des tuiles : elles montrent un glyphe faible, donc la grille continue partout.
uv run scripts/ascii.py photo.jpg --mode tiles -w 36 -o poster.png
- Valeurs par défaut en mode tuiles : cellules carrées (
--aspect 1),--font-size 80(tuiles de 48 px),--gap 1,--bg "#1d1f22". La sortie texte conserve--aspect 0.5. --palette 8: nombre de couleurs de tuiles, choisies une fois dans le sujet. Utilisez 4–6 pour un aspect plus plat et plus calme.- Les glyphes sont aléatoires.
--seed Nen choisit un autre ensemble. Donnez-cpour utiliser plutôt les glyphes de la rampe. - Photo avec fond clair : utilisez une page claire, comme
--bg "#ecebe6". Alors les parties sombres deviennent des tuiles. - Fonctionne aussi dans
animate.py. Les glyphes et couleurs restent les mêmes d'une image à l'autre.
Affiche de mots
--mode words remplit le canevas de mots en majuscules, séparés par un espace. Chaque ligne commence à son propre décalage et dépasse des deux bords. L'image n'apparaît qu'à travers la luminosité de chaque mot : un niveau par mot, à partir de la moyenne de l'image en dessous. Les parties sombres donnent des mots faibles et le sujet des mots lumineux.
--words "A B C"définit le vocabulaire (séparé par des espaces ou des virgules). Par défaut, c'est une courte liste de mots typographiques et de pixels.--accent "#f28c28"place une boîte pleine derrière les mots les plus colorés, avec du texte sombre.--accent-level 0.5(0-1) est le degré de coloration requis pour un mot. Les photos grises n'ont pas de boîtes ; un logo entièrement coloré en a beaucoup, donc augmentez le niveau.- L'arrière-plan par défaut est
#1d1f22.--gapdéfinit l'espacement en px entre les boîtes dans les rangées empilées.--seedchoisit une autre disposition.--fgest ignoré. - Cela fonctionne mieux sur un sujet clair et simple sur fond sombre. Pour un sujet sombre sur une photo claire, ajoutez
--invert. - Dans
animate.py, la disposition reste la même dans chaque image ; seule la luminosité change.
Préréglage : --mode words -w 110 --font-size 16 --accent "#f28c28" -o poster.png
Préréglages
- Matrix :
-c binary --fg matrix --glow 0.8 -o out.png - Terminal rétro ambre :
-c terminal --fg amber -o out.png - Mosaïque photo en couleur :
-c detailed -w 160 -o out.html - Meilleure photo couleur dans un terminal :
--mode halfblock --color - Dessin fin au point :
--mode braille --dither --sharpen -o out.png - Film noir :
--fg "#e8e6df" --contrast 1.35 --bg "#050505" --glow 0.7 -o out.png - Prêt pour l'impression :
--bg white -o out.png - Affiche de tuiles :
--mode tiles -w 36 -o poster.png
Animation
scripts/animate.py crée une animation ASCII. Il accepte les mêmes options d'apparence que ascii.py (-w, -c, --mode, --sharpen, --bg, --fg, --invert, --contrast, --brightness, --font-size, --aspect, --gap, --glow, et les options d'affiche de mots et de tuiles). L'entrée vidéo et la sortie .mp4 nécessitent ffmpeg. GIF et WebP non.
uv run scripts/animate.py cat.gif # jouer dans le terminal, Ctrl-C arrête
uv run scripts/animate.py cat.gif -o out.gif # aussi .webp, .mp4, ou .html (un fichier avec un lecteur play/pause)
uv run scripts/animate.py clip.mp4 -o out.html --start 2 --duration 4 --fps 12
uv run scripts/animate.py photo.jpg --effect matrix -o intro.gif # animer une image fixe
- Entrée : GIF animé, WebP ou APNG, toute vidéo lue par ffmpeg, ou une image fixe avec
--effect. - La temporisation des images provient de la source.
--fpsrééchantillonne.--startet--durationsélectionnent une tranche en secondes. - Il s'arrête à 300 images par défaut et le signale. Augmentez
--max-frames, ou diminuez--fps, pour des clips plus longs. - Une plage tonale unique (et dans le braille un seuil de point unique) est utilisée pour toutes les images, donc la luminosité ne pompe pas.
- Les zones stables ne scintillent pas : un pixel conserve sa valeur jusqu'à ce qu'elle change de plus de
--steady(6 par défaut, sur 255). Augmentez à 16 ou plus pour un film granuleux.--steady 0le désactive. - La vidéo entrelacée est désentrelacée, et la vidéo avec des pixels non carrés conserve sa forme réelle.
- Évitez
--ditherpour l'animation : cela fait ramper les glyphes d'une image à l'autre. - Les GIF ne peuvent pas jouer à plus d'environ 50 fps, donc une vidéo rapide perd certaines images dans
.gif. Utilisez.mp4ou.webppour un 60 fps fluide.
Figures sur fond uni
Pour une figure sombre sur fond clair, comme le cheval qui court de Muybridge, utilisez --bg white. Alors la figure reçoit l'encre et la page reste propre. --mode braille donne la figure animée la plus nette, et --mode halfblock conserve les tons de la photo.
uv run scripts/animate.py horse.gif --mode braille --bg white -o horse.gif
uv run scripts/animate.py juggler.webm --start 17 --duration 4 --mode braille --subject -o juggler.gif
--subject ne conserve que ce qui bouge et peint le reste comme une page vide (blanche lorsque l'arrière-plan est clair, sauf si vous définissez --bg). Il nécessite une caméra fixe : il prend l'arrière-plan à partir de la médiane d'au maximum 25 images. Notes :
- Les parties qui restent immobiles pendant la majeure partie du clip, comme une tête, sont considérées comme arrière-plan et s'estompent.
- Si les bords de l'image changent constamment, la caméra bouge : il le signale et laisse les images telles quelles. Un panoramique lent n'est pas toujours détecté et laisse des contours.
- Dans les clips où chaque image est une photo différente (le cheval et le buffle de Muybridge), utilisez
--bg whiteà la place. --subject-cut(40 par défaut, sur 255) est la différence qu'un pixel doit avoir par rapport à l'arrière-plan pour être compté. Abaissez-le pour une figure faible, augmentez-le pour une vidéo bruitée.
Effets pour images fixes
--effect NAME transforme une image en une intro de 2 à 3,2 secondes à 25 fps qui se termine sur l'art fini et le maintient pendant 1,5 seconde. Chaque effet fonctionne avec tous les modes.
matrix: colonnes tombantes de glyphes avec une tête brillante, laissant l'art derrière elles.decode: les cellules se mélangent à travers des glyphes aléatoires et se verrouillent, balayant de gauche à droite.scan: une ligne CRT brillante balaye vers le bas et tape chaque ligne, avec une courte lueur.glitch: courtes rafales de lignes déchirées, échanges de glyphes et bandes rouge/cyan. Boucle bien.wave: les lignes se balancent latéralement sur une onde sinusoïdale qui gonfle et se calme. Boucle bien.
Scènes
--scene NAME dessine une animation en boucle dans le code, donc aucun fichier d'entrée n'est nécessaire. Chaque boucle dure 2 à 3,2 secondes, et la dernière image se fond dans la première. Tous les modes, options de couleur et sorties fonctionnent. --seed N donne une autre variante (feu, vagues, étoiles, pluie), et --fps change la fluidité mais conserve la durée de la boucle.
uv run scripts/animate.py --scene fire -o fire.gif # flammes montantes, couleurs chaudes
uv run scripts/animate.py --scene donut -o donut.gif # un donut tournant, éclairé et glacé
uv run scripts/animate.py --scene cube --mode braille -o cube.gif # un cube culbutant avec des bords brillants
uv run scripts/animate.py --scene waves --mode halfblock -o waves.gif # houle océanique sous la lune
uv run scripts/animate.py --scene stars -o stars.gif # vol à travers un champ d'étoiles
uv run scripts/animate.py --scene walker --mode braille -o run.gif # un bonhomme allumette courant sur place
uv run scripts/animate.py --scene rain --mode braille -o rain.gif # pluie avec éclaboussures
uv run scripts/animate.py --scene bounce --mode halfblock -o ball.gif # une balle qui s'écrase en rebondissant
uv run scripts/animate.py --scene text --mode halfblock -o text.gif # le mot ASCII chevauchant une vague arc-en-ciel
- Utilisez
-w 60à-w 100.--mode halfblockdonne la meilleure couleur ;--mode brailledonne les lignes les plus nettes. - Sans
-ola scène est jouée dans le terminal. - Une scène est une simple fonction dans
scripts/scenes.py:scene(w, h, n, seed)retournenimages qui bouclent. Pour en ajouter une, écrivez la fonction et donnez-lui la ligne@scene(width, height, frames, fps).
À partir d'une description
Lorsque l'utilisateur décrit une chose animée ("un cheval qui court") au lieu de donner un fichier, trouvez d'abord un clip libre. scripts/fetch.py recherche sur Wikimedia Commons des GIF animés et de courtes vidéos avec une licence libre et télécharge la meilleure correspondance.
- Récupérez un clip :
uv run scripts/fetch.py "running horse" -o /tmp/clip. Il ajoute la bonne extension (.gif,.webm), puis imprime le chemin enregistré et une ligne d'attribution. Pour choisir vous-même, exécutez d'abord avec--list, puis--pick N. - Convertissez le chemin imprimé :
uv run scripts/animate.py /tmp/clip.gif --mode braille -w 80 --bg white -o out.gif. N'importe quel préréglage fonctionne. Pour les longues vidéos, ajoutez--duration 5. - Regardez une image du résultat. Si le sujet est difficile à voir, essayez
--pickavec un autre résultat. - Donnez à l'utilisateur la ligne d'attribution avec le résultat. La plupart des licences (CC BY, CC BY-SA) l'exigent.
Recherchez avec des mots anglais simples et courts pour le sujet et le mouvement. Les dessins au trait, les silhouettes et les clips sur fond uni se lisent le mieux en ASCII. Les vidéos réelles chargées ne fonctionnent souvent pas.
Si rien de approprié n'est trouvé, utilisez plutôt une scène dessinée dans le code : animate.py --scene NOM (voir "Scènes").
Utilisation Python
import sys; sys.path.insert(0, "scripts")
from PIL import Image
from ascii import convert, to_text, to_png
grid = convert(Image.open("cat.jpg"), width=80, charset="blocks", dither=True)
# Les cellules sont (caractère, (r, v, b)). Avec mode="halfblock", ce sont (caractère, haut_rgb, bas_rgb).
# Avec mode="tiles", les cellules de tuiles sont (caractère, encre_rgb, tuile_rgb).
print(to_text(grid))
to_png(grid).save("cat_ascii.png")
from effects import frames # liste de grilles ; la dernière est `grid`
intro = [to_png(g) for g in frames(grid, "decode")]