# 🎬 ComfyUI AE Animation

## 🎥 演示视频

<div align="center">

[![演示视频 - 点击观看](https://img.shields.io/badge/🎬-B站观看演示视频-FF6699?style=for-the-badge&logo=bilibili&logoColor=white)](https://www.bilibili.com/video/BV1yW28B3ETN)

**👉 [点击这里观看完整演示视频](https://www.bilibili.com/video/BV1yW28B3ETN)**

</div>

---

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

---

## 🙏 特别鸣谢

特别感谢 [**Terry Jia (jtydhr88)**](https://github.com/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统一**：两种渲染器行为完全一致
- 📚 **使用指南**：[三维摄像机使用指南](docs/3D_CAMERA_GUIDE.md)

#### 🔧 架构重构
- ✅ **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

```bash
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. 添加关键帧创建摄像机动画

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

📚 **详细指南**：查看 [三维摄像机使用指南](docs/3D_CAMERA_GUIDE.md)

⚠️ **预览说明**：
- UI预览使用2D近似，仅供参考
- 最终渲染使用完整3D透视投影
- 全景模式需要启用摄像机
- 详见 [3D预览限制说明](docs/3D_PREVIEW_LIMITATIONS.md)

#### 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-画布交互操作)

---

## 🐛 已知问题与注意事项

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

### 预览版限制
- 部分功能可能仍在开发中
- UI 和交互可能会持续优化
- 性能优化会持续改进
- 欢迎反馈问题和建议

---

## 🛠️ 开发/构建

### 前端开发

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

```bash
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！

---

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