ComfyUI Extension: ComfyUI-AE-Animation

Authored by wallen0322

Created

Updated

49 stars

After Effects-style animation nodes for ComfyUI with timeline-based keyframe control, layer management, and real-time preview rendering. (Description by CC)

Custom Nodes (0)

    README

    🎬 ComfyUI AE Animation

    🎥 演示视频

    <div align="center">

    演示视频 - 点击观看

    👉 点击这里观看完整演示视频

    </div>

    ⚠️ 预览版说明：本项目目前为预览版本，功能正在持续开发中。后续会持续增加新功能和优化体验，欢迎反馈和建议！

    🙏 特别鸣谢

    特别感谢 Terry Jia (jtydhr88) 在项目开发过程中给予的宝贵帮助和关键思路指导！

    📝 更新日志

    🚀 V3.0 大版本更新（2025-12-09）

    🎮 新增 Camera图层交互

    • ✅ Camera图层可选择：选中Camera后，鼠标/键盘交互直接控制摄像机
    • ✅ 统一交互逻辑：Camera与普通图层操作一致（滚轮缩放/旋转，方向键移动）
    • ✅ 3D旋转后端同步：图层rotationX/Y/Z正确输出到最终渲染
    • ✅ 摄像机Z轴预览：推拉效果实时预览，前后端数据对齐
    • ✅ 前景跟随摄像机：camera-only模式下前景正确跟随摄像机XY/旋转

    🖼️ 新增 GPU渲染引擎

    • ✅ WebGPU加速：全新GPU渲染管线，大幅提升渲染性能
    • ✅ 全景背景渲染：独立Buffer管理，支持纹理重复
    • ✅ 实时预览同步：GPU预览与后端输出完全一致

    🎥 新增 三维摄像机系统

    • ✅ 完整摄像机参数：cam_pos_x/y/z、cam_yaw/pitch/roll、cam_fov
    • ✅ 透视投影算法：根据图层深度动态计算旋转效果
    • ✅ GPU/Canvas统一：两种渲染器行为完全一致
    • 📚 使用指南：三维摄像机使用指南

    🔧 架构重构

    • ✅ Vue 3重写：使用Composition API完全重构前端
    • ✅ 组件化架构：提高可维护性和可扩展性
    • ✅ 性能优化：渲染性能和交互响应大幅提升

    📋 项目简介

    ComfyUI AE Animation 是一个单节点版的 After Effects 风格时间轴编辑器，为 ComfyUI 提供强大的动画制作能力。

    ✨ 核心功能

    • 🎨 多图层管理：支持前景/背景图层管理，灵活组织动画元素
    • 🎯 关键帧动画：位置、缩放、旋转、透明度等属性关键帧动画
    • 🎥 三维摄像机：完整的 3D 摄像机系统，支持位置、旋转、FOV 控制，创建真实的透视效果
    • 🖌️ Mask 编辑：画笔工具创建自定义遮罩，精确控制图层显示区域
    • 📍 路径动画：贝塞尔路径工具创建平滑的运动轨迹
    • ✂️ AI Extract：智能背景提取，自动创建前景图层
    • 🎞️ 实时预览：Canvas 实时渲染预览，所见即所得
    • ⚙️ 参数控制：UI 内直接调整分辨率、FPS、总帧数等项目参数

    🚀 快速开始

    安装

    方式一：ComfyUI Manager（推荐）

    1. 打开 ComfyUI Manager
    2. 在搜索框中输入 ComfyUI-AE-Animation 或 AE Animation
    3. 点击安装
    4. 重启 ComfyUI

    方式二：Git Clone

    cd ComfyUI/custom_nodes
git clone https://github.com/wallen0322/ComfyUI-AE-Animation.git
# 重启 ComfyUI

    首次使用

    1. 启动节点

      • 重启 ComfyUI 后，右上角会出现 AE Timeline 按钮
      • 点击按钮会自动创建并选中 AE Animation 节点，并打开时间轴 UI
      • 或者直接在节点面板添加 AE Animation 节点，然后点击按钮打开 UI

    2. 设置项目参数

      • 在 UI 顶部直接输入 Width、Height、FPS、Frames
      • 点击 Save 按钮将参数同步回节点 widgets
      • 建议分辨率：1920×1080、1280×720 等标准尺寸

    3. 添加图层

      • 点击 +FG 添加前景图层（通过文件选择器选择本地图片）
      • 点击 +BG 添加背景图层
      • 或者通过节点输入端连接图像（自动识别为图层）

    4. 开始创作

      • 选择图层，调整 X、Y、Scale、Rotation、Opacity 等属性
      • 在时间轴上添加关键帧，创建动画
      • 使用工具进行 Mask、路径、Extract 等操作

    📖 详细使用说明

    🎛️ 界面布局

    顶部工具栏

    • 项目操作区（左侧）

      • Save Proj：保存工程文件（JSON 格式），包含所有图层、关键帧、Mask 等数据
      • Load Proj：加载之前保存的工程文件
      • Clear Cache：清理未使用图层的图片缓存，释放内存

    • 运行控制区（中间）

      • Refresh：刷新界面
      • ▶ Run Node：运行节点，生成动画序列
      • 保存到节点：将当前设置保存到节点 widgets

    • 图层操作区（右侧）

      • +FG：添加前景图层
      • +BG：添加背景图层
      • ✕：关闭时间轴 UI

    左侧属性面板（Inspector）

    图层信息卡片

    • 显示当前选中图层的名称和类型（FG/BG）
    • 显示图层资源状态（Image Asset / Empty Asset）

    变换属性（Transform）

    • X / Y：图层位置坐标（相对于画布中心）
    • Scale：缩放比例（1.0 = 100%，可调整到 0.1~10.0）
    • Rotate：旋转角度（0~360 度）
    • Opacity：透明度滑块（0~100%）

    工具区（Tools）

    • Mask：启用 Mask 画笔模式，在画布上涂抹创建遮罩
    • Erase：启用擦除模式，擦除 Mask 区域
    • Path：创建贝塞尔路径，生成路径动画
    • Extract：背景提取工具，从背景中提取区域创建新前景层

    画笔设置

    • Mask Brush：Mask 画笔大小（1~100px）
    • Extract Brush：Extract 画笔大小（1~100px）

    应用/清除

    • Apply：应用当前工具的效果
    • Clear：清除当前工具的效果

    中间画布区域（Viewport）

    顶部工具栏

    • 显示项目信息：宽度×高度 @ 帧率fps
    • 画布适配模式：
      • Fit：保持宽高比，完整显示（可能有黑边）
      • Fill：保持宽高比，填充画布（可能裁切）
      • Stretch：拉伸填充（可能变形）
    • 显示总时长：Duration 00:00:XX

    画布区域

    • 实时预览当前时间点的画面
    • 支持鼠标拖拽移动图层
    • 支持滚轮缩放图层
    • 显示网格背景，方便对齐

    底部时间轴（Timeline）

    顶部控制栏

    • 关键帧操作（左侧）

      • + Key：在当前时间点添加关键帧
      • Del Key：删除当前时间点的关键帧
      • Clear All：清除当前图层所有关键帧

    • 播放控制（中间）

      • 时间显示：00:00:XX（当前播放时间）
      • ⏮：跳转到开始（时间 = 0）
      • ▶ / ❚❚：播放/暂停（空格键快捷键）
      • 时间滑块：拖拽调整当前时间

    • 缩放控制（右侧）

      • Zoom：时间轴缩放滑块，调整时间轴显示范围

    图层列表（左侧）

    • 显示所有图层，按顺序排列
    • 点击图层名称选中图层
    • ▸ / ▾：展开/折叠图层详细信息
    • 👁：显示/隐藏图层
    • 🔒：锁定/解锁图层
    • 图层类型标识：B（Background）或 F（Foreground）

    时间轨道（右侧）

    • 显示时间标尺（0s, 1s, 2s...）
    • 每个图层对应一条轨道
    • 轨道上的彩色条表示图层在时间轴上的存在范围
    • 关键帧标记：◆ 菱形标记表示关键帧位置
    • 播放头：红色竖线表示当前播放时间

    🎨 详细操作指南

    1. 画布交互操作

    基础图层操作 | 操作 | 效果 | |------|------| | 鼠标左键拖拽 | 移动图层位置（X/Y） | | 方向键 ←→↑↓ | 微调图层位置（步进 1px） | | Shift + 方向键 | 快速移动（步进 10px） | | Ctrl + ↑↓ | 调整图层 Z 轴深度（步进 10） | | R 键 | 重置图层变换（位置、缩放、旋转、透明度） |

    滚轮变换操作（需选中图层） | 操作 | 效果 | |------|------| | 滚轮 | 缩放图层（Scale） | | Shift + 滚轮 | X 轴旋转（RotationX，3D 翻转效果） | | Ctrl + 滚轮 | Y 轴旋转（RotationY，3D 翻转效果） | | Alt + 滚轮 | Z 轴旋转（RotationZ，平面旋转） | | Ctrl + Shift + 滚轮 | 调整 Z 轴位置（深度） |

    3D 摄像机模式（启用 Camera，未启用 Pano） | 操作 | 效果 | |------|------| | 左键拖拽（无选中图层） | 摄像机轨道旋转（Yaw/Pitch） | | Shift + 左键拖拽 | 摄像机滚转（Roll） | | 中键拖拽 | 摄像机平移（Pos X/Y） | | 右键拖拽 | 摄像机推拉（Pos Z） | | 滚轮（无选中图层） | 摄像机推拉（Pos Z） |

    全景模式（启用 Pano） | 操作 | 效果 | |------|------| | 中键/右键拖拽 | 全景旋转（Yaw/Pitch） | | 左键拖拽（无选中图层或 Alt） | 平移偏移（Offset X/Y） | | 滚轮（无选中图层） | 调整视野角度（FOV） |

    工具模式操作（Mask/Extract） | 操作 | 效果 | |------|------| | 左键拖拽 | 绘制区域 | | Shift + 左键 | 擦除区域 | | 右键拖拽 | 擦除区域 | | Alt + 左键 | 擦除区域 |

    2. 图层管理

    添加图层

    • 点击顶部 +FG 或 +BG 按钮
    • 在文件选择器中选择图片文件
    • 图片会自动压缩到项目分辨率，优化性能

    选择图层

    • 在时间轴左侧图层列表中点击图层名称
    • 或使用下拉菜单选择图层
    • 选中后，左侧属性面板会显示该图层的属性

    调整图层属性

    • 在左侧属性面板的 Transform 区域直接输入数值
    • 或在画布上直接拖拽图层（调整 X、Y）
    • 使用滚轮缩放图层（调整 Scale）
    • 使用修饰键 + 滚轮调整旋转（见上方交互表格）

    图层排序

    • 在时间轴图层列表中使用 ▲ / ▼ 按钮调整图层顺序
    • 图层顺序影响渲染顺序（上层覆盖下层）

    删除图层

    • 在图层列表中点击删除按钮（如果可用）
    • 或通过节点输入端断开连接

    3. 关键帧动画

    添加关键帧

    1. 在时间轴上拖拽播放头到目标时间点
    2. 选择要动画的图层
    3. 调整图层属性（X、Y、Scale、Rotate、Opacity）
    4. 点击 + Key 按钮添加关键帧
    5. 重复步骤 1-4，在不同时间点添加关键帧

    编辑关键帧

    • 点击时间轴上的关键帧标记（◆）选中关键帧
    • 调整图层属性，关键帧会自动更新
    • 或直接拖拽关键帧标记调整时间位置

    删除关键帧

    • 点击时间轴上的关键帧标记
    • 点击 Del Key 按钮删除
    • 或点击 Clear All 清除所有关键帧

    播放预览

    • 点击 ▶ 按钮开始播放
    • 点击 ❚❚ 暂停播放
    • 使用空格键快速播放/暂停
    • 拖拽时间滑块手动调整时间

    4. Mask 遮罩功能

    创建 Mask

    1. 选择前景图层
    2. 点击 Mask 工具按钮
    3. 调整 Mask Brush 画笔大小
    4. 在画布上涂抹要遮罩的区域
      • 白色区域：不透明（显示）
      • 黑色区域：透明（隐藏）
    5. 点击 Apply 应用 Mask

    编辑 Mask

    • 继续涂抹添加遮罩区域
    • 按住 Shift 键或右键擦除遮罩区域
    • 调整画笔大小适应不同区域

    清除 Mask

    • 点击 Clear 按钮清除当前图层的 Mask

    5. 路径动画

    创建路径

    1. 选择要动画的图层
    2. 点击 Path 工具按钮
    3. 在画布上依次点击 4 个点：
      • 起点
      • 控制点 1
      • 控制点 2
      • 终点
    4. 拖动控制点调整路径形状
    5. 点击 Apply 生成路径关键帧动画

    编辑路径

    • 拖动路径上的控制点调整形状
    • 路径会自动更新关键帧

    6. Extract 背景提取

    提取背景区域

    1. 确保已加载背景图层
    2. 点击 Extract 工具按钮
    3. 调整 Extract Brush 画笔大小
    4. 在背景上涂抹要提取的区域
      • 按住 Shift 键或右键擦除错误涂抹
    5. 点击 Apply 应用提取

    提取效果

    • 背景的选中区域会自动应用模糊效果
    • 选中的内容会创建为新的前景图层（命名为 extracted_X）
    • 新图层可以独立调整位置、缩放、旋转等属性
    • 可以添加关键帧实现动画效果
    • 支持多次提取创建多个图层

    应用场景

    • 人物抠图后对原背景进行背景虚化
    • 提取背景的某个元素单独动画
    • 创建景深效果（前景清晰，背景模糊）

    7. 三维摄像机（新功能）

    启用摄像机

    1. 在项目设置面板中找到 "🎥 3D 摄像机" 部分
    2. 勾选 "启用" 复选框
    3. 摄像机参数立即生效

    摄像机参数

    • 位置
      • X：水平位置（左右移动）
      • Y：垂直位置（上下移动）
      • Z (距离)：摄像机与场景的距离（默认 1000）
    • 旋转
      • Yaw (Y轴)：左右旋转（水平旋转）
      • Pitch (X轴)：上下旋转（俯仰）
      • Roll (Z轴)：滚转（画面倾斜）
    • 投影
      • FOV：视野角度（1°-179°，默认 90°）

    创建 3D 效果

    1. 为不同图层设置不同的 Z 值
      • 前景图层：Z = -200 到 200
      • 中景图层：Z = 0
      • 背景图层：Z = 200 到 500
    2. 调整摄像机旋转参数观察透视效果
    3. 添加关键帧创建摄像机动画

    应用场景

    • 视差滚动效果
    • 摄像机推拉镜头
    • 环绕旋转动画
    • 景深效果

    📚 详细指南：查看 三维摄像机使用指南

    ⚠️ 预览说明：

    • UI预览使用2D近似，仅供参考
    • 最终渲染使用完整3D透视投影
    • 全景模式需要启用摄像机
    • 详见 3D预览限制说明

    8. 画布操作

    缩放画布

    • 使用右上角的 Zoom 滑块（25%~200%）
    • 适合处理竖屏分辨率，避免裁切

    适配模式

    • Fit：保持宽高比，完整显示（推荐用于预览）
    • Fill：保持宽高比，填充画布（推荐用于导出）
    • Stretch：拉伸填充（可能变形，不推荐）

    拖拽图层

    • 在画布上直接拖拽图层调整位置
    • 实时更新 X、Y 属性值

    缩放图层

    • 使用鼠标滚轮缩放图层
    • 实时更新 Scale 属性值

    🔧 节点说明

    AE Animation 节点

    输入参数（可在 UI 顶部调节，同步回节点）

    • width：项目宽度（像素）
    • height：项目高度（像素）
    • fps：帧率（1~120）
    • total_frames：总帧数

    隐藏参数（UI 内部使用，保留但不显示）

    • mask_expansion：Mask 扩展/收缩（-10~10）
    • mask_feather：Mask 羽化（0~20）
    • layers_keyframes：图层和关键帧数据（JSON）
    • start_frame：开始帧
    • end_frame：结束帧

    输入连接

    • background_image：背景图片（可选）
    • foreground_images：前景图片（可选，支持批量输入）

    输出

    • frames：渲染的图像序列（IMAGE 类型）
    • mask_frames：前景遮罩序列（MASK 类型）

    💾 数据管理

    保存工程

    • 点击 Save Proj 按钮
    • 选择保存位置，输入文件名
    • 工程文件包含：
      • 所有图层信息（名称、类型、属性）
      • 所有关键帧数据
      • Mask 数据
      • 路径数据
      • Extract 图层数据
      • 项目参数（分辨率、FPS、总帧数）

    加载工程

    • 点击 Load Proj 按钮
    • 选择之前保存的工程文件
    • 所有数据会自动恢复

    保存到节点

    • 点击 保存到节点 按钮
    • 当前设置会写回节点 widgets
    • 工作流保存后，重新加载会恢复节点状态

    ⚡ 性能优化

    自动优化

    • 图片压缩：导入的图片自动压缩到项目分辨率
    • 懒加载：图片按需加载，避免浏览器崩溃
    • 预览限制：预览画布最大 1920×1080，大分辨率项目保持流畅

    手动优化

    • 清理缓存：点击 Clear Cache 释放未使用图层的图片内存
    • 减少图层数量：删除不需要的图层
    • 降低预览分辨率：在 UI 中设置较小的分辨率进行预览

    ⌨️ 快捷键速查

    | 快捷键 | 功能 | |--------|------| | 空格键 | 播放/暂停动画 | | 方向键 | 移动图层位置 | | Shift + 方向键 | 快速移动（10px） | | Ctrl + ↑↓ | 调整 Z 轴深度 | | 滚轮 | 缩放图层 | | Shift + 滚轮 | X 轴旋转 | | Ctrl + 滚轮 | Y 轴旋转 | | Alt + 滚轮 | Z 轴旋转 | | R 键 | 重置图层变换 | | Delete/Backspace | 删除图层 |

    📖 完整交互操作说明请参考 详细操作指南 - 画布交互操作

    🐛 已知问题与注意事项

    注意事项

    1. 项目尺寸：建议在 UI 内调整分辨率，预览限制 1920×1080，导出使用实际分辨率
    2. 图层数量：前景图层数量 = 节点输入的前景图片 + Extract 创建的图层 + 本地导入图层
    3. Mask 分辨率：Mask 会自动缩放到图层原始尺寸
    4. Extract 图层：创建后会自动缩放到项目尺寸，scale=1 即为全屏显示
    5. 内存管理：大量图层时使用清理缓存功能释放内存
    6. 外部图层：通过节点输入口连接的 foreground_images 会自动显示在 UI 中

    预览版限制

    • 部分功能可能仍在开发中
    • UI 和交互可能会持续优化
    • 性能优化会持续改进
    • 欢迎反馈问题和建议

    🛠️ 开发/构建

    前端开发

    前端位于 frontend/ 目录，使用 Vue 3 + Vite 构建：

    cd frontend
npm install
npm run dev    # 开发模式
npm run build  # 构建生产版本

    构建产物输出到 js/vue-dist/ 目录。

    项目结构

    ComfyUI-AE-Animation/
├── frontend/              # Vue 3 前端源码
│   ├── src/
│   │   ├── TimelineApp.vue    # 主应用组件
│   │   └── components/        # 子组件
│   └── package.json
├── js/
│   └── vue-dist/          # 构建产物（已编译）
├── ae_animation_core.py   # 核心节点逻辑
└── __init__.py            # ComfyUI 节点注册

    静态目录 WEB_DIRECTORY=./js，前端脚本/样式通过 /extensions/ComfyUI-AE-Animation/vue-dist/... 提供。

    📄 许可证

    Apache License 2.0

    👤 作者

    wallen0322

    🤝 贡献

    欢迎提交 Issue 和 Pull Request！

    享受动效创作的乐趣！ 🎬✨