Files

nan 08309f719d feat: Implement cutout tool and depth generation features

- Added a new cutout tool for selecting regions in images, allowing users to choose mesh shapes based on selected areas.
- Introduced depth generation capabilities for rasterized images, including normal data extraction.
- Created jobs for generating depth planes and region data, enhancing the AI data generation workflow.
- Developed a selection refinement process for cutout regions, improving accuracy in generated outputs.
- Established a new region module for handling rasterized image regions and their associated AI generation tasks.
- Enhanced node graph builders for asset generation, facilitating smoother integration of new features.

2026-08-30 23:09:13 +08:00

7.5 KiB

Raw Blame History

Common 公共函数

src/anyimage/operators/common/ 集中已经被多个功能复用的 Blender 侧原子能力，目的是让开发新功能时能够先查找并复用现有实现，避免重复造轮子。

本页只列功能模块直接调用的公共函数，不列 common/ 内部辅助函数、测试或资产工具专用函数，也不列公共类型。

Image 数据块

image_data.py 处理 Blender Image 数据块及其在 Image Empty 上的使用方式，包括像素读取、动画帧、Job 输入、结果 Image 创建和 Empty 引用替换。它不处理 Viewport 手势或选区算法。

函数	职责
`image_data.is_image_empty()`	判断对象是否为带有效 Image 数据的 Empty。
`image_data.require_image_empty()`	按名称取得 Image Empty；对象已失效时抛错。
`image_data.image_pixels()`	以 Blender 原始顺序读取一维 float32 像素。
`image_data.image_rgba()`	读取为 Top-down RGBA float32 数组。
`image_data.video_total_frames()`	返回 Movie 或 Sequence 总帧数，静态图返回 1。
`image_data.image_user_settings()`	读取 Image Empty 的帧起点、偏移、时长和循环设置。
`image_data.default_extract_frames()`	取得当前 Empty 默认应处理的帧数。
`image_data.source_start_frame()`	从源 Image Empty 取得 Job 应处理的起始帧。
`image_data.prepare_image_input()`	将 Packed、Dirty、Sequence 等输入准备为 Job 可读路径，并返回临时标记。
`image_data.prepare_region_input()`	将 `RegionMask` 裁切为带 Mask Alpha 的临时 RGBA Job 输入。
`image_data.cleanup_image_input()`	按临时标记清理由 `prepare_image_input()` 创建的文件或目录。
`image_data.image_base_name()`	去除图片或视频扩展名和 Blender 数字后缀，得到数据块基础名。
`image_data.depth_data_name()`	生成 Depth 结果数据块文件名。
`image_data.color_data_name()`	生成 Color 结果数据块文件名。
`image_data.load_color_result_image()`	加载、命名、Pack 并配置 Job 的 Color 或 Sequence 结果；不修改 Empty。
`image_data.load_normal_result_image()`	加载、命名、设为 Non-Color 并 Pack Normal 结果。
`image_data.create_pixel_result_image()`	从本地编辑后的 RGBA 像素创建 Packed Image；不修改 Empty。
`image_data.replace_empty_image()`	执行 Image Empty 结果替换、共享引用分流、旧数据清理、帧设置继承和可选画布对齐。
`image_data.image_empty_bounds()`	计算 Image Empty 在对象局部坐标中的实际显示边界。

load_*_result_image() 和 create_pixel_result_image() 只创建结果 Image；replace_empty_image() 负责把结果提交给当前 Empty。两者分别表达“创建产物”和“替换引用”。

Image Region 与视图交互

这组公共能力使用固定术语：

Region 是用户在图片空间圈定的业务范围；RegionPath 保存路径点、反选状态和填充规则。
RegionMask 是 Region 的栅格化结果，只包含局部像素权重 values 和源图 bounds。
Mask 只表示二维像素权重或 Alpha 运算，不作为手势、协议或业务范围的别名。
Selection 只用于 Blender 对象选择和界面动作 Refine Selection，不表示中间数据。

image_interaction.py 处理 3D Viewport 中的点击、坐标投影、ImageRegionGesture、工具设置和预览绘制；image_region.py 负责图片空间 Region 的值、栅格化和 Alpha 裁切。前者负责用户如何圈定 Region，后者负责 Region 如何变成 Mask。

Viewport 交互

函数	职责
`image_interaction.report_image_edit_exception()`	将可预期的图片编辑警告和异常映射为 Operator Report。
`image_interaction.image_edit_poll()`	判断当前上下文是否允许启动 Image 编辑工具。
`image_interaction.resolve_image_edit_click()`	解析点击到 Image Empty，并保持或恢复选择状态。
`image_interaction.active_view3d_tool_id()`	取得当前 View3D Workspace Tool ID。
`image_interaction.apply_region_settings()`	将当前 Region 工具的 Refine 设置同步到手势 Operator。
`image_interaction.draw_region_settings()`	绘制 Region 工具的公共 Refine 设置。
`image_interaction.draw_dashed_line()`	绘制手势或透视框虚线。
`image_interaction.draw_polygon_fill()`	绘制手势或透视框填充预览。
`image_interaction.gesture_property()`	声明统一的 Box、Lasso、Line 和 Polyline RNA 属性。
`image_interaction.screen_path_to_image_pixels()`	将屏幕路径投影为 Image Empty 像素坐标。
`image_interaction.serialize_matrix()`	将 4×4 Matrix 序列化为 Operator 可保存的字符串。
`image_interaction.deserialize_matrix()`	恢复已序列化的 4×4 Matrix。
`image_interaction.drawing_in_region()`	判断 Modal 绘制是否仍位于启动时的 Area 和 Region。

Region 栅格化

函数	职责
`image_region.region_path_bounds()`	校验 Region Path 并返回整数像素包围框。
`image_region.rasterize_region_path()`	把 `RegionPath` 栅格化为 `RegionMask`，并可与源 Alpha 相交。
`image_region.crop_pixels_to_alpha()`	按 Alpha 非零区域紧裁切 RGBA 像素。

Mesh 结果构建

mesh_result.py 集中 Convert to Plane 与 Cutout 共同使用的结果构建能力：读取图片几何产物、创建材质、加载节点资产、设置修改器输入，并完成结果对象替换。

ImageGeometry 表示按图片像素组织的三维点、相机内参、有效区域、参考深度和选区统计；load_image_geometry() 从 image_geometry.npz 读取并校验这组数据。

函数	职责
`mesh_result.load_image_geometry()`	读取并校验 `image_geometry.npz`，返回用于构建 Mesh 的 `ImageGeometry`。
`mesh_result.create_image_material()`	从 Image Empty 创建包含颜色、位移、Normal、Alpha 和动画设置的完整材质。
`mesh_result.load_asset_node_group()`	从随扩展分发的 Blend 资产加载指定 Node Group。
`mesh_result.modifier_input_identifier()`	按接口名称解析 Geometry Nodes Modifier 输入 Identifier。
`mesh_result.set_modifier_input()`	跨受支持 Blender RNA 形式设置 Modifier 输入。
`mesh_result.finalize_object_result()`	激活结果对象，并按需替换或保留源 Empty。

节点资产构建和验证专用函数位于 tools/node_assets/，不属于运行时公共能力。

AI 任务准备

ai_job.py 处理多个 AI 功能共同使用的任务准备，包括输入路径校验、Environment 与模型检查、Device 选择，以及 DA3 和 MoGe-2 请求参数组装。它不包含业务 Operator、结果导入或 Undo 操作。

函数	职责
`ai_job.require_input_path()`	解析 Blender 路径并要求其为现存文件或目录。
`ai_job.require_background_input_path()`	在通用路径校验之外限制 BEN2 支持的媒体类型。
`ai_job.production_device()`	读取正式任务使用的计算设备。
`ai_job.require_environment()`	要求 AnyImage AI Environment 已就绪。
`ai_job.invoke_ai_setup_if_needed()`	Environment 未就绪时启动安装交互。
`ai_job.require_model()`	校验模型标识和下载状态，并返回模型记录。
`ai_job.da3_parameters()`	组装 DA3 正式任务与 Debug 共用参数。
`ai_job.moge2_parameters()`	组装 MoGe-2 正式任务与 Debug 共用参数。

7.5 KiB Raw Blame History Unescape Escape