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.

docs/cutout.md

@@ -0,0 +1,31 @@
+# Cutout
+
+Cutout 用套索从 Image Empty 中选择范围，再从四个方向选择生成结果：左侧 **Cutout**、右侧 **Balloon**、下方 **Depth Balloon**、上方 **Depth Surface**。双击图片会把完整画面作为选区。
+
+## 绘制选区
+
+在 Object Mode 的 3D Viewport 左侧工具栏选择 **Cutout**，按住左键绘制，松开后选择形状。绘制时按 `F` 切换反选，右键或 `Esc` 取消当前轨迹。
+
+自交轨迹使用非零环绕填充规则。沿相同方向围住的区域即使重叠多次也会保留；只有反方向环绕使计数抵消时才形成孔洞。因此交错部分不会再被当成洞扣除，同时仍能表达中间的反向内环孔洞。普通选区可以越过 Image Empty 边框，框外轨迹仍会生成网格；选区必须与原图中的可见像素相交才有效。反选仍限制在原图范围，避免把框外无限区域截成任意矩形。未启用 **Refine Selection** 时，选区边缘会做轻量抗锯齿；启用后，BEN2 先在同一个几何选区内计算前景 Alpha，再应用反选。
+
+## 基础面密度
+
+**Pixel Size** 表示基础面相邻采样点大约对应多少源图片像素，可设为 `4`–`32`，默认 `32`。数值越小，规则三角格点越密，后续形状能表达的细节越多，同时网格点数和约束三角化成本也越高。最长边的采样级别限制在 `4`–`1024`。
+
+基础面先从最终 Alpha 提取外边界与孔洞，再以接近等边三角形的六角格点填充内部。轮廓按目标间距重采样和平滑，边界点仍作为约束参与 Delaunay，因此内部点保持均匀，外缘不会退化成规则栅格的阶梯锯齿。
+
+四种结果都启用平滑着色。Cutout 与 Depth Surface 的修改器也在输出阶段显式设置 Smooth Shading；Balloon 与 Depth Balloon 在创建源网格时设置。
+
+Cutout 的基础三角面统一按图片正面逆时针排列，Thickness 沿图片平面法线向前后各偏移一半；背面与轮廓侧壁使用相反绕序，所有封闭面的法线都朝向几何外部。Depth Surface 则保持正面深度表面不动，只沿法线反方向挤出背面。Thickness 是 Blender 场景中的实际距离，因此节点接口使用 Distance 单位显示。
+
+Depth Surface 的 `O Image Depth Surface` 按“深度 → 断层剔除 → 向后厚度 → 零厚度清理 → 展开的 O Smooth 结构 → 平滑着色”从左到右排列，使内置平滑与在完整输出后连接 `O Smooth` 获得相同的输入几何。平滑段把 O Essentials 参考资产的 Repeat Zone、两条不同求值域的边界判断、边界采样与法线一致性权重节点直接放入主节点图，每轮重新计算后再移动点，不再嵌套 `O Smooth` 节点组；内部固定按 `Pin Sharp = 1`、`Pin Boundary = 1` 计算，不暴露这两个参数，`Iterations` 默认 `1`、最小可设为 `0`。Depth Continuity 使用与 `O MoGe2 Surface` 相同的百分比阈值曲线，默认 `0`，对应最宽松的断层阈值；提高数值会逐步剔除更多过远的深度跳变面。
+
+## 计算说明
+
+未启用 **Refine Selection** 时，几何范围只使用抗锯齿套索 mask，原图 Alpha 不参与轮廓；原图 Alpha 只用于确认选区内至少存在可见像素，并继续控制材质透明度。套索或 Refine 产生的 Alpha 只用于几何，不再写进材质颜色贴图：四种结果的 Color 都使用当前 Image Empty 的未裁切 Image 副本，避免选区边缘 Alpha 被材质再次相乘，同时不与源数据块共享可变状态。深度和法线分析同样读取完整图片；若当前图片来自 Upscale，AI 分析读取放大前的原图，材质颜色仍使用当前高清图。Depth Balloon 在整图推理后才用按分析分辨率缩放的套索 mask 限定有效深度。关闭 **Normal** 时，Cutout 与 Balloon 直接在 Blender 内处理，不准备临时输入、不启动 BlendJob；启用 **Normal** 后才提交 Job。MoGe 返回的相机轴法线先按源 Image Empty 的对象坐标编码。Depth Surface 原样保留这张 object-space 贴图；Cutout、Balloon 与 Depth Balloon 则在最终几何节点结果可用后，使用成品网格的 UV、平滑角法线和切线基底重新烘成像素内容不同的 tangent-space 贴图。启用 Refine 时，Job 先计算 BEN2 Alpha 并返回几何 mask，此时几何才从最终 Alpha 提取轮廓。Depth 类型始终通过 Job 取得深度，但也只在启用 **Normal** 时写入 normal。四种形状的网格都在 Blender 主线程构建，不再通过 `contour.json` 传递边界。
+
+最终 Alpha 先由 NumPy 批量找出四向边界，只沿实际周长追踪轮廓，并按包含关系把孔洞归入外轮廓。未 Refine 时直接复用套索 mask；只有真实出框时才建立扩展几何画布。启用 Refine 后完全使用原图画布内的最终 AI Alpha，所有框外套索区域都会被裁掉。格点准备使用批量数组生成；点内判断按 Y 范围分桶，只比较当前扫描带可能相交的轮廓边；边界安全距离也只检查每条边附近的少量格点。短轮廓会自动使用不大于周长八分之一的边界采样间距，避免有效小区域因当前 `Pixel Size` 较大而消失；内部格点仍严格使用用户设置的 `Pixel Size`。UV 与封边边界使用 Blender `foreach_*` 和 NumPy 批量写入，不逐元素遍历。Pillow 只会加速占比较小的 Alpha 模糊和缩放，因此 Blender 本地路径保持纯 NumPy，不新增 wheel。最终约束 Delaunay 和网格创建仍随实际点数增长，极密网格应按成品需要使用。
+
+Cutout 当前只支持静态图片。**Refine Selection**、Depth 与 normal 分析需要已配置的 AI Environment 和对应模型。
+
+Cutout、Balloon、Depth Balloon、Depth Surface 以及普通 Surface 的图片材质共用 `O Image Layer`。节点组始终提供 Normal 输入和 Object Space 开关；没有 normal 纹理时使用 `[0.5, 0.5, 1.0, 1.0]` 中性默认值。这个开关只选择 Blender Normal Map 节点的解码空间，不承担 Object-to-Tangent 转换：三种 tangent-space 结果在接入材质前已经完成像素烘制，Depth Surface 才打开 Object Space 并直接使用 MoGe 原图。