Add comprehensive tests for edge depth extension, empty image edits, and material view adaptation

- Introduced `test_edge_depth.py` to validate the functionality of edge depth extension, ensuring core alpha preservation, proper depth handling, and edge padding behavior. - Created `test_empty_image_edits.py` to verify the behavior of image edits in Blender, focusing on shared edits, preservation of image properties, and handling of failed operations. - Developed `test_material_view_adaptation.py` to test material adaptation preferences, ensuring color space and alpha settings are correctly applied and preserved across various scenarios.
2026-09-06 21:43:47 +08:00
parent 1994d38ccd
commit 7e55af6722
58 changed files with 3607 additions and 200 deletions
--- a/openspec/changes/configure-material-view-adaptation/.openspec.yaml
+++ b/openspec/changes/configure-material-view-adaptation/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-05
--- a/openspec/changes/configure-material-view-adaptation/design.md
+++ b/openspec/changes/configure-material-view-adaptation/design.md
@@ -0,0 +1,61 @@
+## Context
+
+`common/material.py` 通过 `scene.view_settings.view_transform` 选择颜色空间，随后调用 `configure_color_alpha()` 固定设置 PREMUL。当前映射包含 ACES 1.3、ACES 2.0、AgX、Filmic 和 Khronos PBR Neutral；Standard 及未匹配视图返回 sRGB。剪贴板 Mesh 材质使用独立构建入口。
+
+`common/image.py` 的 Alpha 配置服务于普通编辑结果。此次策略集中作用于材质 Color Image，并复用已有像素读取和恢复机制。
+
+## Goals
+
+- 提供一个全局着色偏好，作为材质颜色贴图适配状态的唯一控制来源。
+- 保证实际 inverse 空间搭配 STRAIGHT，实际 sRGB 搭配 PREMUL。
+- 保留 Color 的业务 RGB、Alpha、透明区域 RGB 和共享源图片。
+
+## Decisions
+
+### 偏好与生效时间
+
+在 `AnyImagePreferences` 添加布尔属性 `adapt_material_to_view_transform`，UI 名称为 `Adapt to Scene View Transform`，放入独立 Shading 分组。默认值采用 `False`，让用户主动启用适配；这是本提案的默认选择。读取入口放在 `preferences.py`，通过 `addon_preferences()` 获取；偏好不可用时采用相同默认值。
+
+新建材质时读取当前偏好，已创建的材质 Color Image 保留原配置。切换偏好只决定后续创建的材质贴图策略。创建操作、源图片状态和场景 View Transform 都只能参与贴图配置，不能改写适配开关。View Transform 用于开启适配时选择对应颜色空间，回退到 sRGB 后偏好仍保持开启。
+
+### 颜色空间与 Alpha 一起决策
+
+```mermaid
+flowchart TD
+    A[新建材质 Color] --> B{Preferences 开启视图适配}
+    B -->|是| C[按当前场景选择颜色空间]
+    B -->|否| D[设置 sRGB]
+    C --> E{对应 inverse 空间可用}
+    E -->|是| F[设置 inverse 空间]
+    E -->|否| D
+    F --> G[设置 STRAIGHT]
+    D --> H[设置 PREMUL]
+    G --> I[绑定材质颜色贴图]
+    H --> I
+```
+
+沿用 `VIEW_TRANSFORM_COLOR_SPACES` 中的准确名称。Standard、未匹配的 View Transform、缺失 scene 以及不支持的 inverse 空间统一使用 sRGB + PREMUL；这属于颜色空间解析结果，适配开关仍由 Preferences 保持。Alpha 模式以实际成功应用的颜色空间为准。如果连 sRGB 也无法设置，配置明确报错并保留该贴图之前的有效配置。
+
+### 公共配置边界
+
+在 `common/material.py` 集中配置材质 Color 的颜色空间和 Alpha。公共材质与剪贴板 Mesh 材质创建入口调用同一配置函数，在 Blender 主线程处理，颜色空间映射采用创建时当前场景的 View Transform。审查 Plane、Depth Plane、Cutout 调用链，保证加载、复制或 Pack 步骤保持偏好决定的配置。
+
+材质专属配置函数负责设置 STRAIGHT 或 PREMUL；普通图片编辑继续使用现有 `configure_color_alpha()`。复用 `common` 中的像素读取函数处理数据保留。
+
+颜色空间和 Alpha 都属于 Image 数据块属性。配置作用于本次新建材质专用的 Color Image；当源图还被 Empty、普通图片编辑或已有材质引用时，先复制并仅绑定本次新建材质的 Color 节点。复用 `image_pixels()` 读取业务像素，对 generated、dirty、packed 和文件来源验证两项设置先后变化后的内容保留。
+
+### 与已有 Alpha 变更的协调
+
+活动变更 `enable-image-alpha-blending-and-premul` 中 `Mesh Color images use PREMUL independently of data textures` 的材质规则由本变更细化为颜色空间配对策略。实施时调整对应材质断言，归档时保证最终主规格采用此规则。普通编辑结果默认 PREMUL、Empty Alpha Blending、Depth 与 Normal 数据解释继续按各自规格执行。
+
+## Risks / Trade-offs
+
+- inverse + STRAIGHT 的边缘优势来自用户观察，需使用实际半透明边缘在 Blender 中复核；属性断言只能验证策略落地。
+- Image 颜色空间或 Alpha 切换可能改变像素读取解释，需覆盖 Pack、保存重载以及重新作为编辑源的行为。
+- 新建材质使用共享源图片时，需要隔离本次 Color 配置，保障已有材质及图片的其他用途。
+
+## Validation
+
+测试偏好默认值、UI、注册与逆序注销；覆盖各视图映射、关闭状态、Standard 和 inverse 不可用的回退，并断言创建及回退前后偏好值保持一致。对 Plane、Depth Plane、Cutout、剪贴板材质验证切换偏好后已有 Color 保持原值、新建 Color 使用当前设置及共享图片隔离。回归验证 Empty、普通编辑结果、Depth、Normal 和非目标材质保持原值。对 byte、float、generated、dirty、packed 材质图片验证业务 RGB/Alpha 保留及保存重载；在实际 Blender 中比较半透明边缘并记录结果。
+
+实施完成后运行 `uv run pytest`。本次实施仅修改实现和测试。
--- a/openspec/changes/configure-material-view-adaptation/proposal.md
+++ b/openspec/changes/configure-material-view-adaptation/proposal.md
@@ -0,0 +1,29 @@
+## Why
+
+用户实测材质颜色贴图在 inverse 类颜色空间下使用 STRAIGHT 边缘更好，在 sRGB 下使用 PREMUL 效果合适。当前材质入口自动适配场景 View Transform 并统一设置 PREMUL，需要提供着色偏好，让用户选择适配方式并配套正确的 Alpha 模式。
+
+## What Changes
+
+- Preferences 新增 Shading 分组和 Adapt to Scene View Transform（适配场景视图变换）开关，默认关闭。
+- 开启时根据当前场景选择对应 inverse 颜色空间，并设置 STRAIGHT。
+- 关闭时使用 sRGB + PREMUL；开启适配但实际回退到 sRGB 时也使用 PREMUL。
+- Preferences 是适配开关的唯一控制来源；新建材质读取当前设置，已创建的材质贴图保留原配置。
+- Plane、Depth Plane、Cutout 和剪贴板 Mesh 材质的 Color Image 统一应用该策略，保留业务像素和源图片独立性。
+
+## Capabilities
+
+### New Capabilities
+
+- `material-view-adaptation`: 材质视图适配偏好、颜色空间与 Alpha 配对、应用时机和像素保留。
+
+### Modified Capabilities
+
+无。当前主规格目录为空；与活动变更 `enable-image-alpha-blending-and-premul` 的 Mesh Color 默认值重叠部分，在实施和归档时按本变更的配对策略协调。
+
+## Impact
+
+- `src/anyimage/preferences.py`：偏好属性、统一读取入口和 Shading UI。
+- `src/anyimage/common/material.py`：颜色空间选择与材质 Color 配置。
+- `src/anyimage/common/image.py`：复用现有业务像素读取能力；材质专属策略由 `common/material.py` 承担。
+- `src/anyimage/operators/clipboard_image/actions.py`：接入公共材质 Color 配置。
+- Blender 偏好注册、材质配置、Alpha 数据保留和转换入口测试。
--- a/openspec/changes/configure-material-view-adaptation/specs/material-view-adaptation/spec.md
+++ b/openspec/changes/configure-material-view-adaptation/specs/material-view-adaptation/spec.md
@@ -0,0 +1,108 @@
+## ADDED Requirements
+
+### Requirement: Preferences expose material view adaptation
+
+AnyImage SHALL 在 Preferences 的 Shading 分组提供 `Adapt to Scene View Transform` 布尔选项，默认关闭。扩展设置及读取入口 SHALL 位于 `preferences.py`，并通过 `addon_preferences()` 读取。
+
+#### Scenario: Preferences use the default
+
+- **WHEN** 用户尚未设置该选项或读取不到扩展偏好
+- **THEN** 材质颜色贴图 SHALL 使用关闭适配的行为
+
+### Requirement: Material color space determines alpha presentation
+
+开启适配时，AnyImage SHALL 按当前场景 View Transform 选择既有映射中的 inverse 颜色空间，并使用 STRAIGHT。关闭适配时 SHALL 使用 sRGB + PREMUL。实际回退为 sRGB 时 SHALL 使用 PREMUL，并保持 Preferences 中的适配开关原值。
+
+#### Scenario: A supported view is adapted
+
+- **WHEN** 适配开启，当前场景为 AgX，且 `AgX Base sRGB` 可用
+- **THEN** 材质 Color Image SHALL 使用 `AgX Base sRGB` + STRAIGHT
+
+#### Scenario: Other mapped views are adapted
+
+- **WHEN** 适配开启，场景使用 ACES 1.3、ACES 2.0、Filmic 或 Khronos PBR Neutral，且对应空间可用
+- **THEN** Color Image SHALL 分别使用 `ACES 1.3 sRGB`、`ACES 2.0 sRGB`、`Filmic sRGB` 或 `Khronos PBR Neutral sRGB`
+- **AND** Alpha 模式 SHALL 为 STRAIGHT
+
+#### Scenario: Adaptation is disabled
+
+- **WHEN** 适配关闭，创建任意受支持入口的材质
+- **THEN** Color Image SHALL 使用 sRGB + PREMUL
+
+#### Scenario: The scene resolves to sRGB
+
+- **WHEN** 适配开启，但场景为 Standard、视图未匹配、场景不可用或 inverse 空间不被支持
+- **THEN** Color Image SHALL 使用 sRGB + PREMUL
+
+#### Scenario: The fallback color space is unavailable
+
+- **WHEN** 所需颜色空间及 sRGB 均无法应用
+- **THEN** 配置 SHALL 明确报错并保留贴图之前的有效配置
+- **AND** Preferences 中的适配开关 SHALL 保持原值
+
+### Requirement: Material entry points apply the same policy
+
+AnyImage SHALL 在 Plane、Depth Plane、Cutout 和剪贴板 Mesh 材质创建时统一配置 Color Image。最终模式 SHALL 在后续绑定及交付步骤中保留。Depth 与 Normal SHALL 保留各自的数据解释约定。
+
+#### Scenario: A material is created from an edited color result
+
+- **WHEN** 一个 PREMUL 编辑结果进入开启适配的 inverse 材质
+- **THEN** 最终材质 Color Image SHALL 为 STRAIGHT
+- **AND** 材质交付后 SHALL 保留该模式
+
+#### Scenario: Shadeless material is created
+
+- **WHEN** 用户通过支持 Shadeless 的入口创建材质
+- **THEN** Color Image SHALL 应用相同颜色空间与 Alpha 配对策略
+
+### Requirement: Configuration preserves business pixels and source ownership
+
+材质 Color 配置 SHALL 保留原有业务 RGB、Alpha 和完全透明区域 RGB，并在 Pack、保存重载和再次编辑后保持可读取。配置 SHALL 作用于材质专用 Color Image 或独立 Color 副本。
+
+#### Scenario: The source image has other users
+
+- **WHEN** 源 Image 同时被其他对象引用
+- **THEN** 配置 SHALL 作用于独立 Color 结果
+- **AND** 原 Image 的颜色空间、Alpha 模式和业务像素 SHALL 保持原值
+
+#### Scenario: A color result is packed and reopened
+
+- **WHEN** byte、float、generated、dirty 或 packed 来源的 Color 完成配置并保存重载
+- **THEN** 业务 RGB/Alpha SHALL 在既有编码精度内保留
+- **AND** 结果 SHALL 保持所选颜色空间和 Alpha 模式
+
+### Requirement: Preferences exclusively control material adaptation
+
+Preferences SHALL 是适配开关的唯一控制来源。新建材质 SHALL 读取当前偏好；已创建的材质颜色贴图 SHALL 保留原配置。创建操作和颜色空间解析 SHALL 保持偏好值。
+
+#### Scenario: The preference changes
+
+- **WHEN** 用户在 Preferences 开启或关闭适配
+- **THEN** AnyImage 已创建的材质颜色贴图 SHALL 保持原颜色空间、Alpha 模式和像素
+- **AND** 后续新建材质 SHALL 使用新的偏好设置
+
+#### Scenario: A new material shares its source with an existing material
+
+- **WHEN** 切换偏好后，使用已被现有材质引用的源 Image 创建新材质
+- **THEN** 新材质 SHALL 使用独立 Color Image 并应用当前偏好
+- **AND** 已有材质的贴图及其配置 SHALL 保持原值
+
+#### Scenario: A material is created or an inverse space is unavailable
+
+- **WHEN** 创建材质或颜色空间解析发生回退
+- **THEN** Preferences 中的适配开关 SHALL 保持操作前的值
+
+### Requirement: Adaptation affects only material color textures
+
+本选项 SHALL 仅配置 AnyImage 材质的 Color 贴图。Empty、普通图片编辑结果、Depth、Normal 和非目标材质 SHALL 保持原有行为与数据。
+
+#### Scenario: A material color image is shared with an Empty
+
+- **WHEN** 新建材质的源 Color Image 同时被 Empty 引用
+- **THEN** 系统 SHALL 为材质 Color 创建独立副本并重新绑定目标节点
+- **AND** Empty 引用的原 Image 的颜色空间、Alpha 模式与业务像素 SHALL 保持原值
+
+#### Scenario: Ordinary image editing runs with adaptation enabled
+
+- **WHEN** 开启适配后执行 Mask、Frame、Rectify 或图片编辑 Job
+- **THEN** 编辑结果 SHALL 沿用各自已有颜色空间与 Alpha 规则
--- a/openspec/changes/configure-material-view-adaptation/tasks.md
+++ b/openspec/changes/configure-material-view-adaptation/tasks.md
@@ -0,0 +1,32 @@
+## 1. 着色偏好
+
+- [x] 1.1 在 `preferences.py` 增加默认关闭的 `adapt_material_to_view_transform`、统一读取入口和 Shading 分组。
+- [x] 1.2 补充偏好默认值、读取回退、UI 展示测试，并检查 `__init__.py` 注册和逆序注销。
+
+## 2. 材质配置
+
+- [x] 2.1 在 `common/material.py` 集中颜色空间与 Alpha 配对：inverse + STRAIGHT，sRGB + PREMUL；实现映射、回退和设置失败处理。
+- [x] 2.2 在材质专属配置入口设置 Alpha，复用现有业务像素读取能力，验证颜色空间与 Alpha 连续切换的数据完整性。
+- [x] 2.3 接入公共材质与剪贴板 Mesh 入口，审查 Plane、Depth Plane、Cutout 的独立 Color 所有权及最终交付模式。
+- [x] 2.4 确保新建材质使用独立 Color 图片，隔离共享源对已有材质及其他用途的影响。
+
+## 3. 验证
+
+- [x] 3.1 覆盖开关两种状态、全部既有视图映射、Standard、场景缺失、inverse 不可用及 sRGB 设置失败。
+- [x] 3.2 覆盖各材质入口及 Shadeless，验证切换偏好后已有材质 Color 保持原值，新建材质读取当前设置，创建和回退均保持偏好值。
+- [ ] 3.3 更新现有材质 PREMUL 断言，验证 byte、float、generated、dirty、packed Color 的 RGB/Alpha、透明 RGB、Pack、保存重载和再次编辑。
+- [x] 3.4 在实际 Blender 中用半透明边缘复核 inverse + STRAIGHT 与 sRGB + PREMUL 的效果，并记录验证结果。
+- [x] 3.5 运行 `uv run pytest`，修复相关回归。
+- [x] 3.6 验证仅材质 Color 受影响：共享源、Empty、Mask/Frame/Rectify、图片编辑 Job、Depth、Normal 和非目标材质保持原有行为与数据。
+
+## 4. 规格收敛
+
+- [ ] 4.1 归档时协调 `enable-image-alpha-blending-and-premul` 的 Mesh Color 需求，使最终主规格统一采用本变更的颜色空间与 Alpha 配对。
+
+## 验证记录
+
+2026-09-05：`uv run --no-sync pytest -q --tb=short`：562 passed、2 xfailed、56 subtests passed。`--no-sync` 使用本轮已同步的项目环境。OpenSpec strict 校验通过。
+
+Blender 4.5.3 LTS / Cycles CPU、AgX、16 samples：渲染 64×64 橙色圆形贴图的渐变 Alpha 边缘，192×192 输出。sRGB + PREMUL 和 AgX Base sRGB + STRAIGHT 均正常显示连续半透明边缘；后者中心色更接近输入橙色。该检查确认两种策略可用。
+
+3.3 部分完成：byte、generated byte、dirty、文件和 packed 图片的业务像素及保存重载通过；原生浮点图片在保存重载后的 RGB 不满足原值断言，两种设置均可复现，已用严格 xfail 保留检查。即时配置和共享源保留通过。此项尚未解决，因此保留未完成状态。4.1 留待归档阶段处理。
--- a/openspec/changes/extend-cutout-edge-depth/.openspec.yaml
+++ b/openspec/changes/extend-cutout-edge-depth/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-05
--- a/openspec/changes/extend-cutout-edge-depth/design.md
+++ b/openspec/changes/extend-cutout-edge-depth/design.md
@@ -0,0 +1,69 @@
+## Context
+
+Cutout 的矩形 RGBA 经黑底合成后进入 MoGe，Vector Depth 保存相机 XYZ，节点按 UV 线性采样。边缘 Alpha 可用于保留毛发，但其深度可能属于背景。
+
+本次实验使用 BEN2、MoGe-2 ViT-S Level 5，固定猫（585×643）和人物（234×222）的同一份预测。Alpha ≥ 0.95、内缩 2 px、最近点外延、σ=0.8 px 局部平滑明显减少拖尾。替换深度的可见像素分别约 4.4% 与 9.6%；可靠内部保持原值。8 px 内缩替换人物约 27% 的可见区域，形状变化明显。
+
+实验采用独立投影网格。完整 Blender 的线性采样、平滑、厚度、拉伸剔除及 Normal Map 组合需要在实施阶段验收。实验记录位于 `C:/Users/icrdr/.codex/visualizations/2026/09/05/01a071bc-9eae-7f91-8791-816aa621fd8a/`，其中 `depth_experiment.py` 保存推理入口，`analyze_depth.py` 保存对比算法，`metrics.json` 保存结果；该目录是本次本地证据，自动测试使用可重建的合成数据。
+
+## Goals
+
+保留 Alpha 0.1 的可见轮廓，以可靠内部深度补齐边缘，并保持相机投影与 Cutout 产物单位一致。
+
+## Decisions
+
+### 深度修复入口
+
+在 `server/geometry/edge_depth.py` 集中处理普通数组和 GeometryFrame。`generate_moge2_artifacts()` 增加内部显式选项，由 Cutout Job 在生成深度时开启。Depth Surface 与 Depth Balloon 分别输出修复后的 Vector Depth、Z Depth，并使用对应 Metadata。Normal Writer 继续消费原始预测；普通 Depth Plane 和仅生成 Normal 的路径维持现有入口行为。
+
+```mermaid
+flowchart TD
+    A[Cutout RGBA] --> B[现有黑底合成与 MoGe 推理]
+    B --> C[原始 GeometryFrame]
+    A --> D[对齐到深度图的连续 Alpha]
+    C --> E[构建可靠内部]
+    D --> E
+    E --> F[分量内深度外延与局部平滑]
+    F --> G[按当前像素射线重建 XYZ]
+    G --> H[输出 Vector/Z Depth 与 Metadata]
+    C --> I[现有 Normal Writer]
+    H --> J[现有 Cutout 修改器]
+```
+
+### 可见域与可靠域
+
+- 连续 Alpha 使用与现有 `_alpha_mask()` 相同的最近邻尺寸对齐；可见域为 Alpha ≥ 0.1。
+- 可靠候选为 Alpha ≥ 0.95、模型 Validity > 0、深度有限且为正。
+- 在深度图输出像素单位下，保留到候选域外欧氏距离大于 2 px 的可靠核心；图片矩形边界按边缘延续处理，避免把贴边主体当作透明边缘内缩。
+- 全不透明源图直接使用原始 Frame。所有参数先固定在服务端实现中。
+
+### 外延与回退
+
+可见域按 8 连通分量处理，每个分量只使用自身的可靠核心作为供体。没有内缩核心时使用该分量内未内缩的可靠候选；连候选也没有时保留该分量的原始预测。这样细小或半透明分量具有确定的结果。
+
+对有供体的分量，以最近可靠像素的标量深度补齐非核心区域。透明背景在可见域外扩 4 px 内接收最近可修复分量的延伸值，覆盖平滑核与线性采样所需的邻域；其他可见分量的值由自身规则决定。局部计算边界须保留滤波所需的 padding。
+
+外延结果用 σ=0.8 px、半径 3 px 的 Gaussian 核平滑，仅写回补齐区域；可靠核心逐值保留。分量内平滑使用本分量的外延场，避免滤波读入其他分量深度。未处理区域保留原值。
+
+### 投影与产物一致性
+
+使用 Frame 的像素单位内参和当前像素中心，由修复后的 Z 重建相机 X、Y。复用服务端现有深度反投影函数时，须显式处理其归一化内参约定。核心位置保留原始 XYZ，防止不必要的浮点变化。
+
+修复后的 Frame 保留原模型 Validity；修复不会把模型有效性改写为预测置信度。Metadata 使用修复后的 Depth、原模型 Validity 和现有参考 Alpha Mask 计算，确保参考深度与导出贴图一致。颜色 Alpha、UV 与 Selection Mask 继续由现有路径管理。
+
+### 数值依赖
+
+复用 SciPy 的距离变换、连通分量和 Gaussian 滤波。实施时选择同时支持开发 Python 3.11、服务端 Python 3.12 及其 NumPy 约束的版本，并同步运行环境声明、开发依赖与锁文件。处理按分量局部范围执行，验证 2048 长边输入的时间和峰值内存。
+
+## Risks / Trade-offs
+
+- 高 Alpha 不等同于正确深度 → 保留 2 px 内缩，并用真实深度场检查残余污染。
+- 最近供体在同一分量内可能跨越前后表面 → 保持小内缩、仅局部平滑，并验收耳朵、衣领和手部交界。
+- 半透明孤立分量没有可靠供体时仍可能后缩 → 保留原始预测，测试回退的有限值和确定性。
+- 固定像素宽度在不同输入尺寸下覆盖比例不同 → 以深度图像素明确单位，验证两张原图及缩放输入；进一步调整参数须有新增证据。
+- 原始 Normal Map 与修复几何在边缘可能不一致 → 分别验收 Normal 开关下的边缘着色，记录残余问题。
+- 边缘跳变减小只证明拉伸改善，并不等同于真实三维深度准确 → 同时核对可见域、正面投影和侧视外观。
+
+## Migration Plan
+
+新任务在模型产物导出阶段应用修复，已有 Blender 对象通过重新生成 Cutout 获得结果。实施完成后运行相关测试和完整 pytest，再对现有节点资产执行两张实图验收。
--- a/openspec/changes/extend-cutout-edge-depth/proposal.md
+++ b/openspec/changes/extend-cutout-edge-depth/proposal.md
@@ -0,0 +1,25 @@
+## Why
+
+Cutout 用 Alpha 0.1 保留毛发时，边缘可能读取背景深度，形成严重后缩和长条拉伸。猫与人物的实图实验已验证：从可靠内部外延深度，可以保留原 Alpha 轮廓并明显减少拖尾。
+
+## What Changes
+
+- 为 Cutout 的 Depth Surface 与 Depth Balloon 增加导出前的边缘深度修复。
+- 以 Alpha ≥ 0.95 且模型深度有效的内部区域为依据，内缩 2 个深度图像素后向边缘外延，并仅对补齐区域轻微平滑。
+- 保留颜色 Alpha、0.1 裁切阈值和可靠内部深度；按当前像素的相机射线重建 XYZ。
+- 为细小分量、无可靠深度和透明区采样增加确定的处理规则，并补充自动测试与 Blender 实图验收。
+
+## Capabilities
+
+### New Capabilities
+
+- `cutout-edge-depth`: Cutout 的可靠深度区域、边缘外延、投影保持和产物一致性。
+
+### Modified Capabilities
+
+## Impact
+
+- `server/geometry/`：增加深度修复模块，接入推理产物编排。
+- `server/jobs/cutout.py`：为 Cutout 深度产物启用修复。
+- `runtime.py`、`pyproject.toml`、`uv.lock`：加入 SciPy，复用距离变换与局部滤波，并检查环境及打包测试。
+- 服务端几何与任务测试，以及现有 Blender Cutout 修改器的实图验证。
--- a/openspec/changes/extend-cutout-edge-depth/specs/cutout-edge-depth/spec.md
+++ b/openspec/changes/extend-cutout-edge-depth/specs/cutout-edge-depth/spec.md
@@ -0,0 +1,65 @@
+## ADDED Requirements
+
+### Requirement: Reliable interior supplies edge depth
+
+系统 SHALL 为包含透明内容的 Cutout 深度产物，从 Alpha ≥ 0.95、Validity > 0 且深度有限为正的候选域中，选择欧氏内缩 2 个深度图像素后的可靠核心。可见域 SHALL 继续使用 Alpha ≥ 0.1，核心深度 SHALL 逐值保留。
+
+#### Scenario: Hair samples contain background depth
+- **WHEN** 半透明毛发仍属于可见域，但其预测深度接近背景，所属分量存在可靠核心
+- **THEN** 系统以该分量最近可靠核心的深度补齐毛发区域，并保留原颜色 Alpha 和裁切轮廓
+
+#### Scenario: Subject reaches the image rectangle boundary
+- **WHEN** 不透明主体延伸到图片矩形边界
+- **THEN** 系统按边缘延续计算内缩，不将图片外部自动视为透明背景
+
+### Requirement: Extension has deterministic component fallbacks
+
+系统 SHALL 按可见域的 8 连通分量选择供体。缺少内缩核心时 SHALL 使用本分量未内缩的可靠候选；缺少可靠候选时 SHALL 保留该分量原始预测。
+
+#### Scenario: Narrow component has no eroded core
+- **WHEN** 细小分量的可靠候选在 2 px 内缩后消失
+- **THEN** 系统使用该分量未内缩候选完成外延
+
+#### Scenario: Translucent component has no reliable candidates
+- **WHEN** 独立分量完全由低 Alpha 或模型无效像素组成
+- **THEN** 系统保留该分量预测，不从另一可见分量复制深度
+
+### Requirement: Filtered sampling uses extended depth
+
+系统 SHALL 向可修复分量相邻透明区外扩 4 px 的范围延伸深度，并以 σ=0.8 px、半径 3 px 的 Gaussian 核仅平滑补齐区域。核心及其他未处理区域 SHALL 保留原值。
+
+#### Scenario: Texture sampling straddles the silhouette
+- **WHEN** 线性采样邻域跨越可见边缘和邻近透明背景
+- **THEN** 透明侧提供外延深度，采样不会重新混入该邻域原来的背景深度
+
+#### Scenario: Adjacent components have different depths
+- **WHEN** 两个可见分量分别位于不同深度
+- **THEN** 各分量的供体与平滑输入保持分量隔离
+
+### Requirement: Corrected geometry preserves camera projection
+
+系统 SHALL 根据修复后的 Z 和当前像素中心的相机射线重建 XYZ，使修复前后的相机投影保持一致，并保留核心原始 XYZ。
+
+#### Scenario: Edge pixel inherits an interior depth
+- **WHEN** 边缘像素采用另一像素的可靠 Z
+- **THEN** 重建 XYZ 仍投影到边缘像素自身位置，而不是供体位置；数值测试的归一化投影误差 SHALL 小于 1e-6
+
+### Requirement: Cutout artifacts share corrected depth
+
+系统 SHALL 为 Depth Surface 与 Depth Balloon 的 Vector/Z Depth 和 Metadata 使用同一修复后深度。模型 Validity SHALL 保留其原始语义，Normal Writer SHALL 继续使用原始预测。
+
+#### Scenario: Cutout exports vector depth and metadata
+- **WHEN** Cutout 请求深度产物
+- **THEN** Vector Depth 的 Z 与 Metadata 参考深度来自同一修复后深度场，所有输出坐标有限
+
+#### Scenario: Existing artifact paths do not require correction
+- **WHEN** 输入完全不透明，或请求来自普通 Depth Plane，或 Cutout 只生成 Normal
+- **THEN** 系统使用对应的原始产物路径与预测行为
+
+### Requirement: Edge correction is verified in the full Cutout pipeline
+
+验收 SHALL 使用猫与人物原图依次执行 Remove Background 和 Cutout，固定同一 Alpha 与模型预测比较修复前后结果，并检查 Depth Surface、Depth Balloon 及 Normal 开关组合。
+
+#### Scenario: Side-view regression comparison
+- **WHEN** 两张实图完成完整 Blender 修改器求值
+- **THEN** 主要边缘长条后缩明显减少，原 Alpha 可见域保持一致，可靠核心深度逐值不变，并记录残余台阶、着色或剔除问题
--- a/openspec/changes/extend-cutout-edge-depth/tasks.md
+++ b/openspec/changes/extend-cutout-edge-depth/tasks.md
@@ -0,0 +1,28 @@
+## 1. 数值依赖与深度修复
+
+- [x] 1.1 确定兼容开发和服务端 Python、NumPy 的 SciPy 版本，同步 `runtime.py`、`pyproject.toml` 和 `uv.lock`，检查 Manifest 与环境、打包测试约束。
+- [x] 1.2 在 `server/geometry/edge_depth.py` 实现连续 Alpha 对齐、可靠候选、2 px 欧氏内缩及图片边缘延续，补充阈值和贴边主体测试。
+- [x] 1.3 实现按可见域 8 连通分量选取最近供体，以及无内缩核心、无候选的回退规则，测试细小分量与不同深度的相邻分量。
+- [x] 1.4 实现透明区 4 px 外扩和 σ=0.8 px、半径 3 px 的局部平滑，测试核心逐值不变、邻域采样与跨分量隔离。
+
+## 2. 产物接入
+
+- [x] 2.1 按 Frame 内参和当前像素射线重建修复区域 XYZ；复用现有服务端反投影能力，测试非方形图片、像素中心、有限值及小于 1e-6 的归一化投影误差。
+- [x] 2.2 为 `generate_moge2_artifacts()` 增加内部修复选项，由 Cutout Job 在深度请求中启用；Vector/Z Depth 与 Metadata 共用修复后 Frame，保留模型 Validity 和原始 Normal Writer 输入。
+- [x] 2.3 补充任务回归测试，覆盖 Depth Surface、Depth Balloon、完全不透明图片、普通 Depth Plane 和仅 Normal 请求的产物行为。
+
+## 3. 验证
+
+- [x] 3.1 运行数值、服务端任务、运行环境和打包相关测试，再运行 `uv run pytest`。
+- [x] 3.2 用可重建的 2048 长边输入检查处理时间、峰值内存和分量数量对开销的影响，确认局部范围处理可用。
+- [x] 3.3 使用两张用户原图重新执行 BEN2 与 MoGe，固定同一 Alpha 和预测，对比修复前后边缘跳变、可见域及正面投影；补充缩放输入检查，记录结果。
+- [x] 3.4 使用现有 Blender 节点资产验收两张图的 Depth Surface、Depth Balloon 和 Normal 开关组合，检查线性采样、平滑、厚度与拉伸剔除后的侧视拖尾及残余台阶、着色问题。
+
+## 验证记录
+
+- `uv run pytest -q`：524 passed，56 subtests passed。
+- SciPy 1.15.3 支持 Python ≥ 3.10、NumPy ≥ 1.23.5 且 < 2.5；已在开发和服务端环境执行。
+- 2048×2048、1/64/1024 个分量：0.445/0.399/0.394 秒；独立进程峰值工作集约 453/343/367 MiB（处理前约 229 MiB）。
+- 猫与人物原图及半尺寸图完成重新推理，正面投影误差均小于 3×10⁻⁸，可靠核心逐值保持。猫原图边缘跳变 P95 从约 14.86% 降至 0.10%，人物从约 2.98% 降至 0.35%（以各自参考深度归一化）。
+- Blender 4.5.3 现有资产完成 16 组渲染，并对平滑 2 次、厚度 0.02、Stretch Limit 0.05 组合额外求值；所有网格坐标有限。Depth Surface 主要拖尾消除，猫最大网格边长从 2.266 降至 0.107，人物从 1.311 降至 0.662。Depth Balloon 轮廓整体稳定，人物手部原有拉伸仍可见；原始 Normal 的边缘着色仍有局部差异。
+- 本地验证脚本、预测、指标及渲染位于 `C:/Users/icrdr/.codex/visualizations/2026/09/05/01a071bc-9eae-7f91-8791-816aa621fd8a/verification/`；脚本 `verify_edge_depth.py`、`verify_blender_depth.py` 位于其父目录。
--- a/openspec/changes/improve-cutout-adaptive-mesh/.openspec.yaml
+++ b/openspec/changes/improve-cutout-adaptive-mesh/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-06
--- a/openspec/changes/improve-cutout-adaptive-mesh/design.md
+++ b/openspec/changes/improve-cutout-adaptive-mesh/design.md
@@ -0,0 +1,84 @@
+## Context
+
+当前平面网格由 Alpha 轮廓、均匀内部点和 Blender CDT 构成，Balloon 消费内部高度。Mesh Detail 的源像素间距以及世界坐标度量已有约定。本提案基于四张已抠图样本的独立实验，测量与验证边界见 [实验基准](experiment.md)；实验脚本使用开发 Python，正式 Blender 环境需要独立验证。
+
+## Goals / Non-Goals
+
+以较少顶点表达低密度轮廓与细长结构，提高高密度的实际轮廓贴合度，维持内部连通和尺寸过渡，并降低首次生成耗时。
+
+## Decisions
+
+### 0. Fine Outline 默认开启，两种算法独立选择
+
+Scene 的 `cutout_fine_outline` 与 Operator 的 `fine_outline` 共用默认 True 的属性定义，界面位于 Mesh Detail 之后。菜单捕获设置，本地创建与 AI 返回均使用该快照。关闭时使用原始轮廓平滑与均匀采样，开启时使用以下精细流程。算法选择适用于全部 Shape。
+
+密集蕨叶允许用户选择原算法获得更强概括和更短等待；精细模式仍完整验证约束，失败明确报错。两种模式分别测试，记录复杂输入的实际开销。
+
+### 1. 轮廓精度与网格间距共同受 Mesh Detail 控制
+
+```mermaid
+flowchart TD
+    A[源 Alpha 与 Selection] --> B[按当前 Alpha 阈值构建有效区域]
+    B --> C[清理极小独立区域]
+    C --> D[提取外轮廓和孔洞]
+    D --> E[按像素弧长采样与轮廓概括]
+    E --> F[按细节档位降低简化误差]
+    F --> G[提取并连接稀疏内部路径]
+    G --> H[细分轮廓和路径并均匀化自由点]
+    H --> I[约束三角化及实际边验证]
+    I --> J[既有高度求解与 Shape 创建]
+```
+
+Low / Medium / High / Ultra 的内部目标间距为 32 / 16 / 8 / 4 源像素；实验轮廓 RDP 容差分别为 2.5 / 1.25 / 0.625 / 0.5 像素。Medium 以上先按约 1 像素弧长重采样，再以 0.8 像素尺度轻微平滑像素阶梯。容差针对平滑后的轮廓，最终验收针对源 Alpha，二者分别记录。
+
+高密度从源轮廓重新近似，再限制最长边。轮廓有效性检查覆盖穿越相交、孔洞包含关系和面积；平滑或简化破坏拓扑时，逐次减半处理强度，最后使用源轮廓。像素轮廓原有的顶点接触允许保留，内部约束路径仍须严格远离边界。细桥与内部支撑在最终网格中验证。
+
+像素误差、面积阈值和内部间距在源像素坐标中定义，再通过既有变换转换为世界坐标。触及现有网格分辨率上限时，采用受限的有效间距推导精度档位，防止轮廓无限加密绕过开销限制。
+
+### 2. 极小碎片按独立区域面积处理
+
+实验默认过滤四邻域面积小于 16 源像素的独立区域，保留最大前景区域。与主体相连的细腿按所在区域整体保留；孔洞属于轮廓拓扑。清理仅作用于几何有效区域，材质 Alpha 与用户图片沿用原数据。全透明输入走现有无有效 Selection 的提示。
+
+### 3. 连续内部路径作为三角化约束
+
+从边界约束三角网格的内部边中点和三角形中心构造有效路径图。局部宽度参与选择需要支撑的细部，结构尺度由图像范围决定。选定分支通过一次多源 Dijkstra 与连接候选的最小生成森林补连，再概括为稀疏折线；过短末梢剪枝须保留必要的端部支撑。
+
+线段有效性使用端点内外判定、边界相交及线段最小间距，复用预计算边界数组。对共线接触、孔洞和近零距离使用一致容差。补连搜索采用整个细部有效子图，取消局部最大路径长度限制；实验以到边界距离不超过结构尺度的 0.75 倍限定补连区域，让宽阔中央区域由普通点支撑。该宽度边界仍须通过变宽关节回归，不能被当作所有图像上的连通保证。
+
+简化后每段都必须在轮廓内部。CDT 后通过输入约束映射查找实际网格边，通过原始顶点映射验证每条约束两端间的实际边连通和内部顶点身份，避免 float32 输出坐标使大像素坐标下的短边长度误差触发误报。所有保留细长分支需覆盖端部与关节，不能只验证已经成功选中的少数线段。Alpha 本身断开的区域保持各自独立。
+
+轮廓精度改变时，内部路径坐标可以调整；分支覆盖和连通性是跨档位契约，不要求四档顶点和边完全相同。
+
+### 4. 自由点均匀化按收敛停止
+
+沿用三角格点作为普通内部点种子；固定边界和结构路径，释放其余点。只采样目标积分网格需要的位置，限制到分量包围盒；通过最近邻归属和分组求和计算质心，最多 12 轮。至少 4 轮后，位移 RMS 小于目标间距的 1% 可停止。通过邻面尺寸比和内部最近邻距离离散度验证停止条件。
+
+轮廓与结构线按目标间距细分。最终网格中，端点均在边界的内部边共享一个新增中点，受影响三角形以内部中心点细分；全边界三角形也补入中心点。这消除内部的零高度截断，保持相邻面的公共边一致。极细部沿稀疏路径保留内部支撑。
+
+### 5. 优化计算并限定复用边界
+
+按半径分组建立中轴圆的空间索引，查询时从大半径向小半径筛选，保持宽度估计结果一致。轮廓射线和距离数组在一次分量处理内复用。布点与结构准备分为普通数组接口，复用结果须与重新计算一致。
+
+每次创建依据当前输入和精度重新准备结构；分量内复用距离、射线和宽度索引，创建结束释放。当前交互一次创建一个 Shape，因此直接使用操作局部数据。
+
+首次生成、已准备结构的重建、Blender 对象更新分别计时。实验复用计时不包含输入检查和结构准备，因此不能当作首次生成或跨档位 UI 延迟。
+
+### 6. 正式运行时依赖作为接入门槛
+
+客户端使用 SciPy 的标记、距离变换与 KDTree，NumPy 的轮廓简化及 Blender CDT。距离脊圆用于估计局部宽度，连续内部路径仍由约束图构建。轮廓简化保留 scikit-image 0.25.2 的独立 NumPy 实现及 BSD 许可证。
+
+客户端声明 SciPy 1.15.3；NumPy 使用 Blender 自带版本，由打包器按 Python 目标版本解析兼容范围并排除 NumPy wheel。锁文件和本地 Manifest 同步。此前六图四档实验的轮廓边界一致，保留内部支撑和连通性检查。
+
+## Risks / Trade-offs
+
+- 细桥经平滑或简化消失 → 以源有效域检查连通关系，降低处理强度；将单像素桥、弯折和孔洞列入测试。
+- 路径连接增加宽区域内部线 → 验收普通点均匀性、总点数和邻面尺寸，保留稀疏折线概括。
+- 小独立区域具有内容语义 → 将清理限定为极小面积，保留最大区域，保持材质原 Alpha；记录几何过滤数量。
+- 高密度轮廓复杂度增加 → 批处理与空间索引，按分量限制工作集；测量 2K / 4K 输入及网格上限。
+- 四张实图不足以保证所有细部 → 合成图覆盖弯折、窄桥、多个孔洞、独立岛和边界接触；失败不得静默丢弃约束。
+- [十图扩展实验](experiment-cases.md) 中蕨叶 Low / Ultra 达到约 6 / 23.6 秒，羽毛高密度仍有支撑间断 → 把密集多级分枝和局部零高度边列为实施验收反例，定位候选图数量与边界查询开销。
+- 开发 Python 测时不能代表 Blender 全流程 → 正式接入前分别完成数值阶段和对象/节点阶段验收。
+
+## Migration Plan
+
+依次完成运行时可行性、独立几何回归、双模式接入和 Blender 验收。精细轮廓作为默认模式，原算法作为用户主动选择的概括模式。用户现有 Shape、像素间距和世界变换语义沿用原约定。
--- a/openspec/changes/improve-cutout-adaptive-mesh/experiment-cases.md
+++ b/openspec/changes/improve-cutout-adaptive-mesh/experiment-cases.md
@@ -0,0 +1,32 @@
+# 十张新增实图
+
+2026-09-06，固定上一轮独立 `final.py`，从 Wikimedia Commons 选取十张公开图片。下载图缩至长边不超过 768 像素且不放大，再以本地 BEN2 抠图；已有透明图先合成白底。Alpha 阈值 0.9、独立岛面积阈值 16，四档间距 32/16/8/4。未按单张图片调参。
+
+每档预热一次，测三次数值构建取中位数，计时边界沿用 experiment.md。BEN2 本轮实际使用 CPUExecutionProvider，约每图 3.5–4.1 秒，未纳入网格耗时。
+
+| 图片 | 尺寸 | Low 秒 | Medium 秒 | High 秒 | Ultra 秒 |
+|---|---|---:|---:|---:|---:|
+| 螳螂 | 768×565 | 0.092 | 0.116 | 0.231 | 0.429 |
+| 蚁后 | 475×768 | 0.045 | 0.050 | 0.067 | 0.088 |
+| 蚁蛉 | 479×768 | 0.112 | 0.135 | 0.224 | 0.354 |
+| 捕鸟蛛 | 768×548 | 0.082 | 0.099 | 0.167 | 0.383 |
+| 凤蝶 | 768×412 | 0.069 | 0.098 | 0.201 | 0.540 |
+| 枫叶 | 768×512 | 0.058 | 0.074 | 0.115 | 0.284 |
+| 羽毛 | 576×768 | 0.287 | 0.466 | 0.771 | 1.264 |
+| 剪刀 | 400×290 | 0.058 | 0.072 | 0.117 | 0.229 |
+| 蕨叶 | 768×768 | 6.026 | 10.211 | 18.854 | 23.600 |
+| 骑行者 | 768×507 | 0.089 | 0.103 | 0.149 | 0.272 |
+
+## 新发现
+
+- 蕨叶仅约 97,003 个前景像素，与先前蜘蛛相近，但 Low 已有 8,012 点和 3,459 条内部约束。清理将独立区域从 661 减至 58，移除 1,475 像素；保留下来的细枝和孔洞仍形成显著开销。Ultra 有 24,007 点，约 23.6 秒。密集分枝必须作为性能反例，不能沿用四图结论推断其运行时间。
+- 羽毛 Low / Ultra 分别有 24 / 42 条端点均在边界的内部边，存在局部零高度夹扁风险。额外内部顶点图分量从 1 增至 25。蕨叶的额外内部图分量从 Low 的 3 增至 Ultra 的 172。
+- 剪刀、捕鸟蛛、蚁后和骑行者在四档内部图诊断中没有额外内部分量，但此指标不等于逐腿端部覆盖证明。没有为新图人工指定每条细腿的完整检查点。
+- BEN2 与高 Alpha 阈值造成的分割缺失、图片中主体本身很小、网格自身产生的支撑间断必须分别展示。原图、BEN2、网格和高度图均保存用于对照。
+- 四十组数值构建均完成并保存。蕨叶在全部数值结果保存后触及单例总流程 240 秒超时，随后从 NPZ 补绘图表；超时不属于表中的单次数值构建耗时。
+
+## 验收影响
+
+提案尚不能视为已经解决普遍的细分枝连通和性能问题。正式实施需增加蕨叶型多级分枝、羽毛型细丝的合成回归，检查最终内部顶点图与局部零高度边，并在保留细部支撑的前提下处理候选路径数量和几何查询开销。
+
+逐图来源、作者、许可、全部指标及对比图保存在本机 `cutout-experiment/case-study/report.md` 与 `sources.json`。完整路径前缀为 `C:/Users/icrdr/.codex/visualizations/2026/09/05/01a07226-3125-7c63-b655-8206da43c177/`。
--- a/openspec/changes/improve-cutout-adaptive-mesh/experiment.md
+++ b/openspec/changes/improve-cutout-adaptive-mesh/experiment.md
@@ -0,0 +1,40 @@
+# 实验验收基准
+
+2026-09-06，本机开发 Python 3.11、NumPy 1.x、Blender bpy 4.5.3，使用已完成 BEN2 抠图的四张样图。每项预热一次，交替测三次取中位数。输入尺寸：头骨 620×444、蜘蛛 476×702、甲虫 465×347、卡通 128×123。
+
+## 首次数值构建
+
+单位为毫秒，包含过滤、轮廓、结构准备、布点、约束三角化和既有 Poisson 求解；不含 removebg、进程导入、图片读写、指标计算、绘图、Blender 对象创建与节点求值。下表作为同机正式接入的 1.25 倍耗时验收参照，不作为其他硬件或大图的绝对时限。
+
+| 图片 | Low | Medium | High | Ultra |
+|---|---:|---:|---:|---:|
+| 头骨 | 115 | 183 | 314 | 858 |
+| 蜘蛛 | 233 | 304 | 647 | 1292 |
+| 甲虫 | 60 | 73 | 121 | 275 |
+| 卡通 | 19 | 23 | 32 | 51 |
+
+上一轮蜘蛛 Low / High / Ultra 为约 785 / 965 / 1454 ms；上一轮高密度仍沿用低密度边缘。当前轮廓更精细，因此这是结果质量发生变化的端到端对比。最初正式算法的蜘蛛 Low 约 190 ms、Ultra 约 303 ms，当前仍有额外计算成本。
+
+## 轮廓贴合
+
+从源轮廓采样到实际网格边界的 P95 距离，单位为源像素。误差测量使用过滤后的原始 Alpha 轮廓，包含高密度平滑带来的偏差。
+
+| 图片 | Low | Medium | High | Ultra |
+|---|---:|---:|---:|---:|
+| 头骨 | 1.612 | 1.024 | 0.650 | 0.590 |
+| 蜘蛛 | 1.530 | 0.986 | 0.680 | 0.615 |
+| 甲虫 | 1.566 | 0.968 | 0.687 | 0.609 |
+| 卡通 | 1.666 | 0.868 | 0.652 | 0.605 |
+
+High 的正向最大采样距离约 0.98 像素，Ultra 约 0.88 像素以内；反向采样最大距离分别约 0.73 / 0.63 像素以内。采样距离是实验指标，不是连续 Hausdorff 误差的严格上界。
+
+## 已验证与正式验收边界
+
+- 蜘蛛截图右外侧腿的六个检查位置在间距 4、8、16、28、32、36 像素，以及 Low / High 平移 1 像素时处于同一内部约束图分量；检查点最近距离最高约 10.55 像素。
+- 保留约束覆盖最终实际网格边，端点为内部点且 Balloon 高度为正；不同精度的路径位置与点数允许变化。
+- 含孔洞矩形的内部线段、穿孔、越界、共线接触、零长度内部点和边界点检查通过；随机内外判定与现有函数一致。
+- 半径分组空间索引在四图随机查询上与未索引宽度估计一致；准备结构复用与完整重算的点、面和高度一致。
+- 仍有少量未被选为结构路径的全边界三角形，不能据此声称所有末梢均已获得支撑。正式任务要求补充端部覆盖检查。
+- 当前原型未实现完整的轮廓拓扑重试、操作级缓存身份、Blender 客户端依赖接入和 2K/4K 资源验收，这些在 tasks.md 中保持未完成。
+
+独立脚本及测量数据位于本机会话目录：`C:/Users/icrdr/.codex/visualizations/2026/09/05/01a07226-3125-7c63-b655-8206da43c177/cutout-experiment/final/`；原型入口为其上级的 `final.py`。正式自动测试需使用仓库内可复现的合成样本。
--- a/openspec/changes/improve-cutout-adaptive-mesh/implementation.md
+++ b/openspec/changes/improve-cutout-adaptive-mesh/implementation.md
@@ -0,0 +1,64 @@
+# 实施验收
+
+2026-09-06，Windows、Python 3.11、bpy 4.5.3。Fine Outline 默认开启；关闭调用原有轮廓平滑和均匀布点流程。
+
+## 数值构建
+
+计时包含已加载 Alpha 的过滤、轮廓、路径、布点、三角化及 Poisson 高度；不含抠图、依赖首次导入、对象创建。四张原样本预热后取三次中位数；复杂蕨叶每档一次，供开销判断。两种模式均使用 32 / 16 / 8 / 4 像素目标间距。
+
+| 样本 | 间距 px | 原算法 ms | Fine Outline ms | 原算法点数 | Fine Outline 点数 |
+|---|---:|---:|---:|---:|---:|
+| skull | 32 | 32.7 | 118.4 | 411 | 486 |
+| skull | 16 | 43.2 | 164.4 | 984 | 1112 |
+| skull | 8 | 68.7 | 313.5 | 3233 | 3472 |
+| skull | 4 | 285.3 | 862.0 | 11983 | 12239 |
+| spider | 32 | 195.8 | 235.7 | 1752 | 953 |
+| spider | 16 | 211.2 | 310.5 | 2198 | 1736 |
+| spider | 8 | 243.3 | 661.7 | 3549 | 3879 |
+| spider | 4 | 336.4 | 1303.4 | 9272 | 10076 |
+| beetle | 32 | 22.8 | 62.8 | 184 | 268 |
+| beetle | 16 | 23.9 | 83.2 | 322 | 459 |
+| beetle | 8 | 33.9 | 130.0 | 804 | 1001 |
+| beetle | 4 | 56.8 | 274.8 | 2519 | 2797 |
+| cartoon | 32 | 3.0 | 20.0 | 16 | 47 |
+| cartoon | 16 | 3.1 | 25.2 | 52 | 96 |
+| cartoon | 8 | 4.9 | 34.0 | 188 | 243 |
+| cartoon | 4 | 11.2 | 61.0 | 702 | 755 |
+| fern | 32 | 796.9 | 15637.6 | 4217 | 13946 |
+| fern | 16 | 814.1 | 10733.5 | 4861 | 11961 |
+| fern | 8 | 2226.1 | 20422.6 | 10546 | 18226 |
+| fern | 4 | 2431.2 | 25987.0 | 17748 | 26353 |
+
+二十组精细网格均无两端处于边界的内部边，所有内部顶点的 Poisson 高度为正。复杂蕨叶 Low 的拓扑重试提高了局部精度，点数可能高于 Medium；Mesh Detail 表示目标间距，实际数量还受轮廓拓扑约束影响。密集分枝使用精细模式仍有明显等待，关闭可获得原算法的概括效果。
+
+## 大图与内存
+
+合成前景包含 36 个孔洞及多个独立碎片，网格分辨率上限设置为 128。峰值为独立 Python 进程的 PeakWorkingSetSize，包含 bpy 与数值依赖，不等同于单个数组占用。
+
+| 分辨率 | 受限间距 px | 耗时 ms | 顶点 | 峰值 MiB |
+|---|---:|---:|---:|---:|
+| 2048² | 16.0 | 876.9 | 4802 | 470.3 |
+| 4096² | 32.0 | 3827.1 | 4820 | 1182.2 |
+
+网格点数保持在相近规模；源像素中轴计算的时间与内存仍随图像面积增长。两组均通过零高度内部边与正内部高度检查。
+
+## 依赖与打包
+
+客户端新增 NumPy >=1.26,<2.0、SciPy 1.15.3、scikit-image 0.25.2；uv.lock 已同步。使用项目打包器的 Python 3.11 与平台参数实际下载全部数值 wheel，三平台均成功。
+
+| 平台 | 数值 wheel 数 | 压缩体积 MiB |
+|---|---:|---:|
+| linux | 9 | 77.8 |
+| macos | 9 | 61.8 |
+| windows | 9 | 76.2 |
+
+数值 wheel 体积包含传递依赖，不含原有 BlendJob。实际平台 Manifest 由打包器使用解析出的全部 wheel 名称生成，已增加对应测试；源 Manifest 的平台集合保持一致。本次仅做依赖与测试校验。
+
+## 自动验证
+
+- Cutout 几何、交互、对象、Blender 注册、Manifest 与打包：270 passed、29 subtests passed，退出码 0。
+- 其余全部测试：318 passed、2 xfailed、27 subtests passed，退出码 0。
+- 单进程全量测试的断言结果为 588 passed、2 xfailed、56 subtests passed，但解释器退出阶段出现 Windows 原生访问异常（0xC0000005）；原因尚未确定。分组复跑覆盖全部用例且均正常退出。
+- OpenSpec strict validate 通过。
+
+新增回归覆盖弯腿、变宽关节、1 像素平移、相邻密度、单像素桥、孔洞、密集分枝、极小岛、阈值与输入不变性、源轮廓双向误差、索引与穷举一致性、均匀化误差、CDT 拆分约束、菜单模式快照，以及关闭模式与原流程逐数组一致。既有对象测试覆盖四种 Shape、TEDDY/Poisson 高度消费和非均匀世界变换。
--- a/openspec/changes/improve-cutout-adaptive-mesh/proposal.md
+++ b/openspec/changes/improve-cutout-adaptive-mesh/proposal.md
@@ -0,0 +1,30 @@
+## Why
+
+Cutout 在低密度下轮廓偏离原图，细腿缺少连续内部顶点时 Balloon 会形成扁平断点。实验还发现，高密度只细分简化直边无法提高贴合度；轮廓精度、内部连通性和计算开销需要一起约束。
+
+## What Changes
+
+- 新增默认开启的 Fine Outline（精细轮廓）。开启使用自适应网格；关闭保留原轮廓平滑、概括和均匀布点算法，适合蕨叶等密集细部。
+- 设置保存在 Scene，打开 Shape 菜单时捕获到 Operator，覆盖本地及 AI 返回后的创建流程。
+- Mesh Detail 同时控制轮廓近似误差和内部目标间距；Low 保留概括，High、Ultra 从源轮廓恢复更精细的形状。
+- 为保留的细长结构构建稀疏、连续的内部约束路径，并在最终网格和 Balloon 高度中验证路径完整性。
+- 固定轮廓与结构路径，均匀化其余内部点；通过局部细分处理边缘与内部的尺寸过渡。
+- 在网格生成前过滤极小独立区域，保留最大区域和与主体相连的细腿。
+- 批量复用边界几何检查，合并路径搜索，限制均匀化采样量并按收敛停止；每次创建依据输入重新准备结构。
+- 增加轮廓误差、跨密度连通性、拓扑质量和首次生成耗时的回归验收。
+
+## Capabilities
+
+### New Capabilities
+
+- `cutout-adaptive-mesh`: Cutout 的轮廓精度、稀疏内部支撑、约束网格、碎片清理和性能验收。
+
+### Modified Capabilities
+
+## Impact
+
+- `src/anyimage/operators/cutout_tool/geometry.py` 及 Cutout 几何模块：根据 Fine Outline 选择平面网格算法，复用现有高度求解能力。
+- `src/anyimage/operators/cutout_tool/main.py`、`object.py`：核对各 Shape 的几何输入、像素坐标和高度消费边界。
+- `tests/test_cutout_geometry.py` 及独立性能实验：补充真实问题的合成回归样本和四档密度检查。
+- 客户端数值依赖与打包检查：实验使用 NumPy、SciPy、scikit-image 和 Blender CDT；正式实现需验证 Blender Python 中的可用性与平台 wheel 支持。
+- 沿用 Low / Medium / High / Ultra 的 32 / 16 / 8 / 4 源像素目标间距和现有网格分辨率上限。
--- a/openspec/changes/improve-cutout-adaptive-mesh/specs/cutout-adaptive-mesh/spec.md
+++ b/openspec/changes/improve-cutout-adaptive-mesh/specs/cutout-adaptive-mesh/spec.md
@@ -0,0 +1,98 @@
+## ADDED Requirements
+
+### Requirement: Fine Outline selects the mesh algorithm
+系统 SHALL 提供默认开启的 Fine Outline 设置。开启 SHALL 使用精细轮廓和连续内部支撑算法；关闭 SHALL 使用原始轮廓平滑、概括与均匀布点算法。以下精细网格要求适用于开启状态。
+
+#### Scenario: User chooses abstraction for a fern
+- **WHEN** 用户关闭 Fine Outline 并创建任一 Cutout Shape
+- **THEN** 系统使用原算法，Mesh Detail 和 Alpha Threshold 继续有效
+
+#### Scenario: New scene uses fine outlines
+- **WHEN** Scene 或 Operator 使用默认属性
+- **THEN** Fine Outline 为开启状态，界面在 Mesh Detail 旁提供切换
+
+#### Scenario: Settings change during an AI job
+- **WHEN** 用户打开 Shape 菜单后修改 Scene 的 Fine Outline
+- **THEN** 已发起操作的本地或 AI 返回创建使用菜单捕获的模式
+
+
+### Requirement: Detail controls actual contour accuracy
+系统 SHALL 根据有效 Mesh Detail 同时确定内部目标间距和源轮廓近似精度，保留 Low 的形状概括；High 与 Ultra SHALL 从源轮廓恢复更精细的边缘，而非仅拆分已有直边。系统 SHALL 分别记录相对源轮廓的双向采样误差和网格数量。
+
+#### Scenario: Curved outline is refined at higher detail
+- **WHEN** 未触及网格上限的弧线样本分别使用 Low、High、Ultra 构建网格
+- **THEN** High 与 Ultra 的实际边界包含恢复曲率的新位置，双向 P95 误差低于 Low，Ultra 在规定数值容差内不劣于 High
+
+#### Scenario: Source-pixel spacing and mesh limit remain effective
+- **WHEN** 用户选择四档 Mesh Detail 或输入触及现有网格上限
+- **THEN** 内部目标间距沿用 32、16、8、4 源像素及上限调整规则，轮廓精度采用相应有效档位
+
+### Requirement: Cleanup preserves connected thin structures
+系统 SHALL 按独立前景区域面积过滤极小碎片，默认阈值为 16 源像素，保留最大区域。系统 SHALL 保留主体连接的细长结构、有效孔洞及原材质 Alpha。
+
+#### Scenario: Tiny islands accompany an insect
+- **WHEN** 昆虫主体、与主体相连的单像素细腿和多个小于阈值的独立岛同时存在
+- **THEN** 系统移除极小独立岛，保留主体和细腿，原图片像素保持一致
+
+#### Scenario: Entire subject is smaller than the cleanup threshold
+- **WHEN** 唯一有效区域小于默认面积阈值
+- **THEN** 最大区域被保留并获得有效网格和内部支撑
+
+#### Scenario: Empty selection contains no foreground
+- **WHEN** 当前阈值下没有有效前景
+- **THEN** 系统返回现有无有效 Selection 的错误结果，不创建空对象
+
+### Requirement: Thin branches retain continuous interior support
+系统 SHALL 为过滤后可表示的细长分支提供稀疏连续的内部网格路径，覆盖端部和关节。路径 SHALL 位于有效区域内部，分支连通性 SHALL 在密度变化后维持；已断开的 Alpha 区域独立处理。
+
+#### Scenario: Leg changes width at a joint
+- **WHEN** 细腿经较宽关节继续延伸，且内部目标间距大于腿宽
+- **THEN** 腿内保持单列内部支撑与连续实际网格边，关节不会因宽度筛选丢失连接
+
+#### Scenario: Density and translation change
+- **WHEN** 同一弯腿样本在 Low、Medium、High、Ultra 和平移 1 像素后生成
+- **THEN** 各次端部与关节检查位置均由同一内部路径连通，保留路径端点的 Balloon 高度为正
+
+#### Scenario: Foreground components are separated by transparency
+- **WHEN** 两个细结构之间存在透明间隙
+- **THEN** 系统分别构建各自内部支撑，不跨透明间隙建立连接
+
+### Requirement: Constraint validation uses the final mesh
+系统 SHALL 在最终三角化结果中验证所需内部约束的实际边覆盖、连通性和内部顶点身份，SHALL 拒绝跨边界、穿孔洞、边界接触和丢失约束的结果。失败 SHALL 触发有效修复或明确错误。
+
+#### Scenario: Simplified path would cross a hole
+- **WHEN** 路径概括的候选线段穿过孔洞或碰到其边界
+- **THEN** 系统使用有效内部路径重建该段，不能将候选线段直接送入最终网格
+
+#### Scenario: Triangulation splits an input constraint
+- **WHEN** CDT 将一条内部约束拆分为多个实际网格边
+- **THEN** 系统验证这些边完整覆盖输入约束且首尾相接，而非要求输入边原样保留
+
+#### Scenario: Short constraints at large pixel coordinates
+- **WHEN** 高分辨率图片的短内部约束经 CDT 发生坐标舍入
+- **THEN** 系统通过原始顶点和边映射验证实际约束链的端点连通，有效约束不因长度舍入误报；真实断线、被过滤的约束边和丢失端点仍报错
+
+### Requirement: Ordinary interior sampling remains uniform
+系统 SHALL 固定轮廓与稀疏内部路径、均匀化其余内部点，并以局部细分控制边界和内部的尺寸过渡。均匀化 SHALL 有确定的迭代上限和收敛停止条件。
+
+#### Scenario: Broad cartoon region accompanies narrow appendages
+- **WHEN** 卡通图像包含宽阔中央区域与细耳朵或细腿
+- **THEN** 中央普通点保持接近目标间距，细部使用稀疏内部支撑；通过内部最近邻离散度和邻面尺寸比验收，不能只增加中央点数掩盖不均匀
+
+### Requirement: Each creation uses its current inputs
+系统 SHALL 在每次创建时根据当前像素、Selection、阈值和有效间距准备结构，计算期间复用分量内的几何查询数组。
+
+#### Scenario: Detail or image pixels change
+- **WHEN** 用户改变 Mesh Detail 或 Alpha 后再次创建
+- **THEN** 系统从新输入重建轮廓与内部结构
+
+### Requirement: Performance is measured with quality checks enabled
+系统 SHALL 在四档密度下分别测量两种模式的数值构建与 Blender 创建，保留完整约束检查。基准 SHALL 使用相同已加载 Alpha、固定环境、预热和多次重复，并同时记录点数、轮廓误差、连通性与内存规模。
+
+#### Scenario: Optimized implementation is accepted
+- **WHEN** 正式实现进行性能验收
+- **THEN** 四张基准图的几何质量通过，记录与原算法的耗时比较及复杂蕨叶的实际开销；首次生成计时包含过滤、轮廓、结构、布点、三角化和高度求解，精细模式不能通过静默切换原算法满足计时要求
+
+#### Scenario: Large input reaches the resource limit
+- **WHEN** 2K 或 4K 输入包含大量孔洞和独立区域
+- **THEN** 系统验证网格上限、按分量的有界批次与峰值内存，不能使用小图或缓存计时替代该测量
--- a/openspec/changes/improve-cutout-adaptive-mesh/tasks.md
+++ b/openspec/changes/improve-cutout-adaptive-mesh/tasks.md
@@ -0,0 +1,26 @@
+## 1. 规格与双模式入口
+
+- [x] 1.1 修改 proposal、design 和 spec，明确 Fine Outline 默认开启、关闭使用原算法及复杂输入的性能取舍。
+- [x] 1.2 增加共享 Bool 属性、工具设置与菜单快照，覆盖本地和 AI 返回创建。
+- [x] 1.3 接入两种几何算法，复用 UV、世界度量、高度求解及全部 Shape。
+
+## 2. 精细网格
+
+- [x] 2.1 移植独立实验的轮廓精度、极小独立岛清理及拓扑有效性重试，尊重当前 Alpha 阈值。
+- [x] 2.2 接入宽度索引、连续稀疏路径及 CDT 实际约束验证。
+- [x] 2.3 接入有收敛上限的内部均匀化，并修复最终网格的零高度内部边与无支撑三角形。
+- [x] 2.4 增加弯腿、变宽关节、孔洞、细桥、密集分枝、独立岛与高密度轮廓误差回归。
+
+## 3. 运行时与验收
+
+- [x] 3.1 声明客户端依赖、同步锁文件，验证三平台 wheel 可用性及体积，检查 Manifest 和打包测试。
+- [x] 3.2 测试默认值、关闭模式、菜单快照、本地与异步入口、世界变换及 Blender 类型注册。
+- [x] 3.3 在四图四档和复杂蕨叶上比较正式实现与原算法，记录数值耗时、顶点和支撑检查。
+- [x] 3.4 测量 2K/4K 合成输入的耗时、峰值内存与网格上限。
+- [x] 3.5 运行 Cutout、交互、对象、依赖打包相关测试及完整测试，验证现有 Shape 的节点消费。
+
+## 4. SciPy 依赖精简与大坐标约束校验
+
+- [x] 4.1 接入距离脊宽度采样和 NumPy 轮廓简化，保留许可证，移除 scikit-image 并同步锁文件和本地 wheels。
+- [x] 4.2 用实际约束边的端点连通验证替代长度误差判断，覆盖大坐标短边与真实断线回归。
+- [x] 4.3 验证典型图片、高分辨率输入、打包和 Cutout 相关回归。
--- a/openspec/changes/isolate-shared-empty-image-edits/.openspec.yaml
+++ b/openspec/changes/isolate-shared-empty-image-edits/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-06
--- a/openspec/changes/isolate-shared-empty-image-edits/design.md
+++ b/openspec/changes/isolate-shared-empty-image-edits/design.md
@@ -0,0 +1,63 @@
+## Context
+
+`create_image_edit_result()` 和 Job 编辑结果加载入口先准备结果 Image，`replace_empty_image()` 再替换物体引用。当前仅在旧 Image 没有真实用户且没有 Fake User 时删除旧图并恢复源名。Frame 在替换活动物体之后删除合并源物体，随后再次清理图片。
+
+## Goals
+
+- 以其他 Empty Image 的真实引用决定结果是否独立。
+- 共享编辑保护其他 Empty 的数据、显示和动画状态。
+- 单独使用时保留源 Image 身份和完整名称。
+- 统一结果提交、失败恢复与临时数据清理。
+
+## Decisions
+
+### 1. 按文件中的物体引用判断共享
+
+在 `common/image.py` 复用 `is_image_empty()`，遍历 `bpy.data.objects`，检查当前物体以外是否存在 `data` 等于源 Image 的图片 Empty。比较 Blender 数据块身份；找到首个匹配即可结束。隐藏、未在当前 View Layer 显示、其他场景中的对象均参与判断。同一物体链接到多个集合仍是一个对象。
+
+扫描在主线程最终提交时执行，使异步 Job 运行期间新增的共享物体也得到保护。Frame 提供本次成功后将删除的源物体集合，判断时排除这些物体。
+
+`Image.users` 仅继续承担无引用数据清理等生命周期判断。Fake User 是保存设置，材质引用是图片消费者，两者均不代表另一个 Empty Image。
+
+### 2. 结果先准备，按共享关系提交
+
+```mermaid
+flowchart TD
+    A[准备完整编辑结果] --> B[查找操作后仍保留的其他图片 Empty]
+    B --> C{是否共用源 Image}
+    C -->|是| D[当前 Empty 绑定独立结果]
+    C -->|否| E[将结果内容提交到源 Image]
+    D --> F[保留其他 Empty 与源图状态]
+    E --> G[保留源图身份与名称并释放临时结果]
+```
+
+共享分支沿用结果 Image 的创建、打包与 Blender 唯一名称规则，仅改变当前物体绑定。单独使用分支将准备好的结果内容写入源 Image，保留源名称和 Fake User 设置，统一入口返回最终实际使用的 Image。临时结果不作为额外的最终图片保留。
+
+提交需覆盖像素尺寸、颜色空间、Alpha、Packed 内容、文件路径及图片类型；静态像素结果与动画 Job 结果按各自的数据表示处理。继续复用现有像素和动画辅助函数。调用方使用返回的最终 Image，避免保留已释放的临时结果引用。
+
+AnyImage 材质贴图使用独立的 `_color.png` 等数据。用户手动引用源 Image 时，其引用关系保持原样；单独使用分支原位更新产生的内容变化按普通数据共享处理，不额外遍历或迁移材质引用。
+
+### 3. Frame 使用提交后的存活物体集合
+
+Frame 以活动物体为编辑目标，其他本次合并源物体按既有语义删除。只有合并之外仍保留的 Empty 共用活动源图时才分离。提交成功之后删除合并源物体，再清理其确实没有用户的旧图；活动结果名称由统一提交入口负责。
+
+### 4. 提交具有失败恢复边界
+
+完整结果准备好后才修改源数据。共享分支保留现有物体绑定、显示位置和动画设置恢复；原位分支还需保留可恢复的源内容、尺寸、编码及打包状态，直到提交成功。恢复数据应复用现有图片读取与加载能力，在成功和失败时均释放临时资源。取消编辑时不进入提交。
+
+## Risks / Trade-offs
+
+- [原位写入需要同时维护像素、Packed 数据与动画来源] → 通过真实 Blender 数据测试覆盖静态图片、尺寸变化、序列结果及保存重开，验证结果内容实际持久化。
+- [中途失败留下部分写入] → 对内容写入和物体显示配置分别注入失败，验证源图及物体状态恢复。
+- [Frame 的待删除物体导致错误分离] → 测试所有共享者均被合并、合并外仍有共享者两种情况。
+- [已有未归档图片命名规格包含总用户数语义] → 本 change 明确 Empty 共享判定；归档整合时以本规则统一相关要求。
+
+## Migration Plan
+
+1. 增加真实 Blender 引用关系与结果提交回归用例。
+2. 修改公共提交入口，并核对所有本地编辑与 Job 调用方的返回值和清理职责。
+3. 整合 Frame 存活物体判断，运行相关测试和完整测试。
+
+## Open Questions
+
+无产品规则待确认；原位提交对静态与动画 Image 的具体写入步骤通过实现阶段的真实 Blender 回归验证。
--- a/openspec/changes/isolate-shared-empty-image-edits/proposal.md
+++ b/openspec/changes/isolate-shared-empty-image-edits/proposal.md
@@ -0,0 +1,26 @@
+## Why
+
+图片编辑目前通过旧 Image 的总引用数决定是否保留旧数据，无法直接表达用户关心的其他 Empty Image 是否共用原图。需要以真实物体引用关系决定图片分离，使编辑当前 Empty 时其他共用原图的 Empty 保持原样。
+
+## What Changes
+
+- 在整个文件中查找引用同一 Image 的其他 Empty Image，以此决定编辑结果是否需要独立数据块。
+- 存在其他 Empty Image 时，仅将当前物体切换到结果 Image；不存在时更新当前 Image，保留身份与完整名称。
+- 隐藏物体和其他场景中的 Empty Image 同样参与判断；Frame 按合并后仍保留的物体判断共享。
+- 统一本地像素编辑与 Job 结果提交，保留成功、取消和失败时的图片及物体状态约定。
+
+## Capabilities
+
+### New Capabilities
+
+- `empty-image-edit-isolation`: 定义以 Empty Image 引用关系为依据的编辑分离、单独使用时的更新、Frame 合并及失败恢复规则。
+
+### Modified Capabilities
+
+无。当前 `openspec/specs/` 为空；本能力承接已有 change 中的图片编辑命名与替换约定。
+
+## Impact
+
+- `src/anyimage/common/image.py`：共享判断与统一结果提交入口。
+- `src/anyimage/operators/image_edit_tool/` 及调用图片替换入口的 Job 响应：结果提交与 Frame 合并。
+- `tests/test_image_data.py`、`tests/test_alpha_presentation.py`、`tests/test_blender_addon.py` 及相关图片编辑测试。
--- a/openspec/changes/isolate-shared-empty-image-edits/specs/empty-image-edit-isolation/spec.md
+++ b/openspec/changes/isolate-shared-empty-image-edits/specs/empty-image-edit-isolation/spec.md
@@ -0,0 +1,72 @@
+## ADDED Requirements
+
+### Requirement: Sharing is determined by other image Empty objects
+系统 SHALL 在编辑结果提交时，以整个文件中是否存在其他保留的 Empty Image 引用同一源 Image 判断共享，覆盖隐藏物体及其他场景中的物体。判断 SHALL 使用物体与数据块身份，且 SHALL NOT 使用总引用数、Fake User 或界面计数显示作为分离依据。
+
+#### Scenario: A hidden object shares the source
+- **WHEN** 当前物体与一个隐藏的 Empty Image 引用同一 Image，且界面没有显示引用数量
+- **THEN** 系统识别为共享图片
+
+#### Scenario: An object in another scene shares the source
+- **WHEN** 另一场景中的独立 Empty Image 引用当前源 Image
+- **THEN** 系统识别为共享图片
+
+#### Scenario: One object is linked to multiple collections
+- **WHEN** 仅当前 Empty 引用源 Image，且该物体链接到多个集合
+- **THEN** 系统按单独使用处理
+
+#### Scenario: Non-Empty references exist
+- **WHEN** 仅当前 Empty Image 引用源图，源图另有 Fake User 或用户手动建立的材质引用
+- **THEN** 系统按单独使用处理
+
+#### Scenario: Sharing changes during a job
+- **WHEN** Job 提交后、结果应用前，另一个 Empty Image 开始引用源图
+- **THEN** 最终提交按共享图片处理
+
+### Requirement: Shared edits update only the current Empty
+存在其他保留的 Empty Image 共用源图时，系统 SHALL 仅将当前物体绑定到独立编辑结果，并保持其他 Empty 的 Image 绑定、原图内容和显示状态。结果 SHALL 请求源 Image 的完整名称，由 Blender 处理唯一性后缀。
+
+#### Scenario: Two Empty objects share one image
+- **WHEN** A 与 B 共用同一 Image，用户编辑 A
+- **THEN** A 使用编辑后的独立 Image，B 仍引用原 Image，原图像素、Packed 内容、名称及 B 的显示和动画设置保持原样
+
+### Requirement: A sole image Empty retains its Image identity
+没有其他保留的 Empty Image 共用源图时，系统 SHALL 将编辑结果提交到源 Image，保留数据块身份、完整名称与 Fake User 设置，且成功后 SHALL 释放本次临时结果数据。用户手动建立的其他引用 SHALL 保持原绑定。
+
+#### Scenario: A sole Empty is edited
+- **WHEN** 唯一使用源图的 Empty 完成图片编辑
+- **THEN** 其 Image 身份和完整名称保持不变，内容及尺寸更新为结果，保存重开后内容正确，且不保留额外结果 Image
+
+#### Scenario: A user manually references the source in a material
+- **WHEN** 唯一 Empty 的源图另被用户手动用于材质
+- **THEN** 编辑按单独使用提交，材质引用仍绑定同一 Image
+
+#### Scenario: An animated job result is committed
+- **WHEN** 单独使用的 Empty 收到动画图片编辑结果
+- **THEN** 源 Image 身份和名称保持不变，帧来源及打包结果更新正确，物体动画播放设置按现有工具语义配置
+
+### Requirement: Frame considers surviving Empty objects
+Frame SHALL 按成功合并后仍保留的 Empty Image 判断活动源图是否共享，并在结果提交成功后执行合并源物体删除。
+
+#### Scenario: All other sharing objects are merged
+- **WHEN** A 与 B 共用源图，Frame 将 B 合并到活动物体 A，且没有其他 Empty 使用源图
+- **THEN** A 的源 Image 原位更新，B 按合并规则删除
+
+#### Scenario: A sharing object survives outside the merge
+- **WHEN** Frame 将 B 合并到 A，合并之外的 C 仍引用 A 的源图
+- **THEN** A 使用独立结果，C 及其源 Image 保持原样
+
+### Requirement: Failed or cancelled edits preserve source state
+统一提交入口 SHALL 覆盖本地编辑与 Job 图片编辑。取消或提交失败时，系统 SHALL 保留或恢复源 Image 内容与身份、物体绑定、显示及动画设置，并释放本次临时资源。
+
+#### Scenario: Sole-image commit fails
+- **WHEN** 原位提交在写入内容或配置显示期间失败
+- **THEN** 源图内容、尺寸、Packed 数据及物体状态恢复到提交前状态，临时结果被清理
+
+#### Scenario: Shared-image commit fails
+- **WHEN** 共用图片的当前 Empty 提交失败
+- **THEN** 当前物体恢复原绑定，其他 Empty 及原图保持原样，临时结果被清理
+
+#### Scenario: An edit is cancelled
+- **WHEN** 用户预览编辑后取消
+- **THEN** 原图和所有 Empty 的绑定及显示状态保持原样
--- a/openspec/changes/isolate-shared-empty-image-edits/tasks.md
+++ b/openspec/changes/isolate-shared-empty-image-edits/tasks.md
@@ -0,0 +1,22 @@
+## 1. 固定共享判断与身份约定
+
+- [x] 1.1 增加真实 Blender 数据测试，覆盖两个 Empty 共享、隐藏共享者、跨场景共享者及同一物体链接多个集合，按数据块身份验证判断结果。
+- [x] 1.2 增加单独使用回归，覆盖普通图片、Fake User、手动材质引用，验证结果内容、源 Image 身份、完整名称及临时 Image 数量。
+- [x] 1.3 在 `common/image.py` 复用 `is_image_empty()` 实现其他存活 Empty 的引用查找，支持 Frame 排除待删除对象，并验证提交时重新判断共享。
+
+## 2. 统一图片编辑提交
+
+- [x] 2.1 调整公共结果提交入口，共享分支只更新当前物体绑定，验证其他 Empty 与原图像素、打包及动画状态保持不变。
+- [x] 2.2 实现单独使用时的静态结果原位提交及临时结果释放，覆盖尺寸变化、Alpha、颜色空间、Packed 内容、名称和 Fake User 保留。
+- [x] 2.3 实现动画 Job 结果原位提交，验证帧来源、打包内容、播放设置及保存重开；复用现有图片与动画辅助函数。
+- [x] 2.4 为内容写入和显示配置注入失败，完善源图内容及物体状态恢复，验证失败与取消不残留临时数据。
+
+## 3. 整合工具与 Frame
+
+- [x] 3.1 检查全部 `replace_empty_image()` 调用方，包括 Mask、Rectify、Frame、Remove Background 和 Upscale，使用最终返回 Image 并统一临时结果清理职责。
+- [x] 3.2 Frame 按合并后存活对象判断共享，移除重复命名处理，覆盖共享者全部参与合并及外部共享者保留两种情况。
+
+## 4. 验证
+
+- [x] 4.1 运行相关图片数据、Alpha、图片编辑及 Operator 回归，验证连续编辑、保存重开、共享保护和异常恢复。
+- [x] 4.2 运行 `uv run pytest`，确认全部测试通过。