Extensions/ComfyUI-AE-Animation

ComfyUI Extension

ComfyUI-AE-Animation

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

By wallen0322·Created 9 months ago·Updated 7 months ago· 58

wallen0322/ComfyUI-AE-Animation

Nodes1

On cloudLocal install

CategoryAE Animation

Stars58

Updated7 months ago

Nodes (1)

AE Animation

Readme

🎬 ComfyUI AE Animation

🎥 演示视频

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

</div>

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

🙏 特别鸣谢

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

📝 更新日志

🆕 最新更新 (2025-12-25)

🐛 问题修复

✅ 修复 Mask/Extract 模式下鼠标跟随错位问题
✅ 修复 Stretch 模式渲染错误
✅ 修复 3D 旋转顺序注释错误
✅ 修复 TypeScript 类型错误
✅ 统一边界条件处理机制
✅ 提取公共工具函数优化代码质量

🔧 代码优化

✅ 新增 numberUtil.ts 工具库，统一数值处理
✅ 优化前后端逻辑一致性
✅ 改进 GPU 渲染器性能

🆕 最新更新 (2025-12-09)

✨ 新增功能

✅ 移除背景功能：在 UI 中直接调用 rembg 库移除前景图层的背景，支持多种模型（u2net、u2netp、silueta、isnet-general-use 等），实时预览效果
✅ 撤销功能：支持操作历史记录，使用 Ctrl+Z 或点击 Undo 按钮撤销上一步操作，防止误操作
✅ 恢复图层属性：一键恢复图层属性到原始值，方便快速重置图层变换

🐛 问题修复

✅ 修复了 GPU 纹理创建时的 size 属性类型错误
✅ 优化了撤销操作后的渲染更新逻辑

🚀 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（推荐）

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

方式二：Git Clone

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

首次使用

启动节点
- 重启 ComfyUI 后，右上角会出现 AE Timeline 按钮
- 点击按钮会自动创建并选中 AE Animation 节点，并打开时间轴 UI
- 或者直接在节点面板添加 AE Animation 节点，然后点击按钮打开 UI
设置项目参数
- 在 UI 顶部直接输入 Width、Height、FPS、Frames
- 点击 Save 按钮将参数同步回节点 widgets
- 建议分辨率：1920×1080、1280×720 等标准尺寸
添加图层
- 点击 +FG 添加前景图层（通过文件选择器选择本地图片）
- 点击 +BG 添加背景图层
- 或者通过节点输入端连接图像（自动识别为图层）
开始创作
- 选择图层，调整 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. 关键帧动画

添加关键帧

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

编辑关键帧

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

删除关键帧

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

播放预览

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

4. Mask 遮罩功能

创建 Mask

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

编辑 Mask

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

清除 Mask

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

5. 路径动画

创建路径

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

编辑路径

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

6. Extract 背景提取

提取背景区域

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

提取效果

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

应用场景

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

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

启用摄像机

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

摄像机参数

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

创建 3D 效果

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

应用场景

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

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

⚠️ 预览说明：

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 | 删除图层 |

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

🐛 已知问题与注意事项

注意事项

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

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

ComfyUI-AE-Animation

Nodes (1)

🎬 ComfyUI AE Animation

🎥 演示视频

🙏 特别鸣谢

📝 更新日志

🆕 最新更新 (2025-12-25)

🐛 问题修复

🔧 代码优化

🆕 最新更新 (2025-12-09)

✨ 新增功能

🐛 问题修复

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

🎮 新增 Camera图层交互

🖼️ 新增 GPU渲染引擎

🎥 新增 三维摄像机系统

🔧 架构重构

📋 项目简介

✨ 核心功能

🚀 快速开始

安装

方式一：ComfyUI Manager（推荐）

方式二：Git Clone

首次使用

📖 详细使用说明

🎛️ 界面布局

顶部工具栏

左侧属性面板（Inspector）

中间画布区域（Viewport）

底部时间轴（Timeline）

🎨 详细操作指南

1. 画布交互操作

2. 图层管理

3. 关键帧动画

4. Mask 遮罩功能

5. 路径动画

6. Extract 背景提取

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

8. 画布操作

🔧 节点说明

AE Animation 节点

💾 数据管理

保存工程

加载工程

保存到节点

⚡ 性能优化

自动优化

手动优化

⌨️ 快捷键速查

🐛 已知问题与注意事项

注意事项

预览版限制

🛠️ 开发/构建

前端开发

项目结构

📄 许可证

👤 作者

🤝 贡献

🎥 新增三维摄像机系统