nan
1994d38ccd
- 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.
58 lines
6.4 KiB
Markdown
58 lines
6.4 KiB
Markdown
# 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 时显示和生效。
|
||
|
||
## 执行过程
|
||
|
||
```mermaid
|
||
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 为结果追加数字后缀；源数据可清理时，替换入口让结果恢复准确原名。
|