wiggle

Wiggle Logo Animator

使用 Lottie JSON 格式创建专业的 Logo 动画。导入现有 Logo（PNG/SVG/JPG）或生成简单的文字 Logo，然后使用精心设计的动效模式为其添加动画。输出包括 Lottie JSON、自动渲染的 GIF 预览，以及可选的 MP4 导出。

何时使用此技能

当用户提出以下需求时，触发此技能：

• “为我的 Logo 添加动画”／“创建 Logo 动画”
• “让我的 Logo 摇摆／弹跳／旋转／脉动”
• “为我的 Logo 添加动态波形效果”
• “为我的品牌 Logo 制作动态图形”
• “为我的品牌制作 Lottie 动画”
• Logo 入场、循环或加载动画
• 对提供的 Logo 图像应用任何动画效果

重要： 此技能输出独立的动画文件（Lottie JSON、GIF、MP4），而非交互式 React/HTML 产物。如果用户需要交互式工具或网页组件，请转交给 artifacts-builder 技能。

---

核心工作流程

1. 明确动效理念（30 秒 - 必须！）

创建任何动画之前，先回答以下三个问题：

1. 这个品牌具有什么个性？ （活泼、专业、大胆、优雅、创新、值得信赖）

2. 动画应营造什么情绪？ （兴奋、信任、创意、自信、好奇）

3. 什么动效隐喻最合适？ （自然生长、机械精准、能量迸发、优雅呈现、节奏脉动）

示例： “Canva = 创意工具品牌 → 活泼的能量 + 自然生长 → 同步入场并伴随脉动”

有关详细框架，请参阅下方的动画理念部分。

---

2. 分析 Logo 结构（30 秒 - 必须！）

创建动画之前，先了解要处理的内容：

# For SVG logos - identify elements
python scripts/extract_svg_elements.py logo.svg --list

快速决策树：

Logo has text?
  ├─ YES → Read references/text_animation_guide.md FIRST
  └─ NO  → Continue with standard workflow

Multiple elements (icon + text)?
  ├─ YES → Extract separately, decide timing (simultaneous vs staggered)
  └─ NO  → Animate as single unit

SVG or PNG?
  ├─ SVG → Can extract elements cleanly
  └─ PNG → Limited to single-logo animations

---

3. 准备素材

# Single logo (simple animation)
python scripts/prepare_logo.py logo.png --max-size 500 --optimize
# Creates: logo_optimized.png (30-50KB) + logo_base64.txt

# Multi-element logo (extract FIRST, then convert)
python scripts/extract_svg_elements.py logo.svg --output-dir ./elements/
python scripts/prepare_logo.py elements/icon.svg --max-size 200
python scripts/prepare_logo.py elements/text.svg --max-size 250

尺寸指南：

• 完整 Logo（单个）：500-600px
• 图标元素：100-200px
• 文字元素：200-300px

---

4. 创建 Lottie JSON 动画

开发期间使用外部引用：

{
  "v": "5.7.4",
  "fr": 60,
  "ip": 0,
  "op": 180,
  "w": 800,
  "h": 800,
  "layers": [{
    "ind": 1,
    "ty": 2,
    "nm": "Logo",
    "refId": "logo_image",
    "ks": {
      "o": {
        "a": 1,
        "k": [
          {"t": 0, "s": [0], "e": [100], "i": {"x": [0.42], "y": [1]}, "o": {"x": [0.58], "y": [0]}},
          {"t": 60, "s": [100]}
        ]
      }
    }
  }],
  "assets": [{"id": "logo_image", "w": 512, "h": 512, "p": "logo_optimized.png", "e": 0}]
}

关键： 开发期间使用 "e": 0（外部引用），以避免 Cairo 内存错误。

常见效果请参阅下方的动画模式速查，完整代码示例请参阅 references/detailed_examples.md。

---

5. 验证

# Check Lottie structure (warns about large embedded assets)
python scripts/validate_lottie.py logo_animation.json

# Check loop quality (if creating looping animation)
python scripts/validate_loop.py logo_animation.json

---

6. 渲染

# RECOMMENDED: Preview first (renders only first N frames) - saves time!
python scripts/render_lottie.py logo_animation.json preview.gif --preview-frames 60

# Alternative: Test render mode (200x200, 15fps with confirmation prompt)
python scripts/render_lottie.py logo_animation.json logo.gif --test-render

# If preview looks good → Render full animation
python scripts/render_lottie.py logo_animation.json logo.gif

# Optional: MP4 export (better compression than GIF)
python scripts/render_lottie.py logo_animation.json logo.mp4

# Optional: Batch export all formats
python scripts/batch_export.py logo_animation.json ./output gif,mp4,json

重要说明：

• 资源会根据 Lottie JSON 文件的位置解析（而非当前工作目录）
• 渲染前会自动进行资源验证
• 输出验证会检测空白或损坏的文件
• 使用 --preview-frames N 仅渲染前 N 帧，以便快速验证

---

7. 可选：为分发进行嵌入

成功渲染后，可选地将资源转换为嵌入式 base64，以便独立分发：

// Replace external reference with base64 from logo_base64.txt
"assets": [{"id": "logo_image", "p": "data:image/png;base64,...", "e": 1}]

注意： 保留外部版本，以便后续编辑和渲染！

---

动画理念

两阶段方法

阶段 1：明确理念（实现前先思考）

1. 这个品牌具有什么个性？
2. 动画应营造什么情绪？
3. 什么动效隐喻最合适？

阶段 2：通过技术选择来表达

• 选择属性来表达理念（位置／缩放／旋转／不透明度）
• 选择缓动以匹配品牌个性（缓出 = 自信，弹跳 = 活泼）
• 设置时序以契合情绪（快速 = 有活力，缓慢 = 优雅）

理念示例

“自信而专业”

• 理念：值得信赖、成熟稳健、胜任可靠
• 表现：缓慢的缓出淡入（不透明度 0→100%）＋轻柔缩放（95%→100%）
• 时间：持续 2s，不使用过冲
• 示例：references/real-world-examples/slack-hover-pinch.json

“活泼有活力”

• 理念：有趣、亲切、令人难忘
• 表现：带过冲的弹跳入场
• 时间：持续 1s，使用回弹缓动（0.6/-0.28）
• 示例：references/real-world-examples/reddit-hover-pinch.json

“音频／语音品牌”

• 理念：声音、节奏、波形、动感
• 表现：垂直波形，使用密集关键帧（30-45 个关键帧，60fps）
• 时间：循环 3s，使用自然缓动（0.25/0.75）
• **关键：**请参阅下文“运动类型”部分中的“自然／连续运动”

更多示例见 references/preset_library.md 和 references/animation_theory.md。

---

运动类型速查

根据品牌个性选择运动类型：

静态／企业风格运动

专业品牌（B2B、金融、法律）

参数：

• 关键帧：8-12 个（稀疏、审慎）
• 缓动：0.42/0.58（标准缓入缓出）
• FPS：30
• 时长：1.5-2s

**适用场景：**企业标志、B2B 品牌、专业演示

---

自然／连续运动

音频、音乐、语音 AI、自然品牌

参数：

• 关键帧：25-45 个 ← 流畅度的关键
• 缓动：0.25/0.75（更柔和、更自然）
• FPS：60 ← 流畅度的必要条件
• 时长：3s

**适用场景：**音频应用、音乐平台、语音 AI、天然产品

示例：references/detailed_examples.md 中的垂直条形波形模式

---

大胆／吸引注意力

初创公司、社交媒体、营销

参数：

• 关键帧：15-25 个
• 缓动：0.34/1.56（俏皮弹跳）或 0.6/-0.28（回弹过冲）
• FPS：60
• 时长：0.8-1.5s

**适用场景：**初创公司标志、社交媒体片头、营销活动

---

电影感／复杂运动

高端品牌、电影制作

参数：

• 关键帧：50-120 个
• 缓动：自定义贝塞尔曲线、可变时间
• FPS：60-120
• 时长：3-5s

**适用场景：**奢侈品牌、电影片头、高端代理商作品

---

动画模式速查

单元素模式

模式	时长	属性	使用场景
淡入＋轻柔缩放	1.5s	不透明度：0→100%，缩放：95→100%	企业风格入场
弹跳入场	1.2s	位置、缩放、不透明度	活力品牌
缩放脉冲	循环 3s	缩放：100→103→100%	空闲状态、CTA
平滑旋转	循环 10s	旋转：0→360°	加载动画、科技标志
摇摆／果冻	0.8s	旋转：±5° 振荡	俏皮通知

完整代码示例：references/detailed_examples.md

---

多元素协调

模式 1：同时入场 两个元素一同出现（品牌协调一致）

Icon: {"t": 0, "s": [0]}, {"t": 60, "s": [100]}
Text: {"t": 0, "s": [0]}, {"t": 60, "s": [100]}
// Both start at t:0 → Synchronized

模式 2：错开入场 先呈现图标，再由文本强化表达（讲述故事）

Icon: {"t": 0, "s": [0]}, {"t": 45, "s": [100]}
Text: {"t": 30, "s": [0]}, {"t": 75, "s": [100]}
// Text delayed 30 frames (0.5s at 60fps)

时间指南：

• 15 帧（0.25s）：轻微错开
• 30 帧（0.5s）：序列感明显 ← 最常见
• 45 帧（0.75s）：戏剧性的两段式揭示

完整模式：references/detailed_examples.md#multi-element-coordination

---

用户意图分类

始终对用户意图进行分类，以选择合适的动画风格：

意图	关键帧	缓动	FPS	时长	动效
含蓄/专业	8-12	0.42/0.58	30	1.5-2s	缓慢、可控、尽量少旋转
醒目/吸睛	15-25	0.34/1.56	60	0.8-1.5s	中快速、动态、缩放 ±10-20%
活泼/创意	12-20	0.34/1.56	30-60	1-2s	弹跳、夸张、摆动效果
自然/连续	25-45	0.25/0.75	60	3s	波形、脉冲、流畅节奏

默认： 提供动画，而不是提问，除非用户明确要求提供选项。

---

已知限制

资源路径解析

当前行为：

• 外部资源（PNG/SVG）的解析路径相对于 Lottie JSON 文件所在位置
• 渲染器会在渲染期间将工作目录切换到 JSON 文件所在目录
• 渲染开始前会自动运行资源验证

示例：

project/
├── animations/
│   └── logo_animation.json  (references "logo_optimized.png")
└── logo_optimized.png

# This will FAIL - asset not found

解决方案： 将资源放在与 JSON 文件相同的目录中：

project/animations/
├── logo_animation.json
└── logo_optimized.png  # ✅ Correct location

嵌入式 Base64 与外部引用

嵌入式 Base64（"e": 1）：

• 优点： 独立文件，易于分发
• 缺点： 大于 100KB 的图像会导致 Cairo MemoryError、文件较大、无法编辑

外部引用（"e": 0）：

• 优点： 不会出现内存问题、JSON 文件较小、易于更新资源
• 缺点： 需要将资源文件与 JSON 一起保存

推荐工作流：

1. 开发/渲染期间使用外部引用
2. 渲染成功后，可选择嵌入 Base64 以便分发
3. 保留外部引用版本，以便将来编辑

---

重要警告

❌ 应避免的常见错误

1. 未先确定设计理念就创建动画 → 随机反复尝试会浪费 15-30 分钟
2. 使用 PIL ImageDraw 重新绘制 Logo 文字 → 生成的是不同的文字，并非 Logo 中的文字
3. 渲染前嵌入 Base64 → 导致 Cairo MemoryError 崩溃（图像大于 100KB）
4. 为小元素使用 1000px → 文件过大（400KB+），还会出现内存问题
5. 跳过 Logo 分析 → 工作流有误，必须重来
6. 忘记验证循环 → 动画循环时会出现明显跳变
7. 跳过预览渲染 → 未验证方案前就进行完整渲染，浪费时间
8. 先渲染完整 SVG 再裁剪 → 边缘模糊，文件过大

完整列表及代码示例： references/anti_patterns.md

---

⚠️ Logo 中的文字——重要

如果 Logo 中包含文字，必须遵循专门的工作流：

1. 从 Logo SVG 提取文字（不要使用 PIL ImageDraw 重新绘制）
2. 选择合适的文字动画方法（淡入/描边/变换）
3. 与其他元素正确同步

参见： references/text_animation_guide.md，了解完整指南

---

⚠️ 必须使用外部引用

开发/渲染期间始终使用外部文件引用：

// ✅ CORRECT: External reference
"assets": [{"id": "logo", "p": "logo_optimized.png", "e": 0}]

// ❌ WRONG: Embedded base64 (causes Cairo crash if >100KB)
"assets": [{"id": "logo", "p": "data:image/png;base64,...", "e": 1}]

原因： 嵌入超过 100KB 的图像会导致 Cairo 渲染器崩溃。开发期间请使用外部引用；渲染成功后，可选择嵌入资源。

---

辅助脚本速查表

脚本	用途	示例
prepare_logo.py	优化并转换徽标图像	python scripts/prepare_logo.py logo.png --max-size 500
extract_svg_elements.py	从 SVG 中提取元素	python scripts/extract_svg_elements.py logo.svg --list
validate_lottie.py	检查 Lottie 结构	python scripts/validate_lottie.py animation.json
validate_loop.py	验证循环是否完美	python scripts/validate_loop.py animation.json
render_lottie.py	渲染为 GIF/MP4（含资源验证）	python scripts/render_lottie.py animation.json output.gif
render_lottie.py --preview-frames N	快速预览（前 N 帧）	python scripts/render_lottie.py animation.json preview.gif --preview-frames 60
render_lottie.py --test-render	测试模式，显示尺寸警告	python scripts/render_lottie.py animation.json test.gif --test-render
batch_export.py	导出多种格式	python scripts/batch_export.py animation.json ./output gif,mp4

render_lottie.py 的新功能：

• ✅ 自动验证资源（检查是否缺少外部文件）
• ✅ 解析资源路径（相对于 JSON 文件所在位置）
• ✅ 验证输出（检测空白或损坏的文件）
• ✅ 预览模式（--preview-frames N）——仅渲染前 N 帧
• ✅ 测试模式（--test-render）——小尺寸测试渲染，并提示确认

详细用法： references/script_usage.md

---

Lottie JSON 基础知识

基本结构

{
  "v": "5.7.4",           // Lottie version
  "fr": 60,               // Frame rate
  "ip": 0,                // In point (start frame)
  "op": 180,              // Out point (end frame)
  "w": 800,               // Width
  "h": 800,               // Height
  "layers": [...],        // Animation layers
  "assets": [...]         // Image/asset references
}

图层类型

• 类型 2（图像图层）： 最常见——为 PNG/SVG 图像制作动画
• 类型 4（形状图层）： 程序化几何图形（圆形、矩形、路径）

动画属性

• o： 不透明度（0-100）
• p： 位置 [x, y]
• s： 缩放 [x%, y%]
• r： 旋转（度）
• a： 锚点 [x, y]

关键帧结构

"o": {
  "a": 1,  // Animated (1) or static (0)
  "k": [
    {"t": 0, "s": [0], "e": [100], "i": {...}, "o": {...}},
    {"t": 60, "s": [100]}
  ]
}

• t： 时间（帧编号）
• s： 起始值
• e： 结束值
• i： 入切线（缓入）
• o： 出切线（缓出）

完整规范： references/lottie_spec.md

---

缓动函数

切勿使用线性缓动——专业动画始终使用曲线。

缓动	值	感觉	使用场景
缓入缓出（标准）	0.42/0.58	平衡、专业	企业、通用场景
自然	0.25/0.75	柔和、自然	音频品牌、波形、连续运动
弹跳	0.34/1.56	活泼、有活力	初创公司、活泼的品牌
回弹	0.6/-0.28 & 0.735/0.045	超调、动态	大胆营销、吸引注意力

原理与示例： references/animation_theory.md

---

依赖项

必需

pip install lottie[all]    # Lottie manipulation
pip install Pillow         # Image processing
pip install pycairo        # Cairo rendering (for GIF)

Cairo 安装

macOS：

brew install cairo pkg-config
pip install pycairo

Linux（Ubuntu/Debian）：

sudo apt-get install libcairo2-dev pkg-config python3-dev
pip install pycairo

验证：

python3 -c "import cairo; print('Cairo OK')"

故障排除： references/troubleshooting.md#cairo-and-dependencies

---

故障排除

快速修复

找不到资源错误：

• 原因： 资源与 Lottie JSON 不在同一目录中
• 修复： 将资源移至 JSON 文件所在目录，或使用绝对路径
• 验证： 运行 render_lottie.py——它会在渲染前验证资源

输出空白或损坏：

• 原因： 缺少资源、路径错误或渲染出错
• 修复： 检查资源验证消息，确认文件大小（输出小于 1KB 表示失败）
• 检测： 渲染后会自动验证输出

渲染 GIF 时出现 MemoryError：

• 原因： 嵌入的 base64 图像大于 100KB
• 修复： 改用外部引用（"e": 0）

循环有明显跳变：

• 原因： 最后一帧关键帧与第一帧不匹配
• 修复： 运行 validate_loop.py，并确保最后一帧 = 第一帧

文本显示异常：

• 原因： 使用 PIL ImageDraw 重新绘制文本
• 修复： 使用 extract_svg_elements.py 从 logo SVG 中提取文本

动画过于卡顿：

• 原因： 关键帧过少或 FPS 不合适
• 修复： 增加关键帧（自然动作使用 25-45 个），连续动作使用 60fps

预览渲染可节省时间：

• 提示： 使用 --preview-frames 60，在完整渲染前验证构想
• 提示： 使用 --test-render 进行交互式测试并查看大小警告

完整指南： references/troubleshooting.md

---

高级参考资料

详细文档

• references/detailed_examples.md - 所有模式的完整 Lottie JSON 代码
• references/animation_theory.md - 动效设计原则与缓动理论
• references/preset_library.md - 完整预设合集及实际案例
• references/lottie_spec.md - Lottie JSON 规范详情
• references/script_usage.md - 完整脚本文档
• references/text_animation_guide.md - 专用文本动画工作流
• references/anti_patterns.md - 常见错误及完整代码示例
• references/troubleshooting.md - 完整故障排除指南
• references/real-world-examples/ - 知名品牌的生产环境动画

---

文件大小指南

不同使用场景的目标大小：

使用场景	Lottie JSON	GIF	MP4	图像资源
电子邮件签名	20-50KB	500KB-1MB	200-500KB	每个 <30KB
网站主视觉	30-80KB	1-3MB	500KB-1.5MB	每个 <50KB
社交媒体	50-150KB	3-8MB	1-3MB	每个 <80KB
启动画面	30-100KB	2-5MB	800KB-2MB	每个 <60KB

优化： 使用 scripts/optimize_lottie.py 删除冗余关键帧并对数值进行舍入，以减小文件大小。

---

精选预设

常见预设速查（完整代码见 references/preset_library.md）：

品牌风格：

• 企业沉稳风格 - 淡入 + 轻柔缩放（1.5s）
• 初创活力风格 - 弹跳 + 超调（1.2s）
• 奢华优雅风格 - 缓慢淡入 + 极小幅度缩放（3s）
• 科技故障风格 - 数字干扰效果（1s）

使用场景：

• 网站主视觉 - 快速、专业地登场（0.8s）
• 电子邮件签名 - 微妙循环（3s）
• 社交媒体片头 - 醒目登场（2s）
• 启动画面 - 品牌亮相后退出（2.5s）

实际案例： 在 references/real-world-examples/ 中学习知名品牌的悬停动画：

• Reddit - 俏皮的弹性弹跳
• Slack - 专业克制的挤压效果
• Medium - 柔和的编辑式淡入
• Flickr - 相机快门效果
• Discord - 角色眨眼

---

快速决策清单

创建动画前，请确认：

• 已定义动态理念（个性 + 情绪 + 隐喻）
• 已分析 Logo 结构（文本？多元素？SVG 还是 PNG？）
• 已根据分析选择正确的工作流
• 如果包含文本：已阅读 references/text_animation_guide.md
• 开发期间使用外部引用（"e": 0）
• 元素尺寸合适（完整 Logo 为 500px，单个元素为 100-250px）
• 已选择动态类型（静态/有机/大胆/电影感）
• 已选择时间安排策略（同时播放还是错开播放）
• 将在完整渲染前通过预览渲染进行验证
• 如果创建循环，将运行 validate_loop.py

如果全部勾选 → 放心继续 ✅

---

成功技巧

1. 先明确理念 - 规划 30 秒，可节省 15-30 分钟的反复调整
2. 先分析再制作动画 - 提前了解 Logo 结构
3. 尽早预览，频繁预览 - 完整渲染前，先测试 30-60 帧的版本
4. 开发期间使用外部引用 - 成功渲染后再嵌入 base64
5. 让动态效果契合品牌 - 企业品牌 ≠ 初创公司 ≠ 音频品牌
6. 完美循环很重要 - 使用 validate_loop.py 进行验证
7. 为元素设置合适的尺寸 - 元素应为 100-250px，而不是 1000px
8. 提取，不要重建 - 绝不要使用 PIL 重建 Logo 文本
9. 渲染前进行验证 - 运行 validate_lottie.py 和 validate_loop.py
10. 遇到困难时查阅参考资料 - 每个主题都有详细文档

---

请记住： 目标是通过动态效果强化品牌形象，而不是随意制作动画。理念优先的工作流能够从一开始就确保方向一致。