Communitygithub.com

weft

Erstellt aus Bildern, Videos, Webcam oder Canvas ein Weft-Scanlinien-Mosaik aus farbigen Balken in Reihen. Es zerfällt bei Bewegung in grobe Blöcke und stellt bei Ruhe feine Details wieder her.

Was ist weft?

Weft ist ein Werkzeug zur Erstellung eines charakteristischen Scanlinien-Mosaik-Effekts, inspiriert von traditionellen Risograph-Drucken oder Webmustern. Es zeichnet jedes Bild als Reihen kurzer, farbiger Balken auf einem Papiergrund nach, wobei jede Reihe in zitternde Zellen unterteilt ist, die die vorherrschende Farbe annehmen. Die Besonderheit ist der sanfte Übergang zwischen groben Blöcken bei Bewegung und feiner Auflösung im Ruhezustand – ein Effekt, der an Glitch-Effekte oder einen sich schärfenden Druck erinnert. Ausgeschnittene Motive auf transparentem Hintergrund erhalten eine 3D-Tiefenwölbung und können per Cursor gedreht werden (Gieren und Neigen), ohne verzerrt zu werden. Weft ist als strikt typisiertes TypeScript-Modul mit WebGL2 implementiert und benötigt keine Laufzeitabhängigkeiten. Es funktioniert in jeder Webseite oder jedem Framework, da es einfach in ein Projekt kopiert werden kann. Das Repository enthält eine Demo, Optionen und Integrationsanleitungen für React, Helden, Hover-Karten, Scrollen, Diashows, Enthüllungen, Webcam und Referenzabgleiche. Entwickler müssen die Quelle und den Verwendungszweck festlegen, Optionen wie Paletten, Bewegungsmodi und Übergänge konfigurieren und sicherstellen, dass die Bewegung schnell genug ist, um den gewünschten Lo-Fi-Effekt zu erzielen, während Ruhe lang genug anhält, damit er sich vollständig auflöst. Die Barrierefreiheit wird durch die Berücksichtigung von `prefers-reduced-motion` unterstützt.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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

PfadWas
src/weft.tsDie 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.mdJede Option, ihre Funktion und ihr sinnvoller Bereich.
references/recipes.mdIntegrationen: React, Hero, Hover-Karten, Scrollen, Diashow, Enthüllung, Webcam und Abgleich mit einer Referenz.
references/pitfalls.mdWas beim Bau schiefgelaufen ist und wie man es vermeidet.

Arbeitsablauf

  1. 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?
  2. Kopiere src/weft.ts in das Projekt und behalte die Datei vollständig. Sie benötigt nur einen Bundler oder tsc, die jedes TS-Projekt hat. Für eine reine JS-Seite kompiliere sie einmal mit npx tsc oder esbuild.
  3. Beginne mit demo/main.ts und setze die Optionen anhand der folgenden Entscheidungen.
  4. Zeige zuerst ein Standbild. Friere eine Pose mit ?freeze=0&yaw=-20&pitch=8&break=0 ein 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.
  5. 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), phosphor oder source (die eigenen Farben des Bildes, posterisiert).
  • Du kannst auch eigene Hex-Farben (bis zu 16) übergeben und paper setzen.
  • 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 paper werden 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: true lä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.
  • idle entscheidet, was passiert, wenn der Zeiger ruht. 'poses' driftet durch motion.poses, 'center' kehrt sanft zur Vorderseite zurück, und 'hold' bleibt stehen.
  • Halte turn.yaw bei 34° oder weniger und turn.pitch bei 20° oder weniger für ein flaches Bild. Vollformatige Bilder benötigen etwa 10 bis 15° Gieren.
  • Verwende turn.enabled: false fü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.intro löst sich beim Laden aus groben Blöcken auf, und transition.onSource tut dasselbe, wenn sich die Quelle ändert.
  • Halte rows.coarse / rows.fine bei 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

Verwandte Skills