Was macht weft?
Jedes Bild wird als Reihen kurzer, farbiger Balken auf einem Papiergrund neu gezeichnet. Jede Reihe ist in zitternde Zellen unterteilt. Eine Zelle nimmt die nächstgelegene Palettenfarbe des dortigen Bildes an, manchmal wird sie zum Zweitplatzierten gedithered. Der Balken ist in starken Bereichen in voller Breite und in schwachen schmaler. Zellen, die eine Kante durchläuft, spalten sich in dünne Streifen auf. Wenn sich etwas bewegt, vergrößern sich die Reihen zu großen Blöcken und die Zellen werden mehrmals pro Sekunde neu geschnitten. Wenn die Bewegung ruht, verkleinern sie sich wieder auf feine Details. Dieser Übergang ist die charakteristische Eigenschaft des Looks – bitte schütze ihn.
Ein Motiv, das aus einem einfarbigen oder transparenten Hintergrund ausgeschnitten ist, erhält durch seine Silhouette eine glatte Tiefenwölbung, sodass es sich drehen (Gieren) und neigen (Nicken) kann, ohne gestreckt zu werden. Punkte gleiten seitlich entsprechend ihrer Tiefe und Licht rollt über die Wölbung. Vollformatige Bilder erhalten stattdessen eine sanfte zentrale Wölbung. Das Motiv bleibt automatisch in der Bildmitte zentriert.
Dateien
| Pfad | Was |
|---|---|
src/weft.ts | Die Engine, ein strikt typisiertes TypeScript-Modul ohne Laufzeitabhängigkeiten: createWeft(canvas, options), enableDrop, PALETTES sowie die Typen WeftOptions, WeftConfig und Weft. |
demo/ | Ein Portrait, das sich mit dem Cursor dreht, mit Palette und Balkenrichtungsumschaltern, der Webcam, Drag & Drop und URL-Parametern (Vite). |
references/options.md | Jede Option, ihre Funktion und ihr sinnvoller Bereich. |
references/recipes.md | Integrationen: React, Hero, Hover-Karten, Scrollen, Diashow, Enthüllung, Webcam und Abgleich mit einer Referenz. |
references/pitfalls.md | Was beim Bau schiefgelaufen ist und wie man es vermeidet. |
Arbeitsablauf
- Quelle und Aufgabe festlegen. Was ist es: ein Standbild, ein Video, die Webcam oder eine Leinwand, die die Seite bereits zeichnet? Wo lebt es: ein Heldenbereich, eine Karte, eine ganze Seite? Welche Bewegung ist gewünscht: Cursor-Steuerung, eine sanfte Drift, eine Enthüllung oder ein Übergang zwischen Bildern?
- Kopiere
src/weft.tsin das Projekt und behalte die Datei vollständig. Sie benötigt nur einen Bundler odertsc, die jedes TS-Projekt hat. Für eine reine JS-Seite kompiliere sie einmal mitnpx tscoderesbuild. - Beginne mit
demo/main.tsund setze die Optionen anhand der folgenden Entscheidungen. - Zeige zuerst ein Standbild. Friere eine Pose mit
?freeze=0&yaw=-20&pitch=8&break=0ein und betrachte es, bevor du mehr darum herum baust. Überprüfe die Vorderseite, beide Drehungen, eine Neigung und einen zerbrochenen Rahmen (break=1). Wenn der Benutzer eine Referenz gegeben hat, platziere ein Standbild neben einem Frame der Referenz und vergleiche Palette, Zeilenhöhe und Papierfarbe. - Dann die Bewegung. Überprüfe den Übergang live. Der Zerfall dauert nur einen Bruchteil einer Sekunde, also durchlaufe eine Bildschirmaufnahme Bild für Bild, anstatt auf einen einzigen Blick zu vertrauen. Achte auf drei Dinge: Der Zerfall ist bei Bewegung deutlich sichtbar, jede Ruhephase löst sich vollständig scharf auf, und nichts dehnt sich an den Drehgrenzen.
Entscheidungen
Motiv (subject.mode):
- Verwende
'auto'(Standard). Ein transparentes PNG verwendet'alpha'. Ein Rahmen, dessen Rand überwiegend eine Farbe ist, verwendet'backdrop', das den Hintergrund vom Rand aus flutfüllt, Verläufen folgt und verirrte Flecken entfernt. Alles andere verwendet'none'. - Erzwinge
'none'für Landschaften, Kunstwerke und Screenshots, damit ein cremefarbener Himmel oder Papierrand nicht weggeschnitten wird. - Wenn ein belebter Hintergrund in das Motiv hineinragt, passe
subject.tolerance(Standard 0,16) an, oder besser, verwende ein ausgeschnittenes PNG.
Palette (palette):
- Wähle eine Voreinstellung:
ember(warmes Riso, am besten für Haut),graphite,riso,tide,candy,night(helle Balken auf dunklem Grund),phosphorodersource(die eigenen Farben des Bildes, posterisiert). - Du kannst auch eigene Hex-Farben (bis zu 16) übergeben und
papersetzen. - Farben werden am nächsten zuerst abgeglichen. Füge in jeder Farbfamilie, die das Bild benötigt, einen Dunkel-, einen Mittel- und einen Hellton hinzu, da sonst Gesichter flach oder schlammig wirken.
- Auf einem dunklen
paperwerden Balken in hellen Bereichen automatisch breiter.
Richtung: Verwende 'rows' (horizontal, der klassische Look) oder 'columns'.
Bildausschnitt: focus: 'subject' (Standard) zentriert die Begrenzungsbox des ausgeschnittenen Motivs. Es verschiebt sich nur entlang einer Achse, wenn das Motiv durch den Rahmen beschnitten wird. Verwende 'frame', um das Bild wie komponiert zu erhalten.
Bewegung (motion, turn):
pointer: truelässt den Cursor steuern: x dreht (gieren), y neigt (nicken). Die Ecken werden auf eine Ellipse geklemmt, sodass eine Diagonale niemals volles Gieren und volles Nicken stapelt.idleentscheidet, was passiert, wenn der Zeiger ruht.'poses'driftet durchmotion.poses,'center'kehrt sanft zur Vorderseite zurück, und'hold'bleibt stehen.- Halte
turn.yawbei 34° oder weniger undturn.pitchbei 20° oder weniger für ein flaches Bild. Vollformatige Bilder benötigen etwa 10 bis 15° Gieren. - Verwende
turn.enabled: falsefür ein flaches Mosaik, dessen einzige Bewegung der Übergang ist.
Übergang:
- Drehen unterbricht die Balken automatisch. Rufe
weft.kick(amount)für alles andere auf, z. B. einen Klick, Scrollgeschwindigkeit, einen Folienwechsel oder einen Beat. transition.introlöst sich beim Laden aus groben Blöcken auf, undtransition.onSourcetut dasselbe, wenn sich die Quelle ändert.- Halte
rows.coarse / rows.finebei etwa dem 4- bis 6-fachen.
API auf einen Blick
import { createWeft, enableDrop, type WeftOptions } from './weft';
const weft = createWeft(canvas, {
source: 'portrait.png', // URL, <img>, <video>, <canvas>, File/Blob oder 'camera'
palette: 'ember', // oder ['#1c1a27', ...], oder '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); // jetzt zerfallen
weft.set({ palette: 'night' }); // Live-Änderungen der Optionen, tief zusammengeführt
weft.pose(-20, 6); // programmatisch steuern; pose(null) gibt Kontrolle zurück
weft.setSource('camera');
enableDrop(weft); // ein Bild-/Videodatei überall ablegen
weft.destroy();
Die Leinwand füllt ihre CSS-Box, und die Seite besitzt das Layout. Elemente, die mit data-weft-ui markiert sind, werden in eingefrorenen Standbildern ausgeblendet. weft.advance(dt, x, y) schreitet eine simulierte Uhr fort, für frame-genaues Rendering.
Regeln, die es gut halten
- Verwende die echten Pixel. Zeichne nie ein Foto oder einen Avatar einer Person neu, zeichne es nach oder „bereinige“ es, um es einzuspeisen. Der Effekt ist die Stilisierung.
- Halte das Papier ruhig. Creme, Beige oder Off-White für helle Paletten; ein fast Schwarz mit einem Farbton für dunkle. Vermeide reines #fff und #000.
- Der Übergang benötigt Kontrast in der Zeit. Bewegungen müssen schnell genug sein, um die grobe Seite zu erreichen, und Ruhepausen lang genug (etwa 1 s oder mehr), um sich vollständig aufzulösen.
- UI ist nur aus Symbolen und leise: in einer Ecke mit geringer Deckkraft, markiert mit
data-weft-ui. - Respektiere
prefers-reduced-motion. Die Engine zeigt bereits ein ruhiges, feines Mosaik. - Überprüfe Ecken und Kanten: ganz links, rechts, oben, unten und eine Diagonale, bevor du es als abgeschlossen betrachtest.
Demo ausführen
npm install
npm run dev # Vite, öffnet die Demo
npm run typecheck # strenges tsc