Communitygithub.com

Weft

将任何图像、视频、网络摄像头或画布重新绘制为 Weft 风格:由短彩色条组成的栅格线条马赛克(如同织机上的纬线或 Riso 印刷效果)。在运动时分解为粗大色块,静止时恢复为精细细节;前景主体根据指针位置通过深度视差实现 3D 旋转。

Weft 是什么?

Weft 是一个基于 TypeScript + WebGL2 的图像风格化引擎,能将任意输入(图像、视频、网络摄像头或动态画布)转换为独特的扫描线/条纹马赛克效果,类似织物的纬线或 Riso 印刷半色调。其核心技术在于运动与静止之间的动态转换:当画面运动时,各行会迅速分解为粗大的矩形块;而当画面静止约 1 秒以上,又会逐渐恢复为精细的细节条纹。这种“粗粒→精细”的过渡是该效果的标志性特征。此外,Weft 还能从图像的透明背景中提取主体,为其生成平滑的深度轮廓,实现基于鼠标指针的 3D 偏航和俯仰旋转,且不会产生拉伸变形。该引擎以单一零依赖的 TypeScript 模块形式提供,可直接集成到任何网页或框架(React、Vite 等)中,并支持多种预设调色板、自定义方向(行/列)、聚焦模式、闲置姿态漂移以及通过 `data-weft-ui` 属性管理交互 UI 元素。其 API 简洁,涵盖加载、实时参数调整、姿态控制、源切换及销毁等完整生命周期。

兼容平台~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. 确定源和任务。 是什么:静态图片、视频、网络摄像头,还是页面已绘制的画布?它位于何处:英雄区、卡片、全页?需要哪种运动:光标操控、空闲漂移、展示效果,还是图片间过渡?
  2. 将 src/weft.ts 复制到项目中 并保持文件完整。它只需要一个打包工具或 tsc,任何 TS 项目都有这些。对于纯 JavaScript 页面,使用 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(暖色 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

相关技能