# 编辑界面功能流程说明

本文档用于定义编辑界面的核心模块、用户操作流程和各模块之间的数据流，作为实现与联调依据。

## 1. 功能模块

系统包含以下功能模块：

1. 编辑界面
2. 深度估计
3. 分层与遮罩
4. 补全与纹理延展
5. 漫游渲染与预览
6. 热点与叙事运行

其中，`热点与叙事运行` 用于内部部分场景生成多帧动态化效果，作为静态场景的局部增强能力。

## 2. 总体流程（用户视角）

用户在编辑界面的标准操作流程如下：

1. 打开程序后选择图片。
2. 对图片进行裁剪，确定编辑画布范围。
3. 对裁剪后的全部图像执行深度估计。
4. 执行深度估计。
5. 估计完成后展示深度叠加图，并支持开关切换（显示/隐藏叠加）。
6. 进入圈选与点选阶段，系统先基于深度图自动选出深度变化较明显的候选区域，再由人工圈画/点选补充与修正，确定前景目标与背景区域。
7. 将结果输入分层程序，按深度关系分离目标物体，未分离区域作为底层背景。
8. 对被分层出的区域，支持右键触发补全，输入提示词进行内容补全与纹理延展。
9. 对被分层出的区域，支持右键输入提示词进行叙事帧生成。
10. 在漫游渲染与预览中检查效果并迭代调整。

## 3. 模块详细要求

## 3.1 编辑界面

- 支持图片加载与初始化展示。
- 提供裁剪工具，输出裁剪后的工作区域。
- 深度估计默认作用于裁剪后的全部图像。
- 深度估计完成后支持深度叠加图开关。
- 支持圈选与点选两类交互，用于前景目标确认与细化。
- 右键菜单需至少包含：`补全`、`叙事帧生成`。

### 3.1.1 GUI 总体信息架构（窗口与面板）

建议采用“单主窗口 + 多 Dock + 少量模态对话框”的结构，保证复杂流程可见且可回退。

1. 主窗口（`MainWindow`）  
   - 顶部：菜单栏、主工具栏、阶段切换按钮。  
   - 中央：主画布（编辑/预览共用）。  
   - 左侧：工程树 + 图层树（可 tab）。  
   - 右侧：流程控制、参数设置、属性面板（可 tab）。  
   - 底部：任务状态栏与日志条。

2. 模态/半模态对话框  
   - 裁剪对话框：用于确认裁剪框、比例锁定。  
   - 提示词对话框：用于补全/叙事输入 Prompt。  
   - 任务详情对话框：查看失败原因与重试入口。  
   - 偏好设置对话框：模型端点、默认参数、快捷键。

3. 关键 Dock（建议）  
   - `流程控制 Dock`：按步骤触发（裁剪 -> 深度 -> 候选区域 -> 分层 -> 补全/叙事）。  
   - `图层 Dock`：背景层/对象层/补全层/叙事层管理。  
   - `属性 Dock`：当前选中区域或图层的参数。  
   - `工程树 Dock`：场景、热点、叙事节点。  
   - `预览 Dock`：漫游参数、播放控制、帧速率信息。

### 3.1.2 主窗口布局与阶段条（详细）

主窗口建议增加明确的“阶段条（Step Bar）”，放在工具栏下方：

1. `S1 导入与裁剪`
2. `S2 深度估计（整图）`
3. `S3 候选区域与遮罩修正`
4. `S4 分层`
5. `S5 补全/纹理延展`
6. `S6 热点与叙事帧`
7. `S7 漫游预览`

每个阶段显示 4 种状态：`未开始`、`进行中`、`完成`、`失败`。  
仅允许“当前阶段 + 已完成阶段”可编辑，避免跨阶段误操作。

### 3.1.3 画布交互设计（核心）

画布（建议继续以 `CanvasWidget` 为核心）需支持以下显示层与交互模式：

1. 显示层（可开关）  
   - 原图层  
   - 深度叠加层（支持透明度 0~100）  
   - 自动候选区域层（描边 + 半透明填充）  
   - 人工遮罩层（新增/擦除轨迹）  
   - 分层结果层（前景、中景、背景）  
   - 叙事帧预览层（时间轴预览时启用）

2. 交互模式  
   - 浏览模式：平移、缩放、查看。  
   - 裁剪模式：拖拽裁剪框、锁定比例、确认/取消。  
   - 圈选模式：套索或画笔新增区域。  
   - 点选模式：点击候选区域进行“收录/排除”。  
   - 擦除模式：从最终遮罩中删除误选区域。  
   - 热点编辑模式：绘制热点框并绑定叙事节点。

3. 右键菜单（在画布选区上触发）  
   - `补全...`（打开 Prompt 对话框）  
   - `叙事帧生成...`（打开 Prompt 对话框 + 帧数参数）  
   - `加入前景层` / `加入背景层`  
   - `从遮罩中移除`  
   - `复制遮罩到新图层`

### 3.1.4 流程控制 Dock（按钮与状态）

流程控制 Dock 建议替代“单个开始处理”按钮，拆为分步触发：

1. `开始裁剪` / `应用裁剪`
2. `执行深度估计（整图）`
3. `生成自动候选区域`
4. `确认遮罩并分层`
5. `对选中区域补全`
6. `对选中区域生成叙事帧`
7. `进入漫游预览`

每个按钮旁应有状态灯（灰/蓝/绿/红）与耗时。  
失败时在同一行提供 `重试` 与 `查看详情`。

### 3.1.5 图层 Dock（建议新增）

图层 Dock 至少包含以下节点：

- `Base`（裁剪后的底图）
- `DepthOverlay`（仅可视化）
- `AutoCandidates`（自动候选区域）
- `MaskFinal`（自动 + 人工修正结果）
- `Foreground_i`（可多个）
- `Background`
- `Inpaint_i`
- `NarrativeFrames_i`（关联某一热点/区域）

每个图层支持：可见性、锁定、重命名、透明度、删除（受阶段约束）。

### 3.1.5A 工程树对象模型（本次需求）

工程树中的所有节点统一称为“对象（Object）”，按层级表达空间远近关系与遮挡关系。

1. 对象类型定义  
   - 背景对象（Background Object）：导入图像默认生成的对象，作为底层背景。  
   - 实体（Entity）：由分层直接得到的对象，或由补全后得到的对象。  
   - 活动实体（Active Entity）：由实体派生，已生成叙事动画帧的对象。

2. 继承/派生关系  
   - `背景对象` 不派生自其他对象。  
   - `实体` 可由背景对象或其他实体拆分得到。  
   - `活动实体` 必须派生自实体（实体 -> 活动实体）。

3. 层级与遮挡规则  
   - 工程树越往下，层级越低，表示距离越远。  
   - 距离近的对象会遮挡距离远的对象。  
   - 渲染建议采用“先远后近”的顺序（深层节点先绘制，浅层节点后绘制）。

4. 动画语义  
   - 实体默认是静态对象。  
   - 活动实体支持循环播放叙事帧（自然动画）。  
   - 活动实体同时支持触发动画（例如点击热点、时间线事件触发）。

5. 工程树最低能力  
   - 支持新增多个对象（背景对象、实体、活动实体）。  
   - 支持父子关系（实体下继续派生实体或活动实体）。  
   - 支持对象删除（删除父对象时一并删除子对象）。  
   - 支持在属性区查看对象类型与动画能力状态。

### 3.1.6 属性 Dock（按对象动态切换）

1. 选中“自动候选区域”时  
   - 显示候选评分、面积、平均深度、边界平滑系数。  
2. 选中“遮罩”时  
   - 显示画笔大小、羽化、腐蚀/膨胀。  
3. 选中“补全任务”时  
   - 显示 Prompt、负向提示词、步数、强度、随机种子。  
4. 选中“叙事帧任务”时  
   - 显示 Prompt、目标帧数、帧率、运动幅度、循环方式。  
5. 选中“热点”时  
   - 显示标题、描述、绑定叙事序列、触发方式。

### 3.1.7 任务栏与日志区（建议新增）

底部状态区建议包含：

- 当前阶段与子任务状态（例如“分层计算 67%”）。
- 最近一次接口调用耗时（深度/分层/补全/叙事）。
- 错误摘要（可点击展开完整日志）。
- 后台任务队列（允许补全与叙事并行排队）。

### 3.1.8 结合现有代码的改造清单（`client/gui`）

以下为现有 GUI 与目标流程不匹配点，以及建议修改方向：

1. `MainWindow` 当前以“单次开始处理”为主，缺少分阶段流程控制  
   - 现状：`onProcessingStartRequested()` 串行触发，且 `onDepthEstimationFinished()` 中直接进入分层。  
   - 建议：拆为 `onCropConfirmed`、`onDepthRequested`、`onCandidatesRequested`、`onLayeringRequested` 等独立槽函数，并引入阶段状态机。

2. 缺少裁剪窗口/裁剪模式  
   - 现状：`onOpenImage()` 直接载入整图到画布。  
   - 建议：新增裁剪对话框（如 `CropDialog`）或在 `CanvasWidget` 增加 `Crop` 交互模式，确认后生成工作图并替换当前输入。

3. `CanvasWidget` 交互模式不足  
   - 现状：仅 `View` 与 `EditHotspot`。  
   - 建议：扩展为 `Crop`、`MaskBrushAdd`、`MaskBrushErase`、`CandidatePick`、`PromptRegionSelect` 等模式，并增加对应信号（例如 `maskEdited`、`candidateToggled`）。

4. 缺少画布右键菜单（补全/叙事生成）  
   - 现状：右键菜单仅在工程树中提供“删除热点”。  
   - 建议：在画布选中区域上提供右键菜单，接入补全和叙事任务创建。

5. 缺少图层管理 Dock  
   - 现状：有工程树与属性面板，但没有分层图层树。  
   - 建议：新增 `LayerPanel`（可作为新 Dock），统一管理前景/背景/补全/叙事层可见性与顺序。

6. 预处理 Dock 语义不完整  
   - 现状：`ProcessingPanel` 偏模型选择与“一键开始”。  
   - 建议：重构为“流程控制 + 模型参数”双区结构；模型参数保留，执行入口拆成分步按钮。

7. 深度叠加控制不足  
   - 现状：`MainWindow` 中仅有分层预览开关（`m_layerPreviewCheck`）。  
   - 建议：增加“深度叠加开关 + 透明度滑条 + 深度色图选择”，并在 `CanvasWidget` 绘制层中实现。

8. 任务完成后自动隐藏面板不利于调试  
   - 现状：`onInpaintFinished()` 使用定时器自动隐藏 `m_processingDock`。  
   - 建议：改为默认不自动隐藏，仅在用户手动收起时隐藏。

9. 热点叙事仅文本节点，未覆盖多帧动态任务  
   - 现状：热点主要绑定 `NarrativeNode` 文本说明。  
   - 建议：为热点增加“叙事帧任务列表”与预览入口，支持每个热点关联多组动态帧。

10. 缺少撤销/重做与历史快照  
    - 现状：遮罩、分层、补全、叙事结果缺少统一历史机制。  
    - 建议：引入编辑命令栈（Command Pattern）并在工具栏提供撤销/重做。

### 3.1.9 推荐新增/调整的 GUI 类

建议在 `client/gui` 增加或调整以下类（命名可按现有风格微调）：

- `CropDialog`：裁剪确认窗口。
- `LayerPanel`：图层树与图层操作。
- `TaskPanel`：任务队列与执行状态。
- `PromptDialog`：补全/叙事 Prompt 与高级参数输入。
- `WorkflowController`（可先放 `MainWindow` 内部）：统一阶段状态机与按钮可用性。
- `CanvasWidget`：扩展多交互模式与右键上下文菜单能力。

### 3.1.10 GUI 验收标准（编辑界面维度）

1. 用户在不离开主窗口的情况下可完整完成“裁剪 -> 深度 -> 候选修正 -> 分层 -> 补全/叙事 -> 预览”。  
2. 每一阶段均有明确可视状态与失败重试入口。  
3. 画布右键可直接触发补全与叙事，且默认绑定当前选区。  
4. 图层可见性与锁定状态可稳定控制渲染结果。  
5. 热点不仅可编辑文本，还可绑定并预览多帧叙事结果。

## 3.2 深度估计

- 输入：用户裁剪后的图像（整图）。
- 输出：深度图（与编辑画布对齐）以及可视化叠加图。
- 要求：结果可回传编辑界面用于后续圈选、点选和分层计算。

## 3.3 分层与遮罩

- 输入：深度图、系统自动候选区域、用户圈选/点选结果、人工修正遮罩。
- 输出：前景层（一个或多个对象层）与背景底层。
- 要求：
  - 按深度关系优先分离目标物体。
  - 保留可编辑遮罩，支持后续补全和叙事生成直接复用。

### 3.3.1 自动候选区域筛选规则（建议）

为保证“先自动、再人工补充”的效率，建议在深度图上执行以下候选区域提取流程：

1. 深度预处理  
   - 对深度图进行归一化到 `[0, 1]`。  
   - 使用轻量平滑（如 3x3 中值滤波或双边滤波）抑制噪声，避免过碎片区域。

2. 深度变化检测  
   - 计算深度梯度幅值（可使用 Sobel）。  
   - 以阈值 `T_grad`（默认 0.12）筛选“深度变化较明显”像素，形成初始候选掩码。

3. 连通域与面积过滤  
   - 对候选掩码进行连通域分析。  
   - 过滤面积过小区域（默认最小面积为裁剪图总像素的 `0.2%`），减少噪声候选。

4. 形态学修正  
   - 执行一次闭运算填补小孔洞。  
   - 执行一次开运算移除细小毛刺，提升候选边界可用性。

5. 候选排序与展示  
   - 按“区域面积 + 平均梯度强度”综合评分排序。  
   - 默认展示 Top-K（建议 K=5）作为可点选候选区域。

6. 人工补充与修正  
   - 用户可通过圈选新增候选外区域。  
   - 用户可通过点选/擦除剔除误检区域。  
   - 最终输出为“自动候选 + 人工修正”的统一遮罩，进入分层流程。

参数建议支持在设置面板中可配：`T_grad`、最小面积比例、Top-K、平滑强度。

## 3.4 补全与纹理延展

- 触发方式：用户对分层区域右键选择 `补全`。
- 输入：目标层或遮罩区域 + 文本提示词（Prompt）。
- 输出：补全结果图层，用于修复空洞、扩展纹理或增强局部细节。
- 要求：
  - 补全结果与原图层对齐。
  - 支持重复执行与结果覆盖/回退。

## 3.5 漫游渲染与预览

- 将分层结果组织为可漫游场景进行实时预览。
- 支持查看层间深度关系导致的视差效果。
- 支持回到编辑阶段继续修改并再次预览（闭环迭代）。

## 3.6 热点与叙事运行（内部能力）

- 面向内部选定场景，不作为默认对外能力。
- 触发方式：用户右键选择目标区域并输入提示词。
- 输出：多帧叙事动态结果（局部区域动态化）。
- 目标：在静态场景中对关键区域生成连续帧，强化叙事表达。
- 说明：该模块与补全共享部分输入（区域与提示词），但输出为时间序列帧。

## 4. 关键数据流

1. 原图 -> 裁剪图
2. 裁剪图（整图） -> 深度图 + 深度叠加图
3. 深度图 + 圈选/点选 + 人工遮罩 -> 分层结果（前景层、背景层）
4. 分层区域 + Prompt -> 补全结果图层
5. 分层区域 + Prompt -> 叙事多帧结果
6. 分层与生成结果 -> 漫游渲染预览

## 5. 交互与状态建议

- 建议提供统一的图层面板，显示前景层、背景层、补全层、叙事层。
- 深度叠加图开关应为全局可见状态，便于在不同阶段快速核对。
- 右键操作应绑定当前选中区域，避免误触发到非目标层。
- 对补全和叙事生成增加任务状态：`待执行`、`执行中`、`完成`、`失败`。
- 建议保留操作历史，支持撤销/重做，便于快速迭代。

## 6. 验收要点（首版）

- 可以完整跑通“加载 -> 裁剪 -> 深度估计 -> 分层 -> 补全/叙事 -> 预览”的链路。
- 深度叠加图可正常显示和关闭。
- 圈选与点选结果可正确作用于分层。
- 自动候选区域应可稳定生成，并支持人工补充与修正后进入分层。
- 右键补全和右键叙事生成均可输入提示词并产出结果。
- 热点与叙事运行可在至少一个内部场景产出多帧动态化效果。