Communitygithub.com

weft

Reconstruye cualquier imagen, video, feed de cámara web o lienzo como Weft, un mosaico de barras de escaneo con barras cortas de colores en filas (como hilos en un telar o una impresión risográfica). Se fragmenta en bloques gruesos al moverse y se resuelve en detalles finos al detenerse, y un sujeto recortado gira en 3D hacia el cursor mediante paralaje de profundidad. Úsalo cuando alguien pida un mosaico de barras, un retrato con líneas de escaneo / rayas / dither lineal, un efecto risográfico o de semitonos de barras, una transición de glitch a detalle o de «grueso a fino», un retrato o avatar que gire con el cursor en ese estilo, o para recrear un clip de referencia con este aspecto. TypeScript + WebGL2, funciona en cualquier página web o framework.

¿Qué es weft?

Weft es un motor de renderizado en TypeScript + WebGL2 que transforma cualquier imagen, video, cámara web o lienzo en un mosaico de barras de escaneo, similar a un telar o una impresión risográfica. La firma visual clave es una transición dinámica: cuando algo se mueve, las filas se agrupan en bloques grandes y las celdas se recortan muchas veces por segundo, produciendo una apariencia gruesa y fragmentada; cuando se detiene, los detalles finos vuelven a resolverse completamente. Además, un sujeto recortado sobre fondo transparente o sólido obtiene un suave relieve de profundidad a partir de su silueta, permitiendo que gire (guiñada) y se incline (cabeceo) sin estirarse, con deslizamiento lateral de puntos según su profundidad y un sombreado que recorre el relieve. Es útil para diseñadores, artistas y desarrolladores que busquen un efecto visual distintivo de mosaico de barras con transición grueso-fino y giro 3D, ideal para retratos, avatares, fondos de héroe, efectos de transición, o para recrear clips de referencia con este estilo. Se integra en cualquier proyecto web (React, Vanilla JS, etc.) mediante un único módulo TypeScript sin dependencias de runtime, con una API sencilla que incluye `createWeft`, `enableDrop` y la posibilidad de cambiar opciones en vivo.

Compatible con~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/JDhruv14/weft/tree/HEAD

Preguntar en tu IA favorita

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

Documentación

¿Qué hace weft?

Cualquier imagen se redibuja como filas de barras cortas de colores sobre un fondo de papel. Cada fila se corta en celdas irregulares. Una celda toma el color de la paleta más cercano a la imagen en esa zona, a veces tramado con el segundo color. Su barra es de ancho completo en áreas fuertes y más estrecha en las tenues, y las celdas por donde pasa un borde se dividen en finas rayas. Cuando algo se mueve, las filas se agrupan en bloques grandes y las celdas se recortan muchas veces por segundo. Cuando se detiene, vuelven a bajar a detalles finos. Esa transición es la firma del estilo, así que protégela.

Un sujeto recortado de un fondo liso o transparente obtiene un suave relieve de profundidad a partir de su silueta, de modo que puede girar (guiñada) e inclinarse (cabeceo) sin estirarse. Los puntos se deslizan lateralmente según su profundidad y la luz recorre el relieve. Las imágenes a tamaño completo obtienen en su lugar un suave relieve central. El sujeto se mantiene centrado automáticamente en el encuadre.

Archivos

rutaqué
src/weft.tsEl motor, un módulo TypeScript estrictamente tipado sin dependencias de ejecución: createWeft(canvas, options), enableDrop, PALETTES y los tipos WeftOptions, WeftConfig y Weft.
demo/Un retrato que gira con el cursor, con alternancia de paleta y dirección de barras, cámara web, arrastrar y soltar, y parámetros de URL (Vite).
references/options.mdCada opción, lo que hace y su rango útil.
references/recipes.mdIntegraciones: React, héroe, tarjetas hover, desplazamiento, presentación de diapositivas, revelado, cámara web y cómo coincidir con una referencia.
references/pitfalls.mdLo que salió mal al construir esto y cómo evitarlo.

Flujo de trabajo

  1. Define la fuente y el trabajo. ¿Qué es: una imagen fija, un video, la cámara web o un lienzo que la página ya dibuja? ¿Dónde vive: un héroe, una tarjeta, una página completa? ¿Qué movimiento se desea: control del cursor, deriva inactiva, un revelado o una transición entre imágenes?
  2. Copia src/weft.ts en el proyecto y mantén el archivo completo. Solo necesita un empaquetador o tsc, ambos están en cualquier proyecto TS. Para una página JS simple, compílalo una vez con npx tsc o esbuild.
  3. Empieza desde demo/main.ts y configura las opciones usando las decisiones a continuación.
  4. Muestra primero una imagen fija. Congela una pose con ?freeze=0&yaw=-20&pitch=8&break=0 y mírala antes de construir más alrededor. Comprueba el frente, ambos giros, una inclinación y un fotograma fragmentado (break=1). Si el usuario dio una referencia, coloca una imagen fija junto a un fotograma de la referencia y compara paleta, altura de fila y color del papel.
  5. Luego el movimiento. Comprueba la transición en vivo. La fragmentación dura una fracción de segundo, así que avanza fotograma a fotograma en una grabación de pantalla en lugar de fiarte de un vistazo. Busca tres cosas: la fragmentación es obvia al moverse, cada reposo se resuelve completamente nítido y nada se estira en los límites del giro.

Decisiones

Sujeto (subject.mode):

  • Usa 'auto' (por defecto). Un PNG transparente usa 'alpha'. Un fotograma cuyo borde es mayoritariamente de un color usa 'backdrop', que rellena el fondo desde el borde, sigue degradados y elimina motas sueltas. Cualquier otra cosa usa 'none'.
  • Forza 'none' para paisajes, obras de arte y capturas de pantalla, para que no se recorte un cielo crema o un borde de papel.
  • Si un fondo con mucho detalle se filtra en el sujeto, ajusta subject.tolerance (por defecto 0.16), o mejor, pasa un PNG recortado.

Paleta (palette):

  • Elige un preset: ember (riso cálido, mejor para piel), graphite, riso, tide, candy, night (barras claras sobre fondo oscuro), phosphor o source (los propios colores de la imagen, posterizados).
  • También puedes pasar tus propios colores hex (hasta 16) y establecer paper.
  • Los colores se emparejan por cercanía. Incluye un oscuro, un medio y un claro en cada familia de tono que la imagen necesite, de lo contrario los rostros se vuelven planos o embarrados.
  • Sobre un paper oscuro, las barras se ensanchan automáticamente en las áreas brillantes.

Dirección: usa 'rows' (horizontal, el aspecto clásico) o 'columns'.

Encuadre: focus: 'subject' (por defecto) centra el cuadro delimitador del sujeto recortado. Solo se desplaza a lo largo de un eje donde el sujeto no esté recortado por el encuadre. Usa 'frame' para mantener la imagen tal como está compuesta.

Movimiento (motion, turn):

  • pointer: true permite que el cursor controle: x gira, y inclina. Las esquinas están fijadas en una elipse, por lo que una diagonal nunca acumula guiñada y cabeceo completos.
  • idle decide qué sucede cuando el puntero reposa. 'poses' deambula por motion.poses, 'center' vuelve suavemente al frente y 'hold' se queda quieto.
  • Mantén turn.yaw en 34° o menos y turn.pitch en 20° o menos para una imagen plana. Las imágenes a tamaño completo necesitan aproximadamente de 10 a 15° de guiñada.
  • Usa turn.enabled: false para un mosaico plano cuya única sea la transición.

Transición:

  • Girar rompe las barras automáticamente. Llama a weft.kick(amount) para cualquier otra cosa, como un clic, velocidad de desplazamiento, cambio de diapositiva o un ritmo.
  • transition.intro se resuelve desde grueso al cargar, y transition.onSource hace lo mismo cuando la fuente cambia.
  • Mantén rows.coarse / rows.fine alrededor de 4 a 6×.

API de un vistazo

import { createWeft, enableDrop, type WeftOptions } from './weft';

const weft = createWeft(canvas, {
  source: 'retrato.png',          // URL, <img>, <video>, <canvas>, File/Blob o 'camera'
  palette: 'ember',                // o ['#1c1a27', ...], o 'source'
  direction: 'rows',
  turn: { yaw: 30, pitch: 18 },
  motion: { pointer: true, idle: 'poses' },
  onSource: (w, h) => { stage.style.aspectRatio = `${w} / ${h}`; },
});
await weft.loaded;
weft.kick(0.8);                    // fragmentar ahora
weft.set({ palette: 'night' });    // cambios de opciones en vivo, fusión profunda
weft.pose(-20, 6);                 // controlar mediante código; pose(null) devuelve el control
weft.setSource('camera');
enableDrop(weft);                  // soltar un archivo de imagen/video en cualquier lugar
weft.destroy();

El lienzo llena su cuadro CSS, y la página posee el diseño. Los elementos marcados data-weft-ui se ocultan en imágenes fijas congeladas. weft.advance(dt, x, y) avanza un reloj simulado, para renderizado fotograma exacto.

Reglas que lo mantienen bueno

  • Usa los píxeles reales. Nunca redibujes, traces o «limpies» la foto o avatar de una persona para alimentarlo. El efecto es la estilización.
  • Mantén el papel tranquilo. Crema, hueso o blanco roto para paletas claras; un casi negro con un toque de color para las oscuras. Evita #fff y #000 puros.
  • La transición necesita contraste en el tiempo. Los movimientos deben ser lo suficientemente rápidos para alcanzar el extremo grueso, y los reposos lo suficientemente largos (aproximadamente 1 s o más) para resolverse completamente.
  • La UI es solo iconos y discreta: en una esquina con baja opacidad, marcada data-weft-ui.
  • Respeta prefers-reduced-motion. El motor ya muestra un mosaico fijo y fino.
  • Comprueba esquinas y bordes: completa izquierda, derecha, arriba, abajo y una diagonal antes de darlo por terminado.

Ejecutar la demo

npm install
npm run dev        # Vite, abre la demo
npm run typecheck  # tsc estricto

Skills relacionados