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