Communitygithub.com

toy-loops

用纯Python和Blender打造无缝循环的3D纸艺立体模型动画和网页交互作品(如GIF、MP4、网页英雄图、Claude的眼睛跟随鼠标),遵循经典动画原则。

toy-loops 是什么?

toy-loops 是一个专注于创建纸艺立体模型风格3D动画和网页交互的技能,完全基于Python编写,在Blender中渲染,并严格遵循经典动画原则。它特别适合制作无缝循环的GIF和MP4动画、用于网页的英雄图(Hero Picture),以及具有交互性的网页作品,例如Claude的眼睛能跟随鼠标移动。该技能的核心在于使用纯函数式帧计算,确保循环完美闭合,并通过独特的白色倒角边缘、暖光和浅景深模拟微观世界效果。它支持Blender、Chrome和Playwright等平台,并提供了一整套工具链,包括循环渲染与编码、质量检测(QA)和网页眼睛生成,确保输出作品在视觉和动画原理上均达到专业水准。

兼容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/Pimboto/claude-skills/tree/HEAD/skills/toy-loops

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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.pyClaude:绑定及其六种眼睛设置;每帧调用一次 .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.pyClaude 模型导出为 .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 不运行脚本:你负责运行脚本并向他展示结果。

不可违背的规则

  1. 先展示,后构建。 在创建新世界或新角色之前,先渲染2-3张静态图(--frames ... --scale 0.5),让 Pimbo 选择。你自己也要先仔细查看每张图片,再展示给他看。
  2. pose(f) 是帧的纯函数。 帧与帧之间不携带状态,不使用未设定种子的随机数,每次周期性运动在循环内都是完整周期数。跨越循环边界的效果使用 looped()。
  3. 像动画师一样制作动画(references/ANIMATION.md)。先写一个动作分镜表,然后使用带缓动函数的关键姿态。在每次动作前加入预备动作,在撞击时使用挤压、在快速运动时使用拉伸,在手臂上使用跟随重叠,以及单帧的眼球切换。永远不要线性地移动一个角色。
  4. 只有当 QA 测试通过(make_loop.py 输出 PASS/FAIL)且你已经逐帧检查过所有动作才算完成(参见下面的“条带图”)。
  5. 说明哪些是测量所得 [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 模型

  • 实时眼睛。
    1. 以 --eyes-off(和用于剪影的 --transparent)渲染: python tools/make_loop.py claude_pose --transparent --eyes-off --tag _noeyes。运行器会隐藏眼睛并写入 eyes.json:每只眼睛的像素中心和以像素每毫米表示的脸部轴线。
    2. 运行 python tools/web_eyes.py <noeyes.png> <eyes.json> <out_dir> --ink-from <render with eyes>。它会生成 index.html 和一个单文件 <dir>_un_archivo.html。
    3. 页面的功能:
      • 眼睛是在脸部平面上绘制的 SVG 形状,因此即使在倾斜的头部上也能保持正确的透视。
      • 它们通过欠阻尼弹簧跟随指针,并且每 2.5-5.5 秒眨眼一次。
      • 指针靠近时显示 ^ ^,按下时显示 > <。
      • 点击时有挤压-拉伸的弹跳效果(使用 --hero 时除外,该选项保持整张图片静止)。
    4. 已在 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。
  • 侧面主光会使正面变暗。
  • 使用绝对灰度级别测量的夜景会显得“太安静”。
  • 弧形背景太窄会露出其边缘。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能