Add comprehensive tests for image processing and mask functionalities

- Introduced tests for color image handling, ensuring source preservation and premultiplied alpha usage.
- Implemented tests for brush stroke operations, validating segment boundaries and brush anti-aliasing.
- Added tests for frame anti-aliasing, confirming correct rendering behavior with various alpha values and depth settings.
- Created tests for frame projection, ensuring accurate overlap calculations and half-plane clipping.
- Developed tests for image premultiplied retention, verifying behavior during loading and packing processes.
- Added undo functionality tests for mask operations, ensuring single transaction behavior during edits.

docs/internals/common.md

@@ -12,6 +12,12 @@
 | `image.require_image_empty()` | 按名称取得 Image Empty；对象已失效时抛错。 |
 | `image.image_pixels()` | 以 Blender 原始顺序读取一维 float32 像素。 |
 | `image.image_rgba()` | 读取为 Top-down RGBA float32 数组。 |
+| `image.homography_from_points()` | 求解四点之间的 Homography。 |
+| `image.projective_output_size()` | 按源像素密度、目标宽高比和资源上限计算投影输出尺寸。 |
+| `image.premultiplied_rgba()` | 将 Blender 顺序像素转换为 Top-down 预乘 Alpha RGBA。 |
+| `image.sample_premultiplied_rgba()` | 在图片边界坐标中双线性采样预乘 Alpha RGBA，范围外返回透明。 |
+| `image.straight_rgba()` | 转换为 straight RGBA，并把相邻可见 RGB 扩展到一圈透明边缘。 |
+| `image.warp_projective_pixels()` | 将源 Quad 重采样为矩形 Blender Image 像素。 |
 | `image.video_total_frames()` | 返回 Movie 或 Sequence 总帧数，静态图返回 1。 |
 | `image.image_user_settings()` | 读取 Image Empty 的帧起点、偏移、时长和循环设置。 |
 | `image.default_extract_frames()` | 取得当前 Empty 默认应处理的帧数。 |
@@ -28,23 +34,23 @@
 | `image.load_packed_rgba_image()` | 加载已有 RGBA 文件，继承源图颜色空间和 Alpha mode，命名并 Pack。 |
 | `image.create_image_edit_result()` | 从本地编辑后的 RGBA 像素创建 Packed Image，以源 Image 完整名称请求新数据块名称；不修改 Empty。 |
 | `image.replace_empty_image()` | 执行 Image Empty 结果替换、共享引用分流、旧数据清理、帧设置继承和可选画布对齐。 |
-| `image.place_empty_image_result()` | 按 Keep Original 决定替换源 Empty 或复制结果，并选择、激活结果 Empty。 |
 | `image.image_empty_bounds()` | 计算 Image Empty 在对象局部坐标中的实际显示边界。 |
 
-Remove Background、Upscale 与四种 Crop 都属于直接 Image 编辑，结果保留源 Image 数据块的完整名称，包括名称中的 `.png` 等格式文字。源数据仍被其他对象引用或启用 Keep Original 时，重名结果由 Blender 自动追加数字后缀；源数据可清理时，替换入口让结果恢复准确原名。`color_data_name()`、`depth_data_name()`、`normal_data_name()` 仅用于 Plane 与 Cutout 等材质派生贴图。
+Remove Background、Upscale、Frame、Mask 与 Rectify 都属于直接 Image 编辑，结果保留 active 或源 Image 数据块的完整名称，包括名称中的 `.png` 等格式文字。源数据仍被其他对象引用时，重名结果由 Blender 自动追加数字后缀；源数据可清理时，替换入口让结果恢复准确原名。`color_data_name()`、`depth_data_name()`、`normal_data_name()` 仅用于 Plane 与 Cutout 等材质派生贴图。
 
 ## Image Selection 与视图交互
 
 这组公共能力使用固定术语：
 
-- Selection 是用户在图片空间圈定的业务范围；`SelectionPath` 保存路径点和反选状态，并提供完整值的 JSON 编解码。
+- Selection 是用户在图片空间圈定的业务范围；`SelectionPath` 只保存路径点，并提供 JSON 编解码。
 - `SelectionMask` 是 Selection 的纯几何栅格化结果，只包含局部像素权重 `values` 和源图几何 `bounds`。
 - Mask 表示二维像素权重或 Alpha 运算。
-- Blender 对象 Selection 由上下文明确区分；图片选区细化动作称为 Refine Selection。
 
-`viewport.py` 处理 View3D 中的点击、坐标投影、`CropSelectionGesture`、工具设置和 Overlay 绘制；手势完成时只把内存中的 `SelectionPath` 交给实际工具。`selection.py` 负责图片空间 Selection 的值、栅格化和 Alpha 裁切；`SelectionPath → SelectionMask` 只在图片编辑或 Shape 生成阶段执行。
+`viewport.py` 处理 View3D 中的点击、坐标投影、`ImageGesture` 和 Overlay 绘制；它为 Lasso、Brush 与 Polyline 提供对应状态机，Brush 拖动阶段只维护简化后的屏幕路径及 Overlay、提交共用的圆形印记和连接条。`selection.py` 负责图片空间 Selection 的值、栅格化和 Alpha 修整；`SelectionPath → SelectionMask` 只在图片编辑或 Shape 生成阶段执行。Frame 在自身业务模块中组合冻结的 Viewport 投影矩阵与对象世界矩阵，把屏幕像素映射到 Image Empty 局部平面；正交视图接受任意有限深度，透视视图只采样观察方向前方的有效交点。
 
-所有 Path 使用 non-zero winding 填充，同方向重复绕行的重叠区域保持选中。栅格器按路径边与像素中心扫描行的交点累计 winding：非反选只建立 Path Bounds 的局部画布，抗锯齿时增加 2 px 边缘；反选使用完整图片范围。栅格阶段不接收图片 Alpha 或颜色，内容相交、空内容和内容 bounds 由 Crop Tool 或 Cutout 业务处理。
+Viewport 对象命中继续由 Blender 原生点选决定。Mask、Rectify 与 Cutout 点到另一对象时只保留原生选择结果；没有命中对象时保留当前 active Image Empty，并把透明区域或 Viewport 空白作为图片操作起点。Frame 的普通空白点击继续清空选择。手势是否与图片范围或可见内容有效相交，由各业务在提交阶段判断。
+
+所有 Path 使用 non-zero winding 填充，同方向重复绕行的重叠区域保持选中。栅格器按路径边与像素中心扫描行的交点累计 winding，只建立 Path Bounds 的局部画布，抗锯齿时增加 2 px 边缘。栅格阶段不接收图片 Alpha 或颜色，Mask 与 Cutout 在各自业务层组合几何 Mask 和图片 Alpha。
 
 ### Viewport 交互
 
@@ -52,13 +58,19 @@ Remove Background、Upscale 与四种 Crop 都属于直接 Image 编辑，结果
 | --- | --- |
 | `viewport.report_image_edit_exception()` | 将可预期的 Selection 警告和异常映射为 Operator Report。 |
 | `viewport.image_edit_poll()` | 判断当前上下文是否允许启动图片编辑工具。 |
-| `viewport.resolve_image_edit_click()` | 解析点击到 Image Empty，并保持或恢复选择状态。 |
+| `viewport.resolve_image_edit_click()` | 执行原生点选；点到另一对象时只保留选择结果，空命中时保留 active Image Empty 并开始点选型编辑。 |
+| `viewport.active_image_edit_source()` | 要求并取得当前 Selection 内的 active Image Empty。 |
+| `viewport.image_edit_selection_keymap()` | 创建普通点击和 Shift 点击的对象选择 keymap，并配置普通点击的空命中策略。 |
+| `viewport.image_edit_drag_keymap()` | 创建拖动图片手势及对象点选 keymap。 |
+| `viewport.image_edit_point_keymap()` | 创建点选型图片手势及 Shift 追加选择 keymap。 |
 | `viewport.active_view3d_tool_id()` | 取得当前 View3D Workspace Tool ID。 |
-| `viewport.apply_crop_settings()` | 将当前 Crop 子工具的持久选项同步到手势 Operator。 |
-| `viewport.draw_crop_settings()` | 绘制当前 Crop 子工具的独立选项。 |
 | `viewport.draw_dashed_line()` | 绘制手势或透视框虚线。 |
 | `viewport.draw_polygon_fill()` | 绘制手势或透视框填充预览。 |
-| `viewport.gesture_property()` | 声明统一的 Box、Lasso 和 Polyline RNA 属性。 |
+| `viewport.ImageGesture` | 复用 Lasso、Brush 与 Polyline 的 Modal 生命周期、源图解析和 Overlay 绘制。 |
+| `viewport.brush_footprint_polygons()` | 生成 Brush Overlay 与释放提交共用的圆形印记和连接条。 |
+| `viewport.preview_union_geometry()` | 在 screen-space scanline bands 中融合 Brush Primitive，并返回一次填充与外轮廓虚线。 |
+| `viewport.preview_fill_geometry()` | 三角化 Lasso、Polyline 的 non-zero winding 填充与外轮廓。 |
+| `viewport.rectangle_screen_path()` | 将两个屏幕点规范为 Frame 使用的矩形四角。 |
 | `viewport.screen_path_to_image_pixels()` | 将屏幕路径投影为 Image Empty 像素坐标。 |
 | `viewport.serialize_matrix()` | 将 4×4 Matrix 序列化为 Operator 可保存的字符串。 |
 | `viewport.deserialize_matrix()` | 恢复已序列化的 4×4 Matrix。 |
@@ -70,10 +82,7 @@ Remove Background、Upscale 与四种 Crop 都属于直接 Image 编辑，结果
 | --- | --- |
 | `selection.selection_path_bounds()` | 校验 Selection Path 并返回整数像素包围框。 |
 | `selection.rasterize_selection_path()` | 以局部 non-zero scanline 把 `SelectionPath` 栅格化为纯几何 `SelectionMask`。 |
-| `selection.save_selection_mask()` | 将一次栅格化的局部 Mask 保存为 Blender 异步响应使用的 sidecar。 |
-| `selection.load_selection_mask()` | 从本地 sidecar 恢复带原 bounds 的 `SelectionMask`。 |
-| `selection.cleanup_selection_mask()` | 删除本地 Selection Mask sidecar。 |
-| `selection.crop_pixels_to_alpha()` | 按 Alpha 非零区域紧裁切 RGBA 像素。 |
+| `selection.trim_pixels_to_alpha()` | 按 Alpha 非零区域修整 RGBA 像素。 |
 
 ## Depth 产物