feat: Update version to 0.13.0 in project files and adjust dependencies
This commit is contained in:
@@ -8,5 +8,5 @@ AnyImage 是一款 Blender 扩展，可以粘贴和编辑图片、创建普通 P
|
||||
- 用 **Plane** 创建可调厚度和细分的图片网格
|
||||
- 用 **Depth Plane** 把静态图片转换为可调节的立体面片
|
||||
- 用 **Cutout** 从套索选区生成 Surface、Balloon 与两种 Depth Shape
|
||||
- 用 **Image Tools / Perspective** 直接清理或矫正 Image Empty
|
||||
- 用 **Crop Box / Lasso / Polyline / Perspective** 清理或矫正 Image Empty
|
||||
- 用 **Remove Background / Upscale** 处理单图、视频和序列帧
|
||||
|
||||
@@ -32,7 +32,7 @@ Operator 向 Server 发送普通字典。Server 返回文件名和 Job 目录；
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Register["anyimage.register()"] --> Types["注册 Preferences / PropertyGroup / Operator / Panel"]
|
||||
Types --> Tools["注册 Image Tools 与 Cutout WorkspaceTool"]
|
||||
Types --> Tools["注册 Crop Tool 与 Cutout WorkspaceTool"]
|
||||
Tools --> RNA["挂载 Scene 与 Image Property"]
|
||||
RNA --> Menu["挂载上下文菜单和剪贴板快捷键"]
|
||||
Menu --> Runtime["注册 JobRuntime"]
|
||||
@@ -42,7 +42,7 @@ flowchart TD
|
||||
|
||||
## 同步与异步路径
|
||||
|
||||
无需 AI 或媒体处理的功能直接在 Blender 中完成，例如 Plane、普通 Image Mask、Perspective，以及未启用 Refine Selection / Normal Map 的 Surface 和 Balloon。需要模型或独立文件处理时，功能 Operator 派生自 `JobOperatorBase`：
|
||||
无需 AI 或媒体处理的功能直接在 Blender 中完成，例如 Plane、普通 Crop、Crop Perspective，以及未启用 Refine Selection / Normal Map 的 Surface 和 Balloon。需要模型或独立文件处理时，功能 Operator 派生自 `JobOperatorBase`：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
|
||||
@@ -27,6 +27,7 @@
|
||||
| `image.load_packed_rgba_image()` | 加载已有 RGBA 文件，继承源图颜色空间和 Alpha mode，命名并 Pack。 |
|
||||
| `image.create_pixel_result_image()` | 从本地编辑后的 RGBA 像素创建 Packed Image；不修改 Empty。 |
|
||||
| `image.replace_empty_image()` | 执行 Image Empty 结果替换、共享引用分流、旧数据清理、帧设置继承和可选画布对齐。 |
|
||||
| `image.place_empty_image_result()` | 按 Keep Original 决定替换源 Empty 或复制结果，并选择、激活结果 Empty。 |
|
||||
| `image.image_empty_bounds()` | 计算 Image Empty 在对象局部坐标中的实际显示边界。 |
|
||||
|
||||
## Image Selection 与视图交互
|
||||
@@ -38,23 +39,23 @@
|
||||
- Mask 表示二维像素权重或 Alpha 运算。
|
||||
- Blender 对象 Selection 由上下文明确区分；图片选区细化动作称为 Refine Selection。
|
||||
|
||||
`viewport.py` 处理 View3D 中的点击、坐标投影、`ImageSelectionGesture`、工具设置和 Overlay 绘制；手势完成时只把内存中的 `SelectionPath` 交给实际工具。`selection.py` 负责图片空间 Selection 的值、栅格化和 Alpha 裁切；`SelectionPath → SelectionMask` 只在图片编辑或 Shape 生成阶段执行。
|
||||
`viewport.py` 处理 View3D 中的点击、坐标投影、`CropSelectionGesture`、工具设置和 Overlay 绘制；手势完成时只把内存中的 `SelectionPath` 交给实际工具。`selection.py` 负责图片空间 Selection 的值、栅格化和 Alpha 裁切；`SelectionPath → SelectionMask` 只在图片编辑或 Shape 生成阶段执行。
|
||||
|
||||
所有 Path 使用 non-zero winding 填充，同方向重复绕行的重叠区域保持选中。栅格器按路径边与像素中心扫描行的交点累计 winding：非反选只建立 Path Bounds 的局部画布，抗锯齿时增加 2 px 边缘；反选使用完整图片范围。栅格阶段不接收图片 Alpha 或颜色，内容相交、空内容和内容 bounds 由 Image Tool 或 Cutout 业务处理。
|
||||
所有 Path 使用 non-zero winding 填充，同方向重复绕行的重叠区域保持选中。栅格器按路径边与像素中心扫描行的交点累计 winding：非反选只建立 Path Bounds 的局部画布，抗锯齿时增加 2 px 边缘；反选使用完整图片范围。栅格阶段不接收图片 Alpha 或颜色，内容相交、空内容和内容 bounds 由 Crop Tool 或 Cutout 业务处理。
|
||||
|
||||
### Viewport 交互
|
||||
|
||||
| 函数 | 职责 |
|
||||
| --- | --- |
|
||||
| `viewport.report_image_edit_exception()` | 将可预期的 Selection 警告和异常映射为 Operator Report。 |
|
||||
| `viewport.image_edit_poll()` | 判断当前上下文是否允许启动 Image 工具。 |
|
||||
| `viewport.image_edit_poll()` | 判断当前上下文是否允许启动图片编辑工具。 |
|
||||
| `viewport.resolve_image_edit_click()` | 解析点击到 Image Empty，并保持或恢复选择状态。 |
|
||||
| `viewport.active_view3d_tool_id()` | 取得当前 View3D Workspace Tool ID。 |
|
||||
| `viewport.apply_selection_settings()` | 将当前 Selection 工具的 Refine Selection 设置同步到手势 Operator。 |
|
||||
| `viewport.draw_selection_settings()` | 绘制 Selection 工具的公共 Refine Selection 设置。 |
|
||||
| `viewport.apply_crop_settings()` | 将当前 Crop 子工具的持久选项同步到手势 Operator。 |
|
||||
| `viewport.draw_crop_settings()` | 绘制当前 Crop 子工具的独立选项。 |
|
||||
| `viewport.draw_dashed_line()` | 绘制手势或透视框虚线。 |
|
||||
| `viewport.draw_polygon_fill()` | 绘制手势或透视框填充预览。 |
|
||||
| `viewport.gesture_property()` | 声明统一的 Box、Lasso、Line 和 Polyline RNA 属性。 |
|
||||
| `viewport.gesture_property()` | 声明统一的 Box、Lasso 和 Polyline RNA 属性。 |
|
||||
| `viewport.screen_path_to_image_pixels()` | 将屏幕路径投影为 Image Empty 像素坐标。 |
|
||||
| `viewport.serialize_matrix()` | 将 4×4 Matrix 序列化为 Operator 可保存的字符串。 |
|
||||
| `viewport.deserialize_matrix()` | 恢复已序列化的 4×4 Matrix。 |
|
||||
|
||||
@@ -39,6 +39,8 @@ uv run build_node --skip-tests
|
||||
|
||||
构建从空 Factory 文件生成全部节点组，关闭 `.blend1` 备份，并覆盖唯一发布资产。
|
||||
|
||||
`O Image Cutout` 在四个 Shape 分支与平滑之后统一处理 **Inward Axis**。Shape 子节点保持内部 `+X` 朝向；默认 `-Z` 分支执行一次轴转换，`+X` 分支保留内部坐标。运行时对象矩阵与该接口配对，保证两种模式落在相同世界空间位置。
|
||||
|
||||
## 修改节点组
|
||||
|
||||
1. 修改 `tools/node_assets/build_*.py`；
|
||||
|
||||
41
docs/internals/operators/crop-tool.md
Normal file
41
docs/internals/operators/crop-tool.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# Crop Tool
|
||||
|
||||
工具栏保留两个独立 AnyImage 入口：四合一 Crop Tool 组与紧接其后的 Cutout Tool。Crop Tool 依次包含 Crop Box、Crop Lasso、Crop Polyline 和 Crop Perspective。
|
||||
|
||||
## 工具设置
|
||||
|
||||
四个子工具各自保存 **Keep Original**，默认关闭。关闭时结果替换源 Image Empty；开启时复制源对象承载结果，保留但取消选择原 Empty，并选择、激活新结果。
|
||||
|
||||
Crop Box、Crop Lasso 和 Crop Polyline 还分别保存 **Invert**；Box 与 Lasso 分别保存 **Refine Selection**。这些状态互不共享。Crop Perspective 没有 Invert 或 Refine Selection。Crop 不注册选项字母快捷键。
|
||||
|
||||
## 执行过程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Group["Crop Box / Lasso / Polyline / Perspective"]
|
||||
Group --> Kind{"Selection Crop？"}
|
||||
Kind -- "Box / Lasso / Polyline" --> Path["采集 SelectionPath"]
|
||||
Path --> Mask["栅格化 SelectionMask"]
|
||||
Mask --> Refine{"Box / Lasso Refine Selection？"}
|
||||
Refine -- "否" --> Local["源 Alpha × Selection"]
|
||||
Refine -- "是" --> Job["refine-image-selection"]
|
||||
Kind -- "Perspective" --> Quad["四点 Quad 与 Homography"]
|
||||
Local --> Result["创建结果 Image"]
|
||||
Job --> Result
|
||||
Quad --> Result
|
||||
Result --> Keep{"当前子工具 Keep Original？"}
|
||||
Keep -- "否" --> Replace["替换源 Empty"]
|
||||
Keep -- "是" --> Copy["保留源 Empty<br/>选择并激活结果 Empty"]
|
||||
```
|
||||
|
||||
## Selection Crop
|
||||
|
||||
`box.py`、`lasso.py` 和 `polyline.py` 定义 WorkspaceTool，交互与落地集中在 `selection.py`。公共 `CropSelectionGesture` 从 `common/viewport.py` 读取当前子工具的独立设置，并把内存中的 `SelectionPath` 交给 `CropImageSelection`。
|
||||
|
||||
本地路径在几何 bounds 内把 Selection 值乘入源 Alpha，再按可见内容紧裁切。Box 或 Lasso 开启 Refine Selection 时，Operator 写出保留源 Alpha 的 bounds 矩形并提交 `server/jobs/refine_image_selection.py`；响应直接加载 BEN2 RGBA。Job request 不包含 Keep Original，保留策略只在 Blender 主线程落地结果时执行。
|
||||
|
||||
## Crop Perspective
|
||||
|
||||
`perspective.py` 接受任意顺序的四个角点并规范为凸 Quad，创建 512 × 512 预览，随后按目标宽高比执行分块 Homography。输出最长边不超过 8192 px，总像素不超过 16,777,216；插值使用预乘 Alpha，结果按可见 Alpha 紧裁切。
|
||||
|
||||
四种 Crop 最终都调用 `common/image.py` 的 `place_empty_image_result()`。该入口负责替换或复制 Image Empty、画布对齐、Collection 归属，以及 Keep Original 下选择并激活结果对象。
|
||||
@@ -33,7 +33,7 @@ Surface 与 Balloon 在本地组合源 Alpha 与几何 Selection 后构建 `Base
|
||||
|
||||
Cutout 工具由 `__init__.py` 注册，交互从 `main.py` 中的 `SelectCutoutSelection` 开始。它接收 Lasso 或双击整图手势，只构建内存中的 `SelectionPath`，然后调用 `interaction.py` 打开 Shape 饼菜单。此时不读取源图像素、不栅格化 Mask，也不扫描可见 Alpha。
|
||||
|
||||
`interaction.py` 读取工具选项，并在构建菜单按钮时把只含 Points 与 Invert 的完整 `SelectionPath` 编码一次，将同一个 JSON 值直接设置给各 `CutoutSelectionToShape`。这次编码只用于跨 Blender Operator 传值，不属于 Selection Mask 构建。**Mesh Detail** 的 Low、Medium、High、Ultra 分别映射到 32、16、8、4 px 的采样间距，再换算期望网格分辨率；档位越高，采样越密。菜单中的 Surface、Balloon、Depth Balloon 和 Depth Surface，以及它们对应的节点分支索引，统一来自 `shape.py`。
|
||||
`interaction.py` 读取工具选项，并在构建菜单按钮时把只含 Points 与 Invert 的完整 `SelectionPath` 编码一次，同时把当前 **Inward Axis** 固定到各 `CutoutSelectionToShape`。这次编码只用于跨 Blender Operator 传值，不属于 Selection Mask 构建。**Mesh Detail** 的 Low、Medium、High、Ultra 分别映射到 32、16、8、4 px 的采样间距，再换算期望网格分辨率；档位越高，采样越密。菜单中的 Surface、Balloon、Depth Balloon 和 Depth Surface，以及它们对应的节点分支索引，统一来自 `shape.py`。
|
||||
|
||||
### 栅格化 Selection
|
||||
|
||||
@@ -92,4 +92,20 @@ Depth Shape 的 Base Plane Depth，以及 Depth Balloon 的 Direction，都由 `
|
||||
|
||||
Normal Map 关闭时材质使用几何法线；开启时，`object.py` 把生成的图片和已经确定的 Normal Space 交给材质节点。最后 `main.py` 提交 Undo，整条 Cutout 流程结束。
|
||||
|
||||
### Inward Axis
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Base["四种 Shape<br/>内部几何 +X"] --> Switch{"Inward Axis"}
|
||||
Switch -- "+X" --> Legacy["节点几何不转换<br/>对象矩阵追加轴变换"]
|
||||
Switch -- "-Z（默认）" --> Orient["O Image Cutout 最终几何轴转换<br/>对象沿用源 Empty local transform"]
|
||||
Legacy --> World["相同世界空间结果"]
|
||||
Orient --> World
|
||||
Normal["Depth Surface<br/>Object Space Normal"] --> Mode{"Inward Axis"}
|
||||
Mode -- "+X" --> Keep["保持原通道"]
|
||||
Mode -- "-Z" --> Swizzle["(-y, z, -x)"]
|
||||
```
|
||||
|
||||
Shape 子节点始终按内部 `+X` 建模。统一的 `O Image Cutout` Modifier 在最终输出处按选项切换轴转换；`object.py` 同步选择对象矩阵，因此默认 `-Z` 与源 Image Empty 的 local transform 一致，旧 `+X` 模式仍保持相同世界空间形状。Depth Surface 的 Object Space Normal 仅在 `-Z` 模式执行通道转换；Tangent Space Normal 不变。
|
||||
|
||||
Balloon 与 Depth Balloon 的材质会创建 Geometry Attribute 节点，把 `o_balloon` 的 Float 输出直接连接到 `O Image Layer` 已有的 **Normal Scale**；Surface 与 Depth Surface 不建立这条连接。
|
||||
|
||||
@@ -1,47 +0,0 @@
|
||||
# Image Tool
|
||||
|
||||
Image Tool 从 Box、Lasso、Line 或 Polyline 手势得到一个图片 Selection，再用它修改当前 Image Empty 的 Alpha。
|
||||
|
||||
## 执行过程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Tool["Box / Lasso / Line / Polyline"] --> Gesture["采集图片空间手势"]
|
||||
Gesture --> Path["构建 SelectionPath"]
|
||||
Path --> Selection["SelectionPath → 几何 SelectionMask"]
|
||||
Selection --> Refine{"Refine Selection？"}
|
||||
Refine -- "否" --> Alpha["读取局部 RGBA<br/>源 Alpha × Selection 值"]
|
||||
Alpha --> Crop["计算内容 bounds<br/>创建并写回 Image"]
|
||||
Refine -- "是" --> Bounds["读取 RGBA<br/>写出几何 bounds 矩形"]
|
||||
Bounds --> Job["refine-image-selection"]
|
||||
Job --> Result["加载并 Pack BEN2 RGBA"]
|
||||
Result --> Replace["按响应内容 bounds 替换 Empty"]
|
||||
```
|
||||
|
||||
四个工具共用 `EditImageMask`。Box 和 Lasso 可以执行 Refine Selection；Line 与 Polyline 始终保留几何边界，直接使用本地 `SelectionMask`。
|
||||
|
||||
## 节点说明
|
||||
|
||||
### 选择工具并采集手势
|
||||
|
||||
`operators/image_tool/__init__.py` 汇总注册类型；`box.py`、`lasso.py`、`line.py` 和 `polyline.py` 分别定义四个 WorkspaceTool。它们都把操作交给 `edit_mask.py` 中的 `EditImageMask`。
|
||||
|
||||
屏幕坐标投射、点击选择、轨迹预览和状态切换来自 `common/viewport.py`。Lasso 按移动距离采点并合并近似共线点；Line 扩展为有向半平面；Polyline 在确认时闭合路径。
|
||||
|
||||
### SelectionPath → SelectionMask
|
||||
|
||||
`ImageSelectionGesture` 把手势整理为内存中的 `SelectionPath`，其中 Points 与 Invert 共同定义 Selection，并直接交给同一个 `EditImageMask` Operator，不经过 JSON。预览和最终 Mask 统一使用 non-zero winding，同方向重复绕行的重叠区域保持选中。实际图片编辑开始后，`EditImageMask` 通过 `common/selection.py` 在必要画布内把路径栅格化为一次纯几何 `SelectionMask`；这一阶段不读取或接收源图 Alpha。预览缓存只在轨迹变化时更新。
|
||||
|
||||
Box 和 Lasso 分别读取自己的 **Refine Selection** 设置。Line 与 Polyline 直接使用几何边界。
|
||||
|
||||
### Refine Selection
|
||||
|
||||
未开启 Refine Selection 时，`edit_mask.py` 在实际编辑阶段读取 RGBA 并使用本地几何 `SelectionMask`。开启后，它按 Selection 几何 bounds 写出完整矩形 RGBA 并提交给 `server/jobs/refine_image_selection.py`；矩形内、Lasso 外的源像素与 Alpha 保持原样。Job 调用 `server/selection/refine_selection.py` 运行 BEN2，并返回按结果 Alpha 收紧后的图片和局部内容 `bounds`。
|
||||
|
||||
Lasso 在 Refine 中只提供矩形上下文，不再作为 BEN2 输出的硬 Mask。响应阶段把局部内容 bounds 映射回源图，并直接加载、配置和 Pack BEN2 已编码的 RGBA 后替换 Empty；不再提取输出 Alpha、重读源图或重新创建同一颜色图片。
|
||||
|
||||
### 源 Alpha × SelectionMask
|
||||
|
||||
`edit_mask.py` 在 `SelectionMask.bounds` 内复用源 RGBA，只把几何 Selection 值乘入源 Alpha，再按行列可见范围计算内容 bounds 并紧裁切。几何 SelectionMask 在合并前后保持不变。像素读取、结果 Image 创建和共享引用处理使用 `common/image.py`。
|
||||
|
||||
公共 Image Empty 替换入口同步更新 `empty_display_size` 和 `empty_image_offset`，使裁切后的内容对齐原图片平面并保持对象 `matrix_world`。
|
||||
@@ -9,9 +9,8 @@
|
||||
| `operators/clipboard_image/` | [Clipboard Image](clipboard-image.md) | 系统剪贴板读取、粘贴与快捷键 |
|
||||
| `operators/convert_to_plane/` | [Convert to Plane](convert-to-plane.md) | Mesh Plane 与 Depth Plane 创建 |
|
||||
| `operators/cutout_tool/` | [Cutout Tool](cutout-tool.md) | Selection、基础 Shape 构建与 Blender 对象创建 |
|
||||
| `operators/crop_tool/` | [Crop Tool](crop-tool.md) | Box、Lasso、Polyline 与 Perspective 图片裁切 |
|
||||
| `operators/debug.py` | [Debug Operator](debug.md) | 模型接口与原始产物验证 |
|
||||
| `operators/image_tool/` | [Image Tool](image-tool.md) | Box、Lasso、Line 与 Polyline 编辑 |
|
||||
| `operators/perspective_tool/` | [Perspective Tool](perspective-tool.md) | 四点透视框与透视校正 |
|
||||
| `operators/remove_background.py` | [Remove Background](remove-background.md) | BEN2 去背与结果替换 |
|
||||
| `operators/upscale.py` | [Upscale](upscale.md) | 当前 Image 的 4× 高清与输入长边检查 |
|
||||
|
||||
|
||||
@@ -1,40 +0,0 @@
|
||||
# Perspective Tool
|
||||
|
||||
Perspective Tool 从图片上的四个角点建立透视四边形，把其中内容重采样为指定宽高比的矩形并写回当前 Image Empty。
|
||||
|
||||
## 执行过程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Click["点击四个角点"] --> Quad["规范为凸四边形"]
|
||||
Quad --> Preview["生成 512 × 512 预览"]
|
||||
Preview --> Ratio["调整目标宽高比"]
|
||||
Ratio --> Size["计算受限输出尺寸"]
|
||||
Size --> Warp["全分辨率 Homography"]
|
||||
Warp --> Crop["按可见 Alpha 紧裁切"]
|
||||
Crop --> Write["Pack 并写回 Empty"]
|
||||
```
|
||||
|
||||
第四点确认后生成预览，拖动鼠标调整目标宽高比，用户确认后执行全分辨率 Warp。整个流程在 Blender 进程内完成。
|
||||
|
||||
## 节点说明
|
||||
|
||||
### 采集并规范四个角点
|
||||
|
||||
`operators/perspective_tool/__init__.py` 导出注册类型，交互和计算集中在 `edit_perspective.py`。`ImagePerspectiveTool` 启动 `EditImagePerspective`，后者接受任意顺序的四个图片角点，再根据源图 X/Y 方向整理成不交错的凸 Quad。
|
||||
|
||||
图片坐标投射和首次点击选择复用 `common/viewport.py`。四个角点在该流程中统一表示为 Quad。
|
||||
|
||||
### 预览并调整比例
|
||||
|
||||
第四点确定后，`edit_perspective.py` 创建 512 × 512 预览纹理。鼠标移动更新目标宽高比和 HUD，并可吸附到常用比例。
|
||||
|
||||
输出尺寸根据 Quad 边长和目标比例计算，最长边不超过 8192 px，总像素不超过 16,777,216。
|
||||
|
||||
### 执行 Homography
|
||||
|
||||
确认后，`edit_perspective.py` 计算 Homography，并按 256 行分块处理全分辨率像素。插值使用预乘 Alpha，避免透明边缘混入黑色。
|
||||
|
||||
### 裁切并写回
|
||||
|
||||
Warp 结果按可见 Alpha 紧裁切，再通过 `common/image.py` 创建 Packed Image 并替换当前 Empty。写回时保持中心和覆盖尺度近似一致。
|
||||
Reference in New Issue
Block a user