Add image selection refinement functionality with BEN2 integration

- Implemented viewport.py for handling 3D view projections, gestures, and overlay drawing.
- Created refine_image_selection.py to manage the refinement of gesture masks and output image bounds.
- Added selection module with refine_selection.py to process and crop images based on alpha channel visibility.
- Introduced __init__.py for selection module to expose refine_selection function.

openspec/changes/normalize-moge-alpha-depth/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-31

openspec/changes/normalize-moge-alpha-depth/design.md

@@ -0,0 +1,93 @@
+## Context
+
+Cutout Job 会把最终 Region 图像交给 MoGe-2。Remove Background 路径会清除全透明像素下的 RGB，Fit to Foreground 路径则可能保留隐藏 RGB；MoGe-2 只读取 RGB，因此两条业务路径当前并不等价。
+
+几何预测的另一处边界也不统一：MoGe-2 先返回专用 `Prediction`，Normal Writer 直接读取它，Depth Writer 才临时转换为 `GeometryFrame`；DA3 则有另一套转换入口。这样 `GeometryFrame` 没有真正成为模型预测与几何产物之间的稳定协议。
+
+MoGe-2 返回连续的 Depth/Points Field 和原始 Mask。当前 Depth Writer 会按有效性 Mask 清零 RGB，而 Depth Surface 线性采样 RGB、不读取 Alpha，因此 Mask 边界的零坐标会把网格拉向相机原点。
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- 以 MoGe-2 单帧预测的数据类型重建 `GeometryFrame`，并让 MoGe-2 与 DA3 都通过模型适配器产出该类型。
+- 让 Depth EXR、Normal Texture 和 `depth.json` 只消费 `GeometryFrame`，不直接依赖模型专用预测结构。
+- 让所有 MoGe-2 调用在同一个 Server 边界获得确定的黑底 RGB 输入。
+- 让 Depth EXR 分别表达连续数值场与原始模型 Mask，两者互不改写。
+- 保留严格的 Metadata 校准筛选，并阻止非有限数值进入 Blender。
+
+**Non-Goals:**
+
+- 不修改 BEN2、MoGe-2 或 DA3 模型实现及其推理分辨率。
+- 不改变 Depth EXR 文件名、尺寸、RGBA 通道布局或节点组接口。
+- 不用输入 Alpha 覆盖模型 Mask，也不在本次变更中让 Geometry Nodes 按 Alpha 丢弃点。
+- 不把 DA3 恢复为当前生产路径；仅保持其适配器与统一协议可用、可测试。
+
+## Decisions
+
+### 1. `GeometryFrame` 是单帧几何预测协议
+
+`GeometryFrame` 按 MoGe-2 单帧结果定义：
+
+- `depth: ndarray[H, W]`，必需的 `float32` 深度场；
+- `normal: ndarray[H, W, 3] | None`，MoGe-2 提供，DA3 可为空；
+- `validity: ndarray[H, W]`，必需的 `float32` 模型有效性信号；MoGe-2 的原始 Mask 转换为 `0/1`，DA3 保存原始连续 Confidence；
+- `intrinsics: ndarray[3, 3]`，必需的 `float32` 像素坐标内参；
+- `points: ndarray[H, W, 3] | None`，可选的 `float32` 相机空间点场；
+
+构造时校验 dtype、维度和同帧空间尺寸，但不在容器内改写预测值。`validity` 是唯一存储的模型有效性信号；不再同时保存 `mask`、`confidence` 和派生的 `valid_mask`，避免相同职责出现多个可漂移来源。
+
+MoGe-2 的生产推理入口直接返回一组 `GeometryFrame`，在适配器内完成 batch 拆分、Mask 到 Validity 的转换和内参像素化。用于调试 NPZ 的原始单次推理入口继续返回模型原始字典，因为它不是 Artifact 生产边界。DA3 保留原始调试推理，并提供同样的逐帧适配器：`normal=None`，从深度和内参生成 Points，并把 Confidence 作为连续 Validity。
+
+不选择在通用层保留 MoGe-2 `Prediction` 再二次转换，因为这会继续允许 Writer 绕过统一协议。也不把 `GeometryFrame` 限定为 MoGe-2 类型，避免 DA3 和后续模型各自复制 Artifact 逻辑。
+
+### 2. 所有几何 Artifact Writer 只消费 `GeometryFrame`
+
+Vector Depth Writer 从 `frame.points` 和 `frame.validity` 写 EXR；Z Depth Writer 从 `frame.depth` 和 `frame.validity` 写 EXR；Normal Writer 从 `frame.normal` 生成贴图；Metadata Writer 从 `frame.depth`、`frame.intrinsics` 和调用方提供的业务 Region Mask 计算 `depth.json`。
+
+Writer 只依赖通用 `GeometryFrame`，不导入 `moge2` 或 `da3`。缺少所需可选字段时明确失败，例如没有 `points` 不能写 Vector Depth，没有 `normal` 不能写 Normal Texture。Artifact 编排层从 MoGe-2 取得一帧 `GeometryFrame` 后，把同一对象传给各 Writer，不再读取模型专用属性。
+
+Metadata 所需的校准有效性按使用点计算：正的 `frame.validity`、有限且为正的 Depth，以及业务 Region Mask 的交集。它不是 `GeometryFrame` 的第二个持久字段，也不反向影响 EXR Alpha 或 RGB。
+
+### 3. 在最终 MoGe-2 输入边界统一黑底合成
+
+读取最终 `region_image_path` 为 RGBA，按输入上限缩放，然后使用 `output_rgb = source_rgb * alpha` 合成到黑底，并始终写为 Job 内的 RGB PNG。即使无需缩放，也经过相同规范化步骤。
+
+这会让半透明像素保留按 Alpha 衰减后的颜色，并彻底消除 Alpha 为零时隐藏 RGB 的差异。Metadata 和 Normal 输出所需的业务 Alpha 仍从原始 Region 图读取，不从已移除 Alpha 的模型输入读取。
+
+不在 Blender 的 `prepare_region_input()` 提前处理，因为该入口还服务其他 Job，而且 Fit to Foreground 会在 Server 端重新生成 RGBA，无法形成唯一收口点。
+
+### 4. Depth RGB 保留连续 Field，Alpha 只记录 `frame.validity`
+
+Vector/Z Depth Writer 无条件把完整 Points/Depth Field 写入 RGB，并仅把 `frame.validity` 写入 Alpha。零 Validity 不再导致 RGB 清零，使 Depth Surface 在边缘线性采样时仍能得到连续坐标。
+
+Writer 在创建文件前要求所需 Field 全部有限。Mask 为假不豁免该检查，因为 Geometry Nodes 仍会读取 Mask 外 RGB；NaN/Inf 会传播到网格。有限但非正的 Depth 仍忠实写入，正值条件只属于 Metadata 校准。
+
+不把非有限值替换为零或最近有效值：前者会重新引入相机原点尖刺，后者不再忠实于模型结果。
+
+### 5. 测试固定协议、工作流等价与连续性
+
+测试分为四层：
+
+1. `GeometryFrame` 校验，以及 MoGe-2/DA3 适配器的字段、形状、dtype、Validity 映射和批次拆分。
+2. 模型输入验证 Alpha 为 `0`、`0.5`、`1` 的黑底合成，并验证不同隐藏 RGB 得到相同透明区输入。
+3. Writer 验证只接收 `GeometryFrame`、Validity 为零时 RGB 保留原值、Alpha 等于 `frame.validity`、缺字段与 NaN/Inf 明确失败；Normal 和 Metadata 不再读取 MoGe-2 专用结果。
+4. Depth Surface 使用边缘 Mask 为假但 XYZ 连续的 Vector Depth，验证求值网格不会聚集到相机原点。
+
+## Risks / Trade-offs
+
+- [MoGe-2 返回类型变化会影响调用方] → 生产调用集中在 Artifact 编排层；一次性迁移并删除旧 `Prediction`/转换入口，不保留兼容层。
+- [GeometryFrame 严格 dtype 会暴露模型适配错误] → 在适配器边界显式转换并用模型级测试固定协议。
+- [黑底输入会改变当前 Fit to Foreground 的预测] → 这是统一语义的预期行为，用像素级测试固定合成规则。
+- [零 Validity 区域的有限 Field 可能精度较低] → Alpha 完整保留模型判断供消费者解释；连续 Field 用于避免几何塌缩。
+- [完整 Field 中一个非有限值会使 Job 失败] → 失败优于生成被 NaN/Inf 污染的网格，错误信息区分 Depth、Point 和 Normal Field。
+
+## Migration Plan
+
+1. 重建 `GeometryFrame` 与两种模型适配器，迁移 MoGe-2 生产推理返回值并删除旧专用中间结构。
+2. 将 Depth、Normal 和 Metadata Writer 改为只消费 `GeometryFrame`，再迁移 Artifact 编排层。
+3. 建立统一的 MoGe-2 黑底输入准备，并补充像素与工作流等价测试。
+4. 调整 EXR 通道写入与数值检查，增加 Depth Surface 回归测试。
+5. 更新 GeometryFrame、Artifact 和 Cutout 内部文档并运行全量测试。
+
+现有 Job 目录中的旧 EXR 不迁移；重新运行对应功能即可生成新语义 Artifact。回退时必须同时回退协议、适配器、Writer 与测试。

openspec/changes/normalize-moge-alpha-depth/proposal.md

@@ -0,0 +1,32 @@
+## Why
+
+同一前景图片通过“Remove Background 后生成 Depth Surface”和“原图启用 Fit to Foreground 后生成 Depth Surface”时，当前会向 MoGe-2 提交不同的隐藏 RGB，导致不同的 Mask 与 Depth 结果；Vector/Z Depth 又按有效 Mask 将 RGB 清零，使连续深度场在 Mask 边界退化到相机原点。与此同时，Depth 与 Normal 产物仍直接读取 MoGe-2 专用 Prediction，绕过了原本用于统一 MoGe-2 与 DA3 几何预测的 `GeometryFrame` 边界。
+
+## What Changes
+
+- 在最终 MoGe-2 推理入口统一将 RGBA 按 Alpha 合成到黑底；Alpha 为 `0.5` 的像素以一半原色、一半黑色进入模型，使 Remove Background 与 Fit to Foreground 工作流具有相同的输入语义。
+- 以 MoGe-2 的单帧预测数据设计统一 `GeometryFrame`：包含 Depth、Normal、Validity、相机内参与可选 Points。Validity 统一承载 MoGe-2 的 `0/1` Mask 或 DA3 的连续 Confidence。
+- MoGe-2 的生产推理直接返回 `GeometryFrame` 序列；DA3 保留原始 Debug Prediction，并提供到相同 `GeometryFrame` 的适配作为参考路径。
+- Depth EXR、Normal Map 与 `depth.json` Writer 只消费 `GeometryFrame`，不直接读取 MoGe-2 Prediction 或模型专用字段。
+- `vector-depth.exr` 的 RGB 对所有像素保存 MoGe-2 原始相机空间 XYZ，不再因 Validity 为零而写成零。
+- `z-depth.exr` 的 RGB 对所有像素保存 MoGe-2 原始 Depth，不再因 Validity 为零而写成零。
+- 两种 Depth EXR 的 Alpha 只保存模型原始 Validity，不与输入 Alpha、正深度检查或有限性检查合并。
+- 非有限 Depth 或 XYZ 不进行静默替换；Artifact 生成明确失败，避免 NaN/Inf 进入 Blender Geometry Nodes。
+- `GeometryFrame.validity` 是模型有效性信号的唯一事实；Depth Metadata 的参考深度按需组合输入 Alpha、Validity 与数值有效性，但不在 Frame 中保存第二套有效性字段。
+- **BREAKING（内部产物语义）**：Depth EXR 中 Alpha 为零像素的 RGB 将从固定零值改为模型原始结果；依赖旧清零行为的内部消费者必须同步更新。
+
+## Capabilities
+
+### New Capabilities
+
+- `moge-depth-artifacts`: 规定统一 `GeometryFrame`、MoGe-2 黑底输入以及 GeometryFrame 驱动的 Depth/Normal/Metadata 产物语义。
+
+### Modified Capabilities
+
+无。
+
+## Impact
+
+- 影响 `server/models/geometry.py`、`server/models/moge2.py`、`server/models/da3.py`、Geometry Writer 与其测试。
+- Cutout Depth Surface 与 Convert to Depth Plane 将消费连续的 Depth RGB；现有 EXR 文件名、尺寸、通道布局和 Job 返回协议保持不变。
+- 不改变 BEN2 模型、MoGe-2 模型、Blender Operator 标识符、节点组接口或外部依赖。

openspec/changes/normalize-moge-alpha-depth/specs/moge-depth-artifacts/spec.md

@@ -0,0 +1,113 @@
+## Purpose
+
+统一透明 Region 的 MoGe-2 输入像素语义，并规定 Depth EXR 独立保存连续模型结果与模型 Validity，使不同前景工作流生成一致、可解释且不会在有效性边界坍缩的几何产物。
+
+## ADDED Requirements
+
+### Requirement: GeometryFrame 是统一几何预测边界
+
+系统 SHALL 以单帧 `GeometryFrame` 表示供产物生成使用的几何预测。Frame SHALL 包含二维 float32 Depth、同尺寸 float32 Validity、3×3 float32 像素空间相机内参，以及可选的同尺寸三通道 float32 Normal 与 Points。Validity SHALL 统一保存模型提供的逐像素有效性信号。
+
+#### Scenario: MoGe-2 预测适配
+- **WHEN** MoGe-2 完成一帧预测
+- **THEN** 系统生成包含 Depth、Normal、由原始 Mask 转换而来的 `0/1` Validity、像素空间相机内参与按需 Points 的 `GeometryFrame`
+
+#### Scenario: DA3 预测适配
+- **WHEN** DA3 预测被转换为统一几何结果
+- **THEN** 系统生成包含 Depth、派生 Points、由原始 Confidence 提供的连续 Validity 与相机内参的 `GeometryFrame`，且 Normal 为空
+
+#### Scenario: Frame 字段维度不一致
+- **WHEN** 任一像素 Field 的高宽与 Depth 不一致，或相机内参不是 3×3
+- **THEN** `GeometryFrame` 构建失败并报告字段维度错误
+
+### Requirement: Geometry Artifact 只消费 GeometryFrame
+
+系统 SHALL 从 `GeometryFrame` 生成 Vector Depth、Z Depth、Normal Map 与 Depth Metadata，Artifact Writer SHALL NOT 直接依赖 MoGe-2 或 DA3 专用 Prediction 类型。
+
+#### Scenario: 生成 Vector Depth
+- **WHEN** 一个 `GeometryFrame` 包含 Points
+- **THEN** Vector Depth Writer 从 Frame 的 Points 与 Validity 生成 `vector-depth.exr`
+
+#### Scenario: 生成 Z Depth 与 Metadata
+- **WHEN** 一个 `GeometryFrame` 包含 Depth、Validity 与 Intrinsics
+- **THEN** Z Depth 与 Metadata Writer 从该 Frame 生成 `z-depth.exr` 与 `depth.json`
+
+#### Scenario: 生成 Normal Map
+- **WHEN** 一个 `GeometryFrame` 包含 Normal
+- **THEN** Normal Writer 从 Frame 的 Normal 及调用方提供的 Region 可见 Mask 生成 Normal Map
+
+#### Scenario: 缺少所需 Field
+- **WHEN** Writer 请求的 Points 或 Normal 在 `GeometryFrame` 中为空
+- **THEN** 产物生成失败并报告缺少对应 Geometry Field
+
+### Requirement: MoGe-2 使用统一黑底输入
+
+系统 SHALL 在 MoGe-2 推理前将最终 Region RGBA 合成到黑底，模型 RGB SHALL 等于源 RGB 乘以归一化 Alpha。
+
+#### Scenario: 完全透明像素
+- **WHEN** 最终 Region 像素的 Alpha 为 `0`
+- **THEN** MoGe-2 接收到的对应 RGB 为 `(0, 0, 0)`
+
+#### Scenario: 半透明像素
+- **WHEN** 最终 Region 像素的 Alpha 为 `0.5`
+- **THEN** MoGe-2 接收到的对应 RGB 为源 RGB 的一半
+
+#### Scenario: 完全不透明像素
+- **WHEN** 最终 Region 像素的 Alpha 为 `1`
+- **THEN** MoGe-2 接收到的对应 RGB 与源 RGB 相同
+
+#### Scenario: 前景工作流输入一致
+- **WHEN** Remove Background 与 Fit to Foreground 产生相同的可见 RGB 和 Alpha，仅完全透明像素下的隐藏 RGB 不同
+- **THEN** 两条工作流提交给 MoGe-2 的模型 RGB 完全相同
+
+### Requirement: Vector Depth 独立保存 Points 与 Validity
+
+系统 SHALL 在 `vector-depth.exr` 的 RGB 中保存 `GeometryFrame.points` 的每个原始有限相机空间 XYZ，且 SHALL 不因 `GeometryFrame.validity` 为零而修改 XYZ；Alpha SHALL 只保存 `GeometryFrame.validity`。
+
+#### Scenario: Validity 为零的有限 Point
+- **WHEN** MoGe-2 为一个像素返回有限 XYZ 且原始 Mask 转换得到的 Validity 为 `0`
+- **THEN** EXR RGB 等于该 XYZ，Alpha 等于 `0`
+
+#### Scenario: Validity 为一的有限 Point
+- **WHEN** MoGe-2 为一个像素返回有限 XYZ 且原始 Mask 转换得到的 Validity 为 `1`
+- **THEN** EXR RGB 等于该 XYZ，Alpha 等于 `1`
+
+#### Scenario: 输入 Alpha 不改变 Vector Depth Alpha
+- **WHEN** Region 输入 Alpha 与 MoGe-2 原始 Mask 不同
+- **THEN** `vector-depth.exr` Alpha 等于由 MoGe-2 原始 Mask 转换得到的 Validity
+
+### Requirement: Z Depth 独立保存 Depth 与 Validity
+
+系统 SHALL 在 `z-depth.exr` 的 RGB 三个通道中保存 `GeometryFrame.depth` 的每个原始有限 Depth，且 SHALL 不因 `GeometryFrame.validity` 为零而修改 Depth；Alpha SHALL 只保存 `GeometryFrame.validity`。
+
+#### Scenario: Validity 为零的有限 Depth
+- **WHEN** MoGe-2 为一个像素返回有限 Depth 且原始 Mask 转换得到的 Validity 为 `0`
+- **THEN** EXR RGB 三个通道均等于该 Depth，Alpha 等于 `0`
+
+#### Scenario: Validity 为一的有限 Depth
+- **WHEN** MoGe-2 为一个像素返回有限 Depth 且原始 Mask 转换得到的 Validity 为 `1`
+- **THEN** EXR RGB 三个通道均等于该 Depth，Alpha 等于 `1`
+
+#### Scenario: 输入 Alpha 不改变 Z Depth Alpha
+- **WHEN** Region 输入 Alpha 与 MoGe-2 原始 Mask 不同
+- **THEN** `z-depth.exr` Alpha 等于由 MoGe-2 原始 Mask 转换得到的 Validity
+
+### Requirement: Depth Artifact 拒绝非有限结果
+
+系统 MUST 在写入 Depth EXR 前校验所有待写入 Depth 或 XYZ；任何通道包含 NaN 或 Inf 时 MUST 终止 Artifact 生成并报告错误，且 MUST NOT 以零值替换。
+
+#### Scenario: Vector Depth 包含非有限值
+- **WHEN** 任意原始 XYZ 分量为 NaN 或 Inf
+- **THEN** `vector-depth.exr` 生成失败并报告无效 Point Field
+
+#### Scenario: Z Depth 包含非有限值
+- **WHEN** 任意原始 Depth 为 NaN 或 Inf
+- **THEN** `z-depth.exr` 生成失败并报告无效 Depth Field
+
+### Requirement: 校准筛选不改写 Depth Artifact
+
+系统 SHALL 按需使用输入 Alpha、正的 `GeometryFrame.validity`、正 Depth 与有限性共同筛选 Depth Metadata 的参考样本，但 SHALL NOT 把该派生筛选结果存为 Frame 的第二套有效性字段，且 SHALL NOT 改写 Depth EXR 的 RGB 或 Alpha。
+
+#### Scenario: 零 Validity 区域存在连续 Depth
+- **WHEN** Validity 为零的区域存在有限 Depth 或 XYZ
+- **THEN** 这些值保留在 EXR RGB 中，同时不进入参考深度计算

openspec/changes/normalize-moge-alpha-depth/tasks.md

@@ -0,0 +1,23 @@
+## 1. 统一 GeometryFrame 边界
+
+- [x] 1.1 按单帧 MoGe-2 数据重建 `GeometryFrame`：定义 Depth、Normal、Validity、Intrinsics、Points 字段及 dtype/shape 校验，删除 `mask`、`confidence`、`valid_mask`、`model_mask` 多重状态并补充单元测试。
+- [x] 1.2 让 MoGe-2 生产推理直接返回 `GeometryFrame` 序列，在适配器中完成 batch 拆分、Mask 到 `0/1` Validity 的转换和内参像素化；删除旧 `Prediction` 与二次转换入口，并验证每个字段忠实来自原始预测。
+- [x] 1.3 为 DA3 保留原始调试推理并实现 `GeometryFrame` 适配器，验证 `normal=None`、派生 Points、Intrinsics 和由 Confidence 提供的连续 Validity，保持该参考路径可用。
+
+## 2. 统一 MoGe-2 输入
+
+- [x] 2.1 将模型输入准备改为始终读取最终 Region RGBA、按输入上限缩放并以 `RGB × Alpha` 合成到黑底；用像素测试验证 Alpha 为 `0`、`0.5`、`1` 的输出。
+- [x] 2.2 增加不同隐藏 RGB 的工作流等价测试，验证可见 RGB 与 Alpha 相同时生成完全一致的 MoGe-2 RGB 输入；运行相关 Server Job 测试。
+
+## 3. 让几何产物只消费 GeometryFrame
+
+- [x] 3.1 修改 Vector/Z Depth Writer，使其只接收 `GeometryFrame`，完整写入有限的 Points/Depth RGB，并把 `frame.validity` 单独写入 Alpha；用 EXR 回读测试验证 Validity 为零时 Field 仍保留。
+- [x] 3.2 为 Depth Writer 增加缺少 Points、NaN/Inf 失败测试，验证错误明确区分 Point Field 与 Depth Field，且失败时不生成 EXR。
+- [x] 3.3 修改 Normal Writer 只从 `GeometryFrame.normal` 读取预测，保留业务 Region Mask 的可见性处理，并增加缺少 Normal 与非有限值测试。
+- [x] 3.4 修改 Metadata Writer 从 `GeometryFrame` 按需计算正 Validity、正且有限 Depth、业务 Region Mask 的校准交集；迁移 Artifact 编排层，使其不再读取 MoGe-2 专用预测字段，并运行 Server Job/Runtime 测试。
+
+## 4. Depth Surface 回归与文档
+
+- [x] 4.1 增加边缘 Mask 为假但 XYZ 连续的 Depth Surface 测试，验证求值网格不会聚集到相机原点；运行 `uv run pytest tests/test_cutout_objects.py tests/test_node_assets.py`。
+- [x] 4.2 更新 GeometryFrame、模型适配、MoGe 输入、Depth/Normal/Metadata Artifact 语义及 Cutout Runtime 文档；运行 `uv run pytest tests/test_docs.py`，不构建文档产物。
+- [x] 4.3 运行 `uv run pytest` 完成全量回归，确认两条前景工作流、Depth Plane、Depth Surface、打包和文档检查全部通过。