AnyImage/docs/internals/operators/image-edit-tool.md

Image Edit Tool

工具栏包含 Frame、Mask、Rectify 三合一 Image Edit 组，Cutout 作为紧接其后的独立工具。

工具设置

Frame 和 Rectify 没有业务选项。Frame 让 active Image Empty 承载合成结果，并删除其他参与合并的选中 Image Empty；Rectify 直接替换 active Image Empty 的图片。

Mask 保存 Gesture、Mode 和 Radius。Gesture 包含 Lasso、Brush 与 Polyline；Mode 包含 Set、Add 与 Subtract，默认使用 Subtract；Radius 默认 25 px，仅在 Brush 时显示和生效。

执行过程

flowchart TD
    Group["Frame / Mask / Rectify"]
    Group --> Kind{"子工具"}
    Kind -- "Frame" --> Sources["选中 still Image Empty<br/>active 为对象和深度基准"]
    Sources --> Project["Frame 像素生成观察射线<br/>与图片平面求交"]
    Project --> Composite["逐像素深度与 Alpha 合成"]
    Composite --> Canvas["完整 Frame Canvas<br/>范围外透明"]
    Canvas --> Facing["active 朝向当前视角<br/>删除其他参与对象"]
    Kind -- "Mask" --> Gesture{"Lasso / Brush / Polyline"}
    Gesture --> Mask["栅格化 SelectionMask"]
    Mask --> Mode{"Set / Add / Subtract"}
    Mode --> Alpha["只合成当前 Alpha<br/>保持完整 Canvas"]
    Kind -- "Rectify" --> Quad["四点 Quad 与 Homography"]
    Alpha --> Replace["替换 active Empty 的 Image"]
    Quad --> Replace

Frame

frame.py 读取所有选中的 still Image Empty，并要求 active object 是 Selection 内的 still Image Empty。仅有 active 状态但未选中的图片不构成输入；active 是非图片对象时，即使 Selection 中存在图片也以 warning 取消。Frame 可以从 Viewport 任意位置开始，但结果矩形必须与 active 图片投射相交。选中的非 Image Empty 被忽略；任一选中 Image Empty 是视频或序列时整体取消。

每个参与图片使用冻结的 Viewport 投影矩阵与对象世界矩阵建立屏幕到图片平面的 Projective Transform。Frame 输出像素中心沿当前观察射线映射到图片局部平面，再换算为源像素坐标；有限且位于 Image Empty 显示边界内的交点参与采样。正交视图接受任意有限视图深度；透视视图只接受观察方向前方的交点。图片部分跨越透视观察原点时，前方区域继续采样，后方、平行射线和图片范围外透明。

输出像素按观察射线上的几何深度从远到近排序，再以预乘 Alpha 合成；同深度时 active 位于最上层。Frame 与 active 的交叠通过连续有效投射区域和 Frame 矩形的正面积交集判断，不依赖源 Alpha 或离散输出像素中心。输出分辨率使用 Frame 在当前 Region 中的屏幕像素宽高，不超过 Region 尺寸，并由 Preferences 的 Maximum Frame Resolution 等比限制最长边；总像素不超过 16,777,216。透明边缘保留在完整 Canvas 中；紧邻内容的一圈透明像素保留相邻 RGB，避免线性插值产生黑边。

Frame 与 Cutout Lasso 只在 CLICK_DRAG 后进入手势。Mask 与 Rectify 使用 PRESS 启动。三个绘制型工具都由 Blender 原生点选决定命中对象：点到另一对象时只切换 active，不开始编辑；没有命中对象时保留当前 active Image Empty，因此透明区域和 Viewport 空白都可作为起点。Mask 使用 PAINT_CROSS cursor；Brush 单击生成一个圆形印记。Polyline 通过逐点单击建立路径，至少三个点后在起点周围显示随鼠标接近而放大的闭合圈，并以点击 15 px UI Scale 命中范围、双击或 Enter 完成；Backspace 删除最后一点。手势与图片范围、可见内容的有效性在提交阶段判断。Frame 的普通空白点击继续清空选择，Shift 点击由显式 Viewport 对象选择 keymap 处理。

结果平面本地 XY 平行视平面且正面朝向观察者。正交视图与 active 原点位于透视观察方向前方时，结果沿用 active 对象原点的视图深度；透视 active 原点位于视后方但图片仍有有效前方交叠时，结果使用有效交叠区域屏幕中心与 active 图片平面的交点深度。active Blender Object 保留名称、Collection 和身份并承载 packed 合成 Image，其他参与 Image Empty 随后删除；整个操作属于一个 Undo 步骤。

Mask

mask.py 定义一个 WorkspaceTool 和一个 EditImageAlpha Operator。Operator 启动时冻结 Scene 中保存的 Gesture、Mode 和 Radius；Lasso 把自由手绘闭合路径转换为图片像素，Polyline 把逐点闭合路径送入同一个 SelectionMask 与 Alpha 合成入口。

Brush 拖动阶段只维护经过距离与近共线简化的屏幕轨迹，并为每个采样点生成圆、为每对相邻点生成等宽连接条；不读取源 RGBA，不创建临时 Image，也不投影、栅格化或更新 Pixel Buffer。Overlay 在局部 screen-space scanline bands 中合并这些 Primitive，生成无内部接缝、尖角或三角孔的一次填充与闭合外轮廓；Subtract 为红色，Set/Add 为灰色。释放后把同一组 Primitive 投影到图片，以逐像素最大值合入单个覆盖画布，再通过公共 Alpha 合成与 Image 替换入口提交 Packed 结果。取消或切换工具只结束 Overlay，源 Image 与共享引用始终不变。

设当前 Alpha 为 A、手势权重为 M：Set 计算 A × M，Add 计算 max(A, M)，Subtract 计算 A × (1 - M)。RGB 原样保留。结果始终使用源图片宽高和原有画框，因此 Image Empty 的 identity、matrix、display size 和 offset 保持不变；全透明结果同样有效。

Rectify

rectify.py 接受任意顺序的四个角点并规范为凸 Quad，创建 512 × 512 预览，随后按目标宽高比执行分块 Homography。输出最长边不超过 8192 px，总像素不超过 16,777,216；插值使用预乘 Alpha，结果按可见 Alpha trim 后映射回源图片平面。

Mask 与 Rectify 最终都以 packed Image 调用 common/image.py 的 replace_empty_image()。Mask 不提供 placement bounds；Rectify 使用校正区域的 placement bounds 调整图片画框。Frame 复用同模块的 Image 创建、Homography、预乘采样和单对象替换函数，并在自身业务边界完成多图合成与对象删除。

三个工具的结果都以源 Image 的完整名称请求命名，不移除 .png 等名称内容，也不添加材质贴图后缀。源数据仍被其他对象引用时，Blender 为结果追加数字后缀；源数据可清理时，替换入口让结果恢复准确原名。