CommunityImagemgithub.com

Dith

Usa a CLI dith para pontilhar fotos e logotipos, gerar texturas processuais e exportar animações retro ou de impressão em loop a partir de receitas reproduzíveis.

O que é Dith?

Dith é uma ferramenta CLI de pontilhamento determinístico construída para agentes de IA. Ela é ideal para desenvolvedores e designers que precisam de resultados pixel-perfeitos, reproduzíveis e previsíveis ao converter imagens em estilos de pontilhamento, como gravuras, impressões retrô, arte de jogos e gráficos de terminal. A ferramenta suporta múltiplos formatos de saída, incluindo PNG, WebP, SVG e até mesmo texto Braille para visualização em terminais. Sua infraestrutura 'recipe' permite salvar e reutilizar configurações, garantindo que o mesmo conjunto de entradas e flags produza arquivos byte-idênticos. O Dith funciona em diversas plataformas (macOS, Linux, Windows) e pode ser usado tanto em ambientes interativos quanto headless, fornecendo relatórios JSON detalhados para validação automática dos resultados. Além de pontilhar imagens estáticas, ele também pode gerar animações em loop a partir de padrões processuais, GIFs ou sequências de quadros, com controle sobre cintilação, paletas e temporização.

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

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

O que Dith faz?

dith é uma CLI de pontilhamento determinístico construída para agentes. Cada comando aceita --json, escreve saída exata de paleta e retorna um relatório legível por máquina. As mesmas entradas e flags sempre produzem arquivos byte-idênticos.

Configuração

  1. Verifique se o binário existe com dith --version.
    • Dentro da cópia fonte do dith sem uma instalação global, execute via cargo run --release -- <args> (ou mbx run -- <args> quando mbx estiver disponível).
    • Se o dith estiver ausente, informe o usuário e ofereça um comando de instalação de references/cli.md. Aguarde a aprovação do usuário antes de instalar qualquer coisa.
  2. Não confie em catálogos memorizados quando o conjunto exato for importante. Pergunte ao binário:
    • dith list presets|algorithms|palettes|generators|formats --json, filtrável com --tag <substr> ou --category <name>
    • dith capabilities para o manifesto completo de comandos, faixas de parâmetros e a receita padrão (cerca de 40 KB, então prefira list quando um catálogo for suficiente)

Fluxo de trabalho principal

  1. Entenda a origem. Para uma imagem existente, execute dith inspect <image> --json. Ele informa dimensões, transparência, percentis de luminância (p5/p50/p95), dynamic_range, cores dominantes e recomendações de preset com comandos prontos para uso.
  2. Escolha um ponto de partida no guia de estilo abaixo. Quando a direção estiver em aberto, renderize uma folha de contato e analise-a antes de assumir o compromisso: dith compare <image> -o sheet.png --presets mac-classic,editorial-print,risograph,film-stipple --json
  3. Valide conjuntos complexos de flags primeiro com --dry-run --json. Isso detecta valores inválidos e mostra as output_dimensions planejadas sem escrever arquivos.
  4. Renderize com apply, generate, animate ou batch, sempre com --json. Comandos de arquivo único sobrescrevem saídas existentes por padrão. Adicione --no-clobber quando os arquivos existentes não devem ser tocados; no batch ele se aplica a cada arquivo.
  5. Verifique antes de relatar sucesso. Veja Verificar o resultado.
  6. Torne reproduzível quando a aparência for reutilizada. Passe --emit-recipe (adiciona um objeto recipe ao relatório) ou --save-preset <name> (escreve .dith/presets/<name>.json).

Escolha uma aparência

Comece por um preset e depois sobrescreva flags individuais. Flags explícitas sempre vencem o preset.

ObjetivoComece comNotas
Clássico 1-bit Mac / retrato editorial--preset mac-classic (atkinson)Atkinson descarta 2/8 do erro, então os realces permanecem arejados. Adicione --sharpen 0.4 em fotos suaves.
Impressão monocromática refinada / jornal--preset editorial-print (ostromoukhov)Gradientes mais suaves da família de difusão de erro.
Stipple cinematográfico, sem artefatos de grade--preset film-stipple (blue-noise)Melhor aparência moderna geral; também estável em animação.
Pôster Risograph--preset risograph, risograph-red, risograph-duoAparências de dois tons e sobreimpressão de dois tambores em papel quente.
Meio-tom de quadrinhos / zine--preset halftone-zineCombine com --format svg --svg-shape circle para pontos vetoriais.
Game Boy / arte pixel--preset gameboy, pico8Bayer ordenado mais --pixel-size encorpado.
Brilho CRT / terminal--preset crt-amber, phosphorImagens com tons escuros funcionam melhor com estes.
Gravura / xilogravura--preset woodcut, --algorithm crosshatchTelas de linha; ajuste com --pattern-scale.
Blueprint / técnico--preset blueprintAzul prussiano e dois tons de giz.
Manter as próprias cores da foto--preset lo-fi-photo ou --auto-palette NExtrai N cores Oklab (2–64) da imagem.
Cores de marca exatas--colors "#0f172a,#2563eb,#f5efe6"Combine com qualquer algoritmo ou preset.
Gradientes hero neon / UI escura--preset vapor-mesh com generate mesh

references/catalog.md tem cada preset, paleta, algoritmo e gerador com quando usar cada um.

Regras de criação

  • Tom antes do pontilhamento. O pontilhamento amplifica entrada plana ou turva.
    • dynamic_range baixo (abaixo de cerca de 0.5) ou uma distribuição p5–p95 estreita: adicione --auto-levels ou --contrast 0.1..0.3.
    • Foto suave indo para 1-bit ou Atkinson: --sharpen 0.3..0.6.
    • Meios-tons escuros: --gamma 0.7..0.9 (valores abaixo de 1 clareiam). Entrada clara e desbotada: --gamma 1.2..1.5.
    • Ajustando a densidade geral: --bias (negativo escurece, positivo clareia, faixa ±0.5).
  • Tamanho primeiro. Limite com --max-dim (ou --width/--height mais --fit contain|cover|stretch). Padrões de pontilhamento são por pixel, então uma imagem pontilhada nunca deve ser redimensionada depois. Renderize no tamanho de exibição final.
  • Pixels encorpados. --pixel-size N reduz a resolução, pontilha e então aumenta a resolução com vizinho mais próximo, de modo que as dimensões de saída permanecem inalteradas.
  • Tamanho da tela ordenada. --pattern-scale 2..4 amplia células Bayer, meio-tom, linha e blue-noise para uma textura mais ousada e gráfica.
  • Espaço de cor. Mantenha o padrão oklab. Use srgb apenas para imitar matemática de hardware legado; linear é luz fisicamente linear.
  • Determinismo. Algoritmos estocásticos (blue-noise, random, ign), --noise e --auto-palette usam --seed (padrão 42). Altere a semente para variações e mantenha-a fixa para reprodutibilidade.
  • Transparência. Logotipos e ícones com alfa: --alpha-mode preserve mantém o canal alfa, threshold fornece uma máscara nítida de 1 bit, dither fornece um fade pontilhado e flatten --background "#hex" compõe sobre uma cor.
  • Desativando partes do preset. A maioria dos presets monocromáticos ativa --grayscale e --auto-levels. Use --no-grayscale, --no-auto-levels e --no-serpentine para desabilitar o que um preset ativou.

Formatos de saída

O formato é inferido da extensão -o; passe --format para sobrescrevê-lo.

  • PNG (padrão): sem perdas e pixel-exato. Quase sempre a escolha certa.
  • WebP: compacto para a web. JPEG destrói padrões de pontilhamento, então nunca o use para saída pontilhada, a menos que o usuário insista.
  • SVG: --svg-shape rect (retângulos mesclados por run-length, menor), circle (pontos de meio-tom) ou dot (pontos internos). --svg-skip-bg remove a cor de fundo dominante para sobreposições. O SVG cresce com a contagem de pixels, e círculos são muito maiores que retângulos, então mantenha --max-dim em torno de 120–320.
  • Texto de terminal: --format braille|ascii com --text-width N. -o é opcional e o texto vai para stdout.
  • Stdin/stdout: passe - como entrada ou como -o -.

Animação

dith animate aceita um de quatro tipos de entrada:

  • um nome de padrão (sphere, waves, mesh, plasma, ...) para um loop processual contínuo. Cada padrão se move de forma diferente (a esfera fica parada enquanto sua luz orbita, por exemplo); o campo motion de dith list generators --json o descreve. Para verificar o movimento de forma barata antes de uma renderização completa, exporte uma spritesheet pequena (--anim-format spritesheet --sheet-cols <frames> --canvas-width 160 --canvas-height 120) e observe-a.
  • um GIF animado, APNG ou WebP para re-pontilhar
  • vários arquivos de imagem como uma sequência de quadros
  • uma única imagem estática, que recebe "film boil" (--temporal boil é o padrão para este caso)

A saída vai para .gif (paleta exata, menor), .apng (RGBA completo), uma spritesheet .png via --anim-format spritesheet --sheet-cols N ou quadros PNG numerados via --frames-dir DIR.

  • Cintilação. --temporal locked (o padrão) fixa a tela e a semente entre os quadros, mas só torna regiões estáticas absolutamente sólidas com algoritmos por pixel: telas ordenadas (bayer*, halftone, telas de linha), blue-noise, ign, random e threshold. A difusão de erro (floyd-steinberg, atkinson, stucki, riemersma, ...) passa cada alteração para os pixels vizinhos, então qualquer coisa que se move faz o stipple cintilar abaixo e à direita dela. Atkinson cintila menos. O campo temporally_stable de dith list algorithms --json informa qual é qual. boil dá uma cintilação proposital de desenho à mão; defina --boil-rate 2 para animar "em dois". grain re-randomiza o stipple a cada quadro.
  • Loops contínuos. Padrões processuais fazem loop por construção. Para varreduras, use --sweep-mode pulse ou --ping-pong.
  • Varreduras animam um parâmetro ao longo do tempo: --sweep-bias, --sweep-brightness, --sweep-contrast, --sweep-gamma, --sweep-strength, --sweep-pixel-size, cada um escrito START..END. Modele-os com --easing e pause em keyframes com --hold-start e --hold-end.
  • Paleta. Uma paleta global compartilhada é o padrão e mantém as cores estáveis. Use --per-frame-palette apenas para filmagens cujas cores mudam muito.
  • Temporização. Os quadros são limitados a 2..=240. --duration S é uma alternativa a --frames (quadros = S × fps); passar ambos é um erro. Os atrasos do GIF são armazenados em etapas de 10 ms, então --fps 10|20|25|50 fornece temporização exata do GIF (15 fps torna-se 70 ms por quadro). APNG é exato.
  • Tamanho. O tamanho do arquivo cresce com quadros × pixels, e o ruído do pontilhamento mal comprime.
    • GIFs são codificados por delta automaticamente: cada quadro após o primeiro armazena apenas o que mudou. Algoritmos por pixel travados com áreas estáticas são, portanto, muito menores que difusão de erro ou boil/grain, onde quase todos os pixels mudam a cada quadro.
    • Para atingir um orçamento, passe --max-size 2MB (também 500KB, 1.5MiB ou bytes). Dith reduz as dimensões do quadro, mantendo a contagem de quadros e fps, até que o arquivo caiba, e relata size_fit_scale (1.0 = intacto). Se size_fit_scale retornar pequeno (abaixo de cerca de 0.5), o resultado pode ser pequeno demais para uso. Reduza o tamanho de outra forma: menos quadros, um algoritmo ordenado travado ou menos cores de paleta.
    • Mantenha as telas processuais modestas (os padrões são 480×360).
  • Cores processuais. Sem --stops, os padrões usam uma rampa simples de quase preto a quase branco. Passe --stops para escolher os tons de origem deliberadamente; geralmente parece melhor, especialmente com uma paleta colorida.
  • Presets em fontes processuais. Os presets são ajustados para fotos. Para generate, animate <pattern> e compare/preview --pattern, o dith pula seus auto-levels, contraste e nitidez, porque eles cortam gradientes limpos em manchas planas. Passe essas flags explicitamente para aplicá-las de qualquer forma.

Verificar o resultado

Leia o relatório JSON em vez de assumir sucesso:

  • "status": "ok". batch pode retornar "partial_failure" com código de saída 1; verifique failed e cada items[].error.
  • output_dimensions para imagens, ou frame_count, frame_dimensions e total_duration_ms para animações, correspondem à intenção.
  • bytes_written > 0; é 0 em --dry-run.
  • palette_colors e color_usage estão conforme o esperado. Se uma cor cobrir mais de cerca de 95% dos pixels, a imagem está quase em branco: ajuste --bias, --gamma ou --contrast, ou tente --invert.

Quando a estética for importante, observe a saída. Abra arquivos PNG com uma ferramenta de visualização de imagens se você tiver uma; caso contrário, adicione --preview para obter uma miniatura Braille em preview_braille. Para animações, exporte uma spritesheet ou --frames-dir e visualize os quadros PNG. Para SVGs, renderize um PNG com as mesmas flags e visualize-o.

Erros

Com --json, os erros vão para stderr como {"status":"error","code","message","suggestion","valid_values"?}.

  • Saída 2: entrada inválida sua. Os códigos incluem CLI_USAGE_ERROR, INVALID_ARGUMENT (um valor fora da faixa; a mensagem inclui a faixa), UNKNOWN_PRESET e códigos semelhantes (valid_values lista as opções) e OUTPUT_EXISTS (--no-clobber encontrou um arquivo existente). Corrija as flags e tente novamente.
  • Saída 1: falha de tempo de execução ou E/S (RUNTIME_ERROR), como uma entrada ausente ou um arquivo indecodificável. batch também sai com 1 quando qualquer item falha.

Interativo vs headless

--view, preview (tela cheia por padrão) e compare --view são visualizadores interativos do protocolo Kitty destinados a um humano em um terminal. Em shells de agente não interativos, renderize para arquivos, use --preview ou --format braille, ou passe --inline (por exemplo dith preview img.png --inline --mode braille --cols 60). Use o visualizador de tela cheia apenas quando o usuário quiser explicitamente assistir em seu próprio terminal.

Referências

  • references/cli.md: cada subcomando e flag, com faixas, padrões e campos de relatório JSON.
  • references/catalog.md: presets, paletas, algoritmos e geradores, e quando escolher cada um.
  • references/recipes.md: receitas prontas para tarefas comuns (hero da web, avatar, logotipo SVG, cartão social, spritesheet CSS, GIF de revelação, preset de marca, exportação em lote).

Habilidades Relacionadas