¿Qué hace dith?
dith es una CLI de tramado determinista construida para agentes. Cada comando acepta --json, escribe salida exacta a la paleta y devuelve un informe legible por máquina. Las mismas entradas y parámetros siempre producen archivos byte-idénticos.
Configuración
- Verifica la existencia del binario con
dith --version.- Dentro del repositorio de dith sin una instalación global, ejecútalo mediante
cargo run --release -- <args>(ombx run -- <args>cuandombxesté disponible). - Si dith no está presente, informa al usuario y ofrece un comando de instalación desde references/cli.md. Espera su aprobación antes de instalar cualquier cosa.
- Dentro del repositorio de dith sin una instalación global, ejecútalo mediante
- No confíes en catálogos memorizados cuando el conjunto exacto sea importante. Pregunta al binario:
dith list presets|algorithms|palettes|generators|formats --json, filtrable con--tag <substr>o--category <name>dith capabilitiespara el manifiesto completo de comandos, rangos de parámetros y la receta predeterminada (alrededor de 40 KB, por lo que es preferiblelistcuando un solo catálogo es suficiente)
Flujo de trabajo principal
- Comprende la fuente. Para una imagen existente, ejecuta
dith inspect <image> --json. Reporta dimensiones, transparencia, percentiles de luminancia (p5/p50/p95),dynamic_range, colores dominantes y recomendaciones de presets con comandos listos para ejecutar. - Elige un punto de partida de la guía de estilo a continuación. Cuando la dirección sea abierta, renderiza una hoja de contactos y mírala antes de comprometerte:
dith compare <image> -o sheet.png --presets mac-classic,editorial-print,risograph,film-stipple --json - Valida primero los conjuntos de parámetros complejos con
--dry-run --json. Esto detecta valores incorrectos y muestra lasoutput_dimensionsplaneadas sin escribir archivos. - Renderiza con
apply,generate,animateobatch, siempre con--json. Los comandos de un solo archivo sobrescriben las salidas existentes por defecto. Agrega--no-clobbercuando los archivos existentes no deban ser tocados; enbatchse aplica a cada archivo. - Verifica antes de reportar éxito. Consulta Verificar el resultado.
- Hazlo reproducible cuando el estilo se reutilizará. Pasa
--emit-recipe(agrega un objetorecipeal informe) o--save-preset <name>(escribe.dith/presets/<name>.json).
Elegir un estilo
Comienza desde un preset, luego sobrescribe parámetros individuales. Los parámetros explícitos siempre ganan sobre el preset.
| Objetivo | Comienza con | Notas |
|---|---|---|
| Mac clásico 1-bit / retrato editorial | --preset mac-classic (atkinson) | Atkinson descarta 2/8 del error, así que las altas luces se mantienen aireadas. Agrega --sharpen 0.4 en fotos suaves. |
| Impresión monocromática refinada / periódico | --preset editorial-print (ostromoukhov) | Gradientes más suaves de la familia de difusión de error. |
| Punteado fílmico, sin artefactos de cuadrícula | --preset film-stipple (blue-noise) | Mejor aspecto general moderno; también estable en animación. |
| Póster Risografía | --preset risograph, risograph-red, risograph-duo | Aspectos de duotono y sobreimpresión de dos tambores en papel cálido. |
| Medio tono cómic / fanzine | --preset halftone-zine | Combínalo con --format svg --svg-shape circle para puntos vectoriales. |
| Game Boy / pixel art | --preset gameboy, pico8 | Bayer ordenado más --pixel-size grande. |
| Brillo CRT / terminal | --preset crt-amber, phosphor | Las imágenes oscuras se adaptan mejor a estos. |
| Grabado / xilografía | --preset woodcut, --algorithm crosshatch | Tramas de líneas; ajusta con --pattern-scale. |
| Plano técnico / técnico | --preset blueprint | Duotono azul prusiano y tiza. |
| Mantener los colores originales de la foto | --preset lo-fi-photo o --auto-palette N | Extrae N colores Oklab (2–64) de la imagen. |
| Colores exactos de marca | --colors "#0f172a,#2563eb,#f5efe6" | Combínalo con cualquier algoritmo o preset. |
| Degradados héroes neón / interfaz oscura | --preset vapor-mesh con generate mesh |
references/catalog.md tiene todos los presets, paletas, algoritmos y generadores con cuándo usar cada uno.
Reglas de creación
- Tono antes del tramado. El tramado amplifica la entrada plana o turbia.
- Bajo
dynamic_range(menos de aproximadamente 0.5) o un rango p5–p95 estrecho: agrega--auto-levelso--contrast 0.1..0.3. - Foto suave a 1-bit o Atkinson:
--sharpen 0.3..0.6. - Medios tonos oscuros:
--gamma 0.7..0.9(valores menores a 1 aclaran). Entrada brillante y lavada:--gamma 1.2..1.5. - Ajuste de densidad general:
--bias(negativo es más oscuro, positivo es más claro, rango ±0.5).
- Bajo
- Tamaño primero. Limita con
--max-dim(o--width/--heightmás--fit contain|cover|stretch). Los patrones de tramado son por píxel, por lo que una imagen tramada nunca debe redimensionarse después. Renderiza al tamaño de visualización final en su lugar. - Píxeles gruesos.
--pixel-size Nreduce la resolución, tramado y luego escala por vecino más cercano, por lo que las dimensiones de salida no cambian. - Tamaño de pantalla ordenada.
--pattern-scale 2..4agranda las celdas Bayer, medio tono, línea y ruido azul para una textura más audaz y gráfica. - Espacio de color. Mantén el valor predeterminado
oklab. Usasrgbsolo para imitar matemáticas de hardware heredado;lineares luz físicamente lineal. - Determinismo. Los algoritmos estocásticos (
blue-noise,random,ign),--noisey--auto-paletteusan--seed(predeterminado 42). Cambia la semilla para variaciones y mantenla fija para reproducibilidad. - Transparencia. Logotipos e iconos con alfa:
--alpha-mode preservemantiene el canal alfa,thresholdda una máscara de 1-bit nítida,ditherda un fundido punteado yflatten --background "#hex"compone sobre un color. - Desactivar partes del preset. La mayoría de los presets monocromáticos activan
--grayscaley--auto-levels. Usa--no-grayscale,--no-auto-levelsy--no-serpentinepara desactivar lo que un preset activó.
Formatos de salida
El formato se infiere de la extensión -o; pasa --format para sobrescribirlo.
- PNG (predeterminado): sin pérdidas y exacto al píxel. Casi siempre la opción correcta.
- WebP: compacto para la web. JPEG destruye los patrones de tramado, por lo que nunca se debe usar para salida tramada a menos que el usuario insista.
- SVG:
--svg-shape rect(rectángulos fusionados por longitud de ejecución, más pequeño),circle(puntos de medio tono) odot(puntos insertados).--svg-skip-bgelimina el color de fondo dominante para superposiciones. El SVG crece con el recuento de píxeles, y los círculos son mucho más grandes que los rectángulos, así que mantén--max-dimalrededor de 120–320. - Texto de terminal:
--format braille|asciicon--text-width N.-oes opcional y el texto va a stdout. - Stdin/stdout: pasa
-como entrada o como-o -.
Animación
dith animate toma uno de cuatro tipos de entrada:
- un nombre de patrón (
sphere,waves,mesh,plasma, ...) para un bucle procedural sin fisuras. Cada patrón se mueve de manera diferente (la esfera permanece quieta mientras su luz orbita, por ejemplo); el campomotiondedith list generators --jsonlo describe. Para verificar el movimiento de manera económica antes de un renderizado completo, exporta una hoja de sprites pequeña (--anim-format spritesheet --sheet-cols <frames> --canvas-width 160 --canvas-height 120) y mírala. - un GIF animado, APNG o WebP para volver a tramar
- varios archivos de imagen como una secuencia de fotogramas
- una sola imagen estática, que recibe ebullición de película (
--temporal boiles el valor predeterminado para este caso)
La salida va a .gif (paleta exacta, más pequeño), .apng (RGBA completo), una hoja de sprites .png mediante --anim-format spritesheet --sheet-cols N, o fotogramas PNG numerados mediante --frames-dir DIR.
- Parpadeo.
--temporal locked(el valor predeterminado) fija la pantalla y la semilla entre fotogramas, pero solo hace que las regiones estáticas sean sólidas como una roca con algoritmos por píxel: pantallas ordenadas (bayer*,halftone, pantallas de línea),blue-noise,ign,randomythreshold. La difusión de error (floyd-steinberg,atkinson,stucki,riemersma, ...) pasa cada cambio a los píxeles vecinos, por lo que cualquier cosa que se mueva hace que el punteado brille debajo y a la derecha de ella. Atkinson brilla menos. El campotemporally_stablededith list algorithms --jsonindica cuál es cuál.boilda un brillo dibujado a mano a propósito; configura--boil-rate 2para animar "en doses".grainrealeatoriza el punteado en cada fotograma. - Bucles sin fisuras. Los patrones procedurales se bucean por construcción. Para barridos, usa
--sweep-mode pulseo--ping-pong. - Barridos animan un parámetro en el tiempo:
--sweep-bias,--sweep-brightness,--sweep-contrast,--sweep-gamma,--sweep-strength,--sweep-pixel-size, cada uno escritoSTART..END. Dales forma con--easingy pausa en fotogramas clave con--hold-starty--hold-end. - Paleta. Una paleta global compartida es el valor predeterminado y mantiene los colores estables. Usa
--per-frame-palettesolo para metraje cuyos colores cambien mucho. - Temporización. Los fotogramas están limitados a 2..=240.
--duration Ses una alternativa a--frames(fotogramas = S × fps); pasar ambos es un error. Los retrasos de GIF se almacenan en pasos de 10 ms, por lo que--fps 10|20|25|50da una temporización exacta de GIF (15 fps se convierte en 70 ms por fotograma). APNG es exacto. - Tamaño. El tamaño del archivo crece con fotogramas × píxeles, y el ruido de tramado apenas se comprime.
- Los GIF se codifican por diferencia automáticamente: cada fotograma después del primero solo almacena lo que cambió. Por lo tanto, los algoritmos por píxel bloqueados con áreas estáticas son mucho más pequeños que la difusión de error o
boil/grain, donde casi cada píxel cambia en cada fotograma. - Para cumplir con un presupuesto, pasa
--max-size 2MB(también500KB,1.5MiBo bytes). Dith reduce las dimensiones del fotograma, manteniendo el recuento de fotogramas y fps, hasta que el archivo quepa, e informasize_fit_scale(1.0 = sin cambios). Sisize_fit_scaleresulta pequeño (menos de aproximadamente 0.5), el resultado puede ser demasiado pequeño para usarse. Reduce el tamaño de otra manera en su lugar: menos fotogramas, un algoritmo ordenado bloqueado o menos colores de paleta. - Mantén los lienzos procedurales modestos (los valores predeterminados son 480×360).
- Los GIF se codifican por diferencia automáticamente: cada fotograma después del primero solo almacena lo que cambió. Por lo tanto, los algoritmos por píxel bloqueados con áreas estáticas son mucho más pequeños que la difusión de error o
- Colores procedurales. Sin
--stops, los patrones usan una rampa simple de casi negro a casi blanco. Pasa--stopspara elegir los tonos de origen deliberadamente; generalmente se ve mejor, especialmente con una paleta de colores. - Presets en fuentes procedurales. Los presets están ajustados para fotos. Para
generate,animate <pattern>ycompare/preview --pattern, dith omite sus auto-niveles, contraste y nitidez, porque esos recortan degradados limpios en parches planos. Pasa esos parámetros explícitamente para aplicarlos de todos modos.
Verificar el resultado
Lee el informe JSON en lugar de asumir éxito:
"status": "ok".batchpuede devolver"partial_failure"con código de salida 1; verificafailedy cadaitems[].error.output_dimensionspara imágenes, oframe_count,frame_dimensionsytotal_duration_mspara animaciones, coinciden con la intención.bytes_written > 0; es0en--dry-run.palette_colorsycolor_usageson como se esperaba. Si un color cubre más del 95% de los píxeles aproximadamente, la imagen está casi en blanco: ajusta--bias,--gammao--contrast, o prueba--invert.
Cuando la estética importe, mira la salida. Abre archivos PNG con una herramienta de visualización de imágenes si tienes una; de lo contrario, agrega --preview para obtener una miniatura Braille en preview_braille. Para animaciones, exporta una hoja de sprites o --frames-dir y visualiza los fotogramas PNG. Para SVG, renderiza un PNG con las mismas banderas y visualízalo.
Errores
Con --json, los errores van a stderr como {"status":"error","code","message","suggestion","valid_values"?}.
- Salida 2: entrada no válida de tu parte. Los códigos incluyen
CLI_USAGE_ERROR,INVALID_ARGUMENT(un valor fuera de rango; el mensaje incluye el rango),UNKNOWN_PRESETy códigos similares (valid_valuesenumera las opciones), yOUTPUT_EXISTS(--no-clobberencontró un archivo existente). Corrige las banderas y vuelve a intentar. - Salida 1: error de ejecución o E/S (
RUNTIME_ERROR), como una entrada faltante o un archivo no decodificable.batchtambién sale con 1 cuando falla algún elemento.
Interactivo vs sin cabeza
--view, preview (pantalla completa por defecto) y compare --view son visores interactivos del protocolo Kitty destinados a un humano en la terminal. En shells de agente no interactivos, renderiza a archivos, usa --preview o --format braille, o pasa --inline (por ejemplo, dith preview img.png --inline --mode braille --cols 60). Solo usa el visor de pantalla completa cuando el usuario quiera explícitamente mirar en su propia terminal.
Referencias
- references/cli.md: cada subcomando y bandera, con rangos, valores predeterminados y campos de informe JSON.
- references/catalog.md: presets, paletas, algoritmos y generadores, y cuándo elegir cada uno.
- references/recipes.md: recetas listas para copiar para trabajos comunes (héroe web, avatar, logotipo SVG, tarjeta social, hoja de sprites CSS, GIF revelador, preset de marca, exportación por lotes).