p5-paint-animation

p5 绘画动画

三种流程，同一个引擎。根据输入选择：

输入	流程	输出
文本提示词 / 短语	A：书写动画	手写内容在横线纸上逐渐显现，追踪笔迹以供摄像机跟随
照片	B：重新绘制 + 逐渐上色	笔触绘画，可输出静态图或绘画过程影片，摄像机拉远
视频 / Live Photo	C：动态绘画	在锁定的笔触网格上重新绘制每一帧

适用场景 / 不适用场景

适用于：营造手工制作般的动态效果——自行书写的手写文字、转换为笔触画作的照片（静态或动态），以及作为动态绘画呈现的短片。 不适用于：清晰的排版文字或品牌准确的文字（请使用真实字体）、照片级真实的输出、时长超过约 10s 的素材（渲染成本随帧数增长，每帧约需 5–20s），或实时 / 交互式页面（本工具会离线渲染 MP4/PNG）。

要求和副作用

• 要求：Node 22.12+、PATH 中有 ffmpeg、约 500MB 磁盘空间（Chromium）。
• sh scripts/setup.sh（手动运行一次）使用已提交的锁定文件，从 npm registry 下载固定版本的依赖：puppeteer 25.9.0、p5 2.3.2 (LGPL-2.1) 和 p5.brush 2.2.1 (MIT)。Puppeteer 会从 Google 的下载服务下载其固定版本的 Chrome for Testing 构建版。仅下载；无需凭据，不产生费用，不会上传任何内容。
• 渲染会在空白页面中启动沙盒化的无头 Chromium。会阻止草图发起网络和本地文件请求；草图会以数据 URL 的形式接收输入。
• 只会在你指定的路径中写入文件（out.png / out.mp4，以及同级的 .track.json；使用 --keep-frames 1 时还会生成 _frames_* 目录）。
• 可选，仅用于流程 C 的主体抠图：npx hyperframes remove-background（从 npm 下载 HyperFrames CLI；在本地使用 CoreML 推理，不会有数据离开设备）。

验证是否成功

运行下面任一命令进行渲染，然后打开输出文件：最后一帧必须显示完整作品（文字已全部写完 / 绘画已完全覆盖），使用相同的 --seed 重新运行必须在画布上生成完全相同的字节。评审时使用的冒烟测试：node render-anim.mjs sketches/handwriting.anim.js /tmp/t.mp4 --size 1600x900 --seed 7 --inject 'PHRASE="go make something"'。

设置（一次即可）

sh scripts/setup.sh

安装 scripts/package-lock.json 中记录的准确依赖树。 以下所有命令均从 scripts/ 目录运行。

流程 A — 提示词 → 书写动画

node render-anim.mjs sketches/handwriting.anim.js out.mp4 \
  --size 1600x900 --fps 24 --seed 7 --hold 12 \
  --inject 'PHRASE="your text here";SIZE=170'

• 完整字符集：小写字母、大写字母、数字、? . , - / @。会自动换行。
• 使用 --inject 调整参数：SIZE、INK（十六进制）、BRUSH（"2B" 铅笔、"crayon" 蜡笔、"charcoal" 炭笔）、PAPER=1 可使用空白纸张。
• 运行会写入 out.track.json——记录每一帧的笔尖位置。若要实现摄像机跟随笔尖移动，可沿平滑后的轨迹裁剪每一帧（指数跟随，增益约为 0.14；摄像机 y 轴锁定在基线上——绝不跟随笔尖的 y 坐标，否则每遇到一个上伸笔画，摄像机都会上下跳动）。
• 若要让书写效果更潦草杂乱，可提高草图中每个字母的抖动幅度；若要让文字与配音同步，先转录配音，再从每个词的口播时间开始绘制笔画。

流程 B — 照片 → 绘画（+ 绘制胶片 + 摄像机）

静帧：

node render.mjs sketches/repaint.anim.js out.png \
  --size 720x900 --seed 3 --image photo.jpg --inject "STYLE=0;DETAIL=3"

绘制胶片（绘画自行绘制，由粗到细，按画家习惯的顺序—— 先画平静区域，最后画脸部）：

node render-anim.mjs sketches/repaint.anim.js out.mp4 \
  --size 720x900 --seed 3 --image photo.jpg --fps 14 --hold 40 \
  --inject 'STYLE=0;DETAIL=3;SUBJECT="0.5,0.5,0.44,0.55"'

• 先裁剪至主体。 人脸在画面中的大小决定一切：自拍距离的人脸能精细呈现；小脸则仍会像人物剪影。使用 4:5 或 9:16 的肖像比例。
• 旋钮：STYLE 0 粉彩 / 1 水粉 / 2 炭笔素描。DETAIL 1 绘画感，2 精细呈现人脸，3 柔和五官（鼻子），5 肖像级（增加第二轮精细绘制）。LOOSE 0.7–1.5 笔触狂放度。SAT 色彩补偿（约 1.1）。
• SUBJECT="cx,cy,rx,ry"（图像比例）会在所有轮次中优先绘制该椭圆内的所有内容，并放置一个 subject-done 帧标记。摄像机拉远方案：先紧贴主体，然后在标记帧处使用 ffmpeg zoompan 平滑拉远（余弦缓动，约 2 秒）： zoompan=z='if(lte(in,M),1.9,1.85-0.85*(0.5-0.5*cos(PI*min((in-M)/28,1))))' （先用 lanczos 放大 2 倍，以保证近景阶段清晰。）

流程 C — 视频 / Live Photo → 动态绘画

node render-video.mjs clip.mov out.mp4 \
  --size 720x900 --fps 12 --seed 7 --inject "STYLE=0;DETAIL=2"

• 笔触网格只根据第 1 帧构建一次并锁定；每帧只重新采样颜色和方向。笔触保持静止——主体移动时，绘画不会“沸腾”。
• Live Photos： 获取配对的 .mov（通过分享表单中的“选项”→开启 Live Photo，或通过 Photos.app → Export Unmodified Original）。如果收到的是裸 JPEG，说明传输时动态效果已被剥离——请对方改发 2–3 秒的普通视频；这本来就是更好的输入。
• 先筛查动态。 Live Photos 包含手机晃动。测量逐帧动态（ffprobe -f lavfi "movie=in.mov,signalstats" → YDIF），使用 --start/--dur 只绘制平静片段，并将结果正反拼接（正向+反向拼接），制作无缝的呼吸循环。
• 摄像机移动幅度大？WORLD=1 通过图像相关性跟踪摄像机，并让笔触以世界坐标为基准——摄像机在一幅不断延展的绘画上平移。仅支持平移；快速变焦会产生漂移。
• 只绘制主体：先生成遮罩帧（npx hyperframes remove-background），使用 --frames DIR 传入带遮罩的 PNG，并设置 MASKED=1，再将 BG 设为纸张颜色。
• 暗光素材：仅使用伽马进行调色（eq=gamma=1.2）。绘制前切勿提高饱和度——阴影中的色度噪声会变成真实的青绿色颜料。

质检关卡（所有流程）

• 查看实际输出帧；切勿只凭预期就交付。检查：人脸是否清晰呈现、画布是否有裸露空隙、首帧／中间帧／末帧是否连贯。
• 相同种子 = 相同渲染结果。固定种子，每次只调整一个旋钮。
• 对于要拼接到长片中的任何素材，按照运动原则用数值验证接缝——此技能生成的是素材，而不是最终的叙事结构。

references/flows.md 包含完整的操作示例；references/gotchas.md 列出了已遇到的故障模式，避免你重蹈覆辙。