toy-loops 是做什么的?
微小的纸艺世界(如小岛、露营地、电影片场),Claude 是其中的演员,配上柔和的暖光和浅景深,看起来像一个微缩景观。每一个物体都由代码构建,每一帧都由其帧号计算得出,因此循环能够完美闭合。其外观源自 Pimbo 在 anymation/3d_ref/style2 中的参考资料,并使用了 reference-video-analysis 技能(第一遍分析:3d_ref/style2/analysis/FIRST_PASS.md)。这些参考资料是私有的学习材料:请复制其工艺手法,切勿挪用其场景。
状态:v1, 2026-11-18. 已制作并通过验证的作品:
claude_isla:经 Pimbo 批准("esta épica")。claude_fogata:第二个循环动画。director_hero:一张2400x1200网页英雄图,制作了两种配色。claude_pose:带实时网页眼睛的剪影动画。claude.glb:3D模型。
文件结构
代码位于 Pimbo 的电脑上:C:\Users\Pimbo\work\anymation\toy3d\skill。除非另有说明,以下所有路径均相对于其 kit/ 文件夹。
| 路径 | 说明 |
|---|---|
lib/toy.py | 外观:带白色倒角的纸质材质、形状、灯光、相机、渲染设置 |
lib/anim.py | 动画工具:缓动函数、Track(姿态到姿态)、弹簧、squash、arc、looped |
lib/chars.py | Claude:绑定及其六种眼睛设置;每帧调用一次 .pose(...) |
lib/runner.py | 逐帧渲染场景;每个场景以 runner.run(...) 结尾 |
loops/<name>/scene.py | 一个循环动画 |
stills/<name>/scene.py | 一张静态图片(T = 1) |
tools/make_loop.py | 在一行命令中完成渲染、编码GIF 1080/720和MP4 x1/x3、质量检测、联系表 |
tools/qa_loop.py | 循环接缝、帧数、静止帧、与参考资料对比的运动量 |
tools/duotone.py | 图片的蓝色单色版本(网页英雄图风格) |
tools/web_eyes.py | 一个网页页面,Claude 的眼睛会跟随光标移动,基于无眼睛的渲染 |
tools/claude_glb.py | Claude 模型导出为 .glb 格式(纯色,保留白色边缘),在 Blender 内运行 |
out/<name>/ | 输出目录:frames/、最终文件、sheet.jpg、qa.json |
完成的作品会复制到 anymation/toy3d/videos/<name>/;网页作品位于 anymation/toy3d/web/。
环境需求:
- Blender 5.2:Pimbo 的便携版位于
anymation/tools/blender;其他地方请设置$BLENDER或将blender加入 PATH。 - ffmpeg 位于 PATH。
- Python 以及 numpy 和 Pillow 库,用于运行工具。
Pimbo 不运行脚本:你负责运行脚本并向他展示结果。
不可违背的规则
- 先展示,后构建。 在创建新世界或新角色之前,先渲染2-3张静态图(
--frames ... --scale 0.5),让 Pimbo 选择。你自己也要先仔细查看每张图片,再展示给他看。 pose(f)是帧的纯函数。 帧与帧之间不携带状态,不使用未设定种子的随机数,每次周期性运动在循环内都是完整周期数。跨越循环边界的效果使用looped()。- 像动画师一样制作动画(
references/ANIMATION.md)。先写一个动作分镜表,然后使用带缓动函数的关键姿态。在每次动作前加入预备动作,在撞击时使用挤压、在快速运动时使用拉伸,在手臂上使用跟随重叠,以及单帧的眼球切换。永远不要线性地移动一个角色。 - 只有当 QA 测试通过(
make_loop.py输出 PASS/FAIL)且你已经逐帧检查过所有动作才算完成(参见下面的“条带图”)。 - 说明哪些是测量所得 [M]、哪些是目测所得 [V]、哪些是假设 [S]。
制作流程
| 步骤 | 内容 | 命令(在 kit/ 下执行) |
|---|---|---|
| 1 | 创意:地点、一个带有开头和循环回归的小故事;时长6-9秒 | 与 Pimbo 讨论 |
| 2 | 复制最接近的场景:loops/claude_isla(白天,户外)或 loops/claude_fogata(夜晚,道具,特效) | |
| 3 | 搭建场景、放置 Claude、设置灯光和相机;查看静态图 | python tools/make_loop.py <name> --frames 0 --scale 0.5 |
| 4 | 写下动作分镜表注释,然后创建 Track;渲染关键姿态 | python tools/make_loop.py <name> --frames 44,62,66,71,77,81 |
| 5 | 快速预览整个循环 | python tools/make_loop.py <name> --preview(每8帧取一帧) |
| 6 | 完整渲染 + GIF + MP4 + QA 测试 | python tools/make_loop.py <name> |
| 7 | 对每个动作生成条带图,修复问题,重新渲染 | 参见下面的“条带图” |
| 8 | 将完成文件复制到 anymation/toy3d/videos/<name>/ 并发送给 Pimbo |
在 Pimbo 电脑上的时间(RX 6800 XT)[M]:
- EEVEE: 每帧 1080x1080 大约 0.7 秒,因此一个 200 帧的循环大约需要 2.5 分钟。
- Cycles: 每帧大约 10 秒,效果几乎相同。仅用于静态图:
--engine cycles --samples 256在 2400x1200 分辨率下大约需要 20 秒。
条带图。 要逐帧查看某个动作:
ffmpeg -framerate 25 -start_number 56 -i out/<n>/frames/%04d.png -frames:v 30 -vf "crop=...,scale=260:-1,tile=6x5" -frames:v 1 strip.jpg
外观简介(详细内容和数值:references/LOOK.md)
- 玩具比例。 1 单位 = 1 米,Claude 宽度约为 9 厘米。真实的相机景深(70 毫米,f/4.5-7)本身就提供了微缩模型的模糊效果。
- 纸质。 每个实体都应用
paper(...):哑光颜色、纤维凹凸、柔和污点。倒角边缘自动获得白色边缘材质(box、prism、disc)。 - 色彩。 色调映射使用 AgX 并搭配 Punchy 风格。白天曝光度为 -1,夜晚约为 -0.35。
- 受光面:Claude 的受光面色彩接近参考资料(我们的 #DA8D6C,参考资料 #EC815B)。
- 亮度:白天帧的平均亮度为 120-140(参考资料为 91-181)。
- 灯光。 一个暖色主光,位置较高且在前方,使顶部比正面更亮。添加一个较弱的冷色补光和一个暖色边缘光。发光物体(火焰、星星、烟雾)使用
flame_mat和no_shadow。 - 相机。 在循环中保持静止(参考资料仅在剪辑或推进时移动相机)。
- GIF 使用正方形 1080 分辨率。
- 英雄图是宽画幅,使用
shift_x将主体推到画面三分之一处。
Claude 角色简介(references/CHARACTERS.md)
claude = Claude('claude', loc)
然后每帧调用:
claude.pose(s, hop, pitch, roll, yaw, arm_l, arm_r, eyes, eye_big, eye_look, loc)
- 眼睛:
sq、happy(^ ^)、line(- -)、squeeze(> <)、dot(. .)、sad。 - 道具: 手持道具父级设置为
claude.hand(side)。 - 挥手: 挥手的那只手必须是面向相机的那只。
网页作品:实时眼睛和 3D 模型
- 实时眼睛。
- 以
--eyes-off(和用于剪影的--transparent)渲染:python tools/make_loop.py claude_pose --transparent --eyes-off --tag _noeyes。运行器会隐藏眼睛并写入eyes.json:每只眼睛的像素中心和以像素每毫米表示的脸部轴线。 - 运行
python tools/web_eyes.py <noeyes.png> <eyes.json> <out_dir> --ink-from <render with eyes>。它会生成index.html和一个单文件<dir>_un_archivo.html。 - 页面的功能:
- 眼睛是在脸部平面上绘制的 SVG 形状,因此即使在倾斜的头部上也能保持正确的透视。
- 它们通过欠阻尼弹簧跟随指针,并且每 2.5-5.5 秒眨眼一次。
- 指针靠近时显示
^ ^,按下时显示> <。 - 点击时有挤压-拉伸的弹跳效果(使用
--hero时除外,该选项保持整张图片静止)。
- 已在 Chrome 中通过 Playwright 测试(指针左、右、上、下、接近、按下、释放):无控制台错误。
- 以
- 3D 模型。 运行
blender -b --factory-startup --python tools/claude_glb.py -- <out.glb> [--eyes sq]。它会生成一个约 27 KB 的 GLB 文件,宽约 9 厘米,已重新导入并检查过。 - 场景和
--eyes-off。 一个在构建时对 Claude 进行摆姿势的场景,必须在pose(f)内再次进行姿势设置;--eyes-off仅在那里生效(参见stills/director_hero)。
质量关卡(tools/qa_loop.py)
FAIL:
- 帧数错误。
- 存在接缝:从最后一帧到第一帧的变化大于正常帧间变化第 90 百分位数。
WARN:
- 存在连续相同的帧(静止帧)。
- 运动量小于平均亮度的 0.8%。测量所得 [M]:参考资料 r2/r3/r4 分别为 1.65/1.97/1.07%,
claude_isla为 0.89%,claude_fogata为 1.66%。
QA 无法评判审美、表演或构图。这些需要通过肉眼观察静态图和条带图来检查。
已知错误(references/KNOWN_ERRORS.md)
那些会导致重新渲染的错误:
- 手臂抬起超过约 70° 会隐藏到身体侧面。
- 高亮发光区域在 AgX 下会变为白色:请使用
flame_mat。 - 侧面主光会使正面变暗。
- 使用绝对灰度级别测量的夜景会显得“太安静”。
- 弧形背景太窄会露出其边缘。