Add tests for clipboard image functionality and mesh plane asset creation

- Implemented a comprehensive test suite for the clipboard image module, covering various functionalities including operator registration, context handling, and image processing.
- Created a new mesh plane asset with customizable parameters and integrated it into the geometry node system.
- Developed a validation script to ensure the correct behavior of the mesh plane asset, including input handling and output verification.

README.md

@@ -8,12 +8,15 @@ 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 保持不变
+- 用 Image Box / Lasso 原位提取 Image Empty 内容，按矩形或手绘范围裁切并 Pack 新图，也可用 BEN2 进一步收紧 Alpha
 - 一键把 Image Empty 转换为立体面片：让 AI 估算深度，或直接用原图作为深度
 - 把单张 Image Empty 转换为透视纹理网格，并自动匹配原对象的 Transform 与 Offset
 - 一键去除图片背景，生成透明前景图
 - 支持视频与序列帧输入，逐帧处理，动画也能得到逐帧对应的立体面片
-- 全部操作都在右键菜单里完成，不需要写任何代码
+- 主要转换操作集中在右键菜单，剪贴板图片可直接用系统粘贴快捷键导入
 
 ## 安装
 
@@ -22,22 +25,26 @@ AnyImage 是一个 Blender 扩展，可以把一张照片、一段视频或一
 3. 点击 `Install from Disk`，选择下载的压缩包
 4. 在扩展偏好设置中确认 Storage Root 与 Device（保持默认即可）；Device 默认取本机
    最快的 DirectML provider；Apple M4 或更新芯片可选 MPS/CoreML，其他 Mac 只提供 CPU
-5. 打开 3D 视图右侧的 `AnyImage` 面板：使用官方源点击 `Install Environment`，使用国内镜像点击 `Install Environment (Mirror)`
+5. 选中 Image Empty，在右键 `AnyImage` 子菜单中点击 `Set Up AI Environment…`；也可以从扩展偏好设置进入
 
-扩展不内置 uv 或 AI 运行库。首次使用会先下载并校验固定版本的 uv，随后自动安装轻量的 ONNX Runtime 环境，再下载 `MoGe-2 ViT-S Normal` 和
-`BEN2 Base`；不安装 PyTorch，也不下载各模型的 Python 源码包。其他 AI 模型可在
-`Models` panel 中按需下载，请保持网络畅通，首次安装需要一些时间。
-Environment Bootstrap 使用连续的 0–100%：uv 为 1–20%、Python 为 20–50%、packages 为 50–98%，最终验证为 98–100%。三个阶段显示真实的 `1/3`、`2/3`、`3/3`，下载占各阶段的 84–87%；开始与最终验证不显示编号，单阶段状态不显示 `1/1`。官方按钮固定使用 GitHub、uv 默认 Python 下载源和 PyPI；镜像按钮固定使用 CNB uv Release、CNB Python 解释器镜像和清华 PyPI，两种方式都不竞速或自动切换。MoGe-2 与 BEN2 属于 post-install，各自使用独立进度，不计入 Environment 的这轮 0–100%，其模型下载源逻辑不受按钮选择影响。
-任一必需模型在两个来源都下载失败时，`Install Environment` 会明确报错；Environment 本身仍会保留。
-选中 Image Empty 后，右键 `AnyImage` 子菜单会在缺少 `MoGe-2 ViT-S Normal` 或 `BEN2 Base`
-时显示 `Download Required Models`，一次补齐缺失项，不会重复下载已经就绪的模型。
-Environment 未安装时，同一位置显示两个安装按钮。Environment 或必需模型未就绪时，
-菜单仍显示 `Convert to Depth Plane`、`Convert to Surface` 和 `Remove Background`，但三个入口都会保持禁用。
-`Balloon Mesh (Lasso)` 默认是 Blender 本地几何功能，在上述状态下仍可使用；开启 `Contour` 或 `Depth` 后，才需要 Environment 与对应的 BEN2 或 MoGe-2 模型。
-这些 UI 状态直接检查 Storage Root 的 `models/` 文件，不会仅因打开菜单或面板而启动 Job Server。
+扩展不内置 uv 或 AI 运行库。`Set Up AI Environment…` 会先说明下载内容、约 600 MB 的下载量、约 1 GB 的磁盘占用和预计等待时间，并可勾选 `Use Mirror`。确认后会下载并校验固定版本的 uv，自动安装轻量的 ONNX Runtime 环境，再下载 `MoGe-2 ViT-S Normal` 和 `BEN2 Base`；不安装 PyTorch，也不下载各模型的 Python 源码包。`Use Mirror` 只切换 uv、Python 和 Python 包的下载源，模型仍使用自己的下载源与备用镜像规则。
+
+Environment Bootstrap 使用连续的 0–100%：uv 为 1–20%、Python 为 20–50%、packages 为 50–98%，最终验证为 98–100%。三个阶段显示真实的 `1/3`、`2/3`、`3/3`，下载占各阶段的 84–87%；开始与最终验证不显示编号，单阶段状态不显示 `1/1`。MoGe-2 与 BEN2 属于 post-install，各自使用独立进度，不计入 Environment 的这轮 0–100%。任一必需模型在两个来源都下载失败时，安装任务会明确报错；Environment 本身仍会保留。
+
+选中 Image Empty 后，右键 `AnyImage` 子菜单依次显示 Balloon、三个 AI 功能和环境入口。Environment 或必需模型未就绪时，点击 `Convert to Depth Plane…`、`Convert to Surface…` 或 `Remove Background` 会打开对应准备对话框：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。
 
 ## 快速上手
 
+### 粘贴剪贴板图片
+
+复制图片后，在 3D View、Shader Editor、Compositor 或 Geometry Nodes 中按 `Ctrl+V`；macOS 使用 `Cmd+V`。AnyImage 会根据当前上下文创建 Reference Image、带材质的 Plane、图片节点或笔刷 Texture，并将图片 Pack 到当前 `.blend`。完整说明见[粘贴剪贴板图片](docs/clipboard-image.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)。
+
 ### 转换为立体面片
 
 1. 在 3D 视图中选中一个 Image Empty（空物体，显示方式为 Image）
@@ -50,9 +57,15 @@ Environment 未安装时，同一位置显示两个安装按钮。Environment
    - `Keep Original` 默认关闭，位于分割线下方；开启后保留源 Image Empty
 4. 点击确认，稍等片刻就得到带位移的立体面片。`O DA3 Depth Plane` 与 `O MoGe2 Depth Plane` 都使用 `.color` 的 `Alpha > 0.5` 划分前景范围，范围外由 `Background Depth` 控制。
 
+### 套索提取图片
+
+选中静态图片的 Image Empty，在 3D Viewport 左侧工具栏选择 Image Box / Lasso 工具组。默认的 Image Box 拖出矩形区域；长按工具按钮可切换 Image Lasso 并绘制自由轮廓。两者使用默认鼠标光标，并以类似 Select Tool 的白色虚线显示选区，分别采用 Sculpt Mode 的 Box Mask 与 Lasso Mask 图标，共用相同设置。该工具组与 Balloon Lasso 相邻，并通过一个间隔与前方的 Add Cube 分开。松开左键后会把同一个 Empty 原位更新为新图片并 Pack 到 .blend。Image Box / Lasso 与 Balloon Lasso 都只放在工具栏，不出现在右键 AnyImage 子菜单中。
+
+区域外的 RGBA 会统一设为透明黑，避免后续只读取 RGB 的图像处理重新识别透明区内容。输出画布取最终 Alpha 大于 0 的最小 bounding box，再按 Padding 向四周增加指定的透明像素，默认 0 px。对象原点会移动到新画布中心，显示尺寸与图片比例同步更新，裁切后的像素仍与原图在世界空间重合。Keep Original 默认关闭；开启后保留源 Empty，并创建承载裁切图的副本。Contour 默认关闭；开启后 BEN2 会在 lasso 内进一步细化 Alpha，再计算最终 bounding box。Contour 仅支持静态图片，并需要 AI Environment 与 BEN2。
+
 ### 套索生成 Balloon
 
-选中单张图片的 Image Empty，右键打开 `AnyImage` 子菜单并选择 `Balloon Lasso Tool`。Blender 会激活 3D Viewport 左侧工具栏底部、紧邻 Add Cube、且不增加分隔空隙的独立 Balloon Lasso，Poly Build 的绿色图标、Annotate 同款铅笔光标、Tool Header 与状态栏共同提示当前工具状态，不再用黄色外框或强制修改 Shading、Overlay。Blender 的公开 Workspace Tool API 不支持按 Active Object 动态隐藏工具，因此图标在 Object Mode 中保持可见，但只有 Active Object 是 Image Empty 时才能启动 Stroke。
+选中单张图片的 Image Empty，右键打开 `AnyImage` 子菜单并选择 `Balloon Lasso Tool`。Blender 会激活 3D Viewport 左侧工具栏底部、紧邻 Image Box / Lasso 工具组的独立 Balloon Lasso；该工具组与 Add Cube 之间保留一个间隔。Balloon 使用 Poly Build 的绿色图标、Annotate 同款铅笔光标，Tool Header 与状态栏共同提示当前工具状态，不再用黄色外框或强制修改 Shading、Overlay。Blender 的公开 Workspace Tool API 不支持按 Active Object 动态隐藏工具，因此图标在 Object Mode 中保持可见，但只有 Active Object 是 Image Empty 时才能启动 Stroke。
 
 按住左键沿目标轮廓绘制，松开后生成一个带原图 UV 的封闭网格。每次拖动都是一个独立完成的顶层 `Extract Balloon` Operator，工具本身继续保持激活，下一次拖动会创建另一个 Balloon；因此 `Ctrl+Z` 只撤销最近一次生成，`Ctrl+Shift+Z` 重做。每次生成后源 Image Empty 都保持选中和 Active。未绘制时没有持续 Modal 拦截事件，视图导航和其他原生快捷键由 Blender 正常处理；绘制中可用右键或 `Esc` 取消当前轨迹。选择左侧工具栏中的其他工具即可离开 Balloon Lasso。
 
@@ -113,10 +126,9 @@ Session 逐帧推理，显存峰值不随视频帧数平方增长。Debug 只保
 
 ## 常见问题
 
-- 从 0.12.0–0.12.5 升级到 0.12.6 或更高版本后，请重新执行一次 `Install Environment`，重建不再单独安装 BlendJob 的 Server Environment
-- 首次使用需要下载模型，如果下载慢或失败，可在 Image Empty 的 `AnyImage` 右键菜单点击
-  `Download Required Models`，也可在 `Models` panel 里逐项重试
-- 安装 Environment 时下载状态会显示平均速度；网络适合海外源时选择 `Install Environment`，国内网络选择 `Install Environment (Mirror)`。每个按钮固定使用对应来源，失败时不会自动切换
+- 从 0.12.0–0.12.5 升级到 0.12.6 或更高版本后，请重新执行一次 `Set Up AI Environment…`，重建不再单独安装 BlendJob 的 Server Environment
+- 首次使用需要下载模型；Environment 已安装但默认模型下载慢或失败时，点击 `Download Required Models…` 可补齐缺失项，也可在 AnyImage 扩展偏好设置中逐项重试
+- 安装 Environment 时下载状态会显示平均速度；网络适合国内镜像时在确认对话框勾选 `Use Mirror`，否则保持关闭。选择的来源固定用于 uv、Python 和 Python 包，失败时不会自动切换
 - 默认模型下载会在 Hugging Face 与 OmooLab 镜像之间自动回退；某一来源暂时断线不会阻止后续模型尝试另一来源
 - 模型直链建连超过 10 秒，或连接后连续 60 秒没有收到数据，会切换到下一来源；不限制总下载时长
 - 找不到右键入口时，请确认选中了 Empty，且显示方式为 Image