Add comprehensive tests for cutout and mesh functionalities

- Introduced `test_cutout.py` to validate cutout pie menu behavior, image lasso options, and mesh detail calculations.
- Added `test_mesh.py` to ensure correct tangent normal rasterization, plane source topology, and depth surface evaluations.
- Created `test_mesh_blender.py` to verify material node groups, tangent baking, and local cutout building from Blender images.
- Implemented tests for handling alpha regions and ensuring geometry nodes maintain expected behavior.

README.md

@@ -78,6 +78,14 @@ Image Perspective 是 deform 工具，不提供 Refine 或反选。它与其他
 
 完整操作说明见 [Image 编辑工具](docs/image-tools.md)。
 
+### Cutout 基础面与四种形状
+
+在 Object Mode 的 3D Viewport 左侧工具栏选择 `Cutout`，沿 Image Empty 绘制后可从四个方向选择 Cutout、Balloon、Depth Balloon 或 Depth Surface；双击会选择完整图片。`Pixel Size` 控制规则三角格点密度。未启用 `Refine Selection` 时，几何只跟随套索，忽略原图 Alpha；启用后才使用 BEN2 Alpha 收紧几何选区。自交轨迹按非零环绕规则填充：同方向的重叠区域保留，只有反方向抵消的内环形成孔洞。未 Refine 的普通选区可以越过图片边框继续生成网格，但必须与原图可见像素相交；启用 Refine 后，框外部分会随最终 AI Alpha 被裁掉。基础面内部使用均匀六角格点，平滑轮廓作为约束边界；小选区会自动缩短边界采样间距，避免在较大的 `Pixel Size` 下被误判为空，同时不增加内部格点密度。Cutout 的 Thickness 以场景距离沿图片平面法线对称加厚，前盖、背面和轮廓侧壁均保持朝外。套索和 Refine Alpha 只决定几何轮廓；四种结果的材质颜色使用当前 Empty Image 的未裁切副本，深度与法线也分析完整图片，因此选区抗锯齿不会再次降低材质边缘 Alpha。若当前图片来自 Upscale，AI 分析会回溯到放大前的原图，颜色仍保留高清版本。未启用 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。启用 Refine 时，Job 提供 BEN2 修正后的几何 Alpha；轮廓提取与建面仍由 Blender 完成。Depth Balloon 与 Depth Surface 因需要深度分析继续使用 Job，是否额外写入 normal 同样由 `Normal` 控制。
+
+完整说明见 [Cutout](docs/cutout.md)。
+
+`O Image Depth Surface` 将 `O Smooth` 的 Repeat Zone、双域边界采样和法线权重节点直接展开在主节点图中，并固定按 `Pin Sharp = 1`、`Pin Boundary = 1` 计算，不暴露这两个参数；`Iterations` 默认 `1`、最小可设为 `0`。`Depth Continuity` 默认 `0`，采用最宽松的断层阈值。Thickness 保持正面的深度表面不动，只向背面挤出。
+
 ### 套索生成 Balloon
 
 选中单张图片的 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。
@@ -92,7 +100,7 @@ Image Perspective 是 deform 工具，不提供 Refine 或反选。它与其他
 
 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 Balloon Layer` 材质补回网格分辨率未能表达的细节；`Normal Strength` 默认 `0.5`，可在材质节点中调整。Balloon 材质通过 Custom Properties 直接保存源 Image datablock 引用，不依赖材质名或节点组名识别；勾选 `Reuse Material` 时优先复用同一 Image、同一材质类型的标记材质。Depth Balloon 共用一张原图尺寸的 normal，后续套索会把自己的有效区域合并进去，重叠区域采用最新结果。旧材质仍保留节点识别回退。当前只支持静态图片。
+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，后续套索会把自己的有效区域合并进去，重叠区域采用最新结果。旧材质仍保留节点识别回退。当前只支持静态图片。
 
 ### 去除背景
 
@@ -116,7 +124,7 @@ Surface 输出流程构建 DA3 与 MoGe-2 源网格：MoGe-2 使用深度断层
 修改器完成剔面、快速重拓扑、Relax 与 UV 重投；顶层 `Iterations` 可设为 `0`。开启 Remove Background
 时，BEN2 Alpha 只要大于 `0` 就视为前景；三角形三个顶点必须全部为前景，任一顶点 Alpha 为 `0`
 都会删除该面并且不再交给 Geometry Nodes；Surface 材质使用生成的颜色图片。匹配相机默认不创建；开启后会作为 Surface 的子级。
-MoGe-2 的像素级 normal 会作为 Object Space normal 贴图接入 `O MoGe2 Surface Layer`，并与原图
+MoGe-2 的像素级 normal 会作为 object-space normal 贴图接入 `O Image Layer`，并与原图
 Bump 合并；网格本身不写入 custom normal，因此重拓扑降低顶点数后仍能保留细腻的法线细节。
 当前此功能仅支持单张图片。