# CAVE 自定义屏幕搭建器 V01 使用说明

适用对象：第一次使用该脚本的新手、需要快速搭建多屏 / CAVE / 圆柱弧面屏的 AE 操作人员。

## 1. 快速上手流程

1. 打开脚本面板，先检查左侧“工程设置”。
   - `时长`、`帧率` 会影响新建的主素材、屏幕合成、3D 预览、总输出。
   - `主素材宽/高` 是 `CAVE_Custom_01_主素材` 的尺寸。
   - `3D预览宽/高` 是 `CAVE_Custom_04_3D预览` 的尺寸。
   - `总输出布局` 推荐按场景选择：
     - `按角色展开`：适合三折、四折、五折 CAVE。
     - `按矩阵顺序`：适合矩阵、线性屏、圆柱分段屏。
     - `自定义拖拽顺序`：适合手动用“上移/下移”排顺序。

2. 点击右上“初始化工程”。
   - 脚本会创建/更新：
     - `CAVE_Custom_01_主素材`
     - `CAVE_Custom_03_总输出`
     - `CAVE_Custom_04_3D预览`
     - `CAVE_Space_Root`
     - `CAVE_Controller`
     - `CAVE_Preview_Camera`

3. 在左侧“屏幕参数”设置单块屏幕。
   - `屏幕名字`：如 `左墙`、`正面`、`地面`、`圆柱_01`。
   - `屏幕宽/高(px)`：该屏幕合成的像素尺寸。
   - `真实宽/高(m)`：真实物理尺寸，用于记录和导出。
   - `像素比例(px/m)`：像素与米的比例，圆柱半径也会按这个比例换算。
   - `屏幕中心点`：决定 Preview 图层的 Anchor Point。
   - `输出角色`：决定总输出中如何展开；不确定时使用 `自动识别`。

4. 创建屏幕。
   - 单块屏幕：点击“新增屏幕”。
   - 三折/四折/五折：在“屏幕列表”下方选择模板，点击“创建模板”。
   - 批量矩阵/圆柱：展开“矩阵创建”，选择预设，点击“预览矩阵”，满意后点击“创建矩阵屏幕”。

5. 检查结果。
   - 在 `CAVE_Custom_04_3D预览` 查看空间位置。
   - 在 `CAVE_Custom_03_总输出` 查看展开排列。
   - 如果辅助层太多，点击“显示辅助层 / 隐藏辅助层”切换时间线整洁度。

## 2. 常用操作说明

### 初始化工程

第一次使用必须点击。后续如果工程结构乱了，也可以再次点击，它会补齐基础合成和基础控制对象。

注意：初始化不会主动删除你已经创建的屏幕。

### 新增屏幕

按照左侧“屏幕参数”和“新屏幕初始变换”创建一个新屏幕。

常见用法：
- 创建 `正面`：旋转保持 0。
- 创建 `左墙`：Y 旋转通常为 `-90`。
- 创建 `右墙`：Y 旋转通常为 `90`。
- 创建 `地面`：X 旋转通常为 `-90`。
- 创建 `顶面`：X 旋转通常为 `90`。

### 读取选中屏幕

当你在 AE 中选中了某个屏幕合成、Preview、Wire、Vertex 或 ScreenCtrl，点击“读取选中屏幕”，脚本会把参数读回左侧 UI。

适合：
- 修改已有屏幕尺寸。
- 修改已有屏幕中心点。
- 复制已有屏幕参数。

### 更新选中尺寸

先选中目标屏幕，再点击“读取选中屏幕”，修改左侧参数后点击“更新选中尺寸”。

默认会保留控制器的位置、旋转、缩放。

如果勾选“更新选中屏幕时同时应用上方变换”，则会覆盖控制器位置、旋转、缩放。

### 显示/隐藏辅助层

用于整理 `CAVE_Custom_04_3D预览` 时间线。

会隐藏或显示：
- `CAVE_ScreenCtrl_*`
- `CAVE_Wire_*`
- `CAVE_Vertex3D_*`
- `CAVE_Vertex2D_*`

始终保持可见：
- `CAVE_Space_Root`
- `CAVE_Controller`
- `CAVE_Preview_Camera`

## 3. 屏幕列表

屏幕列表显示已经创建的屏幕。

支持操作：
- `刷新`：重新扫描工程。
- `读取`：读取选中屏幕到左侧 UI。
- `复制`：复制选中屏幕。
- `删除`：删除选中屏幕。
- `重建`：重建选中屏幕的 Preview、Wire、Vertex、Power Pin。
- `上移 / 下移`：改变总输出顺序。
- `设角色`：批量设置输出角色。

支持 `Ctrl / Shift` 多选。

建议：
- 做矩阵或圆柱分段时，总输出布局选 `按矩阵顺序`。
- 做 CAVE 五折时，总输出布局选 `按角色展开`。

## 4. 模板创建

模板位于屏幕列表下方。

可用模板：
- `三折幕`
- `四折幕-地面`
- `四折幕-顶面`
- `五折幕`
- `L型-左`
- `L型-右`
- `U型`

操作方式：
1. 先在左侧设置基础屏幕宽高、真实尺寸、像素比例。
2. 在模板下拉中选择模板。
3. 点击“创建模板”。
4. 到 3D 预览和总输出检查结果。

## 5. 矩阵创建

矩阵创建适合快速生成线性屏、矩阵屏、弧形屏、圆柱弧面屏。

### 矩阵预设

可用预设：
- `自定义`
- `5连屏`
- `3x2矩阵`
- `弧形五连屏`
- `内拐圆柱屏`
- `外拐圆柱屏`

### 普通矩阵参数

普通矩阵使用：
- `创建方式`
  - `线性横向`
  - `线性纵向`
  - `矩阵行列`
- `从起点创建 / 以中心展开`
- `行 / 列`
- `列步XYZ`
- `行步XYZ`
- `列旋转XYZ`
- `行旋转XYZ`

示例：5 连屏
- 预设：`5连屏`
- 创建方式：`线性横向`
- 列：`5`
- 列步 XYZ：`1920, 0, 0`
- 点击“预览矩阵”
- 确认后点击“创建矩阵屏幕”

### 圆柱弧面屏

圆柱预设使用：
- `内拐圆柱屏`
- `外拐圆柱屏`

参数：
- `圆柱半径(m)`：圆柱半径，按像素比例换算到 3D 空间。
- `圆柱角度(°)`：总弧度角，常见为 `90`、`180`、`270`。
- `圆柱分段`：生成多少块屏幕，最大建议 `64`。

推荐流程：
1. 总输出布局选择 `按矩阵顺序`。
2. 屏幕参数中设置高度、真实高度、像素比例。
3. 矩阵预设选择 `内拐圆柱屏` 或 `外拐圆柱屏`。
4. 输入半径、角度、分段。
5. 点击“预览矩阵”。
6. 满意后点击“创建矩阵屏幕”。

说明：
- 圆柱每段屏幕宽度会按弧长自动计算。
- 命名为 `圆柱_01`、`圆柱_02`、`圆柱_03` 等。
- 内拐和外拐的 Z 方向、旋转方向相反。

## 6. 批量与 JSON

### 批量重建几何

用于修复或刷新全部屏幕的 Preview、Wire、Vertex、Power Pin。

适合：
- 手动移动过控制器后需要统一刷新。
- 脚本更新后需要重建旧工程。

### 保存 JSON

保存当前布局数据，方便备份或复用。

会保存：
- 工程尺寸
- 输出布局模式
- 屏幕尺寸
- 真实尺寸
- 中心点
- 输出角色
- 位置、旋转、缩放

### 载入 JSON

从 JSON 导入屏幕布局。

注意：载入 JSON 不会自动清空现有屏幕，会追加创建。

## 7. 新手推荐场景

### 场景 A：创建五折幕

1. 初始化工程。
2. 左侧设置基础屏幕尺寸。
3. 总输出布局选择 `按角色展开`。
4. 模板选择 `五折幕`。
5. 点击“创建模板”。
6. 检查 `CAVE_Custom_04_3D预览` 和 `CAVE_Custom_03_总输出`。

### 场景 B：创建 5 连屏

1. 初始化工程。
2. 总输出布局选择 `按矩阵顺序`。
3. 展开“矩阵创建”。
4. 矩阵预设选择 `5连屏`。
5. 点击“预览矩阵”。
6. 满意后点击“创建矩阵屏幕”。

### 场景 C：创建圆柱弧面屏

1. 初始化工程。
2. 总输出布局选择 `按矩阵顺序`。
3. 展开“矩阵创建”。
4. 选择 `内拐圆柱屏`。
5. 设置：
   - 圆柱半径：`1`
   - 圆柱角度：`180`
   - 圆柱分段：`6`
6. 点击“预览矩阵”。
7. 确认弧面方向正确后点击“创建矩阵屏幕”。

## 8. 常见问题

### 看不到下方按钮怎么办？

使用右侧滚动条或鼠标滚轮滚动。也可以收起暂时不用的模块，例如“新屏幕初始变换”或“批量与JSON”。

### 总输出排列不对怎么办？

先确认 `总输出布局`：
- CAVE 折幕用 `按角色展开`。
- 矩阵和圆柱用 `按矩阵顺序`。

然后在屏幕列表中使用 `上移 / 下移` 调整顺序，再点击“重建总输出”。

### 预览层太多，时间线很乱怎么办？

点击“显示辅助层 / 隐藏辅助层”。

### 修改中心点后位置偏了怎么办？

中心点会影响旋转和对齐。建议：
1. 选中屏幕。
2. 在左侧设置“屏幕中心点”。
3. 点击“应用”。
4. 检查 3D 预览。

### 圆柱弧面太密或太卡怎么办？

降低“圆柱分段”。新手建议从 `6`、`8`、`12` 开始测试。