nan
bdbde1a10d
- Renamed "Base Plane Depth" to "Reference Depth" across validate_cutout.py for consistency. - Introduced a new specification for Cutout mesh sampling to ensure source pixel spacing is preserved and limits are applied correctly. - Unified naming conventions for image editing results to maintain consistency across Remove Background, Upscale, and Crop operations. - Updated the handling of Refine Selection to ensure it retains the original bounds and does not apply unnecessary cropping. - Enhanced material generation logic to connect image color directly to IOR Level, improving the rendering of dark areas. - Established clear requirements for geometry depth controls and image result materials to ensure consistent behavior across different components. - Removed outdated logic and ensured all changes are documented and tested for regression.
118 lines
8.7 KiB
Markdown
118 lines
8.7 KiB
Markdown
# Common 公共函数
|
||
|
||
`src/anyimage/common/` 按 AI、Image、Selection、Viewport、Depth、Material、Object 和 Node 八个业务模块提供 Blender 侧复用能力。调用方直接从对应模块导入函数。
|
||
|
||
## Image 数据块
|
||
|
||
`image.py` 处理 Blender `Image` 数据块及其在 Image Empty 上的完整生命周期，包括像素读取、动画帧、Job 输入、结果 Image 创建和 Empty 引用替换。
|
||
|
||
| 函数 | 职责 |
|
||
| --- | --- |
|
||
| `image.is_image_empty()` | 判断对象是否为带有效 Image 数据的 Empty。 |
|
||
| `image.require_image_empty()` | 按名称取得 Image Empty；对象已失效时抛错。 |
|
||
| `image.image_pixels()` | 以 Blender 原始顺序读取一维 float32 像素。 |
|
||
| `image.image_rgba()` | 读取为 Top-down RGBA float32 数组。 |
|
||
| `image.video_total_frames()` | 返回 Movie 或 Sequence 总帧数，静态图返回 1。 |
|
||
| `image.image_user_settings()` | 读取 Image Empty 的帧起点、偏移、时长和循环设置。 |
|
||
| `image.default_extract_frames()` | 取得当前 Empty 默认应处理的帧数。 |
|
||
| `image.source_start_frame()` | 从源 Image Empty 取得 Job 应处理的起始帧。 |
|
||
| `image.prepare_image_input()` | 将 Packed、Dirty、Sequence 等输入准备为 Job 可读路径，并返回临时标记。 |
|
||
| `image.prepare_image_bounds_input()` | 复用调用方已读取的 RGBA，按几何 bounds 写出保留原始 Alpha 的矩形 Job 输入。 |
|
||
| `image.cleanup_image_input()` | 清理由图片输入 helper 创建的临时文件或目录。 |
|
||
| `image.image_base_name()` | 去除图片或视频扩展名和 Blender 数字后缀，得到数据块基础名。 |
|
||
| `image.depth_data_name()` | 生成 Depth 结果数据块文件名。 |
|
||
| `image.color_data_name()` | 生成 Color 结果数据块文件名。 |
|
||
| `image.load_image_edit_result()` | 加载、Pack 并配置直接编辑源 Image 的 Job 结果，以源 Image 完整名称请求新数据块名称。 |
|
||
| `image.load_color_result_image()` | 加载、命名、Pack 并配置材质 Color 或 Sequence 结果；不修改 Empty。 |
|
||
| `image.load_normal_result_image()` | 加载、命名、设为 Non-Color 并 Pack Normal Map。 |
|
||
| `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 等材质派生贴图。
|
||
|
||
## Image Selection 与视图交互
|
||
|
||
这组公共能力使用固定术语：
|
||
|
||
- 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 生成阶段执行。
|
||
|
||
所有 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()` | 判断当前上下文是否允许启动图片编辑工具。 |
|
||
| `viewport.resolve_image_edit_click()` | 解析点击到 Image Empty，并保持或恢复选择状态。 |
|
||
| `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.screen_path_to_image_pixels()` | 将屏幕路径投影为 Image Empty 像素坐标。 |
|
||
| `viewport.serialize_matrix()` | 将 4×4 Matrix 序列化为 Operator 可保存的字符串。 |
|
||
| `viewport.deserialize_matrix()` | 恢复已序列化的 4×4 Matrix。 |
|
||
| `viewport.drawing_in_region()` | 判断 Modal 绘制是否仍位于启动时的 Area 和 Region。 |
|
||
|
||
### Selection 栅格化
|
||
|
||
| 函数 | 职责 |
|
||
| --- | --- |
|
||
| `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 像素。 |
|
||
|
||
## Depth 产物
|
||
|
||
`depth.py` 负责 Blender 侧共享的 Depth 文件加载和相机尺度换算，直接加载 Server 写出的 EXR。
|
||
|
||
| 函数 | 职责 |
|
||
| --- | --- |
|
||
| `depth.load_depth_metadata()` | 读取并校验 `depth.json` 中的图片尺寸、相机内参与参考深度。 |
|
||
| `depth.load_depth_result_image()` | 直接加载、命名、设为 Non-Color 并 Pack `vector-depth.exr` 或 `z-depth.exr`。 |
|
||
| `depth.camera_depth_values()` | 从已加载 Depth Image 读取用于本地标定的 Z 与有效区。 |
|
||
| `depth.depth_uniform_scale()` | 根据相机内参、参考深度和 Image Empty 范围计算统一尺度。 |
|
||
|
||
## Object 构建
|
||
|
||
`material.py` 构建 Image 材质；`object.py` 处理 Object 与 Geometry Nodes Modifier；`node.py` 加载节点资产。
|
||
|
||
| 函数 | 职责 |
|
||
| --- | --- |
|
||
| `node.load_node_group()` | 从随扩展分发的 Blend 资产加载指定 Node Group。 |
|
||
| `material.create_image_material()` | 从 Image Empty 创建包含颜色、位移、Normal Map、Alpha 和动画设置的完整材质；非 Shadeless 材质由 Color 直接驱动 Principled IOR Level。 |
|
||
| `object.modifier_input_identifier()` | 按接口名称解析 Geometry Nodes Modifier 输入 Identifier。 |
|
||
| `object.set_modifier_input()` | 跨受支持 Blender RNA 形式设置 Modifier 输入。 |
|
||
| `object.finalize_object_result()` | 激活结果对象，并按需替换或保留源 Empty。 |
|
||
|
||
|
||
## AI 准备
|
||
|
||
`ai.py` 统一处理 AI 功能的 Environment、模型、Device、输入校验、Job 参数和公共 UI。
|
||
|
||
| 函数 | 职责 |
|
||
| --- | --- |
|
||
| `ai.draw_ai_setup()` | 绘制 AI 未就绪时的安装入口，并返回当前状态。 |
|
||
| `ai.draw_ai_property()` | 按 AI 就绪状态绘制并启用业务属性。 |
|
||
| `ai.require_input_path()` | 解析 Blender 路径并要求其为现存文件或目录。 |
|
||
| `ai.require_background_input_path()` | 在通用路径校验之外限制 BEN2 支持的媒体类型。 |
|
||
| `ai.production_device()` | 读取正式任务使用的计算设备。 |
|
||
| `ai.require_environment()` | 要求 AnyImage AI Environment 已就绪。 |
|
||
| `ai.invoke_ai_setup_if_needed()` | Environment 未就绪时启动安装交互。 |
|
||
| `ai.require_model()` | 校验模型标识和下载状态，并返回模型记录。 |
|
||
| `ai.da3_parameters()` | 组装 `debug-da3` 参数。 |
|
||
| `ai.moge2_parameters()` | 组装 MoGe-2 正式任务与 Debug 共用参数。 |
|