Que fait Weft ?
Toute image est redessinée sous forme de rangées de courtes barres colorées sur un fond papier. Chaque rangée est découpée en cellules saccadées. Une cellule prend la couleur de palette la plus proche de l'image à cet endroit, parfois tramée avec la seconde couleur. Sa barre est pleine largeur sur les zones fortes et plus étroite sur les zones faibles, et les cellules traversées par un bord se divisent en fines rayures. Lorsque quelque chose bouge, les rangées montent en gros blocs et les cellules se redécoupent plusieurs fois par seconde. Lorsque cela s'arrête, elles redescendent en détail fin. Cette transition est la signature du rendu, donc protégez-la.
Un sujet découpé sur fond uni ou transparent reçoit un dôme de profondeur lisse à partir de son silhouette, lui permettant de pivoter (lacet) et de basculer (tangage) sans distorsion. Les points glissent latéralement selon leur profondeur et la lumière roule sur le dôme. Les images plein cadre reçoivent un léger dôme central à la place. Le sujet est automatiquement maintenu centré dans le cadre.
Fichiers
| chemin | description |
|---|---|
src/weft.ts | Le moteur, un module TypeScript strictement typé sans dépendance runtime : createWeft(canvas, options), enableDrop, PALETTES, et les types WeftOptions, WeftConfig et Weft. |
demo/ | Un portrait qui suit le curseur, avec toggles de palette et de direction, la webcam, le glisser-déposer, et des paramètres d'URL (Vite). |
references/options.md | Chaque option, son rôle et sa plage utile. |
references/recipes.md | Intégrations : React, hero, cartes au survol, défilement, diaporama, révélation, webcam, et correspondance avec une référence. |
references/pitfalls.md | Ce qui a mal tourné lors de la construction et comment l'éviter. |
Workflow
- Déterminez la source et le travail. Quelle est la source : une image fixe, une vidéo, la webcam ou un canvas que la page dessine déjà ? Où se trouve-t-elle : un hero, une carte, une page entière ? Quel mouvement est souhaité : pilotage par curseur, dérive au repos, révélation ou transition entre images ?
- Copiez
src/weft.tsdans le projet et gardez le fichier entier. Il nécessite seulement un bundler outsc, que tout projet TS possède déjà. Pour une page en JS pur, compilez-le une fois avecnpx tscouesbuild. - Partez de
demo/main.tset configurez les options selon les décisions ci-dessous. - Montrez d'abord une image fixe. Figez une pose avec
?freeze=0&yaw=-20&pitch=8&break=0et examinez-la avant d'ajouter du mouvement. Vérifiez le devant, les deux rotations, une bascule et une image décomposée (break=1). Si l'utilisateur a fourni une référence, placez une image fixe à côté d'une image de celle-ci et comparez la palette, la hauteur des rangées et la couleur du papier. - Ensuite le mouvement. Vérifiez la transition en direct. La décomposition ne dure qu'une fraction de seconde, parcourez donc un enregistrement écran image par image plutôt que de vous fier à un seul coup d'œil. Recherchez trois choses : la décomposition est évidente lors du mouvement, chaque repos est parfaitement net, et rien ne s'étire aux limites de rotation.
Décisions
Sujet (subject.mode) :
- Utilisez
'auto'(par défaut). Un PNG transparent utilise'alpha'. Une image dont le bord est principalement d'une seule couleur utilise'backdrop', qui remplit l'arrière-plan à partir du bord, suit les dégradés et supprime les taches parasites. Tout le reste utilise'none'. - Forcez
'none'pour les paysages, œuvres d'art et captures d'écran, afin qu'un ciel crème ou un bord de papier ne soit pas découpé. - Si un arrière-plan chargé empiète sur le sujet, ajustez
subject.tolerance(par défaut 0.16), ou mieux, passez un PNG détouré.
Palette (palette) :
- Choisissez un préréglage :
ember(riso chaud, idéal pour la peau),graphite,riso,tide,candy,night(barres claires sur fond sombre),phosphor, ousource(les couleurs propres de l'image, posterisées). - Vous pouvez aussi passer vos propres couleurs hexadécimales (jusqu'à 16) et définir
paper. - Les couleurs sont appariées par proximité. Incluez un foncé, un moyen et un clair pour chaque famille de teinte dont l'image a besoin, sinon les visages deviennent plats ou boueux.
- Sur un
papersombre, les barres s'élargissent automatiquement sur les zones lumineuses.
Direction : utilisez 'rows' (horizontal, le rendu classique) ou 'columns'.
Cadrage : focus: 'subject' (par défaut) centre la boîte englobante du sujet détouré. Il ne se déplace que le long d'un axe où le sujet n'est pas rogné par le cadre. Utilisez 'frame' pour conserver la composition de l'image.
Mouvement (motion, turn) :
pointer: truepermet au curseur de piloter : x pour le lacet, y pour le tangage. Les coins sont contraints sur une ellipse, donc une diagonale n'empile jamais le lacet et le tangage complets.idledécide ce qui se passe lorsque le pointeur est au repos.'poses'dérive à traversmotion.poses,'center'revient doucement vers le devant, et'hold'reste en place.- Gardez
turn.yawà 34° ou moins etturn.pitchà 20° ou moins pour une image plate. Les images plein cadre veulent environ 10 à 15° de lacet. - Utilisez
turn.enabled: falsepour une mosaïque plate dont le seul mouvement est la transition.
Transition :
- La rotation décompose automatiquement les barres. Appelez
weft.kick(amount)pour toute autre action, comme un clic, la vitesse de défilement, un changement de diapositive ou un battement. transition.introse résout à partir du grossier au chargement, ettransition.onSourcefait de même lorsque la source change.- Maintenez
rows.coarse / rows.fineautour de 4 à 6×.
Aperçu de l'API
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); // décomposer maintenant
weft.set({ palette: 'night' }); // changements d'options en direct, fusion profonde
weft.pose(-20, 6); // piloter par code ; pose(null) redonne le contrôle
weft.setSource('camera');
enableDrop(weft); // déposer un fichier image/vidéo n'importe où
weft.destroy();
Le canvas remplit sa boîte CSS, et la page gère la disposition. Les éléments marqués data-weft-ui sont masqués dans les images fixes figées. weft.advance(dt, x, y) fait avancer une horloge simulée, pour un rendu image par image exact.
Règles pour le garder de qualité
- Utilisez les pixels réels. Ne redessinez jamais, ne tracez ni ne « nettoyez » la photo ou l'avatar d'une personne pour l'alimenter. L'effet est la stylisation.
- Gardez le papier calme. Crème, os ou blanc cassé pour les palettes claires ; un quasi-noir avec une touche de couleur pour les sombres. Évitez le #fff et #000 purs.
- La transition a besoin de contraste dans le temps. Les mouvements doivent être assez rapides pour atteindre l'extrémité grossière, et les repos assez longs (environ 1 s ou plus) pour se résoudre complètement.
- L'interface utilisateur est composée d'icônes seules et discrètes : dans un coin à faible opacité, marquée
data-weft-ui. - Respectez
prefers-reduced-motion. Le moteur affiche déjà une mosaïque fine et fixe. - Vérifiez les coins et les bords : gauche complet, droite, haut, bas et une diagonale avant de déclarer le travail terminé.
Exécuter la démo
npm install
npm run dev # Vite, ouvre la démo
npm run typecheck # tsc strict