initial commit
This commit is contained in:
347
doc/editor-workflow.md
Normal file
347
doc/editor-workflow.md
Normal file
@@ -0,0 +1,347 @@
|
||||
# 编辑界面功能流程说明
|
||||
|
||||
本文档用于定义编辑界面的核心模块、用户操作流程和各模块之间的数据流，作为实现与联调依据。
|
||||
|
||||
## 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. 验收要点（首版）
|
||||
|
||||
- 可以完整跑通“加载 -> 裁剪 -> 深度估计 -> 分层 -> 补全/叙事 -> 预览”的链路。
|
||||
- 深度叠加图可正常显示和关闭。
|
||||
- 圈选与点选结果可正确作用于分层。
|
||||
- 自动候选区域应可稳定生成，并支持人工补充与修正后进入分层。
|
||||
- 右键补全和右键叙事生成均可输入提示词并产出结果。
|
||||
- 热点与叙事运行可在至少一个内部场景产出多帧动态化效果。
|
||||
0
doc/editor.md
Normal file
0
doc/editor.md
Normal file
90
doc/models.md
Normal file
90
doc/models.md
Normal file
@@ -0,0 +1,90 @@
|
||||
# 后端模型处理
|
||||
|
||||
当前后端主要围绕四类模型提供服务：深度估计、语义分割、图像补全和动画生成。
|
||||
|
||||
前端通过 GET /models 获取模型列表和参数配置，用来动态生成 UI；推理接口分别为：
|
||||
|
||||
POST /depth
|
||||
|
||||
POST /segment
|
||||
|
||||
POST /inpaint
|
||||
|
||||
POST /animate
|
||||
|
||||
## 一、深度估计
|
||||
|
||||
输入一张 RGB 图像，输出每个像素的相对深度，用于后续的分层和视差计算。
|
||||
|
||||
这一部分是整个伪3D效果的基础，深度质量直接决定最终效果上限。
|
||||
|
||||
模型：
|
||||
|
||||
* ZoeDepth：https://github.com/isl-org/ZoeDepth.git
|
||||
* Depth Anything v2：https://github.com/DepthAnything/Depth-Anything-V2.git
|
||||
* MiDaS：https://github.com/isl-org/MiDaS.git
|
||||
* DPT：https://github.com/isl-org/DPT.git
|
||||
|
||||
接口说明
|
||||
|
||||
HTTP：POST /depth
|
||||
|
||||
请求体：DepthRequest
|
||||
|
||||
实现：models_depth.py 中的 run_depth_inference
|
||||
|
||||
|
||||
## 二、语义分割
|
||||
|
||||
对图像进行像素级分区，用于辅助分层（天空 / 山 / 地面 / 建筑等）。
|
||||
|
||||
在伪3D流程中，这一步主要解决一个问题：
|
||||
|
||||
哪里可以拆开，哪里必须保持整体
|
||||
|
||||
模型：
|
||||
* Mask2Former：https://github.com/facebookresearch/Mask2Former.git
|
||||
* SAM：https://github.com/facebookresearch/segment-anything.git
|
||||
|
||||
接口说明
|
||||
|
||||
HTTP：POST /segment
|
||||
|
||||
请求体：SegmentRequest
|
||||
|
||||
实现：models_segmentation.py 中的 run_segmentation_inference
|
||||
|
||||
## 三、图像补全
|
||||
|
||||
在进行视差变换或分层后，图像中会出现“空洞区域”，需要通过生成模型进行补全。
|
||||
|
||||
这一部分主要影响最终画面的“真实感”。
|
||||
|
||||
模型：
|
||||
* SDXL Inpainting：https://github.com/AyushUnleashed/sdxl-inpaint.git
|
||||
* ControlNet：https://github.com/lllyasviel/ControlNet.git
|
||||
|
||||
接口说明
|
||||
|
||||
HTTP：POST /inpaint
|
||||
|
||||
请求体：InpaintRequest
|
||||
|
||||
实现：models_inpaint.py 中的 run_inpaint_inference
|
||||
|
||||
## 四、动画生成
|
||||
|
||||
通过文本提示词生成短动画（GIF），用于从静态描述快速预览动态镜头效果。
|
||||
|
||||
这部分当前接入 AnimateDiff，并通过统一后端接口对外提供调用能力。
|
||||
|
||||
模型：
|
||||
* AnimateDiff：https://github.com/guoyww/animatediff.git
|
||||
|
||||
接口说明
|
||||
|
||||
HTTP：POST /animate
|
||||
|
||||
请求体：AnimateRequest
|
||||
|
||||
实现：`python_server/model/Animation/animation_loader.py` + `python_server/server.py` 中的 `animate`
|
||||
Reference in New Issue
Block a user