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
- 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>(oumbx run -- <args>quandombxestiver 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.
- Dentro da cópia fonte do dith sem uma instalação global, execute via
- 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 capabilitiespara o manifesto completo de comandos, faixas de parâmetros e a receita padrão (cerca de 40 KB, então prefiralistquando um catálogo for suficiente)
Fluxo de trabalho principal
- 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. - 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 - Valide conjuntos complexos de flags primeiro com
--dry-run --json. Isso detecta valores inválidos e mostra asoutput_dimensionsplanejadas sem escrever arquivos. - Renderize com
apply,generate,animateoubatch, sempre com--json. Comandos de arquivo único sobrescrevem saídas existentes por padrão. Adicione--no-clobberquando os arquivos existentes não devem ser tocados; nobatchele se aplica a cada arquivo. - Verifique antes de relatar sucesso. Veja Verificar o resultado.
- Torne reproduzível quando a aparência for reutilizada. Passe
--emit-recipe(adiciona um objetorecipeao 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.
| Objetivo | Comece com | Notas |
|---|---|---|
| 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-duo | Aparências de dois tons e sobreimpressão de dois tambores em papel quente. |
| Meio-tom de quadrinhos / zine | --preset halftone-zine | Combine com --format svg --svg-shape circle para pontos vetoriais. |
| Game Boy / arte pixel | --preset gameboy, pico8 | Bayer ordenado mais --pixel-size encorpado. |
| Brilho CRT / terminal | --preset crt-amber, phosphor | Imagens com tons escuros funcionam melhor com estes. |
| Gravura / xilogravura | --preset woodcut, --algorithm crosshatch | Telas de linha; ajuste com --pattern-scale. |
| Blueprint / técnico | --preset blueprint | Azul prussiano e dois tons de giz. |
| Manter as próprias cores da foto | --preset lo-fi-photo ou --auto-palette N | Extrai 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_rangebaixo (abaixo de cerca de 0.5) ou uma distribuição p5–p95 estreita: adicione--auto-levelsou--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/--heightmais--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 Nreduz 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..4amplia 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. Usesrgbapenas para imitar matemática de hardware legado;linearé luz fisicamente linear. - Determinismo. Algoritmos estocásticos (
blue-noise,random,ign),--noisee--auto-paletteusam--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 preservemantém o canal alfa,thresholdfornece uma máscara nítida de 1 bit,ditherfornece um fade pontilhado eflatten --background "#hex"compõe sobre uma cor. - Desativando partes do preset. A maioria dos presets monocromáticos ativa
--grayscalee--auto-levels. Use--no-grayscale,--no-auto-levelse--no-serpentinepara 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) oudot(pontos internos).--svg-skip-bgremove 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-dimem torno de 120–320. - Texto de terminal:
--format braille|asciicom--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 campomotiondedith list generators --jsono 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,randomethreshold. 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 campotemporally_stablededith list algorithms --jsoninforma qual é qual.boildá uma cintilação proposital de desenho à mão; defina--boil-rate 2para animar "em dois".grainre-randomiza o stipple a cada quadro. - Loops contínuos. Padrões processuais fazem loop por construção. Para varreduras, use
--sweep-mode pulseou--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 escritoSTART..END. Modele-os com--easinge pause em keyframes com--hold-starte--hold-end. - Paleta. Uma paleta global compartilhada é o padrão e mantém as cores estáveis. Use
--per-frame-paletteapenas 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|50fornece 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ém500KB,1.5MiBou bytes). Dith reduz as dimensões do quadro, mantendo a contagem de quadros e fps, até que o arquivo caiba, e relatasize_fit_scale(1.0 = intacto). Sesize_fit_scaleretornar 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).
- 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
- Cores processuais. Sem
--stops, os padrões usam uma rampa simples de quase preto a quase branco. Passe--stopspara 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>ecompare/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".batchpode retornar"partial_failure"com código de saída 1; verifiquefailede cadaitems[].error.output_dimensionspara imagens, ouframe_count,frame_dimensionsetotal_duration_mspara animações, correspondem à intenção.bytes_written > 0; é0em--dry-run.palette_colorsecolor_usageestão conforme o esperado. Se uma cor cobrir mais de cerca de 95% dos pixels, a imagem está quase em branco: ajuste--bias,--gammaou--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_PRESETe códigos semelhantes (valid_valueslista as opções) eOUTPUT_EXISTS(--no-clobberencontrou 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.batchtambé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).