CommunityImagengithub.com

dith

Utiliza la CLI de dith para aplicar tramado (dithering) a fotos y logotipos, generar texturas procedurales y exportar animaciones retro o de impresión sin repetición a partir de recetas reproducibles.

¿Qué es dith?

Dith es una herramienta de línea de comandos para tramado determinista, diseñada específicamente para agentes de IA. Garantiza que las mismas entradas y parámetros siempre produzcan archivos byte-idénticos, lo que la hace ideal para flujos de trabajo automatizados y reproducibles. Soporta una amplia variedad de efectos visuales y algoritmos de tramado, desde clásicos como Atkinson y Ostromoukhov hasta halftones, líneas de grabado y malla de vapor neón. Permite generar texturas procedurales, animaciones GIF/APNG y exportar en formatos PNG, WebP, SVG o incluso texto Braille, todo con soporte completo para JSON en cada comando. Su uso principal es transformar imágenes (fotos, logos, ilustraciones) en estilos retro, de impresión o pixel art, manteniendo un control preciso sobre el color, la paleta y el tiempo de animación. Está construido en Rust y se ejecuta en cualquier sistema operativo con soporte para Rust, ofreciendo referencias detalladas para cada subcomando y catálogos de presets, paletas y generadores.

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

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿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

  1. 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> (o mbx run -- <args> cuando mbx esté 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.
  2. 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 capabilities para el manifiesto completo de comandos, rangos de parámetros y la receta predeterminada (alrededor de 40 KB, por lo que es preferible list cuando un solo catálogo es suficiente)

Flujo de trabajo principal

  1. 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.
  2. 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
  3. Valida primero los conjuntos de parámetros complejos con --dry-run --json. Esto detecta valores incorrectos y muestra las output_dimensions planeadas sin escribir archivos.
  4. Renderiza con apply, generate, animate o batch, siempre con --json. Los comandos de un solo archivo sobrescriben las salidas existentes por defecto. Agrega --no-clobber cuando los archivos existentes no deban ser tocados; en batch se aplica a cada archivo.
  5. Verifica antes de reportar éxito. Consulta Verificar el resultado.
  6. Hazlo reproducible cuando el estilo se reutilizará. Pasa --emit-recipe (agrega un objeto recipe al 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.

ObjetivoComienza conNotas
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-duoAspectos de duotono y sobreimpresión de dos tambores en papel cálido.
Medio tono cómic / fanzine--preset halftone-zineCombínalo con --format svg --svg-shape circle para puntos vectoriales.
Game Boy / pixel art--preset gameboy, pico8Bayer ordenado más --pixel-size grande.
Brillo CRT / terminal--preset crt-amber, phosphorLas imágenes oscuras se adaptan mejor a estos.
Grabado / xilografía--preset woodcut, --algorithm crosshatchTramas de líneas; ajusta con --pattern-scale.
Plano técnico / técnico--preset blueprintDuotono azul prusiano y tiza.
Mantener los colores originales de la foto--preset lo-fi-photo o --auto-palette NExtrae 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-levels o --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).
  • Tamaño primero. Limita con --max-dim (o --width/--height má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 N reduce 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..4 agranda 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. Usa srgb solo para imitar matemáticas de hardware heredado; linear es luz físicamente lineal.
  • Determinismo. Los algoritmos estocásticos (blue-noise, random, ign), --noise y --auto-palette usan --seed (predeterminado 42). Cambia la semilla para variaciones y mantenla fija para reproducibilidad.
  • Transparencia. Logotipos e iconos con alfa: --alpha-mode preserve mantiene el canal alfa, threshold da una máscara de 1-bit nítida, dither da un fundido punteado y flatten --background "#hex" compone sobre un color.
  • Desactivar partes del preset. La mayoría de los presets monocromáticos activan --grayscale y --auto-levels. Usa --no-grayscale, --no-auto-levels y --no-serpentine para 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) o dot (puntos insertados). --svg-skip-bg elimina 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-dim alrededor de 120–320.
  • Texto de terminal: --format braille|ascii con --text-width N. -o es 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 campo motion de dith list generators --json lo 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 boil es 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, random y threshold. 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 campo temporally_stable de dith list algorithms --json indica cuál es cuál. boil da un brillo dibujado a mano a propósito; configura --boil-rate 2 para animar "en doses". grain realeatoriza el punteado en cada fotograma.
  • Bucles sin fisuras. Los patrones procedurales se bucean por construcción. Para barridos, usa --sweep-mode pulse o --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 escrito START..END. Dales forma con --easing y pausa en fotogramas clave con --hold-start y --hold-end.
  • Paleta. Una paleta global compartida es el valor predeterminado y mantiene los colores estables. Usa --per-frame-palette solo para metraje cuyos colores cambien mucho.
  • Temporización. Los fotogramas están limitados a 2..=240. --duration S es 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|50 da 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én 500KB, 1.5MiB o bytes). Dith reduce las dimensiones del fotograma, manteniendo el recuento de fotogramas y fps, hasta que el archivo quepa, e informa size_fit_scale (1.0 = sin cambios). Si size_fit_scale resulta 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).
  • Colores procedurales. Sin --stops, los patrones usan una rampa simple de casi negro a casi blanco. Pasa --stops para 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> y compare/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". batch puede devolver "partial_failure" con código de salida 1; verifica failed y cada items[].error.
  • output_dimensions para imágenes, o frame_count, frame_dimensions y total_duration_ms para animaciones, coinciden con la intención.
  • bytes_written > 0; es 0 en --dry-run.
  • palette_colors y color_usage son como se esperaba. Si un color cubre más del 95% de los píxeles aproximadamente, la imagen está casi en blanco: ajusta --bias, --gamma o --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_PRESET y códigos similares (valid_values enumera las opciones), y OUTPUT_EXISTS (--no-clobber encontró 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. batch tambié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).

Skills relacionados