AnyImage/docs/image-tools-technical.md

Image 工具技术实现

Image Box、Lasso 与 Perspective 位于 operators/image_extract/。三者共享源图选择、设置、图片写回、空间定位、Continuous 分层和可选背景清理。

模块职责

flowchart LR
    Box["box.py\nWorkspaceTool"] --> Region["region.py\nBox / Lasso Operator"]
    Lasso["lasso.py\nWorkspaceTool"] --> Region
    Perspective["perspective.py\n四点与透视矫正"]
    Region --> Common["common.py\n共享选择、设置与结果写回"]
    Perspective --> Common
    Common --> Job["extract-image-background\n可选 BEN2 Job"]

box.py 与 lasso.py 只声明 WorkspaceTool。两者通过 selection_shape 复用 ExtractImageRegion；Perspective 保留独立 Operator，因为它还有四点输入、比例预览和 Homography。

首次点击

resolve_image_extract_click() 将首次点击归为两种结果：

点击目标	结果
另一张 Image Empty	只选择并设为 Active
当前 Active 图片、空白或非图片对象	使用当前 Active 图片开始取区

这段逻辑由三个工具共用。点击非图片对象后会恢复原选择，避免触发对象移动或更换源图。

处理管线

flowchart TD
    Input["屏幕选区"] --> Pixels["转换到源图片像素坐标"]
    Pixels --> Background{"Remove Background?"}
    Background -- 否 --> Local["Blender 内处理 RGBA"]
    Background -- 是 --> Server["选区画布 → BEN2 → 局部图片"]
    Local --> Tool{"工具类型"}
    Server --> Tool
    Tool -- Box / Lasso --> Crop["Alpha bounds + Padding"]
    Tool -- Perspective --> Warp["预乘 Alpha Homography"]
    Warp --> Crop
    Crop --> Result["创建并 Pack Image\n定位 Empty"]

Box 与 Lasso 将选区外 RGBA 清为透明黑，再按非零 Alpha 的最小范围裁切。Perspective 先将四点规范为沿源图 X/Y 方向的凸四边形，再按确认的宽高比重采样；点击顺序不参与输出旋转。

透视预览固定生成一次 512 × 512 临时 Image。鼠标移动只改变屏幕上的预览比例；确认后才执行全分辨率重采样。

背景清理

extract-image-background 与标准 remove-background Job 共用 remove_image_background()。图片工具的 Job 只增加三项选区语义：

• polygon mask；
• 局部图片在源图中的 bounds；
• Box / Lasso 使用的透明 Padding。

Perspective 请求的 Job Padding 固定为 0。局部结果回到 Blender 后先换算为源图坐标，再执行透视矫正和最终 Padding。

Empty 定位与 Continuous

Box 与 Lasso 根据裁切前后的像素 bounds 换算 Empty 的中心和显示尺寸。Perspective 使用源四边形的轴对齐 bounds 近似放置结果。三者都沿用源 Empty 的矩阵，因此朝向与深度不变。

Continuous 关闭时直接更新源 Empty；开启时复制对象，并沿操作开始时捕获的 View 方向偏移：

offset = display_size × world_scale × 0.001 × layer

layer 记录在源对象的 _anyimage_extract_layer Custom Property 中，使连续结果依次靠近当前 View。

维护约束

• WorkspaceTool 的显示设置放在 box.py、lasso.py、perspective.py。
• Box / Lasso 的共享交互放在 region.py，跨三个工具的行为放在 common.py。
• Blender 数据只在主线程 Operator 中读写；Server 参数保持为可序列化字典。
• 普通裁切不启动 Job Server；只有 Remove Background 需要 Environment 与 BEN2。