Communitygithub.com

Weft

將任何圖片、影片、網路攝影機畫面或 Canvas 重新繪製成 Weft 效果——一種由短彩色橫條組成的掃描線馬賽克(如同織布機上的經緯線或 Risograph 印刷)。它會在移動時碎裂成粗顆粒區塊,靜止時恢復精細細節,並且主體會根據滑鼠深度視差進行 3D 轉向。

Weft 是什麼?

Weft 是一個基於 TypeScript + WebGL2 的 AI 代理技能,能夠將任何圖片、影片、網路攝影機或 Canvas 輸出轉換為獨特的掃描線條馬賽克效果。其核心特點在於「粗細轉換」:當畫面移動時,行會放大成粗塊,單元格每秒多次重新切割;當畫面靜止時,則逐步恢復精細細節,形成鮮明的視覺簽名。此外,從純色或透明背景中切割出的主體會獲得平滑的深度曲面,可實現無拉伸的 3D 轉向(偏航與俯仰),而全畫面圖片則採用溫和的中心曲面效果。此技能支援所有現代網頁或框架,並提供完整的 TypeScript API,包括 `createWeft`、`enableDrop`、多種預設調色板(如 ember、graphite、riso 等)以及豐富的配置選項。它適用於開發者希望實現條馬賽克、掃描線/條紋/線條抖動肖像、Risograph 或半色調條效果、粗到細過渡動畫,或是可隨滑鼠轉動的肖像大頭貼等場景。

相容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/JDhruv14/weft/tree/HEAD

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Weft 是做什麼的?

任何圖片都會被重新繪製成紙張背景上的一行行短彩色條。每一行被切割成抖動的單元格。單元格會選取該處最接近圖片顏色的調色板色彩,有時會抖動到第二接近的顏色。在強烈區域,條會是全寬;在微弱區域則較窄,且邊緣經過的單元格會分裂成細條紋。當有東西移動時,行會放大成粗塊,單元格每秒多次重新切割。當靜止時,它們會逐步恢復精細細節。這種過渡是該視覺風格的標誌,請務必保護它。

從純色或透明背景中切割出的主體,會根據其輪廓獲得平滑的深度曲面,因此可以轉向(偏航)和傾斜(俯仰)而不會拉伸。點會根據其深度橫向滑動,光線則在曲面上滾動。全畫面圖片會獲得溫和的中心曲面。主體會自動保持在畫面中央。

檔案

路徑說明
src/weft.ts引擎,一個嚴格型別的 TypeScript 模組,無運行時依賴:createWeft(canvas, options)、enableDrop、PALETTES,以及型別 WeftOptions、WeftConfig 和 Weft。
demo/一個可隨滑鼠轉動的肖像,附帶調色板和條方向切換、網路攝影機、拖放功能以及 URL 參數(Vite)。
references/options.md每個選項、其功能及有效範圍。
references/recipes.md整合範例:React、英雄區塊、懸停卡片、滾動、幻燈片、揭示效果、網路攝影機,以及匹配參考畫面。
references/pitfalls.md構建此效果時出現的問題及如何避免。

工作流程

  1. 確定來源和任務。 它是什麼:靜態圖片、影片、網路攝影機,還是頁面已有的 Canvas?它位於何處:英雄區塊、卡片、全頁?需要哪種動態:滑鼠操控、閒置漂移、揭示效果,還是圖片間的過渡?
  2. 將 src/weft.ts 複製到專案中,並保持檔案完整。它只需要一個打包工具或 tsc,任何 TS 專案都具備。對於純 JS 頁面,使用 npx tsc 或 esbuild 編譯一次即可。
  3. 從 demo/main.ts 開始,並根據以下決策設定選項。
  4. 先顯示一張靜態圖片。 使用 ?freeze=0&yaw=-20&pitch=8&break=0 凍結一個姿勢,然後再在其周圍構建更多內容。檢查正面、兩個轉向、一個傾斜和一個碎裂的幀(break=1)。如果使用者提供了參考畫面,將靜態圖片放在其一個幀旁邊,比較調色板、行高和紙張顏色。
  5. 然後處理動態。 即時檢查過渡效果。碎裂只持續不到一秒,因此請逐幀查看螢幕錄影,而不是僅憑一瞥。尋找三件事:移動時碎裂明顯,每次靜止都能完全恢復清晰,且在轉向極限處沒有任何拉伸。

決策

主體(subject.mode):

  • 使用 'auto'(預設值)。透明 PNG 使用 'alpha'。邊框主要由單一顏色構成的幀使用 'backdrop',它會從邊框開始填充背景,跟隨漸層並去除雜散斑點。其他情況使用 'none'。
  • 對於風景、藝術作品和螢幕截圖,強制使用 'none',以免米色天空或紙張邊框被切割掉。
  • 如果雜亂的背景滲入主體,請調整 subject.tolerance(預設值 0.16),或者更好的方法是傳入已切割的 PNG。

調色板(palette):

  • 選擇一個預設:ember(暖色 Risograph,最適合膚色)、graphite、riso、tide、candy、night(淺色條在深色背景上)、phosphor 或 source(圖片本身的顏色,經過海報化處理)。
  • 你也可以傳入自己的十六進制顏色(最多 16 種)並設定 paper。
  • 顏色採用最近匹配優先。每個圖片需要的色系都要包含深色、中間色和淺色,否則臉部會變得扁平或混濁。
  • 在深色 paper 上,條會在高亮區域自動變寬。

方向:使用 'rows'(水平,經典效果)或 'columns'。

取景:focus: 'subject'(預設值)會將切割主體的邊界框置中。它只會在主體未被畫面裁切的方向上進行偏移。使用 'frame' 則保持圖片原有的構圖。

動態(motion、turn):

  • pointer: true 讓滑鼠控制方向:x 軸轉向,y 軸傾斜。轉角會被限制在一個橢圓上,因此對角線不會同時達到最大偏航和最大俯仰。
  • idle 決定滑鼠靜止時的行為。'poses' 會在 motion.poses 中漂移,'center' 會慢慢回到正面,'hold' 則保持不動。
  • 對於平面圖片,請將 turn.yaw 保持在 34° 或以下,turn.pitch 保持在 20° 或以下。全畫面圖片大約需要 10 到 15° 的偏航。
  • 使用 turn.enabled: false 來獲得一個僅有過渡動態的平面馬賽克。

過渡:

  • 轉向會自動使條碎裂。對於其他情況(如點擊、滾動速度、幻燈片切換或節拍),請呼叫 weft.kick(amount)。
  • transition.intro 會在載入時從粗顆粒開始解析,transition.onSource 則在來源變更時執行相同操作。
  • 將 rows.coarse / rows.fine 保持在大約 4 到 6 倍。

API 一覽

import { createWeft, enableDrop, type WeftOptions } from './weft';

const weft = createWeft(canvas, {
  source: 'portrait.png',          // URL、<img>、<video>、<canvas>、File/Blob 或 'camera'
  palette: 'ember',                // 或 ['#1c1a27', ...] 或 '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);                    // 立即碎裂
weft.set({ palette: 'night' });    // 即時選項變更,深度合併
weft.pose(-20, 6);                 // 在程式碼中控制;pose(null) 交還控制權
weft.setSource('camera');
enableDrop(weft);                  // 隨處拖放圖片/影片檔案
weft.destroy();

Canvas 會填滿其 CSS 盒子,頁面擁有佈局控制權。標記了 data-weft-ui 的元素會在凍結的靜態畫面中隱藏。weft.advance(dt, x, y) 會推進模擬時鐘,用於幀精確渲染。

保持品質的規則

  • **使用真實像素。**絕不重新繪製、描摹或「清理」某人的照片或頭像來輸入。效果本身就是風格化。
  • **保持紙張平靜。**淺色調色板使用奶油色、骨色或米白色;深色調色板使用帶有一點色彩感的近黑色。避免純 #fff 和 #000。
  • **過渡需要時間上的對比。**移動必須足夠快以達到粗顆粒端,而靜止必須足夠長(約 1 秒或更長)以完全解析。
  • UI 僅為圖示且低調:位於角落,低透明度,標記為 data-weft-ui。
  • 尊重 prefers-reduced-motion。引擎已經會顯示靜態的精細馬賽克。
  • 檢查角落和邊緣:在宣告完成前,檢查完全左、右、上、下以及對角線方向。

執行範例

npm install
npm run dev        # Vite,開啟範例
npm run typecheck  # 嚴格的 tsc

相關技能