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预览限制说明](./3D_PREVIEW_LIMITATIONS.md)

## 故障排除

### 问题：摄像机旋转没有效果
**解决方案**:
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预览限制说明](./3D_PREVIEW_LIMITATIONS.md)

## 示例场景

### 场景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。