wallen0322-ComfyUI-AE-Animation/docs/3D_CAMERA_GUIDE.md

三维摄像机使用指南

概述

ComfyUI-AE-Animation 的三维摄像机功能已修复并增强，现在可以正常使用。本指南将帮助你了解如何使用三维摄像机创建动态的3D效果。

修复内容

1. 摄像机位置参数

• 修复前: cam_pos_z 默认值为 0，导致摄像机位置不正确
• 修复后: cam_pos_z 默认值为 1000，提供合理的摄像机距离
• 新增: 完整支持 cam_pos_x, cam_pos_y, cam_pos_z 三个位置参数

2. 摄像机旋转算法

• 修复前: 使用简单的视差效果，不够准确
• 修复后: 使用透视投影公式，根据图层深度计算准确的旋转效果
• 公式: effectiveDistance = max(100, cam_pos_z + layer_z)

3. GPU 渲染支持

• 修复前: 摄像机旋转标记为"实验性"功能，需要手动启用
• 修复后: 摄像机旋转默认启用，GPU 和 Canvas 2D 渲染器保持一致

使用方法

1. 启用三维摄像机

在 AE Timeline 界面的项目设置面板中：

1. 勾选 "启用" 复选框（在 "🎥 3D 摄像机" 部分）
2. 摄像机参数将立即生效

2. 摄像机参数说明

位置参数

• X: 摄像机在水平方向的位置（左右移动）
• Y: 摄像机在垂直方向的位置（上下移动）
• Z (距离): 摄像机与场景的距离
  • 默认值: 1000
  • 值越大，摄像机离场景越远，透视效果越弱
  • 值越小，摄像机离场景越近，透视效果越强

旋转参数

• Yaw (Y轴): 摄像机左右旋转（水平旋转）
  • 正值：向右旋转
  • 负值：向左旋转
• Pitch (X轴): 摄像机上下旋转（俯仰）
  • 正值：向上旋转
  • 负值：向下旋转
• Roll (Z轴): 摄像机滚转（画面倾斜）
  • 正值：顺时针旋转
  • 负值：逆时针旋转

投影参数

• FOV: 视野角度（Field of View）
  • 范围: 1° - 179°
  • 默认值: 90°
  • 值越大，视野越广，透视变形越明显
  • 值越小，视野越窄，接近正交投影

3. 创建3D效果

基础透视效果

1. 启用三维摄像机
2. 为不同图层设置不同的 Z 值
   • 前景图层: Z = -200 到 200
   • 中景图层: Z = 0
   • 背景图层: Z = 200 到 500
3. 调整 cam_pos_z 来控制透视强度

摄像机旋转动画

1. 在时间轴上添加关键帧
2. 设置起始帧的摄像机旋转值（如 Yaw = 0）
3. 设置结束帧的摄像机旋转值（如 Yaw = 30）
4. 播放预览，观察旋转效果

摄像机移动动画

1. 添加关键帧
2. 改变 cam_pos_x 或 cam_pos_y 创建平移效果
3. 改变 cam_pos_z 创建推拉效果

4. 高级技巧

视差效果

• 将图层放置在不同的 Z 深度
• 移动摄像机时，近处的图层移动速度快，远处的图层移动速度慢
• 这会创建自然的深度感

透视变形

• 使用较大的 FOV（如 120°）创建广角效果
• 使用较小的 FOV（如 30°）创建长焦效果
• 结合摄像机旋转可以创建戏剧性的视觉效果

全景背景

• 启用 "全景模式"（pano_enable）
• 使用 2:1 比例的全景图作为背景
• 摄像机旋转将在全景图上进行球面投影

技术细节

渲染管线

1. Canvas 2D 渲染器

   • 使用 2D 变换模拟 3D 效果
   • 透视公式: offset = tan(angle) * effectiveDistance
   • 适用于预览和调试

2. WebGPU 渲染器

   • 使用真实的 3D 变换矩阵
   • 支持硬件加速
   • 与 Canvas 2D 保持视觉一致性

坐标系统

• X 轴: 向右为正
• Y 轴: 向下为正（屏幕坐标系）
• Z 轴: 向前为正（远离摄像机）

变换顺序

图层变换顺序：

1. 锚点偏移
2. 缩放
3. 旋转（Z → Y → X）
4. 平移

摄像机变换顺序：

1. 平移
2. 旋转（Roll → Pitch → Yaw）

⚠️ 重要：预览限制

UI预览 vs 最终渲染

UI预览（实时）：

• 使用Canvas 2D或CSS 3D
• 仅为近似效果
• 用于快速调整和设置关键帧
• 性能优先，准确性次之

最终渲染（后端）：

• 使用完整的3D透视投影
• 准确的矩阵变换
• 正确的深度排序和透视变形
• 质量优先

为什么预览不准确？

1. 技术限制：浏览器Canvas 2D不支持真正的3D透视
2. 性能考虑：实时预览需要高帧率，完整3D计算会卡顿
3. 兼容性：2D近似在所有浏览器都能流畅运行

推荐工作流程

1. 在UI中调整参数和关键帧（使用2D近似预览）
2. 点击"Run Node"渲染测试帧
3. 根据渲染结果调整参数
4. 重复直到满意

📚 详细说明：查看 3D预览限制说明

故障排除

问题：摄像机旋转没有效果

解决方案:

1. 确认已启用三维摄像机
2. 检查图层是否设置了 Z 值
3. 确认 cam_pos_z 不为 0

问题：透视效果太强或太弱

解决方案:

1. 调整 cam_pos_z 值
   • 增大值减弱透视
   • 减小值增强透视
2. 调整图层的 Z 值分布

问题：图层渲染顺序错误

解决方案:

1. 检查图层的 Z 值
2. Z 值越大，图层越远（后渲染）
3. 确保前景图层的 Z 值小于背景图层

问题：全景模式背景显示异常

解决方案:

1. 确保已启用三维摄像机（全景模式需要摄像机）
2. 检查背景图片是否为2:1比例（如4096×2048）
3. UI预览可能不准确，查看最终渲染结果

问题：预览和渲染结果不一致

这是正常的:

1. UI预览使用2D近似算法
2. 最终渲染使用完整3D透视
3. 以最终渲染结果为准
4. 查看 3D预览限制说明

示例场景

场景1：简单的旋转效果

摄像机设置:
- cam_pos_z: 1000
- cam_yaw: 0 → 30 (关键帧动画)

图层设置:
- 背景: Z = 500
- 中景: Z = 0
- 前景: Z = -200

场景2：推拉镜头

摄像机设置:
- cam_pos_z: 2000 → 500 (关键帧动画)
- FOV: 90

图层设置:
- 所有图层保持固定位置
- Z 值分布: -500 到 500

场景3：环绕效果

摄像机设置:
- cam_yaw: 0 → 360 (循环动画)
- cam_pitch: -10 (轻微俯视)
- cam_pos_z: 1500

图层设置:
- 圆形排列的多个图层
- 每个图层不同的 X, Y, Z 位置

性能优化

1. 使用 WebGPU 渲染器

   • 自动启用（如果浏览器支持）
   • 提供更好的性能

2. 限制图层数量

   • 过多图层会影响性能
   • 建议不超过 20 个图层

3. 优化图片尺寸

   • 使用合适的图片分辨率
   • 避免过大的图片文件

更新日志

v1.1.0 (2025-12-08)

• ✅ 修复摄像机位置参数默认值
• ✅ 改进摄像机旋转算法
• ✅ 统一 GPU 和 Canvas 2D 渲染器行为
• ✅ 移除实验性标记
• ✅ 添加完整的参数支持

---

如有问题或建议，请在 GitHub 上提交 Issue。