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 | 构建此效果时的问题及如何避免。 |
工作流程
- 确定源和任务。 是什么:静态图片、视频、网络摄像头,还是页面已绘制的画布?它位于何处:英雄区、卡片、全页?需要哪种运动:光标操控、空闲漂移、展示效果,还是图片间过渡?
- 将
src/weft.ts复制到项目中 并保持文件完整。它只需要一个打包工具或tsc,任何 TS 项目都有这些。对于纯 JavaScript 页面,使用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(暖色 Riso,最适合皮肤)、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();
画布填充其 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