Communitygithub.com

Weft

Reconstruit toute image, vidéo, flux webcam ou canvas en une mosaïque à barres de trame : des rangées de barres colorées courtes (comme des fils sur un métier à tisser ou un risographe). L'effet se dégrade en gros blocs lors du mouvement et retrouve un détail fin à l'arrêt ; un sujet détouré pivote en 3D vers le curseur par parallaxe de profondeur.

Qu'est-ce que Weft ?

Weft est un moteur de rendu de mosaïque à barres de trame (scanline) pour le web, écrit en TypeScript et utilisant WebGL2. Il transforme n'importe quelle source visuelle (image, vidéo, webcam ou canvas) en rangées de courtes barres colorées sur un fond « papier », créant un effet rappelant le risographe, les trames offset ou le tissage. L'originalité de Weft réside dans sa transition dynamique « brut → fin » : lorsque le contenu ou le curseur bouge, les rangées se regroupent en gros blocs grossiers ; dès que le mouvement cesse (environ une seconde), le détail fin revient progressivement. Cet effet est particulièrement apprécié pour les portraits, avatars ou visuels interactifs. Weft supporte également un effet de profondeur 3D : un sujet détouré (sur fond transparent ou uni) reçoit un dôme de profondeur lisse basé sur son silhouette, permettant de le faire pivoter (lacet et tangage) en suivant le curseur, sans distorsion. Les images plein cadre bénéficient d'un léger dôme central. La bibliothèque fonctionne dans n'importe quelle page web ou framework (React, Vite, etc.) et est fournie avec un fichier unique `src/weft.ts` sans dépendance runtime, plus des démos et une documentation complète sur les options, les recettes d'intégration et les pièges à éviter.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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

chemindescription
src/weft.tsLe 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.mdChaque option, son rôle et sa plage utile.
references/recipes.mdIntégrations : React, hero, cartes au survol, défilement, diaporama, révélation, webcam, et correspondance avec une référence.
references/pitfalls.mdCe qui a mal tourné lors de la construction et comment l'éviter.

Workflow

  1. 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 ?
  2. Copiez src/weft.ts dans le projet et gardez le fichier entier. Il nécessite seulement un bundler ou tsc, que tout projet TS possède déjà. Pour une page en JS pur, compilez-le une fois avec npx tsc ou esbuild.
  3. Partez de demo/main.ts et configurez les options selon les décisions ci-dessous.
  4. Montrez d'abord une image fixe. Figez une pose avec ?freeze=0&yaw=-20&pitch=8&break=0 et 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.
  5. 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, ou source (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 paper sombre, 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: true permet 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.
  • idle décide ce qui se passe lorsque le pointeur est au repos. 'poses' dérive à travers motion.poses, 'center' revient doucement vers le devant, et 'hold' reste en place.
  • Gardez turn.yaw à 34° ou moins et turn.pitch à 20° ou moins pour une image plate. Les images plein cadre veulent environ 10 à 15° de lacet.
  • Utilisez turn.enabled: false pour 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.intro se résout à partir du grossier au chargement, et transition.onSource fait de même lorsque la source change.
  • Maintenez rows.coarse / rows.fine autour 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

Skills associés