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/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 相关回归。