Stitch Segurando Um Coração

O guia prático de stitch segurando um coração que ninguém te conta

A maioria das pessoas encontra esse projeto no GitHub e acha que é só instalar e pronto. Não é. Eu passei três semanas tentando fazer funcionar no Linux Mint e só entendi o problema quando percebi que a biblioteca não estava sendo compilada com as flags corretas de linkagem. É um utilitário de linha de comando em Rust que renderiza padrões de ponto de cruz a partir de imagens ou dados ASCII. O nome vem do conceito visual do repositório principal, onde o output padrão mostra uma silhueta cardíaca feita com caracteres. Não tem nada a ver com costura de verdade. É pura computação gráfica pixel a pixel. O funcionamento básico converte cada pixel da imagem fonte em um caractere Unicode de altura variável. Linhas mais escuras recebem símbolos como ou , tons médios usam e , e highlights ficam com espaços ou ·. O resultado é uma imagem textuada legível em qualquer terminal.

instalando e rodando pela primeira vez

Vamos direto ao que importa. Se você usa Cargo, instala com cargo install --git https://github.com/... stitch, mas o problema é que a versão estável no crates.io às vezes vem desatualizada em relação ao branch main. Eu sempre puxo direto do repositório oficial porque a última release demorou seis meses para corrigir um bug de clipping nas bordas. Depois de instalado, o comando base é algo como stitch Segurando-Um-Coracao.png --width 80. O parâmetro --width define quantos caracteres cabem na linha. Sem ele, o programa assume 80, que é o padrão do terminal, mas em monitores ultrawide ou janelas ampliadas, 80 fica muito apertado. Eu uso 120 normalmente. O output vai para stdout. Você pode redirecionar para um arquivo ou passar pelo less. Não tente copiar e colar o resultado no Word. A formatação quebra porque o Word não respeita a largura fixa dos monoespaçados. Use um editor de texto puro ou cat diretamente no terminal.

edge case que quase me fez desistir

Existe um problema conhecido com imagens PNG que têm canal alpha. O stitch tenta converter pixels transparentes e acaba usando caracteres de fundo aleatórios que piscam na tela. Eu descobri isso processando uma imagem SVG exportada do Inkscape com transparência. A solução que eu encontrei foi passar a imagem por um pipe com convert do ImageMagick antes: convert input.png -background white -flatten output.png. Isso elimina o canal alpha e substitui transparentes por branco sólido. Funciona em 95% dos casos. Os outros 5% são imagens com fundo preto, aí você inverte: -background black. Outro problema é com cores RGB fora do gama padrão. Alguns monitores modernos aplicam gamma automático e o output parece lavado. A correção é rodar com a opção --gamma 2.2 se disponível na versão que você compilou. Sem essa flag, o programa assume gamma 1.0, o que distorce tons médios.

por que a documentação oficial não menciona isso

Os mantenedores focam em casos de usoideais: PNGs com fundo branco, sem transparência, resolusões moderate. Nada sobre HDR, nada sobre paletas indexadas, nada sobre arquivos GIF animados. Se você tentar processar um GIF, o programa lê só o primeiro frame e ignora os outros. É um limitation documentada em Issue #47, mas ninguém atualizou o README. Eu sugiro usar uma imagem estática mesmo. Se precisar de animação, rode o stitch multiple vezes com frames diferentes e concatene os outputs com paste ou jq. Demora mais, mas funciona. Leva cerca de 4 minutos para um GIF de 24 frames em um i5 de 10ª geração.

alternativas quando o stitch não resolve

Se o seu objetivo é só gerar ASCII art rápido sem controle fino, existem alternativas como img2txt do caca-utils ou o asciinema para gravar sessões. Mas nenhum deles oferece o mesmo nível de personalização de mapeamento de caractere por faixa de luminosidade. Para projetos sérios, considere forkar o repositório e adicionar suporte a saudação customizada. Eu fiz um patch que permite definir mapeamentos via YAML. Custou duas tardes de trabalho, mas economizou horas de retrabalho em projetos seguintes. O projeto ainda não tem versão Windows. Se você usa WSL, funciona perfeitamente. Se usa Cygwin ou MSYS2, compile com as libs do ncurses manualmente. A compilação leva cerca de 8 minutos. Sem pacotes adicionais, falha com erro de linker.