Add cutout profile and teddy balloon height calculations

- Implemented cotangent Poisson field and Poisson balloon profile in cutout_profile.py.
- Added teddy balloon heights calculation and related functions in cutout_teddy.py.
- Introduced interaction utilities for image editing in interaction.py.
- Developed depth normalization and analysis functions in cutout_depth.py.
- Created a validation script for cutout assets in validate_cutout_asset.py.

README.md

@@ -10,7 +10,7 @@ AnyImage 是一个 Blender 扩展，可以把一张照片、一段视频或一
 
 - 在 3D View、Node Editor 与绘画模式中按 `Ctrl+V`（macOS 为 `Cmd+V`）直接粘贴并 Pack 剪贴板图片
 - 不运行 AI，把 Image Empty 转换为可实时调整 Thickness 与 Subdivide 的 Mesh Plane
-- 从 Image Empty 套索提取不规则区域，通过 Poisson 或 Teddy / Chordal Axis 成成封闭 Balloon，并可用 BEN2 分析轮廓、MoGe-2 添加可调深度；源 Empty 保持不变
+- 用 Cutout 套索从 Image Empty 生成 Surface、Balloon、Depth Balloon 或 Depth Surface；四种结果共用单面基础薄片、局部方向与清理逻辑
 - 用 Image Box / Lasso / Line / Polyline 直接清理 Image Empty；按 `F` 反选，也可用 BEN2 细化选区
 - Image 编辑会直接更新未共享的图片；图片被多个 Image Empty 共用时，只为当前 Empty 分离编辑结果
 - 用 Image Perspective 勾勒四个角点，把透视四边形矫正为矩形裁切图，并沿用源 Image Empty 的空间朝向
@@ -36,7 +36,7 @@ Environment Bootstrap 使用连续的 0–100%：uv 为 1–20%、Python 为 20
 
 选中 Image Empty 后，`AnyImage` 会显示在右键菜单最上方。Mesh / Depth / Surface 转换为一组，Remove Background 与 Upscale 作为图片处理归为下一组，环境入口位于最后。Environment 或必需模型未就绪时，点击 `Convert to Depth Plane…`、`Convert to Surface…`、`Remove Background` 或 `Upscale` 会打开对应准备对话框：Environment 未安装时入口显示 `Set Up AI Environment…`，安装 Environment 与默认模型；Environment 已安装但默认模型缺失时入口显示 `Download Required Models…`，只补齐缺失模型。全部就绪后，菜单入口改为 `AI Environment Settings…`，并打开 AnyImage 扩展偏好设置。
 
-其他 AI 模型统一在 AnyImage 扩展偏好设置中按需下载。`Balloon Lasso Tool` 的本地几何功能始终可用；AI 未就绪时，只禁用 Tool Settings 中的 `Contour`、`Depth` 与 Depth Model，并在同处根据状态显示 `Set Up AI Environment…` 或 `Download Required Models…`。共享的 AI 状态检测直接检查 Environment 和 Storage Root 的 `models/` 文件，不会仅因打开菜单或设置而启动 Job Server。
+扩展偏好设置先显示 Environment 状态与 Diagnostics，再依次提供默认展开、可折叠的 Depth & Normal、Remove Background、Upscale 和 Cutout 功能区。Depth Model 按三档 MoGe-2、两档 DA3 排列；选择 DA3 时会提示该模型不能生成 normal。可选模型的状态与下载按钮位于对应模型选择项下方，BEN2 则归在 Remove Background。共享的 AI 状态检测直接检查 Environment 和 Storage Root 的 `models/` 文件，不会仅因打开菜单或设置而启动 Job Server。
 
 ## 快速上手
 
@@ -46,7 +46,7 @@ Environment Bootstrap 使用连续的 0–100%：uv 为 1–20%、Python 为 20
 
 ### 转换为普通图片平面
 
-选中 Image Empty 后，右键选择 `AnyImage > Convert to Mesh Plane`。该操作不运行 AI，会创建带图片材质和 `O Mesh Plane` Geometry Nodes 修改器的基础四边形。`Thickness` 与 `Subdivide` 都在修改器中实时成成；`Subdivide` 使用二分级别（`3` 为短边 `8` 段），`Thickness = 0` 时结果为真正的单面。操作会立即执行；创建后可在 Last Operation 中调整 `Shadeless` 和 `Keep Original`，调整时保持源图片的世界位置、旋转与缩放。完整说明见 [Mesh Plane](docs/mesh-plane.md)。
+选中 Image Empty 后，右键选择 `AnyImage > Convert to Mesh Plane`。该操作不运行 AI，会创建带图片材质和 `O Mesh Plane` Geometry Nodes 修改器的基础四边形。`Thickness` 与 `Subdivide` 都在修改器中实时生成；`Subdivide` 使用二分级别（`3` 为短边 `8` 段）。`Thickness = 0` 时结果为真正的单面。操作会立即执行；创建后可在 Last Operation 中调整 `Shadeless` 和 `Keep Original`，调整时保持源图片的世界位置、旋转与缩放。完整说明见 [Mesh Plane](docs/mesh-plane.md)。
 
 ### 转换为立体面片
 
@@ -68,7 +68,7 @@ Lasso 绘制时与 Box、Line、Polyline 一样显示白色虚线轮廓和淡灰
 
 ### 四点透视矫正
 
-`Image Perspective` 是 Image Mask 工具组之后的独立工具，位于该组与 Balloon Lasso 之间。四个角可以按任意顺序点击，完成后会在源图片坐标中自动求出不交错的凸四边形，并以原图 X/Y 方向确定输出旋转。绘制时显示白色虚线和半透明选区面，`Backspace` 删除最近一个角点，右键或 `Esc` 取消；切换其他工具也会立即退出。首次点击遵循同一选择规则。Perspective 不依赖当前 View 的相机内参，因此透视和正交 View 都可以使用。
+`Image Perspective` 是紧随 Image Mask 工具组之后的独立工具。四个角可以按任意顺序点击，完成后会在源图片坐标中自动求出不交错的凸四边形，并以原图 X/Y 方向确定输出旋转。绘制时显示白色虚线和半透明选区面，`Backspace` 删除最近一个角点，右键或 `Esc` 取消；切换其他工具也会立即退出。首次点击遵循同一选择规则。Perspective 不依赖当前 View 的相机内参，因此透视和正交 View 都可以使用。
 
 第四个角点按下时会在 Viewport 中央显示带蓝色边框的矫正图片预览，中央显示当前比例，下方显示鼠标操作提示；鼠标同时移到 Viewport 中心，为左右两个方向保留相同的调节空间。水平移动连续调整宽高比，按住 `Ctrl` 吸附到 `1:1`、`4:3`、`3:4`、`16:9`、`9:16`，下一次左键确认并创建；`Backspace` 返回第三点，右键或 `Esc` 取消。初始比例取四边形两组对边的平均长度比。预览使用一次成成的 512 × 512 临时图片，移动鼠标时只改变 UI 显示比例。
 
@@ -80,27 +80,17 @@ Image Perspective 是 deform 工具，不提供 Refine 或反选。它与其他
 
 ### Cutout 基础面与四种形状
 
-在 Object Mode 的 3D Viewport 左侧工具栏选择 `Cutout`，沿 Image Empty 绘制后可从四个方向选择 Cutout、Balloon、Depth Balloon 或 Depth Surface；双击会选择完整图片。`Point Spacing` 以原图像素为单位控制规则三角格点间距，裁切范围大小不会改变密度。未启用 `Refine Selection` 时，几何只跟随套索，忽略原图 Alpha；即使启用 `Normal` 并改走 Job，图片边框外的选区也会保留。启用 Refine 后才使用 BEN2 Alpha 收紧几何选区，框外部分会随最终 AI Alpha 被裁掉。自交轨迹按非零环绕规则填充：同方向的重叠区域保留，只有反方向抵消的内环形成孔洞。未 Refine 的普通选区必须与原图可见像素相交。基础面内部使用均匀六角格点，平滑轮廓作为约束边界；小选区会自动缩短边界采样间距，避免在较大的 `Point Spacing` 下被误判为空，同时不增加内部格点密度。Cutout 的 Thickness 以场景距离沿图片平面法线对称加厚，前盖、背面和轮廓侧壁均保持朝外。套索或 Refine 的最终 Alpha 会确定紧凑矩形裁剪范围和几何轮廓，也用于构造 MoGe-2 局部分析图：选区内保留当前图片的原始 RGB 与有效 Alpha，图片边框外和选区外 RGBA 全部置零。材质 Color 使用同一裁剪范围内未乘选区 Alpha 的当前图片像素，只保留图片原有 Alpha；因此不会因几何 mask 再次产生透明边。当前图片若为 Upscale 结果，颜色、深度和法线都基于高清图的所选区域。裁剪后的 Color 与 normal 可以是非正方形，网格位置和 UV 会映射回原 Image Empty 中对应区域。几何只保留最终 Alpha 大于等于 `0.5` 的区域，边缘低置信度面会被剔除。未启用 Refine 且关闭 `Normal` 时，Cutout 与 Balloon 会直接在 Blender 内完成遮罩、轮廓提取和建面，不启动 BlendJob。`Normal` 默认关闭；启用后才通过 MoGe-2 成成 normal 纹理，并改用 Job。Depth Surface 直接使用 MoGe-2 原成的 object-space normal；Cutout、Balloon 与 Depth Balloon 会依据成品网格的平滑 TBN 另行烘制 tangent-space normal。
+在 Object Mode 的 3D Viewport 左侧工具栏选择 `Cutout`，沿 Image Empty 绘制后可从四个方向选择 Surface、Balloon、Depth Balloon 或 Depth Surface；双击会选择完整图片。`Point Spacing` 以完整原图像素为单位控制规则三角格点间距，裁切范围大小不会改变密度。未启用 `Refine Selection` 时，几何只跟随套索；启用后才使用 BEN2 Alpha 收紧选区。`Normal` 默认关闭；启用后才通过 MoGe-2 生成 normal 纹理。未启用 Refine 且关闭 Normal 时，Surface 与 Balloon 完全在 Blender 内生成，不启动 BlendJob。
 
-完整说明见 [Cutout](docs/cutout.md)。
+四种结果的源网格统一为真正的单面薄片，并分别使用 `O Image Surface`、`O Image Balloon`、`O Image Depth Balloon`、`O Image Depth Surface` 四个独立 Geometry Nodes。局部纸面统一位于 YZ 平面，局部 `+X` 朝纸面内侧，局部 `-X` 是外侧和深度箭头方向；对象原点统一位于裁切图片中心，对象矩阵补偿后薄片仍落在源 Image Empty 的原位置。`Thickness = 0` 时保留单面；Surface 与 Depth Surface 的 Thickness 是场景距离，Balloon 与 Depth Balloon 的 Thickness 是 `o_balloon` 高度倍率，默认 `1` 保留算法原值。加厚按整片连通区域处理，内部三角边不生成侧壁。Surface 与 Depth Surface 会以边界三角边的中位长度为目标宽度，沿 Thickness 方向自动增加侧壁分段，使侧壁面片尽量接近正方形；Balloon 与 Depth Balloon 不增加这些分段线。
 
-`O Image Depth Surface` 将 `O Smooth` 的 Repeat Zone、双域边界采样和法线权重节点直接展开在主节点图中，并固定按 `Pin Sharp = 1`、`Pin Boundary = 1` 计算，不暴露这两个参数；`Iterations` 默认 `1`、最小可设为 `0`。`Depth Continuity` 默认 `0`，采用最宽松的断层阈值。Thickness 保持正面的深度表面不动，只向背面挤出。
+四个修改器都有默认折叠的 `Options` 面板，`Cleanup` 统一放在其中。节点按 Mesh Island 累计离散面面积，并以基础面三角形的中位面积自动估算 Point Spacing 尺度；默认 `1` 会删除面积小于约一个点间距平方的孤立小面，因此无需在 Cutout 创建后写入绝对场景单位阈值。Depth Balloon 的 `Base Plane`，以及 Depth Surface 的 `Depth Continuity`、`Smooth` 也收纳在该面板。
 
-### 套索成成 Balloon
+四种 Cutout 形态都会在创建基础网格时计算 Balloon profile，并统一写入 `FLOAT/POINT` 属性 `o_balloon`；不再写入 `o_boundary`。AnyImage 扩展 Preferences 的 **Balloon Profile** 可选择 Poisson 或 Teddy，两个 Balloon 节点组只读取属性，不再自行估算轮廓。两个 Depth 形状都从内部打包的浮点深度图片采样，不把深度写成点属性；内部深度 Image datablock 统一使用 `_depth.exr` 后缀，`Depth Image` socket 在修改器中隐藏。
 
-选中单张图片的 Image Empty，右键打开 `AnyImage` 子菜单并选择 `Balloon Lasso Tool`。Blender 会激活 3D Viewport 左侧工具栏底部、位于独立 Image Perspective 之后的 Balloon Lasso；Image Mask 工具组与 Add Cube 之间保留一个间隔。Balloon 使用 Poly Build 的绿色图标、Annotate 同款铅笔光标，Tool Header 与状态栏共同提示当前工具状态，不再用黄色外框或强制修改 Shading、Overlay。Blender 的公开 Workspace Tool API 不支持按 Active Object 动态隐藏工具，因此图标在 Object Mode 中保持可见，但只有 Active Object 是 Image Empty 时才能启动 Stroke。
+Depth Balloon 的 Base Plane 位于当前裁切后网格的中心，而不是原图中心。默认朝向由选区内有效 MoGe 深度进行稳健平面回归；细长选区会保留长轴趋势，同时抑制缺少空间支撑的短轴倾角。Single Arrow 沿局部 `-X` 指向实际深度方向；沿箭头移动的场景距离与前表面的同向位移严格一致。Geometry Nodes 会先用 Base Plane 校正深度，再让 `Depth Scale` 乘整个校正结果；因此 `Depth Scale = 0` 时 Base Plane 和深度图都不再改变深度分支。`Double Sided` 默认关闭，使背面保持 Balloon 厚度，开启后则把受 Base Plane 调整后的最终前表面关于对象局部 YZ 平面完整镜像；Base Plane 只定义正面的朝向与基线，不会移动对称中心。Depth Surface 先按深度图片位移和断层剔除，再清理新产生的小岛、加厚并执行展开的 O Smooth 结构；`Iterations` 默认 `1`，`Depth Continuity` 默认 `0`。
 
-按住左键沿目标轮廓绘制，松开后成成一个带原图 UV 的封闭网格。每次拖动都是一个独立完成的顶层 `Extract Balloon` Operator，工具本身继续保持激活，下一次拖动会创建另一个 Balloon；因此 `Ctrl+Z` 只撤销最近一次成成，`Ctrl+Shift+Z` 重做。每次成成后源 Image Empty 都保持选中和 Active。未绘制时没有持续 Modal 拦截事件，视图导航和其他原成快捷键由 Blender 正常处理；绘制中可用右键或 `Esc` 取消当前轨迹。选择左侧工具栏中的其他工具即可离开 Balloon Lasso。
-
-- `Mode`、`Thickness`、`Resolution (m)`、`Reuse Material`、`Contour`、`Depth` 和启用 `Depth` 后出现的 `Depth Model` 显示在 Tool Header / Tool Settings
-- `S`：调用 Blender 原成 Radial Control 调节 Thickness；通过 `zoom_path` 把默认 `1.0` 映射为约 100 px 的交互圆，软上限为 `5.0`，不设硬上限
-- `D`：调用 Blender 原成 Radial Control 调节 Resolution；通过独立 `zoom_path` 把默认 `0.1 m` 映射为约 100 px 的交互圆，数值越小网格越密
-
-`Resolution (m)` 会根据 Scene Unit Scale 换算为网格使用的世界距离，因此不同单位设置下仍代表相同的物理采样间距。Poisson 模式使用尺度无关的求解判断，支持 `0.02 m` 等较密采样。两个 AI 选项默认关闭；`Contour` 使用 BEN2 Alpha 严格大于 `0.5` 的最大连通前景重建轮廓，`Depth` 使用所选 MoGe-2 模型。MoGe 的物理距离会先减去稳健拟合的基面，再换算为不受绝对拍摄距离影响的相对起伏；近侧与远侧信号都保留，不削顶、不截平。
-
-Depth Balloon 使用局部 X 作为深度轴，并创建 `<Balloon> Base Plane` Single Arrow Empty。Empty 的旋转定义基面朝向，沿自身局部 Z 移动则调整 middle level。默认深度校准为 `修正深度 = (0.5 × 相对基面深度 + 原始 Balloon 最大半厚度) × Depth Strength`；原始最大半厚度来自成成后的固定网格，不受修改器 `Thickness` 影响。这在 `Thickness = 1` 时等价于旧参数的 `Depth Strength = 0.5` 和两倍半厚度基面偏移。节点再以 Smoother Step 中心程度插值修正厚度与修正深度；`Thickness` 只控制厚度分支，`Depth Strength` 只控制深度分支。`Double Sided Depth` 默认关闭，使背面维持稳定厚度。
-
-MoGe normal 会转换成适配 Balloon UV 的 tangent-space `normal.png`，由统一的 `O Image Layer` 材质补回网格分辨率未能表达的细节；`Normal Scale` 默认 `1`，`Bump Scale` 默认 `0`，未连接 normal 时使用 `[0.5, 0.5, 1.0, 1.0]` 中性值。Balloon 材质通过 Custom Properties 直接保存源 Image datablock 引用，不依赖材质名或节点组名识别；勾选 `Reuse Material` 时优先复用同一 Image、同一材质类型的标记材质。Depth Balloon 共用一张原图尺寸的 normal，后续套索会把自己的有效区域合并进去，重叠区域采用最新结果。旧材质仍保留节点识别回退。当前只支持静态图片。
+Surface、Balloon 与 Depth Balloon 的 MoGe normal 会依据最终网格 TBN 烘成 tangent-space 纹理；Depth Surface 直接使用适配新局部轴向的 object-space normal。完整说明见 [Cutout](docs/cutout.md)。
 
 ### 去除背景
 
@@ -147,7 +137,7 @@ Layer Color 同时驱动 Principled BSDF 的 Base Color、Subsurface Radius 和
 
 生成的颜色、深度和法线 Image datablock 分别使用 `_color.png`、`_depth.exr`、`_normal.png` 和 `_upscale.png` 后缀，让 Blender 保持对真实图片格式的识别。
 
-AnyImage 支持视频（mp4、mkv、mov 等）和序列帧，会逐帧处理并成成逐帧对应的立体面片。色色图片与 `.depth` 按源 Empty Image 的类型载入：普通单图为 `IMAGE`，Movie/Sequence 即使只处理一帧也仍为 `SEQUENCE`。处理范围默认
+AnyImage 支持视频（mp4、mkv、mov 等）和序列帧，会逐帧处理并成成逐帧对应的立体面片。`_color.png` 与 `_depth.exr` Image datablock 按源 Empty Image 的类型载入：普通单图为 `IMAGE`，Movie/Sequence 即使只处理一帧也仍为 `SEQUENCE`。处理范围默认
 跟随 Empty 上设置的 `Image Frames` 与 `Offset`，不需要额外配置。DA3 的转换任务复用同一个 ONNX
 Session 逐帧推理，显存峰值不随视频帧数平方增长。Upscale 也会逐帧成成受输出上限约束的 4× 色色序列并写回 Empty。Debug 只保存模型 API 的直接返回：DA3 多帧输入
 保留联合推理，MoGe-2、BEN2 与三档高清模型按各自的单图 API 逐帧保存。高清 Debug 输出 4× RGB `prediction*.png`，不做强度混合或图片替换；三个模型都由适配层自动分块，因此接受任意图片宽高。