Communitygithub.com

Weft

Weft é uma habilidade de IA que recria qualquer imagem, vídeo, feed de webcam ou canvas como um mosaico de barras coloridas e curtas em linhas (como fios em um tear ou uma impressão risográfica). Ela se fragmenta em blocos grossos durante o movimento e retorna ao detalhe fino quando para, e um assunto recortado gira em 3D em direção ao cursor, com paralaxe de profundidade.

O que é Weft?

Weft é uma ferramenta poderosa para desenvolvedores que desejam aplicar um efeito visual estilizado de mosaico de barras (scanline) em imagens, vídeos ou câmeras ao vivo, semelhante a uma impressão risográfica ou a um tear. Ela se destaca por sua transição única de 'grosso para fino': quando o conteúdo se move, as barras se quebram em blocos grandes e granulados, e quando o movimento cessa, o detalhe fino retorna, criando um contraste visual marcante. A habilidade é implementada em TypeScript + WebGL2, é auto-contida em um único módulo (`weft.ts`) e funciona em qualquer página web ou framework moderno (React, Vue, etc.). O efeito é altamente configurável: você pode escolher paletas de cores (pré-definidas ou personalizadas), direção das barras (linhas ou colunas), modo de recorte do assunto (com paralaxe 3D que gira em direção ao cursor), e controlar a transição. Ele é ideal para criar retratos, avatares, efeitos de glitch, ou qualquer estilo de mosaico/risografia. A API é limpa: `createWeft(canvas, options)` retorna um objeto com métodos como `set()`, `kick()`, `pose()` e `setSource()`, e o suporte a 'prefers-reduced-motion' é nativo.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Weft faz?

Qualquer imagem é redesenhada como linhas de barras coloridas curtas sobre um fundo de papel. Cada linha é dividida em células irregulares. Uma célula assume a cor da paleta mais próxima da imagem naquele ponto, às vezes pontilhada com a segunda mais próxima. Sua barra tem largura total em áreas fortes e é mais estreita em áreas claras, e células por onde uma borda passa se dividem em listras finas. Quando algo se move, as linhas sobem para blocos grandes e as células se recortam muitas vezes por segundo. Quando para, elas descem de volta para o detalhe fino. Essa transição é a marca registrada do visual, então proteja-a.

Um assunto recortado de um fundo liso ou transparente recebe uma suave cúpula de profundidade a partir de sua silhueta, para que ele possa girar (eixo Y) e inclinar (eixo X) sem esticar. Os pontos deslizam lateralmente conforme sua profundidade e a luz rola pela cúpula. Imens em quadro cheio recebem uma cúpula central suave. O assunto é mantido centralizado no quadro automaticamente.

Arquivos

caminhoo que é
src/weft.tsO motor, um módulo TypeScript estritamente tipado sem dependências de runtime: createWeft(canvas, options), enableDrop, PALETTES, e os tipos WeftOptions, WeftConfig e Weft.
demo/Um retrato que gira com o cursor, com alternância de paleta e direção das barras, webcam, arrastar-e-soltar e parâmetros de URL (Vite).
references/options.mdCada opção, o que faz e seu intervalo útil.
references/recipes.mdIntegrações: React, herói, cartões de hover, scroll, slideshow, revelar, webcam e correspondência a uma referência.
references/pitfalls.mdO que deu errado ao construir isso e como evitar.

Fluxo de trabalho

  1. Defina a fonte e o trabalho. O que é: uma imagem estática, um vídeo, a webcam ou um canvas que a página já desenha? Onde vive: um herói, um cartão, uma página inteira? Qual movimento é desejado: direção do cursor, deriva ociosa, revelar ou uma transição entre imagens?
  2. Copie src/weft.ts para o projeto e mantenha o arquivo intacto. Ele precisa apenas de um bundler ou tsc, que qualquer projeto TS já possui. Para uma página JS pura, compile-o uma vez com npx tsc ou esbuild.
  3. Comece a partir de demo/main.ts e defina as opções usando as decisões abaixo.
  4. Mostre primeiro uma imagem estática. Congele uma pose com ?freeze=0&yaw=-20&pitch=8&break=0 e observe-a antes de construir mais ao redor. Verifique a frente, ambas as rotações, uma inclinação e um quadro fragmentado (break=1). Se o usuário forneceu uma referência, coloque uma imagem estática ao lado de um quadro dela e compare paleta, altura da linha e cor do papel.
  5. Depois o movimento. Verifique a transição ao vivo. A fragmentação dura uma fração de segundo, então examine quadro a quadro uma gravação de tela em vez de confiar em uma olhada. Procure por três coisas: a fragmentação é óbvia ao mover, cada parada resolve completamente nítido, e nada estica nos limites da rotação.

Decisões

Assunto (subject.mode):

  • Use 'auto' (padrão). Um PNG transparente usa 'alpha'. Um quadro cuja borda é majoritariamente de uma cor usa 'backdrop', que preenche o fundo a partir da borda, segue gradientes e remove manchas soltas. Qualquer outra coisa usa 'none'.
  • Force 'none' para paisagens, obras de arte e capturas de tela, para que um céu creme ou borda de papel não seja cortada.
  • Se um fundo complexo vazar para o assunto, ajuste subject.tolerance (padrão 0.16), ou melhor, passe um PNG recortado.

Paleta (palette):

  • Escolha uma predefinição: ember (riso quente, melhor para pele), graphite, riso, tide, candy, night (barras claras sobre escuro), phosphor, ou source (as próprias cores da imagem, posterizadas).
  • Você também pode passar suas próprias cores hexadecimais (até 16) e definir paper.
  • As cores são combinadas pela mais próxima. Inclua um tom escuro, um médio e um claro em cada família de matiz que a imagem precisar, caso contrário os rostos ficam planos ou turvos.
  • Em um paper escuro, as barras alargam automaticamente em áreas claras.

Direção: use 'rows' (horizontal, o visual clássico) ou 'columns'.

Enquadramento: focus: 'subject' (padrão) centraliza a caixa delimitadora do assunto recortado. Ele só se desloca ao longo de um eixo onde o assunto não é cortado pelo quadro. Use 'frame' para manter a imagem como composta.

Movimento (motion, turn):

  • pointer: true permite que o cursor controle: x gira, y inclina. Os cantos são presos em uma elipse, para que uma diagonal nunca acumule rotação total e inclinação total.
  • idle decide o que acontece quando o ponteiro para. 'poses' deriva através de motion.poses, 'center' retorna suavemente para a frente, e 'hold' permanece parado.
  • Mantenha turn.yaw em 34° ou menos e turn.pitch em 20° ou menos para uma imagem plana. Imagens em quadro cheio desejam cerca de 10 a 15° de rotação.
  • Use turn.enabled: false para um mosaico plano cujo único movimento é a transição.

Transição:

  • A rotação quebra as barras automaticamente. Chame weft.kick(amount) para qualquer outra coisa, como um clique, velocidade de scroll, mudança de slide ou batida.
  • transition.intro resolve de grosso ao carregar, e transition.onSource faz o mesmo quando a fonte muda.
  • Mantenha rows.coarse / rows.fine em torno de 4 a 6×.

API de relance

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

const weft = createWeft(canvas, {
  source: 'portrait.png',          // URL, <img>, <video>, <canvas>, File/Blob ou 'camera'
  palette: 'ember',                // ou ['#1c1a27', ...], ou '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);                    // quebra agora
weft.set({ palette: 'night' });    // mudanças de opção em tempo real, mesclagem profunda
weft.pose(-20, 6);                 // direciona no código; pose(null) devolve o controle
weft.setSource('camera');
enableDrop(weft);                  // solta um arquivo de imagem/vídeo em qualquer lugar
weft.destroy();

O canvas preenche sua caixa CSS, e a página é dona do layout. Elementos marcados como data-weft-ui são ocultados em imagens congeladas. weft.advance(dt, x, y) avança um relógio simulado, para renderização exata por quadro.

Regras para manter a qualidade

  • Use os pixels reais. Nunca redesenhe, trace ou "limpe" a foto ou avatar de uma pessoa para alimentá-lo. O efeito é a estilização.
  • Mantenha o papel calmo. Creme, osso ou off-white para paletas claras; um quase preto com um toque de cor para as escuras. Evite #fff e #000 puros.
  • A transição precisa de contraste no tempo. Os movimentos devem ser rápidos o suficiente para alcançar a extremidade grossa, e as paradas longas o suficiente (cerca de 1 s ou mais) para resolver completamente.
  • UI é apenas ícone e discreta: em um canto com baixa opacidade, marcado data-weft-ui.
  • Respeite prefers-reduced-motion. O motor já mostra um mosaico fino e estático.
  • Verifique cantos e bordas: esquerda, direita, cima, baixo e uma diagonal antes de considerar concluído.

Execute a demonstração

npm install
npm run dev        # Vite, abre a demonstração
npm run typecheck  # tsc rigoroso

Habilidades Relacionadas