hfut-bishe/doc/editor-workflow.md

编辑界面功能流程说明

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

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. 验收要点（首版）

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