CommunityImagemgithub.com

arte-ascii

Transforme qualquer imagem, GIF ou vídeo em arte ASCII ou animação ASCII, como texto simples, saída de terminal truecolor, HTML, PNG, GIF, WebP ou MP4. Também anima imagens estáticas com efeitos matrix, chuva, decodificação, varredura, glitch e onda. Também cria animação ASCII a partir de uma descrição curta como "um cavalo correndo", usando um clipe licenciado livremente do Wikimedia Commons.

O que é arte-ascii?

O pacote de habilidades `arte-ascii` fornece uma ferramenta versátil, baseada em Python, para converter mídia visual em arte ASCII e animações. Ele inclui dois scripts principais: `scripts/ascii.py` para imagens estáticas e `scripts/animate.py` para animações. A saída pode ser gerada em vários formatos como texto simples, HTML, PNG, GIF, WebP e MP4, suportando uma ampla gama de opções de personalização, como diferentes rampas de caracteres, modos de saída (incluindo meios-blocos e braille para imagens coloridas), esquemas de cores e efeitos visuais. Sua funcionalidade principal está em tornar imagens e vídeos acessíveis em formatos textuais, ideal para criar arte de terminal, pôsteres ou conteúdo de mídia social. Ele suporta vários métodos de conversão, incluindo uma opção de pôster de palavras e um modo de pôster de azulejos que transforma imagens em composições abstratas com grade. Para animação, `animate.py` pode manipular arquivos GIF, WebP e vídeos, aplicar efeitos de transição a imagens estáticas, gerar cenas animadas proceduralmente (fogo, ondas, estrelas, chuva) e até mesmo buscar clipes do Wikimedia Commons a partir de uma descrição textual. A habilidade foi projetada para ambientes de desenvolvimento, fornecendo funções Python reutilizáveis (`convert`, `to_text`, `to_png`) para integração em projetos maiores. Ela depende apenas do Python 3.9+ e da biblioteca Pillow (mais ffmpeg para suporte a vídeo), com gerenciamento automático de dependências via `uv`, tornando a configuração trivial.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/rasabaq/ascii-skill/tree/HEAD

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Arte ASCII

scripts/ascii.py cria imagens estáticas e scripts/animate.py cria animações (veja "Animação"). Ambos precisam apenas de Python 3.9+ e Pillow (mais ffmpeg para vídeo). Com uv instalado, uv run baixa o Pillow automaticamente.

uv run scripts/ascii.py IMAGEM [opções]          # ou: python3 scripts/ascii.py (precisa do pillow)

Os caminhos abaixo são relativos à pasta desta habilidade.

Etapas

  1. Obtenha o caminho da imagem. Para uma URL, baixe-a primeiro com curl -L -o /tmp/in.img URL.
  2. Escolha a saída. Use saída padrão (stdout) para mostrar a arte no chat. Use -o arquivo.png ou -o arquivo.html quando o usuário quiser um arquivo para compartilhar.
  3. Execute e, em seguida, leia o resultado. Para um PNG, abra a imagem e observe-a.
  4. Se o assunto estiver difícil de ver, ajuste e execute novamente (veja "Corrigindo resultados fracos").

Opções

OpçãoO que faz
-w 100Largura em caracteres (1–1000). Use 60–80 para chat, 120–200 para PNG/HTML, 120+ para capturas de tela de texto.
-c standardRampa de caracteres: standard, detailed, blocks, terminal, minimal, binary, dots, ou sua própria string de denso a vazio, como -c "#*. ".
-o saida.pngSaída por extensão: .txt, .html, .png, .jpg, .webp. Sem -o, imprime texto simples em stdout.
--bg blackFundo: black (padrão), white, none (PNG/HTML transparente) ou qualquer cor. Em um fundo escuro, pixels brilhantes recebem glifos densos. Em um claro, pixels escuros recebem.
--fg matrixUma cor de tinta: matrix, amber, cyan, magenta, mint ou qualquer cor CSS ou hexadecimal. Sem ele, PNG/HTML usam as cores da própria foto.
--colorCódigos ANSI truecolor na saída de texto (stdout ou .txt). Usa --fg se fornecido, senão as cores da foto.
--invertInverte claro e escuro.
--contrast 1.0 --brightness 1.0Fatores aplicados além do ajuste automático de contraste. 1.0 significa sem alteração.
--ditherPontilhamento Floyd-Steinberg. Bom para gradientes suaves e rampas curtas como blocks ou minimal.
--mode rampramp (padrão): um glifo por pixel, escolhido pelo brilho. shape: como ramp, mas as bordas são desenhadas com símbolos da mesma forma (`/ \
--sharpenNitidez nas bordas antes de reduzir. Ajuda rostos e detalhes finos, principalmente no modo braille.
--aspect 0.5Largura do caractere dividida pela altura. Aumente se a arte parecer achatada.
--font-size 12Tamanho do glifo em px para PNG/HTML.
--glow 0.8Brilho suave ao redor dos glifos (0-1) em PNG, HTML e animação, como luz em uma tela antiga. Melhor em um fundo escuro.

Corrigindo resultados fracos

O script já estica cada imagem para sua faixa tonal completa, então a maioria das imagens fica boa sem ajustes.

  • Fotos: -c blocks --dither dá os rostos e animais mais reconhecíveis.
  • Assunto escuro (cachorro preto, cena noturna) desaparece no fundo preto: use --bg white. Aumentar --brightness 1.5 também ajuda. Aumentar o contraste piora cenas escuras.
  • Logotipo escuro em fundo branco aparece como um bloco sólido: adicione --bg white (ou --invert para saída de terminal).
  • Quer mais detalhes na mesma largura: --mode braille --dither --sharpen para estilo de arte de linha, --mode halfblock para uma foto colorida.
  • Muito ruído: use menos colunas ou uma rampa mais curta (-c minimal).
  • Faixas em gradientes: adicione --dither.
  • Saída de chat: nunca use --color, porque códigos de escape aparecem como lixo. Coloque o texto em um bloco de código.
  • SVG não é suportado. Converta para PNG primeiro (rsvg-convert -w 800 logo.svg -o logo.png).

Modos em resumo

  • braille ignora -c. Use com --dither para fotos e sem ele para logotipos. As cores seguem a foto, ou --fg.
  • halfblock ignora -c, --dither e --fg, porque as cores são a imagem. Texto simples (sem --color) não tem cores, então cada célula se torna um bloco de sombra █▓▒░ pelo brilho. --bg none não o torna transparente: pixels transparentes tornam-se pretos.
  • Terminais desenham pontos braille pequenos, então o braille parece mais escuro lá do que em um PNG.

Pôster de azulejos

--mode tiles cria um pôster: uma grade de azulejos quadrados em algumas cores calmas, cada um com um glifo, em uma página carvão. Onde a imagem está próxima da cor da página, as células não são azulejos: elas mostram um glifo tênue, então a grade continua em todos os lugares.

uv run scripts/ascii.py photo.jpg --mode tiles -w 36 -o poster.png
  • Padrões no modo tiles: células quadradas (--aspect 1), --font-size 80 (azulejos de 48 px), --gap 1, --bg "#1d1f22". A saída de texto mantém --aspect 0.5.
  • --palette 8: número de cores de azulejo, escolhidas uma vez a partir do assunto. Use 4–6 para uma aparência mais plana e calma.
  • Os glifos são aleatórios. --seed N escolhe outro conjunto. Use -c para usar glifos de rampa.
  • Foto com fundo claro: use uma página clara, como --bg "#ecebe6". Então, partes escuras se tornam azulejos.
  • Funciona também em animate.py. Glifos e cores permanecem os mesmos de quadro a quadro.

Pôster de palavras

--mode words preenche a tela com palavras em maiúsculas, separadas por um espaço. Cada linha começa em seu próprio deslocamento e ultrapassa ambas as bordas. A imagem aparece apenas através do brilho de cada palavra: um nível por palavra, a partir da média da imagem abaixo dela. Partes escuras produzem palavras fracas e o assunto produz palavras claras.

  • --words "A B C" define o vocabulário (separado por espaço ou vírgula). O padrão é uma lista curta de palavras de tipo e pixel.
  • --accent "#f28c28" coloca uma caixa sólida atrás das palavras mais coloridas, com texto escuro. --accent-level 0.5 (0-1) é o quão colorida uma palavra deve ser. Fotos em cinza não têm caixas; um logotipo totalmente colorido ganha muitas, então aumente o nível.
  • O fundo padrão é #1d1f22. --gap define o px entre caixas em linhas empilhadas. --seed escolhe outro layout. --fg é ignorado.
  • Funciona melhor em um assunto brilhante e simples em um fundo escuro. Para um assunto escuro em uma foto clara, adicione --invert.
  • Em animate.py o layout permanece o mesmo em cada quadro; apenas o brilho muda.

Predefinição: --mode words -w 110 --font-size 16 --accent "#f28c28" -o poster.png

Predefinições

  • Matrix: -c binary --fg matrix --glow 0.8 -o out.png
  • Terminal âmbar retrô: -c terminal --fg amber -o out.png
  • Mosaico de fotos em cores: -c detailed -w 160 -o out.html
  • Melhor foto colorida em um terminal: --mode halfblock --color
  • Desenho de pontos finos: --mode braille --dither --sharpen -o out.png
  • Film noir: --fg "#e8e6df" --contrast 1.35 --bg "#050505" --glow 0.7 -o out.png
  • Amigável para impressão: --bg white -o out.png
  • Pôster de azulejos: --mode tiles -w 36 -o poster.png

Animação

scripts/animate.py faz animação ASCII. Ele aceita as mesmas opções de aparência que ascii.py (-w, -c, --mode, --sharpen, --bg, --fg, --invert, --contrast, --brightness, --font-size, --aspect, --gap, --glow e as opções de pôster de palavras e azulejos). Entrada de vídeo e saída .mp4 precisam de ffmpeg. GIF e WebP não.

uv run scripts/animate.py cat.gif                          # reproduz no terminal, Ctrl-C para
uv run scripts/animate.py cat.gif -o out.gif               # também .webp, .mp4 ou .html (um arquivo com player 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   # anima uma imagem estática
  • Entrada: GIF animado, WebP ou APNG, qualquer vídeo que ffmpeg leia, ou uma imagem estática com --effect.
  • O tempo dos quadros vem da fonte. --fps reamostra. --start e --duration selecionam um trecho em segundos.
  • Ele para em 300 quadros por padrão e avisa. Aumente --max-frames ou abaixe --fps para clipes mais longos.
  • Uma única faixa tonal (e no braille, um único limite de ponto) é usada para todos os quadros, então o brilho não varia.
  • Áreas estáticas não piscam: um pixel mantém seu valor até mudar mais que --steady (padrão 6, de 255). Aumente para 16 ou mais para filme granulado. --steady 0 desliga.
  • Vídeo entrelaçado é desentrelaçado, e vídeo com pixels não quadrados mantém sua forma real.
  • Evite --dither para animação: ele faz os glifos rastejarem de quadro a quadro.
  • GIF não pode reproduzir mais rápido que cerca de 50 fps, então vídeo rápido perde alguns quadros em .gif. Use .mp4 ou .webp para 60 fps suaves.

Figuras em um fundo simples

Para uma figura escura em um fundo claro, como o cavalo correndo de Muybridge, use --bg white. Então a figura recebe a tinta e a página permanece limpa. --mode braille dá a figura em movimento mais nítida, e --mode halfblock mantém os tons da 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 mantém apenas o que se move e pinta o resto como uma página vazia (branca quando o fundo é claro, a menos que você defina --bg). Precisa de uma câmera parada: ele pega o fundo da mediana de até 25 quadros. Notas:

  • Partes que ficam paradas na maior parte do clipe, como uma cabeça, contam como fundo e desaparecem.
  • Se as bordas da imagem mudam constantemente, a câmera se move: ele avisa e deixa os quadros como estão. Uma panorâmica lenta nem sempre é capturada e deixa contornos.
  • Em clipes onde cada quadro é uma foto diferente (cavalo e búfalo de Muybridge), use --bg white.
  • --subject-cut (padrão 40, de 255) é o quanto um pixel deve diferir do fundo para contar. Abaixe para uma figura tênue, aumente para vídeo com ruído.

Efeitos para imagens estáticas

--effect NOME transforma uma imagem em uma introdução de 2 a 3,2 segundos a 25 fps que termina na arte finalizada e a mantém por 1,5 segundos. Todo efeito funciona com todos os modos.

  • matrix: colunas caindo de glifos com uma cabeça brilhante, deixando a arte atrás delas.
  • decode: células se embaralham através de glifos aleatórios e travam, varrendo da esquerda para a direita.
  • scan: uma linha CRT brilhante varre para baixo e digita cada linha, com um brilho curto.
  • glitch: rajadas curtas de linhas rasgadas, trocas de glifos e faixas vermelhas/ciano. Faz loop bem.
  • wave: linhas balançam lateralmente em uma onda senoidal que cresce e acalma. Faz loop bem.

Cenas

--scene NOME desenha uma animação em loop em código, então nenhum arquivo de entrada é necessário. Cada loop tem 2 a 3,2 segundos, e o último quadro flui para o primeiro. Todos os modos, opções de cor e saída funcionam. --seed N dá outra variante (fogo, ondas, estrelas, chuva), e --fps muda a suavidade, mas mantém a duração do loop.

uv run scripts/animate.py --scene fire -o fire.gif                       # chamas crescentes, cores quentes
uv run scripts/animate.py --scene donut -o donut.gif                     # um donut girando, iluminado e com glacê
uv run scripts/animate.py --scene cube --mode braille -o cube.gif        # um cubo caindo com bordas brilhantes
uv run scripts/animate.py --scene waves --mode halfblock -o waves.gif    # ondulação do oceano sob a lua
uv run scripts/animate.py --scene stars -o stars.gif                     # voando por um campo estelar
uv run scripts/animate.py --scene walker --mode braille -o run.gif       # uma figura de palito correndo no lugar
uv run scripts/animate.py --scene rain --mode braille -o rain.gif        # chuva com respingos
uv run scripts/animate.py --scene bounce --mode halfblock -o ball.gif    # uma bola que achata ao quicar
uv run scripts/animate.py --scene text --mode halfblock -o text.gif      # a palavra ASCII montando uma onda arco-íris
  • Use -w 60 a -w 100. --mode halfblock dá a melhor cor; --mode braille dá as linhas mais nítidas.
  • Sem -o a cena é reproduzida no terminal.
  • Uma cena é uma função simples em scripts/scenes.py: scene(w, h, n, seed) retorna n imagens que fazem loop. Para adicionar uma, escreva a função e dê a ela a linha @scene(width, height, frames, fps).

A partir de uma descrição

Quando o usuário descreve algo em movimento ("um cavalo correndo") em vez de fornecer um arquivo, encontre um clipe gratuito primeiro. scripts/fetch.py pesquisa no Wikimedia Commons por GIFs animados e vídeos curtos com licença livre e baixa a melhor correspondência.

  1. Busque um clipe: uv run scripts/fetch.py "cavalo correndo" -o /tmp/clip. Ele adiciona a extensão correta (.gif, .webm) e, em seguida, imprime o caminho salvo e uma linha de atribuição. Para escolher você mesmo, execute com --list primeiro, depois --pick N.
  2. Converta o caminho impresso: uv run scripts/animate.py /tmp/clip.gif --mode braille -w 80 --bg white -o out.gif. Qualquer predefinição funciona. Para vídeos longos, adicione --duration 5.
  3. Olhe para um quadro do resultado. Se o assunto estiver difícil de ver, tente --pick com outro resultado.
  4. Dê ao usuário a linha de atribuição junto com o resultado. A maioria das licenças (CC BY, CC BY-SA) exige isso.

Pesquise com palavras simples em português para o assunto e o movimento. Desenhos de linha, silhuetas e clipes em um fundo simples são lidos melhor como ASCII. Vídeos do mundo real com muitos detalhes muitas vezes não funcionam.

Se nada adequado for encontrado, use uma cena desenhada em código: animate.py --scene NOME (veja "Cenas").

Uso em 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)
# Células são (char, (r, g, b)). Com mode="halfblock" são (char, top_rgb, bottom_rgb).
# Com mode="tiles", células de azulejo são (char, ink_rgb, tile_rgb).
print(to_text(grid))
to_png(grid).save("cat_ascii.png")

from effects import frames  # lista de grades; a última é `grid`
intro = [to_png(g) for g in frames(grid, "decode")]

Habilidades Relacionadas