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.
5.8 KiB
Context
O Image Depth Balloon 当前以原始 Cutout 网格作为对称平面上的轮廓，通过 o_balloon 和深度差构建两侧。新需求已经用用户提供的小车图完成独立实验：正面投射后截留正 Z 区域，两侧围绕固定 XY 平面镜像，并以直壁连接对应外边界。
实验文件位于 C:/Users/icrdr/AppData/Local/Temp/anyimage-car-symmetry/：car-depth-balloon-fast-modes.blend、fast_balloon.py、performance-results.json、mode-validation.json。这些是可复核的实验材料，正式实现和测试自行提供所需资源。
Goals / Non-Goals
Goals: 双模式、手势预设、完整对称网格、独立且可复用的节点构建、统一命名。
Non-Goals: 本变更不包含旧资产兼容层、AI 模型调整或自动推断最佳车身对称方向。
Decisions
名称与手势
| 对象 | 名称 |
|---|---|
| 功能与菜单 | Depth Symmetry |
| 节点组 | O Image Depth Symmetry |
| 构建模块与入口 | image_depth_symmetry.py / build_image_depth_symmetry_group() |
| Shape 标识 | DEPTH_SYMMETRY |
| Mode 顺序 | Balloon、Projected |
Balloon 描述原有鼓起方式；Projected 描述新模式的投射轮廓。功能名称表达两者共同的对称职责，避免用其中一个模式命名整个节点组。
| 手势 | Depth Cutout（现有） | Depth Symmetry |
|---|---|---|
| Lasso | Balloon | Balloon |
| Polyline | Shell | Projected |
在 Cutout 对象创建阶段按 gesture 设置 Mode。预设只影响初值，用户仍可直接切换节点 Mode。裸节点默认 Balloon，保持原有入口的默认行为。
直接构建 Projected 正面
复用 _position_field 读取 Depth Image 的相机 XYZ，乘以 Uniform Scale，将 Y 转为现有 Cutout 坐标约定，以 Reference Depth − metric depth 构建 Z。Depth Scale 沿用已验证的平面坐标与相机坐标插值，并缩放深度差。
将 Depth Direction 对应的方向对齐到局部 Z 轴，输出成形坐标中的正面。Reference Depth 和 Depth Direction 共同改变位移与投射后的轮廓；最终镜像面固定在成形坐标 Z=0，不把镜像结果转回倾斜平面。既有 Depth Axis 作为统一的最终坐标变换保留。
复用公共边界平滑，随后在 POINT 域判断负 Z，并在 FACE 域判断是否包含越界顶点。删除包含越界顶点的整面及其失去面的边线、孤点。仅保留正 Z 面，不产生压扁在对称平面上的外围裙边。平面附近使用与几何尺度相适应的小容差处理零厚度退化。
采用整面删除，因为它只依赖现有网格与字段求值；相较精确裁切，边界具有网格分辨率级别的近似。新分支不使用 Mesh Boolean，也不嵌套 Depth Plane、Depth Cutout 节点组。
镜像与直壁
先完成正面和平滑，再镜像到负 Z，避免封闭后的全网格平滑破坏直壁。以边的面邻接数识别正面外边界，将每个边界点 (x,y,z) 与 (x,y,-z) 连接；生成的侧壁沿 Z 轴延伸，其法线垂直于 Z 轴。保留正背面平滑着色，侧壁使用平面着色。
合并对应顶点，正确处理对称平面上的零厚度边。Double Sided 打开时生成完整封闭网格；关闭时沿用已验证原型的正面预览行为。Balloon 分支原有 Double Sided、Thickness、平滑等语义保持不变。Thickness 继续控制 Balloon 轮廓；Projected 的形体由 Depth Scale、Reference Depth、Depth Direction 控制，不引入未经验证的厚度推断。
复用与模式分派
复用公共节点接口、深度采样、岛清理、边界平滑、普通平滑和属性函数。节点内部保留直接构建的两条几何分支，通过 Mode 选择；共享最终输出和坐标约定，不通过嵌套节点组包装旧实现。
Projected 需要局部辅助函数时放在该业务模块；只有确有其他消费者的函数才进入 common。UV 和现有命名属性继续随拓扑传递，新增临时属性需要明确生命周期；源码与保存资产中 Capture Attribute 数量均为零。
性能与验证
同一小车输入、相同参数与 3 次边界平滑，预热 4 次后连续修改 Reference Depth，记录 24 次依赖图求值的中位数。外部实验的双模式 Projected 分支结果如下：
| 输入顶点 | 布尔原型 | 双模式直接构建 | 提速 |
|---|---|---|---|
| 27,860 | 174.9 ms | 30.9 ms | 约 5.7 倍 |
| 165,771 | 960.7 ms | 135.6 ms | 约 7.1 倍 |
这些数值是当前机器的对比证据，不作为跨机器测试断言。正式验证保留同输入、同平滑、同参数的对照，并分别记录 Reference Depth 与 Depth Direction 调整耗时。几何测试覆盖封闭性、顶点流形性、面绕序、XY 镜像、直壁法线、越界删除、空结果及模式切换；Balloon 分支与变更前的基准几何比较。
Risks / Trade-offs
- 整面删除使切口随网格密度离散变化 → 使用已有采样密度控制，比较多个密度与连续参数变化，明确其为近似边界。
- 深度噪声可能形成小岛或点接触 → 复用岛清理，测试连通性与顶点流形性，退化处删除无效拓扑。
- 在补壁后平滑可能令侧壁弯曲 → Projected 的平滑在正面阶段完成，再镜像和补壁。
- 只在中等网格测量可能掩盖扩展成本 → 同时验证普通与加密输入，记录求值而非渲染耗时。
- 资产与代码名称失配 → 同步重命名 Shape 标识、模块、校准函数、构建/校验清单和界面文本，构建保存资产后检查旧引用。
Migration Plan
实现时整体替换旧名称并更新相关代码、测试和节点资产，不保留旧路径或别名。通过 uv run node-group build 构建并验证 O_AnyImage.blend，检查新组存在、旧组不再由构建产出。已保存在用户工程中的旧节点组不执行自动扫描或重写。