ASCII art
scripts/ascii.py crea imágenes fijas y scripts/animate.py crea animaciones (ver «Animación»). Ambos solo necesitan Python 3.9+ y Pillow (además de ffmpeg para video). Con uv instalado, uv run descarga Pillow automáticamente.
uv run scripts/ascii.py IMAGEN [opciones] # o: python3 scripts/ascii.py (necesita pillow)
Las rutas siguientes son relativas a la carpeta de esta habilidad.
Pasos
- Obtén la ruta de la imagen. Para una URL, descárgala primero con
curl -L -o /tmp/in.img URL. - Elige la salida. Usa salida estándar para mostrar el arte en el chat. Usa
-o archivo.pngo-o archivo.htmlcuando el usuario quiera un archivo para compartir. - Ejecútalo y luego lee el resultado. Para un PNG, abre la imagen y mírala.
- Si el sujeto es difícil de ver, ajusta y vuelve a ejecutar (ver «Corregir resultados débiles»).
Opciones
| Opción | Qué hace |
|---|---|
-w 100 | Ancho en caracteres (1–1000). Usa 60–80 para chat, 120–200 para PNG/HTML, 120+ para capturas de texto. |
-c standard | Rampa de caracteres: standard, detailed, blocks, terminal, minimal, binary, dots, o tu propia cadena de denso a vacío, como -c "#*. ". |
-o out.png | Salida por extensión: .txt, .html, .png, .jpg, .webp. Sin -o imprime texto plano a stdout. |
--bg black | Fondo: black (predeterminado), white, none (PNG/HTML transparente), o cualquier color. Sobre fondo oscuro, los píxeles brillantes obtienen glifos densos. Sobre fondo claro, los píxeles oscuros. |
--fg matrix | Un color de tinta: matrix, amber, cyan, magenta, mint, o cualquier color CSS o hexadecimal. Sin él, PNG/HTML usan los colores reales de la foto. |
--color | Códigos de escape ANSI truecolor en la salida de texto (stdout o .txt). Usa --fg si se da, si no, los colores de la foto. |
--invert | Intercambia claro y oscuro. |
--contrast 1.0 --brightness 1.0 | Factores adicionales sobre el estiramiento automático de contraste. 1.0 significa sin cambios. |
--dither | Difuminado Floyd-Steinberg. Bueno para degradados suaves y rampas cortas como blocks o minimal. |
--mode ramp | ramp (predeterminado): un glifo por píxel, elegido por brillo. shape: como ramp, pero los bordes se dibujan con símbolos de la misma forma (`/ \ |
--sharpen | Afila los bordes antes de reducir. Ayuda a rostros y detalles finos, sobre todo en modo braille. |
--aspect 0.5 | Ancho del carácter dividido por altura. Auméntalo si el arte se ve aplastado. |
--font-size 12 | Tamaño del glifo en píxeles para PNG/HTML. |
--glow 0.8 | Resplandor suave alrededor de los glifos (0-1) en PNG, HTML y animación, como luz en una pantalla antigua. Mejor sobre fondo oscuro. |
Corregir resultados débiles
El script ya estira cada imagen a su rango tonal completo, por lo que la mayoría de las imágenes se ven bien sin ajustes.
- Fotos:
-c blocks --ditherda los rostros y animales más reconocibles. - Sujeto oscuro (perro negro, escena nocturna) desaparece sobre fondo negro: usa
--bg white. Aumentar--brightness 1.5también ayuda. Aumentar el contraste empeora las escenas oscuras. - Logotipo oscuro sobre fondo blanco se muestra como un bloque sólido: añade
--bg white(o--invertpara salida de terminal). - ¿Quieres más detalle al mismo ancho?:
--mode braille --dither --sharpenpara estilo de arte lineal,--mode halfblockpara una foto en color. - Demasiado ruido: usa menos columnas o una rampa más corta (
-c minimal). - Bandas en degradados: añade
--dither. - Salida de chat: nunca uses
--color, porque los códigos de escape aparecen como basura. Envuelve el texto en un bloque de código. - SVG no es compatible. Conviértelo a PNG primero (
rsvg-convert -w 800 logo.svg -o logo.png).
Modos en breve
brailleignora-c. Úsalo con--ditherpara fotos y sin él para logotipos. Los colores siguen la foto, o--fg.halfblockignora-c,--dithery--fg, porque los colores son la imagen. El texto plano (sin--color) no tiene colores, por lo que cada celda se convierte en un bloque de sombra█▓▒░según el brillo.--bg noneno lo vuelve transparente: los píxeles transparentes se vuelven negros.- Los terminales dibujan los puntos braille pequeños, por lo que el braille se ve más tenue allí que en un PNG.
Póster de azulejos
--mode tiles hace un póster: una cuadrícula de azulejos cuadrados en unos pocos colores suaves, cada uno con un glifo, sobre una página carbón. Donde la imagen se acerca al color de la página, las celdas no son azulejos: muestran un glifo tenue, por lo que la cuadrícula continúa en todas partes.
uv run scripts/ascii.py photo.jpg --mode tiles -w 36 -o poster.png
- Valores predeterminados en modo tiles: celdas cuadradas (
--aspect 1),--font-size 80(azulejos de 48 px),--gap 1,--bg "#1d1f22". La salida de texto mantiene--aspect 0.5. --palette 8: número de colores de azulejos, elegidos una vez del sujeto. usa 4–6 para un aspecto más plano y tranquilo.- Los glifos son aleatorios.
--seed Nelige otro conjunto. usa-cpara usar glifos de rampa. - Foto con fondo claro: usa una página clara, como
--bg "#ecebe6". Entonces las partes oscuras se convierten en azulejos. - También funciona en
animate.py. Los glifos y colores se mantienen iguales de un fotograma a otro.
Póster de palabras
--mode words llena el lienzo con palabras en mayúsculas, separadas por un espacio. Cada fila comienza en su propio desplazamiento y se sale por ambos bordes. La imagen se muestra solo a través del brillo de cada palabra: un nivel por palabra, de la media de la imagen debajo de ella. Las partes oscuras dan palabras tenues y el sujeto da palabras brillantes.
--words "A B C"establece el vocabulario (separado por espacios o comas). El predeterminado es una lista corta de palabras de tipo y píxel.--accent "#f28c28"pone un cuadro sólido detrás de las palabras más coloridas, con texto oscuro.--accent-level 0.5(0-1) es cuán colorida debe ser una palabra. Las fotos en gris no obtienen cuadros; un logotipo completamente colorido obtiene muchos, por lo que debes subir el nivel.- El fondo predeterminado es
#1d1f22.--gapestablece los píxeles entre cuadros en filas apiladas.--seedelige otra disposición.--fgse ignora. - Funciona mejor sobre un sujeto brillante y simple sobre un fondo oscuro. Para un sujeto oscuro sobre una foto clara, añade
--invert. - En
animate.pyla disposición se mantiene igual en cada fotograma; solo cambia el brillo.
Preestablecido: --mode words -w 110 --font-size 16 --accent "#f28c28" -o poster.png
Preestablecidos
- Matrix:
-c binary --fg matrix --glow 0.8 -o out.png - Terminal ámbar retro:
-c terminal --fg amber -o out.png - Mosaico de fotos en color:
-c detailed -w 160 -o out.html - Mejor foto en color en terminal:
--mode halfblock --color - Dibujo de puntos finos:
--mode braille --dither --sharpen -o out.png - Cine negro:
--fg "#e8e6df" --contrast 1.35 --bg "#050505" --glow 0.7 -o out.png - Apto para impresión:
--bg white -o out.png - Póster de azulejos:
--mode tiles -w 36 -o poster.png
Animación
scripts/animate.py hace animación ASCII. Acepta las mismas opciones de aspecto que ascii.py (-w, -c, --mode, --sharpen, --bg, --fg, --invert, --contrast, --brightness, --font-size, --aspect, --gap, --glow, y las opciones de póster de palabras y azulejos). La entrada de video y la salida .mp4 necesitan ffmpeg. GIF y WebP no.
uv run scripts/animate.py cat.gif # reproduce en terminal, Ctrl-C detiene
uv run scripts/animate.py cat.gif -o out.gif # también .webp, .mp4, o .html (un archivo con reproductor play/pausa)
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 # anima una imagen fija
- Entrada: GIF animado, WebP o APNG, cualquier video que ffmpeg lea, o una imagen fija con
--effect. - La sincronización de fotogramas proviene de la fuente.
--fpsremuestrea.--starty--durationseleccionan un segmento en segundos. - Se detiene en 300 fotogramas por defecto y lo indica. Aumenta
--max-frameso reduce--fpspara clips más largos. - Se usa un solo rango tonal (y en braille un solo umbral de puntos) para todos los fotogramas, por lo que el brillo no fluctúa.
- Las áreas estáticas no parpadean: un píxel mantiene su valor hasta que cambia más de
--steady(predeterminado 6, de 255). Auméntalo a 16 o más para película granulada.--steady 0lo desactiva. - El video entrelazado se desentrelaza, y el video con píxeles no cuadrados mantiene su forma real.
- Evita
--ditherpara animación: hace que los glifos se arrastren de un fotograma a otro. - GIF no puede reproducirse más rápido que aproximadamente 50 fps, por lo que el video rápido pierde algunos fotogramas en
.gif. Usa.mp4o.webppara 60 fps suaves.
Figuras sobre fondo plano
Para una figura oscura sobre fondo claro, como el caballo corriendo de Muybridge, usa --bg white. Entonces la figura recibe la tinta y la página se mantiene limpia. --mode braille da la figura en movimiento más nítida, y --mode halfblock mantiene los tonos de la foto.
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 mantiene solo lo que se mueve y pinta el resto como una página vacía (blanco cuando el fondo es claro, a menos que establezcas --bg). Necesita una cámara fija: toma el fondo de la mediana de hasta 25 fotogramas. Notas:
- Las partes que se mantienen quietas durante la mayor parte del clip, como una cabeza, cuentan como fondo y se desvanecen.
- Si los bordes de la imagen cambian constantemente, la cámara se mueve: lo indica y deja los fotogramas como están. Un movimiento panorámico lento no siempre se detecta y deja contornos.
- En clips donde cada fotograma es una foto diferente (el caballo y el búfalo de Muybridge), usa
--bg whiteen su lugar. --subject-cut(predeterminado 40, de 255) es cuánto debe diferir un píxel del fondo para contar. Bájalo para una figura tenue, súbelo para video ruidoso.
Efectos para imágenes fijas
--effect NOMBRE convierte una imagen en una intro de 2 a 3.2 segundos a 25 fps que termina en el arte terminado y lo mantiene durante 1.5 segundos. Todos los efectos funcionan con todos los modos.
matrix: columnas descendentes de glifos con una cabeza brillante, dejando el arte detrás.decode: las celdas se mezclan con glifos aleatorios y se bloquean, barriendo de izquierda a derecha.scan: una línea CRT brillante barre hacia abajo y escribe cada fila, con un breve resplandor.glitch: ráfagas cortas de filas rasgadas, intercambios de glifos y bandas rojas/cián. Buena para bucle.wave: las filas se balancean lateralmente en una onda sinusoidal que crece y se calma. Buena para bucle.
Escenas
--scene NOMBRE dibuja una animación en bucle en código, por lo que no se necesita archivo de entrada. Cada bucle es de 2 a 3.2 segundos, y el último fotograma fluye hacia el primero. Todos los modos, opciones de color y salida funcionan. --seed N da otra variante (fuego, olas, estrellas, lluvia), y --fps cambia la suavidad pero mantiene la longitud del bucle.
uv run scripts/animate.py --scene fire -o fire.gif # llamas ascendentes, colores cálidos
uv run scripts/animate.py --scene donut -o donut.gif # una dona giratoria, iluminada y glaseada
uv run scripts/animate.py --scene cube --mode braille -o cube.gif # un cubo que cae con bordes brillantes
uv run scripts/animate.py --scene waves --mode halfblock -o waves.gif # oleaje oceánico bajo la luna
uv run scripts/animate.py --scene stars -o stars.gif # volando a través de un campo estelar
uv run scripts/animate.py --scene walker --mode braille -o run.gif # una figura de palitos corriendo en el lugar
uv run scripts/animate.py --scene rain --mode braille -o rain.gif # lluvia con salpicaduras
uv run scripts/animate.py --scene bounce --mode halfblock -o ball.gif # una pelota que se aplasta al botar
uv run scripts/animate.py --scene text --mode halfblock -o text.gif # la palabra ASCII montando una ola arcoíris
- Usa
-w 60a-w 100.--mode halfblockda el mejor color;--mode brailleda las líneas más nítidas. - Sin
-ola escena se reproduce en la terminal. - Una escena es una función simple en
scripts/scenes.py:scene(w, h, n, seed)devuelvenimágenes que hacen bucle. Para añadir una, escribe la función y dale la línea@scene(width, height, frames, fps).
A partir de una descripción
Cuando el usuario describe algo en movimiento («un caballo corriendo») en lugar de dar un archivo, busca primero un clip libre. scripts/fetch.py busca en Wikimedia Commons GIF animados y videos cortos con licencia libre y descarga la mejor coincidencia.
- Obtén un clip:
uv run scripts/fetch.py "caballo corriendo" -o /tmp/clip. Añade la extensión correcta (.gif,.webm), luego imprime la ruta guardada y una línea de atribución. Para elegir tú mismo, ejecuta primero con--list, luego--pick N. - Convierte la ruta impresa:
uv run scripts/animate.py /tmp/clip.gif --mode braille -w 80 --bg white -o out.gif. Cualquier preestablecido funciona. Para videos largos añade--duration 5. - Mira un fotograma del resultado. Si el sujeto es difícil de ver, prueba
--pickcon otro resultado. - Entrega al usuario la línea de atribución junto con el resultado. La mayoría de las licencias (CC BY, CC BY-SA) la requieren.
Busca con palabras breves en inglés simple para el sujeto y el movimiento. Los dibujos lineales, siluetas y clips sobre fondo plano se leen mejor como ASCII. El video real del mundo real y ocupado a menudo no.
Si no se encuentra nada adecuado, usa una escena dibujada en código: animate.py --scene NOMBRE (ver «Escenas»).
Uso en 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)
# Las celdas son (char, (r, g, b)). Con mode="halfblock" son (char, top_rgb, bottom_rgb).
# Con mode="tiles", las celdas de azulejo son (char, ink_rgb, tile_rgb).
print(to_text(grid))
to_png(grid).save("cat_ascii.png")
from effects import frames # lista de cuadrículas; la última es `grid`
intro = [to_png(g) for g in frames(grid, "decode")]