Add operators for model downloading and surface generation

- Implemented `DownloadModel` and `DownloadRequiredModels` operators for downloading models. - Created `ClearModels` operator to clear model resources. - Added `ConvertToSurface` operator for converting image empties into textured surfaces. - Introduced `GenerateDa3Surface` and `GenerateMoge2Surface` operators for generating surfaces using DA3 and MoGe-2 models respectively. - Developed utility functions for handling image mesh data, assigning attributes, and managing geometry nodes. - Established runtime configuration and post-installation model downloading in `runtime.py`.
2026-08-20 01:56:04 +08:00
parent ee46d98b93
commit 13ef705226
39 changed files with 4729 additions and 3138 deletions
--- a/docs/depth-plane.md
+++ b/docs/depth-plane.md
@@ -32,7 +32,7 @@
    Offset 超出视频长度时同样把窗口收进视频内。材质节点与置换贴图的 Start 保持与原 Empty
    一致；Original 模式的视频或序列帧使用 `color.0001.*` 颜色层同时作为颜色与深度输入；开启
    Remove Background 时同名颜色层包含 BEN2 修改后的 Alpha。
-    DA3 的深度仍以 EXR 序列帧（`depth.0001.exr` 起）保存在 job 目录根下；MoGe-2 分别使用 `moge_depth`、`moge_mask` 与 `moge_normal` EXR 序列。
+    DA3 动画深度以 EXR 序列帧（`depth.0001.exr` 起）保存在 Job 目录根下；MoGe-2 动画只为置换数据创建 `moge_depth.0001.exr` 起的 EXR 序列。MoGe-2 的 `results.npz` 保留完整 depth、normal 与 mask 数组，Server 另外输出对应 PNG 预览。
   DA3 与 MoGe-2 的单帧推理进度只显示模型与阶段名称，不追加 `1/1`；多帧时继续显示当前帧与总数。`Shadeless`、`Remove Background` 与 `Keep Original` 均默认关闭，因此默认删除原对象。`Shadeless` 会以 `O Shadeless` 节点组替代普通 Principled BSDF 路径，并继续通过 Alpha 与 Transparent BSDF 混合。
 3. DA3 或 MoGe-2 完成后会自动创建面片。DA3 面片几何先由 `mini_npz` 的相机内参与深度确定，再通过对象
   Transform 匹配原 Image Empty 的可见尺寸、位置、旋转和 Offset。Original 模式直接使用源 Empty
--- a/docs/development.md
+++ b/docs/development.md
@@ -19,10 +19,13 @@ flowchart LR
 核心边界如下：

 - `src/snapform/__init__.py` 是注册入口，集中注册 Blender 类型、`Scene.snapform_settings`、右键菜单与 Runtime
- `panel.py`、`preferences.py`、`properties.py` 只描述 UI 和 Blender 属性，不直接导入 Server 模型实现
- `operators.py` 将 Blender 状态转换为普通字典参数；Job 完成后在主线程导入图片、网格、材质和相机
- `blender/depth_plane.py` 与 `blender/surface.py` 实现 Image Empty 输入检查、几何构建和资产挂载
- `job_runtime.py` 以入口字符串声明独立 Server，并配置 Environment、Storage Root 与首次安装后的推荐模型下载
+- `menu.py` 与 `panel.py` 是同级 Blender UI 入口；`preferences.py`、`properties.py` 分别保存插件配置和 RNA 状态，它们都不直接导入 Server 模型实现
+- `runtime.py` 创建唯一 `JobRuntime`，配置 Environment、Storage Root、Server 入口与首次安装后的推荐模型下载
+- `operators/` 按功能组织 Blender 操作。Depth Plane、Surface、Background 与 Balloon 各自包含入口 Operator、Job 请求和结果回写，不设置跨功能的 `results.py`
+- `operators/common.py` 只保留跨 Job Operator 共用的参数校验、模型就绪检查、临时输入清理和请求参数构造；`operators/image.py` 与 `operators/material.py` 提供各功能 Operator 共用的 Image Empty、序列和材质操作，三者同层但不互相混合职责
+- `operators/models.py` 与 `operators/debug.py` 分别承载模型管理和 Debug 操作
+- `operators/balloon/` 以持续 `BalloonLasso` 控制器分发单次、可独立 Redo/Undo 的 `ExtractBalloon`；`geometry.py` 负责共用拓扑，`poisson.py` 与 `teddy.py` 分别计算两种厚度场
+- `operators/depth_plane/` 将转换入口、Job 请求、响应回写、深度数据和网格构建收拢在同一功能包；`operators/surface.py` 与 `operators/background.py` 采用相同的功能内聚原则
 - `server/__init__.py` 创建 `JobServer`、注册公开 Job，并把 `ModelManager` 注册为 Resource
 - `server/jobs/` 按任务组织完整流程；DA3、MoGe-2、BEN2 Debug 各自拥有独立模块和 Job，不用模型分支总控函数
 - `server/models/` 包含三个模型适配器及其 ONNX 实现，只负责模型载入、推理和 Prediction；不接收 Job Context、不写文件
@@ -48,52 +51,40 @@ flowchart LR
 │   └── snapform/
 │       ├── __init__.py
 │       ├── blender_manifest.toml
-│       ├── job_runtime.py
-│       ├── operators.py
+│       ├── runtime.py
+│       ├── menu.py
 │       ├── panel.py
 │       ├── preferences.py
 │       ├── properties.py
+│       ├── model_catalog.py
 │       ├── assets/
 │       │   └── O_SnapForm.blend
-│       ├── blender/
-│       │   ├── depth_plane.py
-│       │   └── surface.py
-│       ├── model_catalog.py
+│       ├── operators/
+│       │   ├── common.py
+│       │   ├── image.py
+│       │   ├── material.py
+│       │   ├── models.py
+│       │   ├── debug.py
+│       │   ├── background.py
+│       │   ├── surface.py
+│       │   ├── depth_plane/
+│       │   │   ├── operator.py
+│       │   │   ├── data.py
+│       │   │   └── build.py
+│       │   └── balloon/
+│       │       ├── operator.py
+│       │       ├── geometry.py
+│       │       ├── poisson.py
+│       │       └── teddy.py
 │       ├── server/
 │       │   ├── __init__.py
 │       │   ├── jobs/
-│       │   │   ├── background.py
-│       │   │   ├── debug_ben2.py
-│       │   │   ├── debug_da3.py
-│       │   │   ├── debug_moge2.py
-│       │   │   ├── depth.py
-│       │   │   ├── foreground.py
-│       │   │   ├── frames.py
-│       │   │   └── surface.py
 │       │   ├── geometry/
-│       │   │   ├── projection.py
-│       │   │   ├── grid_mesh.py
-│       │   │   └── surface.py
 │       │   ├── media/
-│       │   │   └── input.py
-│       │   ├── model_download.py
-│       │   ├── model_catalog.py
-│       │   ├── model_manager.py
 │       │   ├── models/
-│       │   │   ├── ben2.py
-│       │   │   ├── da3.py
-│       │   │   ├── moge2.py
-│       │   │   ├── onnx_ben2.py
-│       │   │   ├── onnx_da3.py
-│       │   │   ├── onnx_moge2.py
-│       │   │   └── onnx_runtime.py
 │       │   └── outputs/
-│       │       ├── debug_da3.py
-│       │       ├── debug_moge2.py
-│       │       ├── depth.py
-│       │       └── surface.py
 │       └── wheels/
-│           └── blendjob-0.1.13-py3-none-any.whl
+│           └── blendjob-*.whl
 ├── tests/
 └── tools/
 ```
--- a/docs/features.md
+++ b/docs/features.md
@@ -31,6 +31,7 @@
 - Debug 与 Convert to Depth Plane 的模型选项直接显示下载状态；未下载模型带
  `(Missing)`，已下载模型保持原名
 - Debug 不运行点云、Surface、深度预览、置信度 percentile 或坐标变换等 SnapForm 后处理
+- Image Empty 右键菜单提供单一 Balloon 套索提取，并可在 Last Operation 中切换 Poisson 与 Teddy / Chordal Axis Mode；无需 Environment 或模型，源 Empty 保留
 - Image Empty 右键菜单可直接运行 DA3，根据 `mini_npz` 深度生成面片
 - Image Empty 右键菜单可直接运行 BEN2，保留原图并换用新建的透明背景图片
 - 缺少必需的 `MoGe-2 ViT-S Normal` 或 `BEN2 Base` 时，Image Empty 的 `SnapForm`
@@ -82,6 +83,20 @@
   完成后会打开 job 文件夹，其中的 `foreground.png` 带透明 Alpha；状态栏显示
   BEN2 推理、模型加载与任务总耗时。当前测试固定关闭较慢的 foreground refinement。

+## Extract Balloon
+
+`Balloon Mesh (Lasso)` 是纯 Blender 侧入口，不提交 Job，也不调用 BEN2、深度模型或其他 AI，仅支持静态 Image Empty。它启动不进入 Undo/Redo 历史的持续 `BalloonLasso` 控制器；按住左键绘制套索，松开时控制器调用一次独立的 `ExtractBalloon` Operator 并立即完成，随后继续等待下一次圈选。`Esc` 结束控制器，右键只清除当前未完成轨迹。屏幕轨迹通过视图射线与 Empty 图片平面求交，再结合图片宽高比、Display Size、Image Offset 与 Object Transform 映射为原图像素坐标。
+
+Operator 的 `Mode` 保留两种厚度算法：
+
+- `Poisson` 在共用二维网格上组装 cotangent Laplacian 与面积载荷，求解零边界 Poisson 场；高度取场值平方根并按 `Thickness` 缩放
+- `Teddy / Chordal Axis` 依据 [Teddy: A Sketching Interface for 3D Freeform Design](https://www.cs.princeton.edu/courses/archive/fall00/cs597b/papers/teddy-siggraph99.pdf) 的思路，仅对平滑轮廓做约束 Delaunay，形成袖段、分叉和端点轴，并用轴半径生成局部圆/椭圆式截面。当前实现将厚度场映射到共用均匀网格，并非逐面复刻论文的专用缝合拓扑
+
+每次释放都会把该次套索、源对象名称和启动时的完整 Matrix World 传给一个带 `REGISTER`、`UNDO` 的 `ExtractBalloon`。它完成后立即成为 Last Operation，即使持续 Lasso 仍在运行，也可在左下角修改当前结果的 `Mode`、`Thickness` 和 `Resolution`；每次提取分别拥有 Undo 步骤。重建后会重新把源 Image Empty 设为选中和 Active，便于继续圈选，结果也不会跳回原点。Modal 对中键、滚轮、触控板、NDOF、Alt+左键、HUD 和其他未处理事件返回 `PASS_THROUGH`，所以持续状态不阻断 3D View 导航或参数面板交互。`Thickness` 默认 `1.0`、软上限 `5.0` 且无硬上限。`Resolution` 是 subtype 为 `DISTANCE` 的长度属性，直接表示相邻采样点的目标世界空间距离，默认 `0.1 Blender unit`；数值越小网格越密，不再使用密度倍率换算。
+
+两种模式共用轮廓平滑、按弧长等距重采样和二维约束 Delaunay。边界与内部点以 `Resolution` 的世界距离采样，不随图片分辨率、Display Size 或对象 Scale 改变目标间距。前后表面在同一条零厚度边缘共享顶点，不生成直立侧壁，结果为封闭网格。UV 保持原图坐标；材质使用独立的 `O Texture Layer`，并复制源 Image datablock、按 Convert 系列相同规则命名为 `.color`。创建 Object 与 Mesh 时直接使用源 Image Empty 名称，不主动追加 Balloon 后缀；同一 Blender datablock 集合已有重名时仍由 Blender 自动追加数字编号。源 Image Empty 保持不变，Undo 可移除提取结果。
+
+当前不提供添加/减去选区、边缘羽化和视频跟踪。
 ## Image Empty 去背景

 1. 确认 `Models` panel 中的 `BEN2 Base` 已就绪；首次安装 Environment 时会默认下载。
--- a/docs/server.md
+++ b/docs/server.md
@@ -107,7 +107,7 @@ Environment Bootstrap 的单次 0–100% 只包含 uv、Python 与 packages，

 AI、帧提取和 Models panel 下载的 Job 进度保存在 Server 内存中。Handler 只使用 `context.progress(value, message)` 发布进度，终态由 JobServer 内部管理；SnapForm 不再维护独立的 `server/progress.py` 或 Job 状态 JSON。Blender 每 0.25 秒轮询 `GET /jobs/{job_id}`，任务目录不写 `status.json`。Operator 直接提交参数字典；Job 被接受时由 `JobServer` 自动生成 ID 并创建 `jobs/<opaque-job-id>/`，提交响应同时返回 `job_id` 与 `directory`。路径通过 `JobContext.directory` 传给 Handler，SnapForm Server 强制将输出写入该目录。

-`job_runtime.py` 创建唯一的 `runtime = JobRuntime(...)`，以自身目录为 `entrypoint_root`，传入 `server:server` 相对入口字符串与显式 `snapform` namespace，并导出 `runtime.JobOperatorBase`。Runtime 独占 Storage Root、Environment 路径、安装进程、Server 控制和 Status Bar。Operator 未覆盖 `request(context)` 时会提交全部 Property；覆盖后返回值纯替换默认参数。可选的 `response(context, result)` 在 Blender 主线程直接完成结果导入。SnapForm 不再提供 Client 请求层、Job Mixin、Status Bar 或 Build 中转 Operator。
+`runtime.py` 创建唯一的 `runtime = JobRuntime(...)`，以 `src/snapform/` 为 `entrypoint_root`，传入 `server:server` 相对入口字符串与显式 `snapform` namespace，并导出 `runtime.JobOperatorBase`。Runtime 独占 Storage Root、Environment 路径、安装进程、Server 控制和 Status Bar。Operator 未覆盖 `request(context)` 时会提交全部 Property；覆盖后返回值纯替换默认参数。可选的 `response(context, result)` 在 Blender 主线程直接完成结果导入。SnapForm 不再提供 Client 请求层、Job Mixin、Status Bar 或 Build 中转 Operator。

 Environment 安装是 Server 启动前唯一的 Bootstrap 流程：`environment.json` 记录期望安装的环境声明，`install-status.json` 在安装期间回传进度并在任务收尾后删除，`install.log` 持久记录安装输出。Bootstrap 不创建 Job 目录。Environment 成功后执行普通的 `post_install(runtime)`；默认模型下载此时已经是正式 Server Job，会创建自己的 Job 目录，并使用与其它任务相同的进度和取消协议。

--- a/docs/surface.md
+++ b/docs/surface.md
@@ -60,8 +60,8 @@
   以及面域 `o_mask`、`o_depth_discontinuity`，不伪造 confidence、stretch 或 background 属性，
   也不写入 custom normal。MoGe-2 推理返回的 normal 直接编码为独立的 `normal.png`，Blender 将它
   作为 Non-Color 贴图导入现有材质；normal 不进入 `mesh.npz`。
-   所有 MoGe-2 Image datablock 都以源图片名而非对象名为基名：depth、normal 与 mask 分别使用
-   `图片名.depth`、`图片名.normal`、`图片名.mask`，不附加 `.moge2`。
+   MoGe-2 Surface 独立导入的 normal Image datablock 以源图片名而非对象名为基名，使用
+   `图片名.normal`，不附加 `.moge2`。
 7. 网格以 `reference_depth` 截面匹配 Image Empty 的显示矩形：该截面的投影四角与 Empty 的可见
   边界重合，主点同时匹配 Empty Offset。网格对象直接沿用源 Empty 的 `matrix_world`，因此位置、旋转、
   缩放及父级关系产生的世界变换保持一致。更近的顶点沿 Empty 局部 `+Z` 方向凸出，三角面正面朝向