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
| caminho | o que é |
|---|---|
src/weft.ts | O 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.md | Cada opção, o que faz e seu intervalo útil. |
references/recipes.md | Integrações: React, herói, cartões de hover, scroll, slideshow, revelar, webcam e correspondência a uma referência. |
references/pitfalls.md | O que deu errado ao construir isso e como evitar. |
Fluxo de trabalho
- 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?
- Copie
src/weft.tspara o projeto e mantenha o arquivo intacto. Ele precisa apenas de um bundler outsc, que qualquer projeto TS já possui. Para uma página JS pura, compile-o uma vez comnpx tscouesbuild. - Comece a partir de
demo/main.tse defina as opções usando as decisões abaixo. - Mostre primeiro uma imagem estática. Congele uma pose com
?freeze=0&yaw=-20&pitch=8&break=0e 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. - 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, ousource(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
paperescuro, 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: truepermite 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.idledecide o que acontece quando o ponteiro para.'poses'deriva através demotion.poses,'center'retorna suavemente para a frente, e'hold'permanece parado.- Mantenha
turn.yawem 34° ou menos eturn.pitchem 20° ou menos para uma imagem plana. Imagens em quadro cheio desejam cerca de 10 a 15° de rotação. - Use
turn.enabled: falsepara 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.introresolve de grosso ao carregar, etransition.onSourcefaz o mesmo quando a fonte muda.- Mantenha
rows.coarse / rows.fineem 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