nan
076a8c90f1
- Introduced the two-times upscale specification detailing requirements for unified output, fixed model presets, arbitrary dimensions, and consistent job behavior. - Added scenarios for existing models, repeated upscale, and handling of alpha preservation. - Created the unified depth plane specification outlining geometry modes, stable interface, and asset evaluation. - Defined scenarios for mode switching, relief and camera preservation, and validation of delivered assets.
6.6 KiB
Context
当前 Fine Outline 使用轮廓近似、内部支撑、自由点松弛和 Blender CDT，再通过 support_flat_regions 拆分边界弦及扇形补面；普通模式在 cutout_domain 中采用另一套三角化及 refine_balloon_triangles。两条最终建网路径需要统一，减少质量细化后的再次碎分。
临时实验采用相同轮廓、延伸中线和 10°目标，Tangle 的鱼/甲虫分别为 2797/655 面，Triangle 为 2529/605 面；Tangle 的六张样例均通过面积、孔洞数、中线覆盖和非退化检查。这些是外部 Python 实验，尚不能替代 Blender 验收。实验保留全部有效孔洞，因此新增微孔策略需要独立验证。
现有世界 Edge Length 与相对下限已完成，所有几何尺度沿用其有效间距 h。早期变化中的 Mesh Detail 档位描述以该世界边长行为为准。
Goals / Non-Goals
Goals: 在统一基础网格中保持轮廓、有效孔洞和细分支内部支撑，控制普通区域密度，使用可随 Blender 分发的纯 Python 后端。
Non-Goals: 本次不新增算法选择器、纯平面专用算法或 C++ 二进制，保留现有高度算法。
Decisions
1. 随包分发固定版本的 Tangle Python 源码
第三方实现放在 src/anyimage/operators/cutout_tool/tangle.py，MIT 文本放在现有 src/anyimage/licenses/。实施时固定上游提交及源码哈希，记录来源与必要本地改动，避免跟随浮动 master。实验版本标识为 0.4.18，实际分发以核验的提交为准。
将数值调用整理为内存输入输出：点、带身份的约束边、孔内种子、质量参数，返回顶点、三角面和约束来源。保留上游算法结构，业务预处理和验证由 Cutout 网格模块负责。调用不依赖命令行参数、临时 .poly 文件或额外 Python 进程；隔离 Decimal 精度、模块状态和退出处理，重复调用互不影响。优先使用已有标准库功能，Tangle 本身不新增第三方包。
2. Fine Outline 决定建网区域与轮廓精度
从当前 Alpha Threshold 和 Selection 得到前景，沿用极小独立前景分量清理规则。先按世界平面度量确定有效 h，再做孔洞策略，之后重新提取组件与轮廓：
| 模式 | 内部封闭孔洞 | 外轮廓 | 支撑依据 |
|---|---|---|---|
| 开启 | 保留有效孔洞，填充微孔 | 随 h 保留精细形状 | 微孔处理后的区域 |
| 关闭 | 全部填充 | 随 h 平滑、概括 | 填孔及轮廓概括后的区域 |
微孔初始规则采用双条件：世界平面中的包围盒最长边 ≤ 0.25h，且面积 ≤ 0.04h²，才填充。长而窄的孔保留；0.9h 的孔不会因略小于 h 被移除。实施中先按此保守规则建立边界用例，真实图只用于校准与记录，不依赖其像素尺寸定义阈值。填孔后重建拓扑，处理孔中岛合并，避免重复面。
几何填孔不改写图片或材质 Alpha。背景连通的凹口不是封闭孔洞，仍参与外轮廓。简化后的最终轮廓必须通过有效性检查，内部支撑直接来自最终网格。
3. 质量网格按需补足内部支撑
输入 PSLG 仅包含最终轮廓约束，在与 h 关联的归一化坐标中合并重合点、分割点落边并保留约束身份。各组件以辅助三角化的最大面中心作为初始内部点，孔内种子必须位于对应孔内。像素角自接触处按相邻边长的 1/8 分离，消除零宽连接；简化结果重新验证，保留有效孔洞。
Tangle 使用 10°目标最小角和最大面积 √3/4 × h²。完成面积、孔洞、组件和边界约束校验后，给两端都在边界上的内部边添加共享中点，并一致拆分相邻面；只有孤立全边界三角形需要补重心。已有内部支撑的区域保持原网格。此操作单次完成，新增点数受组件累计顶点上限约束，不重新进行全局三角化。
局部拆分保持轮廓、面积和面朝向，形成细分支到主体的连续内部支撑。它可能降低部分三角形最小角，10°作为基础三角化目标，最终角度与凸起效果共同验收。删除不再使用的中线图、宽度距离场和路径约束处理；辅助 Blender CDT 用于初始点和孔种子。
低分辨率深度投影可能将相邻轮廓采样映射到同一点。深度 Cutout 在投影和平滑后，以平均边长的百万分之一合并已连接重合点，再求壳体厚度，避免数值退化面翻转法线。节点资产与实际求值测试同步验证。
4. 验收同时覆盖平面几何和高度
- 自动化用例使用可再生的合成多孔形状、弯曲细腿、尖角、孔中岛和点落边约束，避免测试依赖用户临时图片。
- 最终网格验证面积、孔洞及组件数量、非退化面、轮廓覆盖；细分支到主体的内部网格边连续连接，内部支撑高度为有限正值。
- 六张用户图用于本地视觉和性能复核，重点比较鱼的多孔区域、甲虫上角到根部及细腿。报告面数、低于 10°占比、小面面积占比、压平面积与位置、耗时，不要求三角面索引或面数与实验逐项相同。
- 分别验证 Fine Outline 两种模式及世界缩放、非均匀缩放、分辨率和透明画布变化。关闭模式使用填孔后的期望拓扑。
- 在项目支持的 Blender 环境中验证源码导入、重复数值调用、基础网格创建与同步/AI 返回路径；包括现有分发覆盖的 Python 3.11/3.13 环境。缺少其中环境时明确记录，不以外部解释器验证代替。
Risks / Trade-offs
- 纯 Python 在密集输入上变慢 → 用预热与重复测量分别记录三角化、完整建网与 Blender 创建；对大规模多孔输入实现确定的迭代/顶点资源上限和明确失败结果，不静默降级。
- 上游命令行实现含进程级状态 → 在数值接口测试 Decimal 上下文、错误退出、重复调用与失败后恢复。
- 孔洞密集或边界尖角仍要求小面 → 保守微孔策略和质量统计共同控制，避免为了禁止短边破坏主体。
- 局部支撑拆分降低部分面角度 → 复核最终角度和粗网格凸起效果。
- 六张图覆盖有限 → 合成回归、Blender 实测与高复杂度资源测试共同验收。
Migration Plan
先固定后端与数值接口，再接入统一区域、中线及三角化，最后清理旧调用。检查源码和许可被现有打包规则收录；仅在实际改变依赖元数据时同步相关清单。运行相关测试，不构建扩展包或同步其他说明文档。若验收失败，在当前实现阶段修复；已集成变更的回退使用版本控制恢复整个变更，不保留运行时旧算法分支。