Add new tests and functionality for image processing and geometry handling
- Introduced color_image.py for preparing standalone color images for tests. - Added hdr_image.py to create HDR textures for testing. - Implemented test_image_depth_panorama.py to evaluate panorama topology, UVs, and depth discontinuities. - Created test_shadeless.py to validate the opacity and HDR color endpoints of the Shadeless group. - Developed moge3_export.py for exporting dynamic MoGe-3 backbone and ONNX graphs. - Added material.py to inherit material slots onto generated geometry. - Built image_depth_panorama.py to construct a quad panorama with depth separation and sampling.
This commit is contained in:
2
openspec/changes/add-ben2-hdr-support/.openspec.yaml
Normal file
2
openspec/changes/add-ben2-hdr-support/.openspec.yaml
Normal file
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-09-10
|
||||
72
openspec/changes/add-ben2-hdr-support/design.md
Normal file
72
openspec/changes/add-ben2-hdr-support/design.md
Normal file
@@ -0,0 +1,72 @@
|
||||
## Context
|
||||
|
||||
Remove Background 通过 ImageEditTarget 准备输入并提交结果。普通文件按路径校验，packed 图片导出 PNG；后端 BEN2 接收 Pillow RGB，预测 mask 后转换成 8-bit RGBA，Job 写入 PNG。源像素、结果载入和图片替换都涉及 HDR 精度边界。
|
||||
|
||||
BEN2 网络输出是 alpha，识别本身可复用既有模型。HDR 支持的关键是分离识别预览与原始 RGB，并让浮点信息贯穿主线程合成、EXR 编码和结果替换。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
本次交付为 HDR 静态图去背景：保留源图的场景线性色彩、有效动态范围和尺寸，以模型预测更新透明度。支持 Image Empty 和材质 Image Texture 两种已有入口，以及 Blender 可读取的外部、packed、generated 浮点静态图片。普通媒体沿用既有处理方式；HDR 动画在提交前明确提示首版支持范围。Upscale 的 HDR 适配作为独立能力评估。
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. 在 Blender 侧捕获源图和准备预览
|
||||
|
||||
以 `Image.is_float` 及真实图片来源判断 HDR 路径，扩展名仅用于来源识别与提示。所有可读浮点静态图片走该路径，包括数值暂时处于 0–1 内的图片。准备时读取当前像素，包含尚未保存的编辑；为本次任务保存独立的 RGBA 数值快照、尺寸、色彩空间和 alpha 解释信息。
|
||||
|
||||
Blender 数据仅在主线程准备与提交阶段访问，Job 参数只包含普通字典中的路径、字符串和数值。后端始终读取 PNG 识别预览，因此公共媒体格式校验仍校验实际提交文件。源图与临时文件的所有权由准备阶段和 Job cleanup 明确交接。
|
||||
|
||||
### 2. 用固定映射生成可识别的普通 RGB
|
||||
|
||||
识别预览从场景线性、非预乘 RGB 生成。Blender 的浮点缓冲已经采用场景线性颜色与预乘 alpha；预览先解关联，再采用按亮度的 Reinhard 映射，以非负亮度 Y 计算 `RGB / (1 + Y)`，执行线性 Rec.709 到 sRGB 编码并限制到可编码范围。负值只在预览中处理；源浮点数值保持原样。全黑图保持有限值。预览按源 alpha 合成到黑底，符合现有 BEN2 输入语义。
|
||||
|
||||
映射固定且不读取用户当前 View Transform、Look、Exposure，避免切换显示设置导致 mask 变化。源颜色解码由 Blender 完成。数据图片与 CHANNEL_PACKED 输入在准备时给出明确错误。
|
||||
|
||||
该映射是首版确定性基线。用实际高动态范围图片验证高光边缘、暗部与半透明物体；若识别不足，在本变更内调整并固定预览算法和对应行为测试。
|
||||
|
||||
### 3. 让 BEN2 推理核心返回数值 alpha
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[主线程捕获 HDR RGBA 快照] --> B[固定色调映射生成 PNG 预览]
|
||||
B --> C[BEN2 推理]
|
||||
C --> D[浮点 alpha 归一化并还原源尺寸]
|
||||
D --> E[Job 写入 alpha.npy]
|
||||
A --> F[主线程合成原始 RGB 与新 alpha]
|
||||
E --> F
|
||||
F --> G[写入 32-bit float RGBA EXR]
|
||||
G --> H[验证并提交到原图片目标]
|
||||
```
|
||||
|
||||
将现有推理核心重构为返回原尺寸 float32 alpha 数组。保留既有 mask 归一化语义，缩放过程使用浮点数据并在最后限制到 0–1，检查尺寸与有限值。普通 RGBA 消费者在自身产物边界完成量化与合成，清理旧核心入口并更新真实调用者。
|
||||
|
||||
Remove Background Job 增加明确的产物模式，例如 `output_kind: "alpha"`，HDR 静态图产出 `alpha.npy` 并通过结果字段声明。读取使用 `allow_pickle=False`，验证形状、范围和有限值。现有普通图片与动画消费者继续取得对应的 RGBA 结果。
|
||||
|
||||
### 4. 主线程合成和 EXR 持久化
|
||||
|
||||
在非预乘语义下计算 `A_out = A_source × A_predicted`，保留原始 RGB。Blender 原生浮点缓冲使用预乘 RGB，因此实现直接将 RGBA 乘以预测 alpha，保持解关联后的颜色；解码 STRAIGHT EXR 后同样采用该缓冲语义。零 alpha 像素的不可恢复颜色置零，NONE 模式按不透明源处理。测试分别比较 straight RGB 或重新合成后的可见颜色。
|
||||
|
||||
创建 `float_buffer=True` 的结果图片，使用独立临时场景指定 32-bit float RGBA EXR、ZIP 压缩，通过 `save_render` 写出场景线性值。结果采用 Linear Rec.709 与 PREMUL，保存后载入并核对数值，再打包和提交；临时场景及文件在对应阶段结束后释放。
|
||||
|
||||
复用 ImageEditTarget 和 common 内的提交、共享引用隔离、图片内容备份与恢复。HDR 的 Empty 提交同时保护材质节点等其他实际使用者。独占源图包含未保存像素或为生成图时，将其当前浮点内容转为内嵌 EXR 并建立撤销基线，保留 Image 身份；一次撤销恢复原始内容，重做恢复处理结果。提交失败时恢复操作前的源状态。先验证候选结果再提交，其他共享使用者保持原状。
|
||||
|
||||
### 5. 保持异步编辑事务完整
|
||||
|
||||
使用提交时的源快照进行合成，完成前复核原目标及图片绑定。纹理节点保存独立的 `anyimage_identity`，提交时与捕获值核对，避免 Blender 删除重建节点后复用 RNA 地址造成误认。增加对捕获后源像素或色彩解释被修改的冲突检查，发现冲突则提示重新执行并保留当前编辑。
|
||||
|
||||
临时预览由输入 cleanup 释放，alpha 由 Job 目录管理，候选 EXR 完成载入和打包后释放临时副本。取消、推理失败、合成失败、提交失败均释放快照与本次临时数据。成功结果支持一次撤销、重做以及保存重开。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- 固定预览映射可能压低极暗部的可辨识度：用代表性 HDR 图片进行真实 BEN2 验收。
|
||||
- Blender 像素、alpha 模式与 EXR 编码之间存在转换：以已知数值的真实 Blender 保存重开测试约束实现。
|
||||
- 源快照增加内存占用：仅保留合成和冲突检测所需的数据，所有终止路径释放；大型输入准备失败时提供可读错误。
|
||||
- 工作区相关公共入口正在修改：实施前核对现有变更，复用最新公共校验和事务接口。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
先完成数值 alpha 核心与现有消费者回归，再实现 HDR 准备、合成和事务提交。验证普通媒体行为及 HDR round-trip 后完成能力交付。Job 协议由同版本插件与后端一起更新。
|
||||
|
||||
## Open Questions
|
||||
|
||||
无需要用户决策的前置问题。Blender 像素空间、PREMUL round-trip 与固定预览的识别质量已通过数值测试及实际 BEN2 推理确认。
|
||||
27
openspec/changes/add-ben2-hdr-support/proposal.md
Normal file
27
openspec/changes/add-ben2-hdr-support/proposal.md
Normal file
@@ -0,0 +1,27 @@
|
||||
## Why
|
||||
|
||||
BEN2 通过普通 RGB 图像预测前景透明度。当前去背景流程用 Pillow 合成并保存 PNG，无法保留 HDR 图像的浮点颜色。将识别预览与原始颜色分离，可以让用户对 HDR 图片去背景，同时保留用于渲染的亮度和色彩。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 为 Remove Background 增加 HDR 静态图处理，覆盖 Blender 已加载的 EXR、Radiance HDR、已打包及生成的浮点图片。
|
||||
- 从提交时的浮点像素生成经过固定色调映射的 RGB 识别预览，原始颜色留在 Blender 侧。
|
||||
- BEN2 提供浮点 alpha 结果；主线程将其与源 alpha 相乘，并与原始颜色合成。
|
||||
- 结果使用 32-bit float RGBA EXR 持久化，支持保存重开、共享图片隔离、撤销和失败恢复。
|
||||
- 对 HDR 动画输入在准备阶段给出明确提示；普通图片与现有视频、序列沿用当前行为。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `hdr-background-removal`: HDR 静态图片的识别预览、alpha 预测、浮点结果及生命周期。
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
无已发布能力规格需要修改；与现有 ImageEditTarget 的目标提交语义衔接。
|
||||
|
||||
## Impact
|
||||
|
||||
- Blender：`common/image.py`、`common/image_target.py`、`operators/remove_background.py`；复杂的 HDR 图像处理可独立放入 `common/hdr_image.py`。
|
||||
- 后端：`server/models/onnx_ben2.py`、`server/models/ben2.py`、`server/jobs/remove_background.py`，以及对应测试。
|
||||
- 输入仍为普通预览 PNG，新增 Job 的 alpha 产物模式，复用 NumPy 保存数值结果。BEN2 权重与运行依赖保持现有配置。
|
||||
- 与进行中的 `unify-ai-input-validation` 及图片目标编辑变更共同使用实施时的真实调用链。
|
||||
@@ -0,0 +1,89 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: HDR still image preparation
|
||||
|
||||
系统 SHALL 为可读的浮点静态图片提供 Remove Background，覆盖 Image Empty 与材质 Image Texture 的外部、packed 和 generated 图片。输入 SHALL 采用任务开始时的当前像素快照。
|
||||
|
||||
#### Scenario: An HDR still is submitted
|
||||
- **WHEN** 用户对可读的 EXR、HDR 或其他浮点静态图片执行 Remove Background
|
||||
- **THEN** 系统捕获当前 RGBA、尺寸与颜色解释，并提交普通 RGB 识别预览
|
||||
|
||||
#### Scenario: Unsaved pixels are present
|
||||
- **WHEN** 源浮点图包含未保存的像素编辑
|
||||
- **THEN** 识别预览与最终 RGB 均使用当前编辑后的快照
|
||||
|
||||
#### Scenario: An HDR animation is submitted
|
||||
- **WHEN** 用户对 HDR 序列或浮点动画执行 Remove Background
|
||||
- **THEN** 系统在创建推理任务前提示本次 HDR 功能支持静态图，并保持源图状态
|
||||
|
||||
### Requirement: Deterministic recognition preview
|
||||
|
||||
系统 SHALL 通过确定性的曝光范围压缩及色彩编码生成 BEN2 的普通 RGB 预览，原始 RGB SHALL 独立保留。预览 SHALL 正确解释源 alpha，且不受用户显示变换设置影响。
|
||||
|
||||
#### Scenario: Highlights exceed one
|
||||
- **WHEN** 源图包含多个大于 1 的不同亮度值
|
||||
- **THEN** 预览先进行色调映射再编码，原始快照保留这些数值
|
||||
|
||||
#### Scenario: Display settings change
|
||||
- **WHEN** 相同源像素分别在不同 View Transform、Look 或 Exposure 下提交
|
||||
- **THEN** 识别预览一致
|
||||
|
||||
#### Scenario: The image is black or contains negative values
|
||||
- **WHEN** 可读源像素为全黑或包含有限负颜色值
|
||||
- **THEN** 预览数值有限，源 RGB 不因预览映射改变
|
||||
|
||||
### Requirement: Float alpha result
|
||||
|
||||
HDR 去背景 Job SHALL 返回原始尺寸的 float32 alpha 数组，数值有限且位于 0–1。系统 SHALL 在使用前验证产物。
|
||||
|
||||
#### Scenario: BEN2 predicts a soft edge
|
||||
- **WHEN** 模型预测连续透明度边缘
|
||||
- **THEN** alpha 经过浮点缩放返回，合成前不量化为 8-bit
|
||||
|
||||
#### Scenario: Alpha is invalid
|
||||
- **WHEN** alpha 文件损坏、尺寸不符或包含非有限及越界数值
|
||||
- **THEN** 系统报告结果错误，保持源图片与目标绑定
|
||||
|
||||
### Requirement: HDR color and transparency persistence
|
||||
|
||||
系统 SHALL 保留源 RGB 的场景线性色彩及动态范围，并以源 alpha 与预测 alpha 的乘积作为结果透明度。结果 SHALL 为同尺寸浮点图像并采用 32-bit float RGBA EXR 持久化，颜色误差 SHALL 限于浮点运算与必要颜色转换的容差。
|
||||
|
||||
#### Scenario: Straight alpha is present
|
||||
- **WHEN** 源图为 straight alpha 且存在大于 1 的 RGB 和部分透明像素
|
||||
- **THEN** 结果 RGB 保留，alpha 等于源 alpha 乘预测 alpha
|
||||
|
||||
#### Scenario: Premultiplied alpha is present
|
||||
- **WHEN** 源图采用 PREMUL 且包含部分透明及完全透明像素
|
||||
- **THEN** 系统按 alpha 关联语义合成，边缘颜色正确且结果没有 NaN 或 Inf
|
||||
|
||||
#### Scenario: The project is saved and reopened
|
||||
- **WHEN** 用户保存含处理结果的 blend 文件后重新打开
|
||||
- **THEN** 结果尺寸、HDR 数值、颜色解释和透明度保持一致
|
||||
|
||||
### Requirement: Transactional target update
|
||||
|
||||
系统 SHALL 复用既有图片目标提交规则，保护共享使用者并支持撤销、重做与错误恢复。Blender 数据访问 SHALL 发生于主线程，任务通信 SHALL 使用可序列化普通参数。
|
||||
|
||||
#### Scenario: Another owner shares the image
|
||||
- **WHEN** 源图片存在其他实际使用者
|
||||
- **THEN** 仅发起操作的目标取得独立 HDR 结果，其他使用者仍引用原图
|
||||
|
||||
#### Scenario: The source changes during inference
|
||||
- **WHEN** 原目标失效、改绑图片或源像素与颜色解释发生修改
|
||||
- **THEN** 系统拒绝覆盖当前状态，提示重新执行并清理本次临时资源
|
||||
|
||||
#### Scenario: The operation is cancelled or fails
|
||||
- **WHEN** 准备、推理、合成或提交取消或失败
|
||||
- **THEN** 系统保持或恢复源图及目标绑定，释放本次快照和临时数据
|
||||
|
||||
#### Scenario: The user undoes and redoes
|
||||
- **WHEN** 用户撤销并重做一次成功的 HDR 去背景
|
||||
- **THEN** 原始和处理后的浮点内容及绑定正确恢复，重做无需重新推理
|
||||
|
||||
### Requirement: Existing media behavior
|
||||
|
||||
系统 SHALL 保留普通图片、视频和普通序列的现有去背景行为，所有 BEN2 消费者 SHALL 适配统一的数值 alpha 核心。
|
||||
|
||||
#### Scenario: An existing regular image or animation is processed
|
||||
- **WHEN** 用户提交现有支持的普通图片或动画
|
||||
- **THEN** 系统按既有帧选择、透明度合成和输出规则完成操作
|
||||
31
openspec/changes/add-ben2-hdr-support/tasks.md
Normal file
31
openspec/changes/add-ben2-hdr-support/tasks.md
Normal file
@@ -0,0 +1,31 @@
|
||||
## 1. 验证浮点图片基础行为
|
||||
|
||||
- [x] 1.1 核对最新输入校验、BEN2 消费者与图片提交调用链，保留工作区已有修改。
|
||||
- [x] 1.2 在真实 Blender 中验证已知 HDR 数值、straight/PREMUL alpha、色彩空间及 32-bit EXR 保存载入行为，确定可用颜色转换与数值容差。
|
||||
- [x] 1.3 检查图片内容备份、原位替换、打包及撤销对 float buffer 的支持，定位需要修改的公共边界。
|
||||
|
||||
## 2. 分离 BEN2 alpha 核心
|
||||
|
||||
- [x] 2.1 将推理核心改为返回原尺寸 float32 alpha，保留归一化行为，使用浮点缩放并校验有限值。
|
||||
- [x] 2.2 更新所有真实 BEN2 消费者及相关测试，在各自输出边界合成 RGBA，移除旧核心入口。
|
||||
- [x] 2.3 为 Remove Background Job 增加静态 alpha 产物模式、结果字段及安全的 NumPy 读写校验，覆盖错误与取消路径。
|
||||
|
||||
## 3. 准备 HDR 识别输入
|
||||
|
||||
- [x] 3.1 在主线程识别浮点静态图并捕获当前 RGBA 快照，覆盖外部、packed、generated 和未保存像素。
|
||||
- [x] 3.2 实现固定色调映射及 sRGB 预览编码，覆盖 alpha、负值、全黑及显示设置独立性。
|
||||
- [x] 3.3 接入 Remove Background 的准备与普通参数提交，明确拒绝 HDR 动画并验证临时输入清理。
|
||||
|
||||
## 4. 合成与提交 HDR 结果
|
||||
|
||||
- [x] 4.1 校验 float alpha 并按 straight/PREMUL 语义合成，保留源 HDR RGB 和尺寸。
|
||||
- [x] 4.2 创建浮点结果并写入无损 32-bit RGBA EXR，完成载入、打包及临时文件释放。
|
||||
- [x] 4.3 复用并补全 ImageEditTarget 的浮点提交与恢复行为，覆盖共享隔离、独占 Image 身份、源修改冲突、撤销和重做。
|
||||
- [x] 4.4 验证取消、失败、目标失效各路径的资源释放和源状态恢复。
|
||||
|
||||
## 5. 验收
|
||||
|
||||
- [x] 5.1 更新并运行相关后端、common 和 Operator 测试，覆盖浮点 alpha 精度与现有普通媒体行为。
|
||||
- [x] 5.2 用已知 RGB 大于 1、有限负值、软 alpha 的图片进行真实 Blender 两种入口及保存重开验证；记录数值误差。
|
||||
- [x] 5.3 用代表性 HDR 实图运行 BEN2，检查高光、暗部、半透明边缘与黑底预览效果，必要时调整固定映射并补齐验证。
|
||||
- [x] 5.4 运行全量 `uv run pytest` 并确认正常退出，检查最终差异及旧入口引用，记录验证结果。
|
||||
32
openspec/changes/add-ben2-hdr-support/validation.md
Normal file
32
openspec/changes/add-ben2-hdr-support/validation.md
Normal file
@@ -0,0 +1,32 @@
|
||||
## 验证环境
|
||||
|
||||
2026-09-10，Windows，项目 uv 环境，Blender Python 4.5.3 LTS，BEN2 本地 `models/BEN2-ONNX/onnx/model_fp16.onnx`，ONNX Runtime CPU。
|
||||
|
||||
## 浮点与编辑事务
|
||||
|
||||
- 真实 Blender 验证外部 EXR、packed、generated、未保存像素，覆盖 Image Empty 与材质 Image Texture，以及共享和独占图片。
|
||||
- RGBA 样本包含大于 1 的颜色、有限负值、零 alpha 与部分透明像素；32-bit ZIP EXR 保存、打包、载入和 blend 保存重开均通过数值检查。
|
||||
- 单独验证 STRAIGHT EXR 解码后的预乘缓冲语义，处理后解关联颜色在 `rtol=1e-6` 内保持一致。
|
||||
- 已验证 Radiance `.hdr` 实际文件读取与识别预览生成，源浮点像素保持不变。
|
||||
- 原生 Operator 的撤销、重做、取消、提交异常和资源释放通过测试；未保存的独占浮点源图采用内嵌 EXR 撤销基线。
|
||||
- 纹理节点删除重建测试覆盖独立身份字段，防止 RNA 地址复用造成异步目标误认。
|
||||
|
||||
## 实际 BEN2 推理
|
||||
|
||||
Cycles 渲染 320×320 金属 Suzanne，16 samples，两盏面光源，原始 RGB 峰值约 112.432。用渲染 alpha 作为轮廓参考，构造三档曝光的灰底 HDR 图，以及保留原始软 alpha 的透明图。四组均执行真实 BEN2 Job、浮点 alpha 读回、Blender 合成及 EXR 持久化。
|
||||
|
||||
| 输入 | 原始 RGB 峰值 | 输出预乘 RGB 峰值 | 轮廓 IoU |
|
||||
| --- | ---: | ---: | ---: |
|
||||
| 正常亮度 | 112.4321 | 112.4235 | 0.9822 |
|
||||
| 16 倍亮度 | 1798.9137 | 1796.3881 | 0.9874 |
|
||||
| 0.05 倍亮度 | 5.6216 | 5.6176 | 0.9757 |
|
||||
| 原始透明度 | 112.4321 | 112.4292 | 0.9656 |
|
||||
|
||||
IoU 使用预测 alpha 与渲染 alpha 的 0.5 阈值轮廓计算。四组 EXR 读回值相对于 `source_rgba × predicted_alpha` 的最大绝对误差均为 0。已目视检查高亮预览、低亮度预览与预测轮廓。该结果验证当前渲染样例的识别效果；不同实图的抠图质量取决于模型预测。
|
||||
|
||||
## 自动检查
|
||||
|
||||
- OpenSpec 严格校验通过。
|
||||
- BEN2 的旧 `infer` 入口及旧节点使用者检查名称已清理，相关调用者和测试已更新。
|
||||
- 最终 `uv run pytest -q`：1074 passed、2 xfailed、52 subtests passed，175.71 秒，退出码 0。两项 xfail 为已有的浮点图片显示色彩空间适配测试。
|
||||
- `git diff --check` 通过。
|
||||
2
openspec/changes/add-moge3-model/.openspec.yaml
Normal file
2
openspec/changes/add-moge3-model/.openspec.yaml
Normal file
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-09-10
|
||||
63
openspec/changes/add-moge3-model/design.md
Normal file
63
openspec/changes/add-moge3-model/design.md
Normal file
@@ -0,0 +1,63 @@
|
||||
## Context
|
||||
|
||||
项目现有几何推理使用 ONNX Runtime，Windows 使用 DirectML，其他平台使用默认 Runtime。MoGe 3 的稀疏细化已在项目外改写为标准 ONNX 索引、聚合和矩阵运算，完整三次细化已实际运行。
|
||||
|
||||
实现使用上游提交 `74fbce054ebed49800de42d0ad0e83495065719a`，骨干与细化分别导出为 ONNX 图。骨干支持动态输入和 token 数，细化支持动态点数。在 RTX 5070 Ti 上，1200–3600 tokens 的完整动态推理约需 4.86–17.11 秒，平均深度相对误差约 0.002%，二值 Mask 完全一致。参考比较关闭 FlexGEMM 独立的 TF32 开关。Windows DirectML 与 Linux CPU 均已通过真实 Job 验证，详细结果见 [验收记录](validation.md)。
|
||||
|
||||
实验脚本与日志位于项目外 `C:/Users/icrdr/AppData/Local/Temp/anyimage-moge3-trial/`。正式转换位于 `tools/models/moge3_export.py`，模型准备和运行使用项目已有的资产机制。
|
||||
|
||||
## Goals
|
||||
|
||||
以最小改动将完整 MoGe 3 接入 MoGe 2 的现有工程流程，沿用输入准备、参数、下载、会话管理和几何产物契约。
|
||||
|
||||
## Decisions
|
||||
|
||||
### 动态尺寸与分辨率等级作为接入门槛
|
||||
|
||||
正式模型接收现有输入准备流程产生的图片尺寸及宽高比，沿用现有 resolution_level 到 token 数的控制方式，输出尺寸对应分析图片。256×192 / 1200 tokens 是原型测试配置，正式推理需通过动态形状及可变 token 数验证，同一组模型资产在任务间接受不同配置。
|
||||
|
||||
沿用已验证的两个图边界：骨干输出初始坐标、编码特征、法线、Mask 和尺度；细化图输出 log-depth 增量。MoGe 3 模块内部使用 NumPy 生成体素邻域并执行三轮调度，学习网络计算全部由 ONNX Runtime 执行，几何恢复复用现有后处理能力。逐层对比用于验证动态化后的数值一致性。
|
||||
|
||||
正式 Runtime 使用标准 ONNX 图和现有执行提供程序，完整执行三次细化。原型中主要网络计算由 DirectML 执行，部分索引与计数节点由 ONNX Runtime CPU 执行；正式验收继续记录实际执行路径。
|
||||
|
||||
### 最小工程改动
|
||||
|
||||
沿用现有图像准备、最大分析尺寸、分辨率等级、设备选择、Job 参数和产物。新模型特有的图集合、索引生成及迭代封装在 `models/onnx_moge3.py`；已有推理调用点只增加必要的模型分派。
|
||||
|
||||
复用现有模型下载与会话生命周期，通用编排名称仅在职责确实扩展时局部调整并一次更新真实调用者。Operator、Blender 响应和节点资产继续消费现有契约。正式运行依赖保持现有 ONNX 和后处理体系，离线转换依赖独立管理。
|
||||
|
||||
### 精度和性能验证
|
||||
|
||||
比较同权重、相同输入与分辨率等级的原始三次细化结果和 ONNX 结果。先用 FP32 验证语义，再评估 FP16。实验需在导出前声明验收容差，记录有效区域深度与点图误差、法线角误差、内参偏差、Mask 一致性及每次细化误差，不得根据结果事后放宽。
|
||||
|
||||
样本包含室内、细小物体、室外、不同宽高比及全景透视视图；覆盖低/高分辨率等级、自动 FOV 与固定 90 度 FOV。记录转换耗时、ONNX 文件大小、会话启动、热推理耗时及峰值内存/显存。Windows 验证 CPU 和 DirectML 的完整执行情况及实际算子回退；其他平台需分别验证，不沿用 PyTorch 的 CUDA 平台限制。
|
||||
|
||||
### 验证后的正式接入
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[已验证的双 ONNX 图原型] --> B[动态尺寸及分辨率等级验证]
|
||||
B --> C{精度 性能 提供程序通过}
|
||||
C -->|通过| D[生成并校验模型资产]
|
||||
D --> E[登记模型与下载]
|
||||
E --> F[统一 MoGe ONNX 推理入口]
|
||||
F --> G[深度平面 裁切 全景]
|
||||
C -->|未通过| H[记录阻碍与实验结果]
|
||||
```
|
||||
|
||||
转换工具放在 `tools/models`，依赖固定版本或上游提交；最终登记所有图文件及 external data 的大小和哈希，完整下载后标记就绪。镜像发布后才登记对应来源。生产推理只读取已准备的 ONNX 资产。
|
||||
|
||||
新增模型沿用现有几何模型枚举，保留已有模型键和默认值；仅调整识别新模型所必需的元数据与筛选。输出使用现有 CPU NumPy 数组和相机内参约定。全景传入 90 度 FOV，保持 Mask 与源有效性、Alpha 合成以及径向距离融合契约。
|
||||
|
||||
缓存按模型、设备和图集合识别，连续帧及视图复用会话，切换模型和关闭时释放资源。取消与失败沿用现有 Job 事务。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- 动态体素分箱可能放大浮点数值差异 → 对相同 FP32 配置按预定容差比较。
|
||||
- 高分辨率等级增加计算量与内存 → 已记录 CPU/DirectML 性能及峰值占用，继续沿用现有分辨率等级控制。
|
||||
- 多图执行会增加 CPU/GPU 数据搬运 → 测量完整流水线耗时并据此决定图边界。
|
||||
- 提供程序算子覆盖不同 → Windows DirectML 与 Linux CPU 已验收，macOS 仍需实机验证。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
先基于已完成原型验证动态尺寸、分辨率等级、精度与性能，再完成转换工具和模型登记。沿用现有设置与默认模型，只增加新模型选择及必要分派。实施更新相关测试，检查依赖与打包内容一致性。
|
||||
23
openspec/changes/add-moge3-model/proposal.md
Normal file
23
openspec/changes/add-moge3-model/proposal.md
Normal file
@@ -0,0 +1,23 @@
|
||||
## Why
|
||||
|
||||
MoGe-3 ViT-L 的完整三次细化已在项目外通过 CPU ONNX Runtime 与 DirectML 原型验证。正式接入应沿用 MoGe 2 的工程流程，以最小改动增加模型选项，并完成动态输入和分辨率等级验证。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 将已跑通的双 ONNX 图原型扩展到现有输入尺寸处理、宽高比和分辨率等级，建立可复现导出与精度比较流程。
|
||||
- 验证通过后新增 `MOGE3_VITL` 模型选项、ONNX 资产下载和就绪检查，保留已有模型及默认值。
|
||||
- 深度平面、裁切与全景统一按模型分派，推理统一采用现有 ONNX Runtime，复用几何产物。
|
||||
- 两个 ONNX 图、体素邻域生成与三次细化封装在 MoGe 3 模型内部；复用现有 Operator、节点资产、Job 参数和用户操作流程。
|
||||
- 以完整细化、数值一致性、执行提供程序兼容性与可用性能作为正式接入门槛。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `moge3-model`: 完整 MoGe 3 的 ONNX 推理、模型选择、资产准备与几何工作流集成。
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
## Impact
|
||||
|
||||
改动集中在离线转换工具、模型登记、MoGe 3 ONNX 模块和必要的推理分派；模型枚举、下载与会话管理沿用既有机制。PyTorch、MoGe、FlexGEMM 与 Triton 仅用于隔离的离线转换及参考验证环境；正式 Server 沿用 ONNX Runtime 与现有后处理依赖。正式接入以动态尺寸、分辨率等级及完整流程验收通过为前提。
|
||||
73
openspec/changes/add-moge3-model/specs/moge3-model/spec.md
Normal file
73
openspec/changes/add-moge3-model/specs/moge3-model/spec.md
Normal file
@@ -0,0 +1,73 @@
|
||||
## Purpose
|
||||
|
||||
让用户通过现有 ONNX Runtime 体系使用完整的 MoGe-3 ViT-L 几何预测，使模型准备、选择和执行在深度平面、裁切与全景中具有一致行为，并通过完整细化及数值验证保证结果可信。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Execute complete MoGe 3 with ONNX
|
||||
|
||||
正式推理 SHALL 通过 ONNX Runtime 执行 MoGe 3 的学习网络计算，并完成三次细化；运行环境 SHALL 无需 PyTorch、FlexGEMM 或 Triton。
|
||||
|
||||
#### Scenario: Production inference
|
||||
- **WHEN** 在仅安装声明的 ONNX 运行依赖的 Server 中执行 MoGe 3
|
||||
- **THEN** 完成包含三次细化的预测，不依赖外部 Torch 环境或服务
|
||||
|
||||
### Requirement: Validate conversion before availability
|
||||
|
||||
系统 SHALL 在完整流程的动态尺寸、分辨率等级、精度、性能和执行提供程序验证通过后才将新模型登记为正式可用模型。
|
||||
|
||||
#### Scenario: Incomplete conversion
|
||||
- **WHEN** 只有关闭细化的模型可以运行，或完整模型未通过预定数值验收
|
||||
- **THEN** 保留验证结果且不将其作为完整 MoGe 3 发布
|
||||
|
||||
### Requirement: Select and prepare model
|
||||
|
||||
系统 SHALL 提供 MOGE3_VITL 选项，保留已有模型键和默认值，下载并校验推理所需的全部 ONNX 资产。
|
||||
|
||||
#### Scenario: Download success
|
||||
- **WHEN** 所需图文件及外部权重全部下载并通过完整性校验
|
||||
- **THEN** 标记模型就绪，深度平面、裁切与全景使用用户所选模型
|
||||
|
||||
#### Scenario: Interrupted download
|
||||
- **WHEN** 下载失败、取消或文件不完整
|
||||
- **THEN** 不标记就绪，并允许重新准备
|
||||
|
||||
### Requirement: Preserve geometry contract
|
||||
|
||||
MoGe 3 SHALL 按所选分辨率等级提供与分析图尺寸对应的深度、法线、有效性、点图和相机内参，并遵循既有源 Alpha 处理契约。
|
||||
|
||||
#### Scenario: Image inference
|
||||
- **WHEN** 有效图片完成推理
|
||||
- **THEN** 有效区域深度为有限正值，产物可供既有几何工作流应用
|
||||
|
||||
#### Scenario: Panorama inference
|
||||
- **WHEN** 全景任务选择 MoGe 3
|
||||
- **THEN** 透视视图使用已知 90 度水平 FOV，模型 Mask 与源有效性共同约束融合及 Alpha 输出
|
||||
|
||||
### Requirement: Reuse existing input and workflow controls
|
||||
|
||||
MoGe 3 SHALL 沿用 MoGe 2 的输入准备、最大分析尺寸、分辨率等级及设备选择流程。同一组已下载模型资产 SHALL 接受现有流程产生的不同图片尺寸、宽高比和分辨率等级，输出尺寸对应分析图片。
|
||||
|
||||
#### Scenario: Vary image dimensions
|
||||
- **WHEN** 用户连续提交现有输入流程支持的不同尺寸和宽高比图片
|
||||
- **THEN** 使用同一组模型资产完成预测，遵循现有分析尺寸限制及输出尺寸契约
|
||||
|
||||
#### Scenario: Change resolution level
|
||||
- **WHEN** 用户修改现有 MoGe Resolution Level 后再次执行任务
|
||||
- **THEN** 新任务采用对应 token 数并执行三次细化，复用已下载模型资产
|
||||
|
||||
#### Scenario: Switch to MoGe 3 in an existing workflow
|
||||
- **WHEN** 用户在深度平面、裁切或全景工作流中将模型改为 MoGe 3
|
||||
- **THEN** 沿用原有任务参数、操作步骤与几何产物，模型内部完成多图及细化调度
|
||||
|
||||
### Requirement: Manage supported sessions
|
||||
|
||||
系统 SHALL 按已验证的 ONNX 设备能力执行，复用连续帧或视图的会话，在模型切换及关闭时释放资源，对不支持的执行方式和推理失败给出明确反馈。
|
||||
|
||||
#### Scenario: Model switching
|
||||
- **WHEN** 用户在 MoGe 2 与 MoGe 3 之间切换
|
||||
- **THEN** 执行新选择并释放旧模型资源
|
||||
|
||||
#### Scenario: Unsupported execution or cancellation
|
||||
- **WHEN** 执行设备不支持、资源不足或任务取消
|
||||
- **THEN** 给出明确状态，不应用部分结果，并允许后续重新运行
|
||||
20
openspec/changes/add-moge3-model/tasks.md
Normal file
20
openspec/changes/add-moge3-model/tasks.md
Normal file
@@ -0,0 +1,20 @@
|
||||
## 1. 原型与动态配置验收
|
||||
|
||||
- [x] 1.1 在项目外将完整 MoGe 3 拆为骨干与细化 ONNX，使用固定 256×192 / 1200 tokens 在 CPU 和 DirectML 上运行三张图、三次细化，保存参考比较及耗时记录。
|
||||
- [x] 1.2 将骨干扩展为动态输入尺寸和可变 token 数，用同一组 ONNX 资产连续运行不同宽高比、分析尺寸与分辨率等级，验证输出尺寸遵循现有契约。
|
||||
- [x] 1.3 定位原型中较大像素误差，确定后续验收容差，在 CPU 与 DirectML 验证动态配置及 90 度 FOV，记录精度、实际执行路径、耗时与内存峰值。
|
||||
- [x] 1.4 汇总动态配置、精度、性能及平台支持矩阵；完整验收通过后进入第 2 阶段，未通过项保留具体实验结论。
|
||||
|
||||
## 2. 模型资产与推理
|
||||
|
||||
- [x] 2.1 将已验证的转换方案整理至 tools/models，固定离线依赖，重新导出并通过相同精度验收以验证可复现性。
|
||||
- [x] 2.2 登记 MOGE3_VITL 的全部 ONNX 图及外部数据文件，验证大小和哈希，测试下载成功、失败、取消与就绪判断。
|
||||
- [x] 2.3 将双图、邻域生成和三次细化封装在 MoGe 3 ONNX 模块，仅增加必要推理分派；测试现有参数、输出尺寸、内参、有效性及分辨率等级传递。
|
||||
- [x] 2.4 更新会话缓存和释放，测试模型交替、连续帧复用与失败后恢复，确认正式环境不需 Torch 或 Triton。
|
||||
|
||||
## 3. 工作流接入与验收
|
||||
|
||||
- [x] 3.1 在现有模型登记与枚举中加入新选项，测试旧模型键和默认值保持、新模型选择及设备错误提示，核对继续使用既有 Job 参数。
|
||||
- [x] 3.2 在深度平面、裁切与全景的必要调用点接入分派，复用现有 Operator 和节点资产，运行产物、90 度 FOV、Alpha、取消与融合回归测试。
|
||||
- [ ] 3.3 在正式 ONNX Runtime 环境运行完整工作流并记录结果，在支持矩阵中的其他平台完成对应验收。（Windows 与 Linux 已通过，macOS 待实机验收，见 validation.md。）
|
||||
- [x] 3.4 检查依赖、Manifest 和打包测试的一致性，运行相关测试与全量 pytest，确认正常退出及最终差异范围。
|
||||
51
openspec/changes/add-moge3-model/validation.md
Normal file
51
openspec/changes/add-moge3-model/validation.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# MoGe 3 ONNX 验收
|
||||
|
||||
2026-09-10。新增 `MOGE3_VITL`，复用 MoGe 2 的输入准备、0–9 分辨率等级、下载、会话缓存和几何产物。骨干支持动态图片尺寸及 token 数，细化图支持动态点数，正式推理执行三次细化。
|
||||
|
||||
## 资产
|
||||
|
||||
转换源码：`tools/models/moge3_export.py`。上游提交为 `74fbce054ebed49800de42d0ad0e83495065719a`，权重 revision 为 `184008f877d7ad1ad4c2cd2182a9bd1f63d0e5be`。固定 Torch、ONNX、NumPy 和上游提交后重复导出，两次文件哈希一致。
|
||||
|
||||
| 文件 | 字节数 | SHA-256 |
|
||||
|---|---:|---|
|
||||
| backbone.onnx | 1324190318 | f21246c6921373c8c79ecdb8c78818a79bd2506c2fb88f4d4cdec21b92f725e3 |
|
||||
| refiner.onnx | 157729628 | 67ad7297aba18f8ef7939e8f700a5b25c41a19ddb68656bc2cd08b54c248fe2a |
|
||||
|
||||
权重内嵌于两个 ONNX 文件。镜像已发布到 `models.omoolab.xyz/moge-3-vitl-onnx/`，使用项目 `ModelManager.download` 下载到新目录，耗时 136.1 秒，大小、哈希及 `ready()` 校验通过。
|
||||
|
||||
## 精度与动态配置
|
||||
|
||||
参考为原始 MoGe 3、相同权重和三次细化。上游 FlexGEMM 的 `SPCONV_ALLOW_TF32` 独立于 Torch TF32 设置；关闭该选项后进行 FP32 比较。验收脚本预设平均深度相对误差小于 0.1%、99 分位小于 1%、二值 Mask 一致率大于 99.9%。
|
||||
|
||||
同一组动态图依次执行以下配置；耗时包含骨干、邻域生成、三次细化和后处理，不包含会话创建。
|
||||
|
||||
| 图片宽×高 | tokens | 水平 FOV | Windows CPU | DirectML | DirectML 平均深度相对误差 | 99 分位 |
|
||||
|---|---:|---|---:|---:|---:|---:|
|
||||
| 384×256 | 1200 | 自动 | 10.65 s | 4.86 s | 0.00216% | 0.02068% |
|
||||
| 257×385 | 2400 | 90° | 22.92 s | 9.67 s | 0.00228% | 0.01823% |
|
||||
| 320×320 | 3600 | 自动 | 36.41 s | 17.11 s | 0.00167% | 0.01609% |
|
||||
|
||||
三项均通过 CPU 和 DirectML 容差，二值 Mask 一致率为 100%。正式模块使用现有 MoGe 2 后处理，等级 0/9 的平均点图相对误差约 0.00217%/0.00173%，平均法线角误差约 0.006°，归一化内参最大绝对偏差小于 0.000002。2400 tokens 是图层测试值；公开等级继续按原公式映射至 1200–3600 tokens。
|
||||
|
||||
## 工作流与平台
|
||||
|
||||
| 平台 / Runtime | 验收结果 |
|
||||
|---|---|
|
||||
| Windows / DirectML 1.24.4 / RTX 5070 Ti | 动态精度、深度、裁切、12 视图全景通过；纯 ONNX 环境 |
|
||||
| Windows / CPU | 动态精度通过；原型 CPU Runtime 为 1.29.0 |
|
||||
| Linux x64 / CPU 1.24.4 / Python 3.12 | 使用项目声明的正式依赖，深度、裁切、12 视图全景通过 |
|
||||
| macOS / CPU、CoreML | 当前没有可用设备，待实机验收 |
|
||||
|
||||
真实 Job 调用仅替换进度/取消传输上下文，图片准备、模型管理、推理、几何处理与文件写入均使用项目代码。Windows 深度、裁切、全景分别约 9.81、5.45、67.13 秒；Linux 分别约 19.19、9.10、112.10 秒。深度/裁切生成 EXR、元数据及法线，全景完成 12 个 90° 视图推理和径向融合并生成 EXR 与元数据。
|
||||
|
||||
DirectML 的主要网络计算在 GPU 执行，部分 Gather、Unsqueeze、Concat、Less、Cast、ReduceSum 由 ONNX Runtime CPU 提供程序执行。正式环境依赖保持原样，未引入 Torch、FlexGEMM 或 Triton。
|
||||
|
||||
等级 0/9 连续运行时，Windows 进程峰值工作集约 1483 MiB；显卡整体占用由 6370 MiB 上升至最高 15716 MiB（每 0.5 秒采样，包含桌面及其他进程，不能视为模型独占显存）。Linux 三个 Job 进程峰值 RSS 约 4664 MiB。高等级的内存占用明显高于低等级。
|
||||
|
||||
## 回归与复现记录
|
||||
|
||||
全量 pytest：1143 passed、52 subtests passed，187.79 秒，正常退出。随后新增会话加载失败恢复测试，MoGe 3 专项 7 passed。覆盖下载完整性、缓存复用/切换/恢复、三次细化、尺寸、参数及现有 Alpha、FOV、取消、全景融合和打包内容契约。OpenSpec 严格校验通过。
|
||||
|
||||
实验与运行日志保存在 `C:/Users/icrdr/AppData/Local/Temp/anyimage-moge3-trial/`：`dynamic_reference.py`、`dynamic_validate.py`、`production_validate.py`、`job_validate.py`、`linux_jobs.py`、`download_validate.py`、`memory_validate.py`，及对应 JSON/日志。Linux 使用只读项目挂载的 Python 3.12 容器；Windows 全量测试使用按项目锁文件创建的独立测试环境。
|
||||
|
||||
任务 3.3 保留未完成状态，待补充 macOS 实机验收。
|
||||
2
openspec/changes/add-panorama-conversion/.openspec.yaml
Normal file
2
openspec/changes/add-panorama-conversion/.openspec.yaml
Normal file
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-09-09
|
||||
86
openspec/changes/add-panorama-conversion/design.md
Normal file
86
openspec/changes/add-panorama-conversion/design.md
Normal file
@@ -0,0 +1,86 @@
|
||||
## Context
|
||||
|
||||
独立原型验证了 12 个透视视图的 MoGe2 推理、距离融合和 Quad Sphere。正式转换沿用 Image Empty 的异步转换流程。用户明确选择通过现有 Remove Background 预先处理背景，转换消费当前图片和 Alpha。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
本次范围是静态 2:1 等距柱状全景的菜单转换、正式节点资产和 Split Threshold。沿用原型的 Subdivide、Depth Scale 和单张深度图片约定。
|
||||
|
||||
## Decisions
|
||||
|
||||
### 入口与对象生命周期
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Image Empty 右键 AnyImage] --> B[Convert to Panorama]
|
||||
B --> C[检查静态图和 2 比 1 尺寸]
|
||||
C --> D[读取当前 RGBA 和 Preferences]
|
||||
D --> E[提交全景 Job]
|
||||
E --> F[加载并打包颜色和深度]
|
||||
F --> G[创建全景对象和节点修改器]
|
||||
G --> H[替换源 Empty 并记录撤销]
|
||||
```
|
||||
|
||||
新增 `operators/convert_to_panorama/`，`operators.py` 定义 `ConvertToPanorama` 与 `GeneratePanorama`，`object.py` 创建结果，`__init__.py` 导出注册清单。公开入口为 `anyimage.convert_to_panorama`，Job 为 `generate-panorama-geometry`。复用 `common` 的输入暂存、材质、深度加载、修改器赋值和对象收尾函数。
|
||||
|
||||
模型、推理级别和分析尺寸从 Preferences 读取，Job 参数为普通字典。Blender 数据只在主线程读取输入和处理响应。新对象中心对应原 Empty 原点，继承其世界变换；局部 +Z 为全景上方，U=0 朝向 +X，U 增加沿 +Y 转动。生成成功后替换源对象并激活结果；失败、取消或源对象已失效时清理本次临时资源。图片显示偏移只属于平面预览，球面方向由完整图片 UV 定义。
|
||||
|
||||
### 后端与数据协议
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[当前 RGBA 全景] --> B[12 个重叠 90 度视图]
|
||||
B --> C[MoGe2 与已知 FOV 的几何恢复]
|
||||
C --> D[有效视图的径向距离]
|
||||
D --> E[横向周期的对数梯度融合]
|
||||
E --> F[尺度锚定与有限距离场]
|
||||
A --> G[源 Alpha 对齐到深度尺寸]
|
||||
F --> H[depth.exr]
|
||||
G --> H
|
||||
```
|
||||
|
||||
`server/jobs/panorama.py` 负责任务调度，`server/geometry/panorama.py` 负责投影与融合。将已知 FOV 接入已有 ONNX 后处理和模型会话生命周期，普通图片继续使用焦距估计。保留原分辨率颜色；视图分析尺寸遵循输入上限，首版目标视图为 512×512，融合网格最长边上限 512 且保持 2:1。Subdivide 独立控制最终网格密度。
|
||||
|
||||
源 Alpha 对齐、黑底模型输入及可见区域排除采用原型已验证的流程。全透明视图跳过推理，部分视图无效时继续融合其余有效观测；全局无有效几何时报错。逐视图及融合前后检查取消，释放模型资源。
|
||||
|
||||
| 字段 | 文件 | 内容 |
|
||||
| --- | --- | --- |
|
||||
| 颜色文件 | `image.0001.png` | 当前 RGBA，保留源 Alpha |
|
||||
| `depth` | `depth.exr` | float32 RGB 重复保存径向距离，A 为融合 Mask × 源 Alpha |
|
||||
| `depth_metadata` | `depth.json` | `projection: equirectangular`、`image_size`、`reference_distance` |
|
||||
|
||||
`reference_distance` 为满足 Alpha 阈值的有限正径向距离中位数，用于 Split Threshold 的尺度归一化。全景元数据按投影类型单独读取；复用现有 EXR 写入及 Non-Color、CHANNEL_PACKED、Pack 配置。颜色由材质采样，几何节点只有一个深度图片输入。
|
||||
|
||||
### Quad Sphere 与 Split Threshold
|
||||
|
||||
新增资产 `O Image Panorama`。Quad Sphere 与球面校正子组的构建定义归入本仓库节点构建模块，参考已检查的 `O Quad Sphere`，运行时从 `O_AnyImage.blend` 加载。面数为 `6 × 4^Subdivide`，默认 Subdivide=7；Depth Scale 默认 1，范围 0–1；Validity Threshold 默认 0.9；Split Threshold 默认 0，范围 0–1。深度图片、材质和参考距离作为数据输入。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[可调细分 Quad Sphere] --> B[固定单位射线与球面 UV]
|
||||
B --> C[按深度 EXR Alpha 剔除无效面]
|
||||
C --> D[相邻面径向距离变化判断]
|
||||
D --> E[Split Edges 与条带面清理]
|
||||
E --> F[分离面角沿原射线取所属面距离]
|
||||
F --> G[Depth Scale 插值到重建表面]
|
||||
G --> H[材质与临时属性清理]
|
||||
```
|
||||
|
||||
提取并复用 `tools/nodes/common/depth_surface.py` 中的相邻面采样、内边判断、Split Edges、面角归属和条带面清理。共用逻辑消费明确的深度字段、基础面中心和归一化比例；Depth Plane 的调用同步适配，保持已有求值结果。
|
||||
|
||||
对全景，令相邻面距离为 rA/rB，单位球面上的面中心为 cA/cB，参考距离为 R。沿用现有 2.5 系数，以 `abs(rA-rB) / R × Split Threshold > 2.5 × distance(cA,cB)` 选择有两个邻面的内边。阈值为 0 时直接保留通过有效性剔除的原网格；阈值增大时选择更多断层边。
|
||||
|
||||
选中断层附近的面角使用其所属面的距离，未选中的顶点保持原采样；所有点沿原始球面射线定位。最终半径为 `1 + Depth Scale × (目标距离 - 1)`。条带面清理遵循当前 Depth Plane 的同一拓扑快照规则。
|
||||
|
||||
全景面中心采样由面中心方向重新计算 UV，横向循环采样；材质面角 UV 独立处理经度分支和极点。这样左右接缝与普通内边参与同样的判断。分裂后保留原射线及面角 UV，末尾清理专用临时属性。
|
||||
|
||||
### 验证与交付
|
||||
|
||||
正式模块从原型迁移有效算法及测试，运行时依赖正式模块与打包资产。此次实现运行相关单元测试、完整回归测试和独立 Blender 求值检查。节点资产更新走现有离线资产流程；扩展包及文档构建属于另行发布操作。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- 径向距离与平面 Z 深度的比较尺度不同 → 用参考距离归一化，并测试相同形状整体缩放后的分裂选择一致。
|
||||
- 全景接缝和极点的 UV 有多种等价表示 → 用方向生成采样坐标，并验证接缝两侧的等价深度断层。
|
||||
- 共享分裂代码近期增加了条带清理 → 保留现有 Depth Plane 回归结果，并覆盖全景分裂后孤立条带、Alpha 边缘和连续斜面。
|
||||
- 天空及遮挡导致预测缺失 → 以当前源图 Alpha 和融合 Mask 确定有效几何，允许通过现有 Remove Background 预先处理。
|
||||
25
openspec/changes/add-panorama-conversion/proposal.md
Normal file
25
openspec/changes/add-panorama-conversion/proposal.md
Normal file
@@ -0,0 +1,25 @@
|
||||
## Why
|
||||
|
||||
全景原型已验证 Quad Sphere、径向深度和单张深度 EXR 的可行性。现在需要把生成流程接入 Image Empty 的常用入口，并通过 Depth Plane 的 Split Threshold 机制处理前后景连接处的拉伸。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 在 Image Empty 的 AnyImage 右键菜单增加 `Convert to Panorama`，通过后台 Job 将静态 2:1 全景转换成可编辑的全景表面。
|
||||
- 将原型的多视图 MoGe2 推理、距离融合和深度 Alpha 导出接入正式 Server。
|
||||
- 新增 `O Image Panorama` 节点资产，提供 Quad Sphere 细分、Depth Scale、Validity Threshold 和 Split Threshold。
|
||||
- 复用 Depth Plane 的分边、面角深度重定位和条带面清理机制，按全景径向距离适配判断。
|
||||
- 延续单深度图片输入：`depth.exr` 的 Alpha 在导出时合成模型 Mask 与当前源图 Alpha。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `panorama-conversion`: Image Empty 菜单、异步转换、对象替换与撤销。
|
||||
- `panorama-geometry-generation`: 全景多视图推理、融合与文件产物。
|
||||
- `panorama-surface`: Quad Sphere、球面 UV、深度有效性剔除与 Split Threshold。
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
## Impact
|
||||
|
||||
涉及 `menu.py`、类型注册、新增 `operators/convert_to_panorama/`、Server Job 与全景几何模块、共享深度表面节点构建函数，以及对应测试。生产节点组由资产构建流程写入 `O_AnyImage.blend`，运行时按名称加载。使用现有 MoGe2、ONNX Runtime、NumPy 与 SciPy 环境。
|
||||
@@ -0,0 +1,33 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Image Empty panorama conversion entry
|
||||
|
||||
系统 SHALL 在 Image Empty 的 AnyImage 右键菜单展示 `Convert to Panorama`，调用 `anyimage.convert_to_panorama`。
|
||||
|
||||
#### Scenario: Select panorama conversion
|
||||
- **WHEN** 用户选中静态 2:1 Image Empty 并选择 Convert to Panorama
|
||||
- **THEN** 提交当前图片及 Alpha 的全景生成任务，使用 Preferences 中的模型、推理级别和分析尺寸
|
||||
|
||||
#### Scenario: Unsupported image
|
||||
- **WHEN** 输入是动画、视频或非 2:1 图片
|
||||
- **THEN** 提示输入限制并保留源对象
|
||||
|
||||
### Requirement: Consume current image alpha
|
||||
|
||||
转换 SHALL 直接使用当前源图及 Alpha。背景处理由用户通过现有 Remove Background 完成。
|
||||
|
||||
#### Scenario: Already removed background
|
||||
- **WHEN** 源 Empty 的天空已透明
|
||||
- **THEN** 当前 Alpha 进入全景任务，转换过程中只运行几何模型
|
||||
|
||||
### Requirement: Complete conversion transaction
|
||||
|
||||
系统 SHALL 在主线程加载结果、打包贴图并创建节点对象，成功后替换源 Empty，并提供完整撤销。
|
||||
|
||||
#### Scenario: Successful conversion
|
||||
- **WHEN** Job 返回有效产物
|
||||
- **THEN** 创建使用 O Image Panorama 的对象，继承源 Empty 世界变换并以其原点为拍摄中心，激活结果并支持撤销恢复源对象
|
||||
|
||||
#### Scenario: Cancelled or failed conversion
|
||||
- **WHEN** 任务失败、取消或响应时源对象已失效
|
||||
- **THEN** 清理本任务暂存及未使用数据块，不应用部分转换结果
|
||||
@@ -0,0 +1,33 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Generate panoramic radial distance
|
||||
|
||||
Server SHALL 从当前 RGBA 全景生成 12 个重叠的 90 度透视视图，使用已知 FOV 恢复 MoGe2 几何并融合为横向周期的径向距离场。
|
||||
|
||||
#### Scenario: Continuous panorama
|
||||
- **WHEN** 输入包含跨越 U=0/1 的连续表面
|
||||
- **THEN** 两侧使用同一周期求解，产出有限正距离且无额外拼接断层
|
||||
|
||||
#### Scenario: Invalid views and cancellation
|
||||
- **WHEN** 部分视图全透明或模型无有效预测
|
||||
- **THEN** 利用其余有效观测完成融合，全局无有效几何时返回明确错误，并在视图与融合阶段响应取消
|
||||
|
||||
### Requirement: Export combined depth alpha
|
||||
|
||||
系统 SHALL 返回颜色文件、`depth.exr` 与 `depth.json`。深度 RGB 保存径向距离，Alpha 在导出时一次合成融合 Mask × 源 Alpha；元数据 SHALL 标明等距柱状投影、深度图尺寸和参考距离。
|
||||
|
||||
#### Scenario: Transparent background
|
||||
- **WHEN** 源图某区域 Alpha 为零
|
||||
- **THEN** 该区域深度 EXR Alpha 为零，颜色文件保留源 Alpha
|
||||
|
||||
#### Scenario: Fractional alpha
|
||||
- **WHEN** 有效模型 Mask 为 1 且源 Alpha 为 0.5
|
||||
- **THEN** 深度导出 Alpha 为 0.5，几何端直接消费该值
|
||||
|
||||
### Requirement: Use managed production runtime
|
||||
|
||||
全景生成 SHALL 使用现有模型会话、Preferences 配置和 Job 生命周期；Job 参数可序列化，Server 与 Blender 数据保持进程边界。
|
||||
|
||||
#### Scenario: Configured inference
|
||||
- **WHEN** 用户修改模型或推理分辨率级别后发起转换
|
||||
- **THEN** 新任务采用配置值，最终网格细分仍由独立 Subdivide 参数控制
|
||||
@@ -0,0 +1,41 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Editable Quad Sphere surface
|
||||
|
||||
系统 SHALL 提供资产 `O Image Panorama`，使用全四边面 Quad Sphere，并提供 Subdivide、Depth Scale、Validity Threshold 和 Split Threshold。几何节点 SHALL 只有一个深度图片输入。
|
||||
|
||||
#### Scenario: Sphere and depth endpoints
|
||||
- **WHEN** 所有样本有效且 Split Threshold 为 0
|
||||
- **THEN** Subdivide=n 产生 6×4^n 个四边面，Depth Scale=0 为单位球，Depth Scale=1 为预测径向距离表面
|
||||
|
||||
#### Scenario: Validity culling
|
||||
- **WHEN** 深度 EXR Alpha 低于 Validity Threshold
|
||||
- **THEN** 按 Depth Plane 的点域布尔字段与面域删除方式剔除对应区域
|
||||
|
||||
### Requirement: Depth Plane split semantics
|
||||
|
||||
全景 SHALL 复用 Depth Plane 的相邻面深度差判断、内边分裂、面角深度重定位和条带面清理机制，并使用参考距离归一化的径向距离适配球面。
|
||||
|
||||
#### Scenario: Disabled splitting
|
||||
- **WHEN** Split Threshold 为 0
|
||||
- **THEN** 分裂与条带清理完全旁路，有效性剔除保持生效
|
||||
|
||||
#### Scenario: Foreground depth discontinuity
|
||||
- **WHEN** 相邻有效面的归一化距离跳变达到分裂条件
|
||||
- **THEN** 分离选中的内边，断层附近面角沿原球面射线使用所属面的距离，未选中顶点保持原始深度采样
|
||||
|
||||
#### Scenario: Threshold and scale consistency
|
||||
- **WHEN** 增大 Split Threshold 或对所有距离与参考距离同时乘以相同正比例
|
||||
- **THEN** 增大阈值不会减少被选中的断层边，等比例距离变化不会改变断层边选择
|
||||
|
||||
#### Scenario: Seam and strip cleanup
|
||||
- **WHEN** 深度断层跨越全景经度接缝或分裂产生孤立条带
|
||||
- **THEN** 经度接缝采用周期采样，面角 UV 保持正确，条带面按 Depth Plane 的同一拓扑快照规则清理
|
||||
|
||||
### Requirement: Packaged node assets
|
||||
|
||||
生产节点组及 Quad Sphere 子组 SHALL 包含在 `O_AnyImage.blend` 中，通过现有加载入口使用。
|
||||
|
||||
#### Scenario: Reopen converted object
|
||||
- **WHEN** 在新 Blender 进程重新打开转换后的文件
|
||||
- **THEN** 无需访问原型目录或外部参考库即可求值，贴图、细分、Depth Scale 和 Split Threshold 均正常工作
|
||||
24
openspec/changes/add-panorama-conversion/tasks.md
Normal file
24
openspec/changes/add-panorama-conversion/tasks.md
Normal file
@@ -0,0 +1,24 @@
|
||||
## 1. 全景后端
|
||||
|
||||
- [x] 1.1 将原型的投影、周期距离融合和参考距离计算迁移到正式 Server 模块，保留解析几何测试
|
||||
- [x] 1.2 为现有 MoGe2 ONNX 推理增加已知 FOV 的几何恢复，复用模型会话并验证普通图片回归
|
||||
- [x] 1.3 实现 generate-panorama-geometry Job、尺寸和有效性检查、取消与清理，导出当前颜色、深度及全景元数据
|
||||
- [x] 1.4 验证源 Alpha 与 Mask 仅在深度导出合成一次，覆盖透明视图、全局无有效数据和跨经度接缝
|
||||
|
||||
## 2. 全景节点资产
|
||||
|
||||
- [x] 2.1 在本仓库实现 Quad Sphere 及校正子组的资产构建，创建 O Image Panorama 的细分、球面 UV 和 Depth Scale
|
||||
- [x] 2.2 复用深度 EXR 加载与 Alpha 剔除，保持几何节点单深度图片输入
|
||||
- [x] 2.3 提取共享 Split Threshold 机制并同步适配现有调用，将径向距离判断、面角重定位和条带清理接入全景
|
||||
- [x] 2.4 覆盖阈值旁路、断层强度、尺度不变性、连续斜面、经度接缝、极点及条带清理，并运行现有深度表面回归
|
||||
|
||||
## 3. 菜单与对象转换
|
||||
|
||||
- [x] 3.1 实现 ConvertToPanorama 与 GeneratePanorama，接入 Preferences、输入暂存、Job 参数与注册清单
|
||||
- [x] 3.2 在 Image Empty 的 AnyImage 菜单添加 Convert to Panorama，验证静态 2:1 输入限制及当前 Alpha 传递
|
||||
- [x] 3.3 实现主线程结果加载、材质、全景对象和修改器，覆盖源变换继承、替换、撤销及失败清理
|
||||
|
||||
## 4. 集成验证
|
||||
|
||||
- [x] 4.1 通过既有离线节点资产流程更新 O_AnyImage.blend，验证新进程加载和打包后独立求值
|
||||
- [x] 4.2 使用已去天空的真实全景与解析样本检查正式菜单流程和 Split Threshold，运行完整测试并检查最终差异
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-09-10
|
||||
55
openspec/changes/reuse-conversion-source-images/design.md
Normal file
55
openspec/changes/reuse-conversion-source-images/design.md
Normal file
@@ -0,0 +1,55 @@
|
||||
## Context
|
||||
|
||||
动机见 proposal.md。Plane 与 Panorama 复制源 Image，Depth / Relief 从 Job 颜色文件重新加载。`configure_material_color_image()` 还会按 Image users 再次复制。图片编辑工具已通过 `has_other_image_empty()` 判断同一 Image 数据块的其他 Empty 引用。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
设计目标是把图像所有权选择集中在转换准备阶段，使材质配置、对象替换与错误恢复使用同一个确定的 Image。转换范围为 Plane、Depth Plane、Relief Plane 和 Panorama。
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. 复用统一的 Empty 引用判断
|
||||
|
||||
在主线程接收转换结果时，使用 `has_other_image_empty()` 检查整个 `bpy.data.objects`，排除正在转换的源对象。判断依据为 Image 数据块身份。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[验证源 Image Empty] --> B{其他 Empty 引用同一 Image}
|
||||
B -->|有| C[复制原图并保留未保存像素]
|
||||
B -->|无| D[复用原 Image]
|
||||
C --> E[应用材质颜色空间与 Alpha 规则]
|
||||
D --> E
|
||||
E --> F[创建材质和转换对象]
|
||||
F --> G[完成对象替换与撤销记录]
|
||||
```
|
||||
|
||||
原 Image 名称、路径和内容来源保留；副本沿用原名并交给 Blender 消歧。复制数据块仍指向同一源文件，按既有资源生命周期保证 generated、dirty 和 packed 图像的内容可保存读取。
|
||||
|
||||
### 2. 所有权选择与材质配置分离
|
||||
|
||||
在 common 中提供四种转换共用的图像准备入口。材质配置函数原地配置已选定的 Image，并返回同一个实例。逐一检查 `create_image_material()` 的调用方，让需要独立结果的入口在配置前准备好 Image。
|
||||
|
||||
普通转换继续采用现有适配开关、inverse 色彩空间映射、sRGB 回退及对应 STRAIGHT / PREMUL 模式。Panorama 的 shadeless float / 非 sRGB 保留分支继续使用源图配置。切换设置时保留业务像素，包括透明区域 RGB 和未保存像素。
|
||||
|
||||
其他材质用户随复用 Image 接受配置变化；这落实与图片编辑工具一致的共享规则。相关转换测试以本变更规格为准，协调 `configure-material-view-adaptation` 中较宽的用户隔离预期。
|
||||
|
||||
### 3. 原图承担颜色来源
|
||||
|
||||
Depth / Relief 回调直接准备源 Image，Job 保留深度、法线和 metadata 产物。删除该调用链独占的 `load_color_result_image()`、`copy_color_images()` 及导出和测试引用。`color_data_name()` 是否保留由 Cutout 等实际调用决定。
|
||||
|
||||
Panorama Job 移除冗余 `image.0001.png` 保存和清理条目。原图与深度允许各自使用既有分辨率，颜色通过现有 UV 采样。Plane 继续从源 Empty 传递动画帧设置。
|
||||
|
||||
### 4. 转换包含失败恢复
|
||||
|
||||
修改复用 Image 前保存必要的颜色空间、Alpha、像素和相关状态；对象替换成功前发生异常时恢复。清理由本次操作创建的对象、网格、材质和 Image 副本负责，原 Image 始终保留。沿用并验证 Blender 的 Undo / Redo，使成功转换能够恢复 Empty 及原图设置。异步结果应用时重新验证源对象及其图像身份，源图已替换的结果应取消应用，避免颜色与深度来源不一致。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [已有材质共享原图配置变化] → 作为明确的共享语义提供行为测试。
|
||||
- [切换颜色空间导致 dirty / generated 像素重读] → 复用 common 像素保存逻辑，并验证透明 RGB、HDR 与保存重载。
|
||||
- [材质创建失败后原图已被修改] → 将配置和对象创建纳入同一恢复范围，覆盖配置成功后发生异常的路径。
|
||||
- [共享配置函数影响其他入口] → 审查所有材质调用点，验证 Cutout 与剪贴板材质行为。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
按公共图像准备、转换接入、后端产物清理的顺序实施，再运行相关测试和全量测试。已有文件在用户再次转换时采用新规则。全部修改集中在源码与测试，可通过回退本次实现恢复原行为。
|
||||
25
openspec/changes/reuse-conversion-source-images/proposal.md
Normal file
25
openspec/changes/reuse-conversion-source-images/proposal.md
Normal file
@@ -0,0 +1,25 @@
|
||||
## Why
|
||||
|
||||
Convert To 当前复制或重新加载颜色贴图，产生额外的 `_color` Image 和后端颜色文件。统一采用图片编辑工具的共享 Empty 判断，可以直接复用原图，并保留材质所需的颜色空间与 Alpha 配置。
|
||||
|
||||
## What Changes
|
||||
|
||||
- Plane、Depth Plane、Relief Plane、Panorama 在没有其他 Image Empty 引用原图时直接复用原 Image；存在其他 Empty 引用时复制 Image 数据块。
|
||||
- 原图保留名称和路径；副本沿用原名并使用 Blender 自动消歧命名。材质颜色直接取自原图。
|
||||
- 由转换入口决定 Image 所有权，再应用现有颜色空间、Alpha 和 Panorama HDR 保留规则。
|
||||
- 共享判断仅考虑其他 Image Empty；已有材质引用同一原图时同步看到配置变化。
|
||||
- 清理 Depth / Relief 和 Panorama 的冗余后端颜色输出与对应加载路径，补充失败恢复和像素保留验证。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `conversion-source-images`: 四种 Convert To 的原图复用、共享隔离、材质配置与结果生命周期。
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
## Impact
|
||||
|
||||
涉及 `common/image.py`、`common/material.py`、两个转换 Operator 包、Server 的 depth_plane / panorama Job、颜色文件辅助函数及相关测试。复用现有依赖和节点资产。
|
||||
|
||||
当前 `openspec/specs` 尚无已归档规格。本变更明确细化 `configure-material-view-adaptation` 中转换入口的共享策略：其他材质用户可以共享配置变化，其他 Image Empty 必须隔离；实施时应协调相关测试预期。
|
||||
@@ -0,0 +1,93 @@
|
||||
## Purpose
|
||||
|
||||
规定 Plane、Depth Plane、Relief Plane 和 Panorama 转换时颜色贴图的来源、共享引用与配置生命周期，使用户能够复用原始 Image，并在其他 Image Empty 仍然使用原图时获得独立且配置正确的材质图像。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Conversion selects images by other Empty references
|
||||
|
||||
四种 Convert To SHALL 在应用转换时检查整个 Blender 数据中的其他 Image Empty 是否引用同一源 Image。没有其他引用时 SHALL 复用原 Image；存在时 SHALL 使用原 Image 的独立副本。
|
||||
|
||||
#### Scenario: Only the converted Empty uses the source
|
||||
|
||||
- **WHEN** 源 Image 没有被其他 Image Empty 引用
|
||||
- **THEN** 转换材质 SHALL 引用原 Image 数据块并保留其名称和路径
|
||||
|
||||
#### Scenario: Another Empty shares the image
|
||||
|
||||
- **WHEN** 另一个 Image Empty 引用同一 Image，包括隐藏对象或其他场景对象
|
||||
- **THEN** 材质 SHALL 使用独立副本，沿用原名并由 Blender 消歧
|
||||
- **AND** 其他 Empty 的 Image 引用、像素、颜色空间和 Alpha 模式 SHALL 保持原值
|
||||
|
||||
#### Scenario: Existing materials share the image
|
||||
|
||||
- **WHEN** 原 Image 被材质引用且没有其他 Image Empty 引用
|
||||
- **THEN** 转换 SHALL 复用原 Image，已有材质 SHALL 同步看到该 Image 的配置变化
|
||||
|
||||
#### Scenario: Separate images have the same file path
|
||||
|
||||
- **WHEN** 另一 Empty 使用路径相同但数据块不同的 Image
|
||||
- **THEN** 该引用 SHALL 视为独立图像，转换 SHALL 复用当前源 Image
|
||||
|
||||
### Requirement: Conversion preserves material presentation rules
|
||||
|
||||
转换 SHALL 对选定的 Image 应用既有材质颜色空间和 Alpha 配对规则，保留业务 RGB、Alpha、透明区域 RGB、精度和未保存像素。Panorama 的 float 或非 sRGB shadeless 图像 SHALL 沿用源颜色空间和 Alpha 模式。
|
||||
|
||||
#### Scenario: Standard material adaptation is applied
|
||||
|
||||
- **WHEN** 普通转换关闭适配，或所需 inverse 空间回退到 sRGB
|
||||
- **THEN** 选定 Image SHALL 使用 sRGB + PREMUL
|
||||
|
||||
#### Scenario: Inverse adaptation is available
|
||||
|
||||
- **WHEN** 普通转换启用适配且对应 inverse 空间可用
|
||||
- **THEN** 选定 Image SHALL 使用该空间与 STRAIGHT
|
||||
|
||||
#### Scenario: Panorama preserves HDR interpretation
|
||||
|
||||
- **WHEN** Panorama 源图为 float 或采用现有保留分支匹配的非 sRGB 空间
|
||||
- **THEN** 材质 Image SHALL 保留原颜色空间、Alpha 模式与 HDR 像素
|
||||
|
||||
#### Scenario: Unsaved and packed pixels remain readable
|
||||
|
||||
- **WHEN** generated、dirty 或 packed 图像完成转换并保存重载
|
||||
- **THEN** 图像业务像素 SHALL 在原有编码精度内保留，包括完全透明区域的 RGB
|
||||
|
||||
### Requirement: Conversion uses source color content directly
|
||||
|
||||
转换材质 SHALL 使用源图内容与分辨率。Depth / Relief 和 Panorama Job SHALL 仅输出各自所需的几何数据产物；转换 SHALL 无需产生额外颜色文件。
|
||||
|
||||
#### Scenario: Depth or relief result is applied
|
||||
|
||||
- **WHEN** Job 返回深度、法线和 metadata
|
||||
- **THEN** 转换 SHALL 使用原图或其独立副本完成材质绑定
|
||||
|
||||
#### Scenario: Panorama result is applied
|
||||
|
||||
- **WHEN** Job 返回深度和 metadata
|
||||
- **THEN** 转换 SHALL 使用源全景颜色完成材质绑定
|
||||
|
||||
#### Scenario: Plane converts an animated image
|
||||
|
||||
- **WHEN** Plane 转换 movie 或 sequence 图像
|
||||
- **THEN** 材质 SHALL 保留源 Empty 的帧起点、偏移、时长和循环设置
|
||||
|
||||
### Requirement: Conversion preserves source state on failure and undo
|
||||
|
||||
转换 SHALL 在失败时恢复复用原图的有效配置和像素，释放本次创建的临时资源，并保留源 Empty。成功转换 SHALL 支持 Undo / Redo。
|
||||
|
||||
#### Scenario: Material or object creation fails
|
||||
|
||||
- **WHEN** 原图已配置但转换在完成对象替换前失败
|
||||
- **THEN** 原图的颜色空间、Alpha、业务像素和源 Empty 引用 SHALL 恢复
|
||||
- **AND** 本次创建的未使用资源 SHALL 清理
|
||||
|
||||
#### Scenario: The source changes during an asynchronous job
|
||||
|
||||
- **WHEN** 结果应用时源对象失效或其 Image 已替换
|
||||
- **THEN** 转换 SHALL 取消应用并保留当前源状态
|
||||
|
||||
#### Scenario: A completed conversion is undone and redone
|
||||
|
||||
- **WHEN** 用户撤销成功的转换再重做
|
||||
- **THEN** 撤销 SHALL 恢复源 Empty 和转换前图像状态，重做 SHALL 恢复转换对象及对应材质配置
|
||||
16
openspec/changes/reuse-conversion-source-images/tasks.md
Normal file
16
openspec/changes/reuse-conversion-source-images/tasks.md
Normal file
@@ -0,0 +1,16 @@
|
||||
## 1. 公共图像准备与材质配置
|
||||
|
||||
- [x] 1.1 在 common 中统一转换图像准备，复用其他 Empty 引用判断；测试覆盖独占、共享 Empty、隐藏或跨场景 Empty、仅材质共享和同路径不同 Image，并检查原名与副本命名。
|
||||
- [x] 1.2 将材质配置改为配置已选定的 Image，审查全部材质创建调用点；运行材质测试，验证配置后 Image 身份、inverse / sRGB 回退、Alpha 配对及 Cutout、剪贴板行为。
|
||||
- [x] 1.3 复用公共像素和状态辅助函数实现转换失败恢复；测试配置失败及配置成功后材质或对象创建失败，确认原图状态恢复与临时资源清理。
|
||||
|
||||
## 2. 转换入口和后端产物
|
||||
|
||||
- [x] 2.1 接入 Plane、Depth Plane、Relief Plane 的原图准备逻辑，保留 Plane 动画设置，并验证异步源对象与 Image 身份；通过转换测试确认引用身份、原始分辨率、帧参数和源图替换时取消应用。
|
||||
- [x] 2.2 接入 Panorama，保留 HDR / 非 sRGB 分支和可保存的源像素；运行全景转换测试，覆盖独占与共享 Image、HDR 数值及 Alpha 模式。
|
||||
- [x] 2.3 移除 Depth / Relief 和 Panorama 的冗余颜色输出及专用加载、复制辅助函数，清理导出和对应测试；通过 Job 测试验证产物集合，并用 rg 确认删除符号无残留业务引用。
|
||||
|
||||
## 3. 集成验证
|
||||
|
||||
- [x] 3.1 验证 byte、float、generated、dirty、packed 图像的透明 RGB 和保存重载行为，覆盖复用与复制两条路径，并验证转换 Undo / Redo 恢复对象及图像配置。Panorama HDR 往返通过；普通材质 float 使用 display 色彩空间重载的两项既有 xfail 保留。
|
||||
- [x] 3.2 运行相关测试与 `uv run pytest`，确认正常退出；检查最终差异仅包含本变更实施内容，已有工作区修改保留，旧颜色路径与测试预期完成清理。全量结果：1125 passed、2 xfailed、52 subtests passed，退出码 0。
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-09-09
|
||||
83
openspec/changes/unify-ai-input-validation/design.md
Normal file
83
openspec/changes/unify-ai-input-validation/design.md
Normal file
@@ -0,0 +1,83 @@
|
||||
## Context
|
||||
|
||||
以当前工作区调用链为依据：
|
||||
|
||||
| 位置 | 发现 | 处理方向 |
|
||||
| --- | --- | --- |
|
||||
| `common/ai.py` | BEN2 专属扩展名与后端重复，Upscale 只检查路径存在 | 统一公共预检 |
|
||||
| `server/media/input.py` | 扩展名提示混排；目录过滤后仅提示没有帧 | 按错误原因和媒体类别提示 |
|
||||
| `server/models/ben2.py` | 单帧校验使用第三套提示 | 复用图片格式校验 |
|
||||
| `common/image.py` | 路径文案限定 Image Empty；序列直接复制；packed 导出失败可能留下目录 | 使用 source 文案、复制前校验、准备失败释放资源 |
|
||||
| Remove BG、Depth/Relief Plane | 内部 Operator 调用位于异常处理之外 | 捕获同步调用错误并取消 |
|
||||
| `operators/ai_setup.py`、`invoke_ai_setup_if_needed()` | 下载、安装与设置入口嵌套调用 | 在公共准备入口和设置 Operator 内处理失败 |
|
||||
| Panorama | 已捕获嵌套调用错误并清理 | 回归现有行为 |
|
||||
|
||||
BlendJob 的 `request()` 错误会被转换为 ERROR report 和 CANCELLED；Blender 的 `bpy.ops` 调用仍可能将该 report 抛为 RuntimeError。异步 Job 失败已有集中处理。前后端可以共享 `server` 内纯 Python 模块，已有 resolution 模块采用这一依赖方向；后端保持可独立加载。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
统一 AI 输入校验、用户可读的错误原因、失败取消状态和临时输入生命周期。支持格式保持 JPG/JPEG/PNG/WEBP 与现有九种视频扩展名；各 Operator 继续表达自己的静态图、尺寸与比例限制。自动转码、扩展格式支持和 BlendJob 框架重构作为独立需求处理。
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. 公共媒体模块维护格式规则与提示
|
||||
|
||||
在 `server/media/input.py` 提供轻量路径/格式校验，按图片、视频或帧目录识别输入，图片模型使用相同规则的图片子集。模块加载和预检仅依赖标准库。
|
||||
|
||||
`common/ai.py` 的 `require_input_path()` 负责 Blender 路径解析并调用该规则；删除 BEN2 专属校验及扩展名常量。`prepare_input()` 在后端再次执行校验，应对独立 Job 请求和提交后源文件变化。前端和后端使用同一消息生成位置，比只在后端检查更早反馈，也避免复制列表。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Source[Blender 源图片] --> Prepare[解析路径与准备输入]
|
||||
Prepare --> Validate[公共媒体校验]
|
||||
Validate --> Submit[提交 Job]
|
||||
Submit --> Recheck[后端公共媒体校验]
|
||||
Recheck --> Decode[读取图片或视频帧]
|
||||
Decode --> Model[模型处理]
|
||||
Validate --> Error[普通错误提示与取消]
|
||||
Recheck --> Error
|
||||
Decode --> Error
|
||||
```
|
||||
|
||||
### 2. 提示由原因决定，格式按类别列出
|
||||
|
||||
保留当前英文 UI 语言，示例模板：
|
||||
|
||||
- `Source image file does not exist: {path}` / `Source video file does not exist: {path}`。
|
||||
- `Unsupported input format: {suffix}. Supported images: {images}. Supported videos: {videos}.` 扩展名排序且小写；无扩展名使用 `(no extension)`。
|
||||
- `No supported image frames found in: {path}. Supported images: {images}.`。
|
||||
- `Unable to read image: {path}` / `Unable to read video: {path}`，底层原因保留异常链供诊断。
|
||||
|
||||
只将路径检查、文件读取与解码边界的预期异常转换为输入提示，模型推理或资源错误保留实际原因。通用输入阶段保持图片与视频类别一致；BEN2 单帧模型内部使用图片子集提示。
|
||||
|
||||
### 3. 明确目录与 Blender 序列的差别
|
||||
|
||||
Blender SEQUENCE 在创建临时目录前验证源扩展名属于支持的图片格式，不支持时直接报格式错误。已识别的同名序列按原排序和帧区间处理。
|
||||
|
||||
通用目录仍仅选择支持格式的图片文件并忽略其他文件；预检与后端使用同一收集规则。全无有效图片时报告目录及支持图片格式。这一提案修复 Blender 序列被误报为空目录的问题，混合目录按筛选契约验收。
|
||||
|
||||
格式校验针对实际提交文件。packed 图片和像素裁剪输出使用现有 PNG 导出路径，普通文件继续使用原始文件；测试应明确两条路径的预期，避免把源名称当作实际编码。`IMAGE_NAME_SUFFIXES` 是命名识别列表，继续按命名职责维护。
|
||||
|
||||
### 4. 在拥有调用与资源的边界处理失败
|
||||
|
||||
Remove BG、Depth/Relief Plane、AI Environment 的嵌套 `bpy.ops` 调用捕获预期 RuntimeError；涉及输入准备的边界同时处理 OSError/ValueError。通过已有 report 出口返回 CANCELLED，规范 Blender 添加的首个 `Error: ` 前缀与尾部换行，保留实际原因。公共 AI setup 入口复用同一报错约定；异步 Job 仍由 BlendJob 管理。
|
||||
|
||||
临时输入在准备完成前由准备函数拥有；Job 成功接管后由 Job cleanup 拥有。准备失败、同步调用抛错、返回 CANCELLED 和异步失败分别验证释放责任。packed 导出失败应清理整个临时目录。清理只能触及本次操作创建的输入，不影响用户原文件和源图片引用。
|
||||
|
||||
优先在现有公共函数与直接调用处落实职责；复用消息格式化即可，保持各业务 Operator 的调用和资源归属可见。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- 前后端文件状态可能变化 → 后端复核并提供同一原因分类。
|
||||
- 测试 mock 不会自动模拟 Blender report 抛错 → 单元测试注入 RuntimeError，补充真实 Blender 入口验证。
|
||||
- 调用层次多可能重复 report → 以最终用户提示无重复前缀、无 Python traceback 为验收点，检查 Blender UI 实际输出。
|
||||
- 解码错误与推理错误容易混淆 → 只在读取边界包装解码异常。
|
||||
- 其他未归档变更修改相关入口 → 以实施时工作区为基线，保留 Undo、源图共享引用及 Panorama 行为。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
依次落地公共校验、消费者接入、调用边界与清理，再运行相关及全量测试。删除旧 BEN2 校验入口并检查引用。变更不涉及持久数据迁移；必要时可整体回退本变更代码与测试。
|
||||
|
||||
## Open Questions
|
||||
|
||||
无实施前置问题。真实 Blender 下 report 的重复展示情况列为实施验收项。
|
||||
29
openspec/changes/unify-ai-input-validation/proposal.md
Normal file
29
openspec/changes/unify-ai-input-validation/proposal.md
Normal file
@@ -0,0 +1,29 @@
|
||||
## Why
|
||||
|
||||
Remove BG 与 Upscale 对同一种输入给出不同的格式提示，Remove BG 的普通校验错误还会经嵌套 Operator 调用变成 Python traceback。检查发现格式规则重复、序列过滤、路径提示和临时输入清理也存在同一调用链上的不一致，需要建立统一的输入与失败处理契约。
|
||||
|
||||
## What Changes
|
||||
|
||||
- AI 文件输入使用同一套格式规则与错误文案，前端提前校验，后端独立复核；错误说明实际扩展名及支持的图片、视频格式。
|
||||
- 区分路径缺失、格式不支持、目录无有效帧和文件无法解码，路径提示统一使用 source image/video，适用于 Image Empty 和材质 Image Texture。
|
||||
- Blender 图片序列在复制前验证格式，避免不支持的序列被当成空目录；通用帧目录明确过滤规则。
|
||||
- Remove BG、Depth/Relief Plane 与 AI Environment 的嵌套调用按普通错误取消操作，并统一资源释放；审查 Panorama 既有处理作为回归范围。
|
||||
- 保留静态图、尺寸、比例等功能专属限制，统一其异常出口；格式能力以当前实际提交文件为准。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `ai-input-validation`: AI 文件、帧目录与 Blender 图片序列的公共校验、错误分类及文案。
|
||||
- `ai-operator-failure-handling`: AI Operator 的失败展示、取消状态与临时输入所有权。
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
无。当前 `openspec/specs/` 为空。本提案与现有 `add-texture-node-image-actions`、`add-panorama-conversion` 变更共同验收相关入口。
|
||||
|
||||
## Impact
|
||||
|
||||
- `src/anyimage/server/media/input.py`、`server/media/__init__.py`、`server/models/ben2.py`：公共格式契约、目录处理与模型输入校验。
|
||||
- `src/anyimage/common/ai.py`、`common/image.py`：前置校验、源路径与序列准备、临时资源释放。
|
||||
- `operators/remove_background.py`、`upscale.py`、`convert_to_plane/operators.py`、`ai_setup.py` 及其他公共入口消费者：错误传播与回归。
|
||||
- 更新相关行为测试，运行全量 pytest，并用 Blender 验证嵌套调用的实际报错。依赖与节点资产沿用当前版本。
|
||||
@@ -0,0 +1,61 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Shared input format validation
|
||||
|
||||
AI 输入 SHALL 使用公共格式规则，在 Blender 提交前与后端处理前校验实际输入路径。支持图片为 JPG/JPEG/PNG/WEBP，视频沿用当前 MP4/MOV/AVI/MKV/WEBM/M4V/MTS/MPG/MPEG，扩展名匹配忽略大小写。
|
||||
|
||||
#### Scenario: Unsupported file in image edits
|
||||
- **WHEN** Remove BG 与 Upscale 使用同一个存在的 `.tiff` 普通文件，且环境和模型已就绪
|
||||
- **THEN** 两者在提交 Job 前取消，展示相同格式提示，包含 `.tiff` 和分类排序的支持格式
|
||||
|
||||
#### Scenario: Direct backend input
|
||||
- **WHEN** 后端直接收到不支持格式的文件或无扩展名文件
|
||||
- **THEN** 使用与前端相同的格式提示规则，无扩展名显示 `(no extension)`
|
||||
|
||||
#### Scenario: Supported uppercase extension
|
||||
- **WHEN** 实际输入为存在的 `.PNG` 或 `.MP4` 文件
|
||||
- **THEN** 通过对应图片或视频格式校验
|
||||
|
||||
#### Scenario: Model image validation
|
||||
- **WHEN** BEN2 单帧入口收到不支持的图片扩展名
|
||||
- **THEN** 使用公共格式提示的图片子集，并与公共图片支持集合一致
|
||||
|
||||
### Requirement: Distinct input failure reasons
|
||||
|
||||
系统 SHALL 区分缺失路径、不支持格式、目录无有效帧和解码失败；提示 SHALL 适用于 Image Empty 和 Image Texture，解码异常转换 SHALL 限定于读取边界。
|
||||
|
||||
#### Scenario: Missing source file
|
||||
- **WHEN** Image Empty 或材质 Image Texture 的源图片或视频文件不存在
|
||||
- **THEN** 提示缺失的 source image/video file 及路径，不将原因报告为格式不支持
|
||||
|
||||
#### Scenario: Invalid encoded data
|
||||
- **WHEN** 支持扩展名的文件内容无法作为对应图片或视频解码
|
||||
- **THEN** 报告无法读取的媒体类型及路径，并保留底层异常供诊断
|
||||
|
||||
### Requirement: Explicit frame selection
|
||||
|
||||
系统 SHALL 在复制 Blender 序列前校验图片格式；通用目录 SHALL 仅收集支持的图片，保持现有排序及帧范围规则。
|
||||
|
||||
#### Scenario: Unsupported Blender sequence
|
||||
- **WHEN** Blender 源序列使用 `.exr` 扩展名
|
||||
- **THEN** 复制前提示不支持的图片格式，不创建临时帧目录
|
||||
|
||||
#### Scenario: Mixed directory
|
||||
- **WHEN** 通用输入目录包含 JPG、PNG、TXT 和 EXR 文件
|
||||
- **THEN** 仅 JPG 与 PNG 参与处理，前后端按相同规则选择并保持原帧范围语义
|
||||
|
||||
#### Scenario: Empty supported frame set
|
||||
- **WHEN** 通用目录为空或只有不支持的文件
|
||||
- **THEN** 提示无支持的图片帧、目录路径及支持的图片格式
|
||||
|
||||
### Requirement: Validate prepared media
|
||||
|
||||
系统 SHALL 校验实际提交的文件，保持各功能自身的媒体类型、尺寸和比例约束。
|
||||
|
||||
#### Scenario: Packed image exported as PNG
|
||||
- **WHEN** 一个名称带 `.exr` 的 packed Image 经现有流程成功导出 PNG
|
||||
- **THEN** 按导出的 PNG 校验，不按源名称拒绝
|
||||
|
||||
#### Scenario: Feature restriction
|
||||
- **WHEN** 输入通过公共格式校验但不满足 Depth Plane 的静态图限制或 Upscale 的尺寸限制
|
||||
- **THEN** 仍按对应业务原因取消，不报告为格式不支持
|
||||
@@ -0,0 +1,33 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Expected operator failures are reported normally
|
||||
|
||||
AI 操作 SHALL 将输入准备与嵌套 Operator 调用的预期失败转换为普通错误提示和 CANCELLED，包括 Remove BG、Depth/Relief Plane、AI Environment 准备及现有 Panorama 入口。提示 SHALL 保留原因并避免重复的 Blender 错误前缀。
|
||||
|
||||
#### Scenario: Nested input validation failure
|
||||
- **WHEN** 内部 Job Operator 报告无效输入且 bpy.ops 抛出 RuntimeError
|
||||
- **THEN** 外部入口返回 CANCELLED，显示原因，不向用户展示未捕获的 Python traceback
|
||||
|
||||
#### Scenario: Environment setup failure
|
||||
- **WHEN** AI Environment 设置入口调用安装或下载 Operator 同步失败
|
||||
- **THEN** 设置入口及调用它的 AI 操作按普通错误取消
|
||||
|
||||
#### Scenario: Successful job startup
|
||||
- **WHEN** 内部 Job Operator 返回 RUNNING_MODAL
|
||||
- **THEN** 外部入口保持现有成功返回与异步处理语义，源图片及 Undo 行为保持有效
|
||||
|
||||
### Requirement: Temporary inputs have explicit ownership
|
||||
|
||||
系统 SHALL 释放本次操作创建的临时输入，在准备失败、启动失败、取消及异步结束时均有负责清理的边界；用户原文件 SHALL 保持不变。
|
||||
|
||||
#### Scenario: Preparation failure
|
||||
- **WHEN** packed 图片导出或序列复制失败
|
||||
- **THEN** 准备函数删除本次临时文件和目录，并保留源图片与源文件
|
||||
|
||||
#### Scenario: Synchronous nested failure
|
||||
- **WHEN** 临时输入准备成功后内部 Operator 抛错或返回 CANCELLED
|
||||
- **THEN** 临时输入被清理，外部操作取消，源图片引用保持不变
|
||||
|
||||
#### Scenario: Asynchronous completion
|
||||
- **WHEN** Job 接管临时输入并在之后成功、失败或取消
|
||||
- **THEN** 输入在 Job 结束时清理，运行期间保持可用，用户原文件不被删除
|
||||
30
openspec/changes/unify-ai-input-validation/tasks.md
Normal file
30
openspec/changes/unify-ai-input-validation/tasks.md
Normal file
@@ -0,0 +1,30 @@
|
||||
## 1. 公共媒体校验
|
||||
|
||||
- [x] 1.1 在 server/media/input.py 统一路径、图片/视频扩展名与格式消息，保持标准库预检及后端独立加载；补充大小写、无扩展名和缺失路径测试。
|
||||
- [x] 1.2 让 prepare_input 与 BEN2 单帧校验复用公共规则；验证直接后端请求与前端提示一致，图片子集限制有效。
|
||||
- [x] 1.3 在实际图片/视频读取边界统一解码失败提示并保留异常原因；覆盖损坏内容，确认推理异常保留自身语义。
|
||||
|
||||
## 2. Blender 输入准备
|
||||
|
||||
- [x] 2.1 将 require_input_path 接入公共预检，移除 require_background_input_path 和 BEN2 重复常量；覆盖 Remove BG/Upscale 同一无效输入的消息及未提交 Job 行为。
|
||||
- [x] 2.2 统一 source image/video 路径提示，覆盖 Image Empty 和材质 Image Texture；回归其他公共校验消费者。
|
||||
- [x] 2.3 在 Blender 序列复制前校验图片格式；验证不支持序列、混合目录、无有效帧目录、帧排序与范围。
|
||||
- [x] 2.4 修复输入准备失败的临时目录释放，验证 packed 导出与序列复制失败；覆盖普通原文件和导出 PNG 的不同实际输入路径。
|
||||
|
||||
## 3. Operator 失败边界
|
||||
|
||||
- [x] 3.1 修复 Remove BG、Depth/Relief Plane 的嵌套调用异常出口，规范错误前缀并处理同步失败/CANCELLED 的临时输入清理。
|
||||
- [x] 3.2 补齐公共 AI setup 入口及 AI Environment 安装/下载嵌套调用的预期失败处理；回归 Panorama 已有错误边界。
|
||||
- [x] 3.3 补充准备失败、同步取消、异步成功/失败/取消的生命周期测试，确认原文件、源图片引用和 Undo 行为保持有效。
|
||||
|
||||
## 4. 验证
|
||||
|
||||
- [x] 4.1 运行相关测试，再运行 uv run pytest 并确认正常退出；检查旧校验名称、重复格式列表与最终差异。
|
||||
- [x] 4.2 在真实 Blender UI 从 Remove BG、Depth/Relief Plane 及 AI setup 入口触发同步失败，确认普通提示无重复前缀、无未捕获 traceback，并检查临时输入已释放。
|
||||
- [x] 4.3 验证有效 PNG、视频、序列与材质贴图入口，记录测试结果及实际验证限制。
|
||||
|
||||
## 验证记录
|
||||
|
||||
- `uv run pytest -q`：1025 passed、2 xfailed、52 subtests passed，退出码 0。随后新增的 4 项原生 Operator 测试通过；最终相关新增测试合计 24 项通过。
|
||||
- Blender 4.5.10 LTS 独立场景：UI 主循环依次调用 Remove BG、Upscale、Depth、Relief 和 AI setup；前四者格式错误完全一致，所有入口仅一层 Error 前缀且没有未捕获 traceback。原生回归另行验证同步失败后的临时输入清理。
|
||||
- 有效图片、视频帧、序列、材质贴图、异步完成/取消/失败和 Undo 由全量回归覆盖；本次验证使用模拟推理与安装失败，不下载模型或执行真实模型推理。
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-09-10
|
||||
71
openspec/changes/unify-material-color-images/design.md
Normal file
71
openspec/changes/unify-material-color-images/design.md
Normal file
@@ -0,0 +1,71 @@
|
||||
## Context
|
||||
|
||||
动机与范围见 proposal.md。普通 Cutout 在内存中新建颜色图，AI Cutout 从裁切临时文件加载；Convert To 使用按 Empty 引用决定复用的分支。剪贴板通过输入字节哈希查找 packed Image，编辑覆盖原 Image 后该标记仍然存在。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
设计目标是让所有材质入口共享范围采样和颜色图交付逻辑，并让剪贴板按当前图像状态验证缓存。输入范围统一使用现有像素坐标约定，静态颜色图以独立 packed Image 交付。
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. 统一范围与颜色文件准备
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[读取当前源图像素和解释设置] --> B[确定像素范围]
|
||||
B --> C[Cutout 使用裁切范围]
|
||||
B --> D[Convert To 和剪贴板 Plane 使用整图范围]
|
||||
C --> E[导出唯一临时颜色文件]
|
||||
D --> E
|
||||
E --> F[独立加载并命名为原名_color]
|
||||
F --> G[配置材质颜色空间和 Alpha]
|
||||
G --> H[打包并绑定材质]
|
||||
E --> I[需要 AI 时准备模型输入并生成几何数据]
|
||||
H --> J[完成对象交付并清理临时资源]
|
||||
I --> J
|
||||
```
|
||||
|
||||
公共准备逻辑放在 common，输入源 Image、当前像素及范围。复用现有像素读取、路径清理和 packed 加载能力；由临时产物携带采样时的尺寸与解释设置，异步响应使用同一次准备的内容。AI 和普通 Cutout 采用相同裁切颜色来源，模型推理的缩放或预览处理只作用于分析输入。
|
||||
|
||||
### 2. 独立加载是材质所有权边界
|
||||
|
||||
每次材质创建都从本次临时颜色文件使用 `check_existing=False` 加载新的 Color Image。名称使用源图基名、`_color` 和实际编码后缀，由 Blender 处理重名。文件位于本次操作的唯一临时目录，与原图路径分离。
|
||||
|
||||
材质构建函数接收已准备好的独立 Color Image，负责配置和节点绑定。所有入口在进入该函数前完成相同准备；Cutout 已准备的产物直接交付。原 Image 的像素、名称、路径、颜色空间和 Alpha 保持原值。材质 Image 由文件独立加载，因此不继承源 Image 的剪贴板缓存属性。
|
||||
|
||||
### 3. 编码精度与颜色解释共同验证
|
||||
|
||||
普通 byte 图片使用无损 PNG；float / HDR 使用保留浮点范围和精度的 EXR。复用 common 中适合的 HDR 编码能力，按源 Alpha 解释正确处理关联 RGB 和透明区域颜色。
|
||||
|
||||
普通 byte 材质沿用适配偏好、inverse 空间映射与 sRGB 回退。所有 float / HDR 材质保留源颜色空间与 Alpha 模式；Panorama 保留现有非 sRGB 规则。导出、独立加载、配置、打包和保存重载作为完整往返验证。普通 float 不再强制套用显示颜色空间，原有重载 xfail 改为源解释保留的正常回归测试。
|
||||
|
||||
float / HDR 在导出后按源解释独立加载并比较像素。STRAIGHT 按 Alpha 解关联后编码；源解释与 EXR 无法同时保留像素时明确拒绝转换并清理临时目录，例如 STRAIGHT 下完全透明像素仍含非零 RGB。float 材质不启用场景视图适配的 Alpha Fix。
|
||||
|
||||
### 4. 临时产物由操作持有
|
||||
|
||||
同步操作持有临时目录直至 Color 完成打包和对象交付；异步操作持有颜色产物及分析输入直至响应、取消或失败处理完成。静态普通颜色文件适合作为模型输入时复用同一临时文件；HDR 分析预览保留独立路径。所有清理入口按真实持有关系释放资源，packed Color 在临时文件删除后仍可保存和重载。
|
||||
|
||||
转换源对象与 Image 身份校验继续使用；材质隔离后清理原图复用及相应的原图配置恢复、打包撤销基线分支。保留对象、材质、网格和临时 Image 的异常清理及转换 Undo / Redo。
|
||||
|
||||
### 5. 剪贴板缓存验证实际内容
|
||||
|
||||
输入字节的 SHA256 继续作为候选索引。首次加载 packed Image 后保存其内容指纹：尺寸、统一读取的 RGBA 像素、颜色空间及 Alpha 模式。命中输入哈希时重新计算当前指纹，匹配才复用；不匹配、缺少指纹或无法读取时跳过该候选，从剪贴板原始字节重新创建。
|
||||
|
||||
指纹在稳定的像素读取约定下计算，包含完全透明像素的 RGB。使用前验证能同时覆盖 Mask、Frame、Rectify、AI 编辑与原生绘制，避免依赖每个编辑入口主动通知。`is_dirty` 不能代表内容是否仍相同，packed 的编辑结果也必须验证。
|
||||
|
||||
剪贴板粘贴为参考图、节点或笔刷时沿用有效原图缓存；粘贴为 Plane 材质时基于该原图按整图范围创建独立颜色产物。旧缓存缺少指纹时按未命中处理，无需迁移用户图像。
|
||||
|
||||
### 6. Plane 收紧为静态图片
|
||||
|
||||
在创建材质或临时文件前拒绝 Movie、Sequence 及其他动画输入，明确报告仅支持静态图。移除 Plane 的帧起点、偏移、时长及循环传递，并沿调用链清理仅供材质动画使用的参数。其他图片编辑功能仍按各自输入约定运行。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [PNG / EXR 往返改变 RGB 或 Alpha 解释] → 覆盖 byte、float、HDR、透明 RGB、dirty、generated 和 packed 来源，检查配置前后与保存重载结果。
|
||||
- [全图内容指纹存在读取成本] → 先以剪贴板输入哈希筛选，仅验证匹配候选，复用 common 的无副作用像素读取。
|
||||
- [临时文件被提前删除] → 操作持有文件直至模型输入使用结束与材质打包完成，测试取消和失败路径。
|
||||
- [旧复用测试与当前要求冲突] → 以本提案的独立 Color 规格更新行为断言，保留有效错误恢复覆盖。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
先实现并验证公共颜色产物，再接入 Cutout、Convert To 与剪贴板 Plane；补充缓存指纹校验，移除被替换的原图复用分支和重复实现。仅对后续操作采用新规则，已有场景数据保留。更新相关测试并运行全量测试，确认旧引用清理和正常退出。
|
||||
28
openspec/changes/unify-material-color-images/proposal.md
Normal file
28
openspec/changes/unify-material-color-images/proposal.md
Normal file
@@ -0,0 +1,28 @@
|
||||
## Why
|
||||
|
||||
材质直接复用原 Image 会让再次导入原文件或再次粘贴剪贴板内容带入材质配置及绘制结果。Cutout 与 Convert To 需要统一的独立颜色图流程，剪贴板缓存则需要确认当前图像仍代表最初粘贴的内容。
|
||||
|
||||
## What Changes
|
||||
|
||||
- Cutout、Plane、Depth Plane、Relief Plane、Panorama 和剪贴板 Plane 统一按图片范围生成材质颜色图：导出独立临时文件、独立加载、以 `_color` 命名、配置并打包。
|
||||
- Cutout 始终使用裁切范围；Convert To 和剪贴板 Plane 使用整图范围。是否使用 AI 只影响深度、法线等推理产物。
|
||||
- 材质颜色图与原 Image、原文件加载路径及剪贴板缓存标记隔离，保留源像素精度和各入口的颜色空间、Alpha 规则。
|
||||
- 普通 byte 图继续场景视图适配；所有 float / HDR 保留源解释，无法无损往返的输入明确拒绝转换。
|
||||
- 保留相同剪贴板内容的复用；缓存命中时核对当前像素、尺寸、颜色空间和 Alpha 模式，修改后的图片不再代表原缓存内容。
|
||||
- **BREAKING**：Convert to Plane 仅接受静态图片，拒绝 Movie 和 Sequence，移除该入口的动画帧参数传递。
|
||||
- 保留失败清理、异步源图校验与撤销能力，清理转换原图复用分支和重复颜色图实现。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `material-color-images`: 所有材质创建入口的范围采样、独立颜色图、精度、配置、静态输入和资源生命周期。
|
||||
- `clipboard-image-cache`: 相同剪贴板内容的有效复用、编辑后的缓存失效以及材质派生图隔离。
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
## Impact
|
||||
|
||||
涉及 `common/image.py`、`common/material.py`、Cutout、两个 Convert To 包、剪贴板图像获取及 Plane 创建入口和相关测试。沿用现有依赖与节点资产。
|
||||
|
||||
本提案取代 `reuse-conversion-source-images` 的材质原图复用策略及 Plane 动画约定；采用当前代码中的失败清理和源对象校验能力继续实施。当前主规格目录为空，新规格集中表达最终行为，后续归档时以本提案的重叠约定为准。
|
||||
@@ -0,0 +1,43 @@
|
||||
## Purpose
|
||||
|
||||
保留相同剪贴板图片的复用能力，同时核对候选 Image 当前内容与解释设置是否仍匹配首次加载状态，确保编辑后的图像和材质派生图不会被误认为原始剪贴板内容再次粘贴。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Clipboard reuse requires an unchanged image
|
||||
|
||||
相同剪贴板输入 SHALL 仅复用当前像素、尺寸、颜色空间和 Alpha 模式均匹配缓存基线的有效 Image。缓存验证 SHALL 包括透明区域 RGB，并保持候选图像原有内容与状态。
|
||||
|
||||
#### Scenario: Repeated content remains unchanged
|
||||
|
||||
- **WHEN** 相同剪贴板内容再次粘贴，缓存图像内容和设置未改变
|
||||
- **THEN** 系统 SHALL 复用该 Image
|
||||
|
||||
#### Scenario: Mask overwrites the cached image
|
||||
|
||||
- **WHEN** Mask 修改了独占的剪贴板 Image，修改结果已打包，再次粘贴原始剪贴板内容
|
||||
- **THEN** 系统 SHALL 加载原始剪贴板内容到另一 Image，保留已编辑图像
|
||||
|
||||
#### Scenario: Shared edit leaves an intact candidate
|
||||
|
||||
- **WHEN** 编辑产生独立结果，另一个用户仍引用未修改的剪贴板原图
|
||||
- **THEN** 再次粘贴 SHALL 复用该未修改原图
|
||||
|
||||
#### Scenario: Other editing or interpretation changes invalidate a candidate
|
||||
|
||||
- **WHEN** 候选图像经过尺寸修改、原生绘制、透明 RGB 修改、颜色空间或 Alpha 模式变更
|
||||
- **THEN** 再次粘贴 SHALL 跳过已变更候选，使用原始剪贴板内容及其初始解释设置
|
||||
|
||||
#### Scenario: Legacy or unreadable cache entry is found
|
||||
|
||||
- **WHEN** 候选缺少内容校验基线或无法读取
|
||||
- **THEN** 系统 SHALL 按未命中处理，并保留已有图像
|
||||
|
||||
### Requirement: Clipboard material results stay outside the source cache
|
||||
|
||||
剪贴板 Plane SHALL 从有效剪贴板原图按整图范围生成独立材质颜色图。参考图、节点和笔刷的后续粘贴 SHALL 按原图缓存有效性选择 Image。
|
||||
|
||||
#### Scenario: Painted material is followed by another paste
|
||||
|
||||
- **WHEN** 用户粘贴为 Plane 并绘制其材质，随后把相同内容粘贴为参考图、节点或笔刷
|
||||
- **THEN** 系统 SHALL 使用原始剪贴板内容，且不复用材质颜色图
|
||||
@@ -0,0 +1,82 @@
|
||||
## Purpose
|
||||
|
||||
统一 Cutout、Convert To 与剪贴板 Plane 的材质颜色图来源和交付约定，使裁切与整图转换使用同一范围采样流程，并保障材质编辑、再次导入原文件及保存重载时图像内容与设置保持隔离。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Material color uses the requested source bounds
|
||||
|
||||
所有材质生成入口 SHALL 按本次准备时的源图像素和范围生成颜色图。Cutout SHALL 使用裁切范围，四种 Convert To 与剪贴板 Plane SHALL 使用整图范围。AI 的参与 SHALL 保持相同颜色来源及颜色分辨率。
|
||||
|
||||
#### Scenario: Cutout uses or omits AI
|
||||
|
||||
- **WHEN** 同一源图和裁切范围分别执行普通 Cutout 和需要 AI 的 Cutout
|
||||
- **THEN** 两者的颜色图 SHALL 对应同一裁切内容、尺寸和原有 Alpha，包含透明区域 RGB
|
||||
|
||||
#### Scenario: A full image is converted
|
||||
|
||||
- **WHEN** 执行 Plane、Depth Plane、Relief Plane、Panorama 或剪贴板 Plane
|
||||
- **THEN** 颜色图 SHALL 对应完整源图片，保持原始尺寸和当前像素
|
||||
|
||||
### Requirement: Every material owns an isolated color image
|
||||
|
||||
每次生成材质 SHALL 使用独立 Color Image 和独立临时颜色文件路径，以源图基名、`_color` 及实际文件后缀命名并打包。原 Image 的内容和解释设置 SHALL 保持不变，材质 Color SHALL 不携带剪贴板原图缓存身份。
|
||||
|
||||
#### Scenario: Source users vary
|
||||
|
||||
- **WHEN** 原图没有其他用户，或被其他 Empty、材质或笔刷引用
|
||||
- **THEN** 新材质 SHALL 使用独立颜色图，原图的引用、像素、名称、路径、颜色空间及 Alpha 模式 SHALL 保持原值
|
||||
|
||||
#### Scenario: Original file is imported after material painting
|
||||
|
||||
- **WHEN** 转换后修改材质颜色图，再次按原文件路径导入图片，包括原 Image 已移除的情况
|
||||
- **THEN** 导入 SHALL 不命中材质颜色图，不带入该颜色图的材质设置和绘制像素
|
||||
|
||||
### Requirement: Encoding preserves color precision and presentation
|
||||
|
||||
颜色图 SHALL 保留对应范围的 RGB、Alpha、透明区域 RGB 及源编码精度，float / HDR SHALL 保留浮点范围。普通 byte 材质 SHALL 沿用颜色空间适配与 Alpha 配对规则，所有 float / HDR 材质 SHALL 保留源颜色空间与 Alpha 模式。
|
||||
|
||||
#### Scenario: Ordinary material is configured
|
||||
|
||||
- **WHEN** 普通 byte 材质适配关闭或回退到 sRGB，或者启用可用的 inverse 空间
|
||||
- **THEN** 颜色图 SHALL 分别采用 sRGB + PREMUL 或对应 inverse 空间 + STRAIGHT，原图设置保持不变
|
||||
|
||||
#### Scenario: HDR and unsaved pixels are serialized
|
||||
|
||||
- **WHEN** float / HDR、generated、dirty 或 packed 源图完成颜色图生成、打包和保存重载
|
||||
- **THEN** 结果 SHALL 在对应编码精度内保留业务像素、动态范围与选定的颜色解释
|
||||
- **AND** 所有 float / HDR 材质 SHALL 保留源图颜色空间与 Alpha 模式；Panorama 非 sRGB 分支沿用源解释
|
||||
|
||||
#### Scenario: Float source interpretation prevents lossless serialization
|
||||
|
||||
- **WHEN** 按源颜色空间和 Alpha 模式解码 EXR 后无法保留源浮点像素
|
||||
- **THEN** 操作 SHALL 明确拒绝转换，清理临时资源并保持源图不变
|
||||
- **AND** float / HDR 材质 SHALL 不启用场景视图适配的 Alpha Fix
|
||||
|
||||
### Requirement: Material operations release temporary resources safely
|
||||
|
||||
临时颜色文件 SHALL 在打包和相关 Job 使用结束后释放。取消或失败 SHALL 清理本次临时文件与未交付数据，保留源对象及原图。成功转换 SHALL 支持 Undo / Redo；异步源对象失效或 Image 被替换时 SHALL 取消应用。
|
||||
|
||||
#### Scenario: Packed result survives file cleanup
|
||||
|
||||
- **WHEN** 操作成功且临时目录已删除
|
||||
- **THEN** 材质颜色图 SHALL 仍能正确读取并保存重载
|
||||
|
||||
#### Scenario: An operation fails or is cancelled
|
||||
|
||||
- **WHEN** 导出、模型处理、图像加载、材质或对象创建失败，或用户取消 Job
|
||||
- **THEN** 本次临时资源 SHALL 释放，源对象、源像素和源图设置保持原值
|
||||
|
||||
#### Scenario: Conversion is undone and redone
|
||||
|
||||
- **WHEN** 用户撤销并重做转换
|
||||
- **THEN** 撤销 SHALL 恢复源对象和源图，重做 SHALL 恢复带独立颜色图的转换结果
|
||||
|
||||
### Requirement: Plane accepts static images only
|
||||
|
||||
Convert to Plane SHALL 仅接受静态图片；Movie、Sequence 和动画图像 SHALL 在创建颜色图或对象前被拒绝，并给出明确错误。
|
||||
|
||||
#### Scenario: Animated source is selected
|
||||
|
||||
- **WHEN** 源 Image 为 Movie 或 Sequence，即使其声明时长为一帧，或源图片含多帧
|
||||
- **THEN** Plane SHALL 报告仅支持静态图片，并保持源对象及图像不变
|
||||
25
openspec/changes/unify-material-color-images/tasks.md
Normal file
25
openspec/changes/unify-material-color-images/tasks.md
Normal file
@@ -0,0 +1,25 @@
|
||||
## 1. 公共颜色图流程
|
||||
|
||||
- [x] 1.1 在 common 中统一按范围导出、独立加载、命名与打包的颜色产物流程，明确临时目录所有权；测试整图和局部裁切的尺寸、RGB、Alpha、独立 Image 身份及原路径隔离。
|
||||
- [x] 1.2 实现 byte PNG 和 float / HDR EXR 的精度与解释配对，复用适合的公共像素和编码能力；验证 generated、dirty、packed、透明 RGB、HDR 动态范围及材质配置后的保存重载，保留 float / HDR 源解释，无法无损往返时明确拒绝，替换原普通 float 重载 xfail。
|
||||
- [x] 1.3 保留公共材质函数对已准备 Color 的配置及节点绑定职责，验证 inverse / sRGB 回退、Alpha 配对、Panorama HDR 保留和源 Image 设置不变。
|
||||
|
||||
## 2. 接入材质入口
|
||||
|
||||
- [x] 2.1 将普通与 AI Cutout 接入同一裁切颜色产物，协调分析输入与异步文件生命周期；同源同范围测试确认两条路径颜色一致、透明 RGB 保留，推理分辨率不改变颜色分辨率。
|
||||
- [x] 2.2 将 Plane、Depth Plane、Relief Plane 和 Panorama 接入整图范围流程，移除转换原图复用及相应恢复分支，保留异步源身份校验；验证不同共享用户下原图不变、四个入口使用独立 `_color` Image。
|
||||
- [x] 2.3 将 Plane 限定为静态图片并清理该入口帧参数及仅供材质动画使用的路径；测试 Movie、Sequence 单帧与多帧输入在创建临时资源前被拒绝，静态转换与 Operator 注册正常。
|
||||
- [x] 2.4 将剪贴板 Plane 接入整图颜色产物，确保结果不携带缓存身份；测试创建材质后绘制再粘贴为参考图、节点或笔刷，得到原始剪贴板内容。
|
||||
|
||||
## 3. 剪贴板缓存有效性
|
||||
|
||||
- [x] 3.1 为新缓存建立内容指纹，按输入哈希筛选后核对当前像素、尺寸、颜色空间与 Alpha；测试未变内容复用、变化内容跳过、透明 RGB 变化、旧缓存缺少指纹和候选读取失败，验证读取不改变候选状态。
|
||||
- [x] 3.2 补充实际编辑后的重复粘贴测试，覆盖 Mask 覆盖原 Image、已打包编辑结果、共享 Empty 保留原图、尺寸修改及原生绘制；确认原始粘贴内容正确且编辑结果保留。
|
||||
|
||||
## 4. 生命周期与最终验证
|
||||
|
||||
- [x] 4.1 验证导出、加载、模型、材质和对象创建失败以及 Job 取消的资源清理，确认原图与源对象保持有效；通过临时目录删除后的保存重载及转换 Undo / Redo 测试。
|
||||
- [x] 4.2 添加“生成材质 → 绘制 → 再按原文件路径导入”的回归，包含原 Image 已删除场景，验证不会命中材质 Color；检查所有材质入口及重复实现的最终引用。
|
||||
- [x] 4.3 更新受影响测试并运行全量 `uv run pytest`，确认正常退出；检查最终差异、旧引用和 OpenSpec 严格校验，保留工作区已有修改。
|
||||
|
||||
验证结果：`uv run pytest` 共 1162 项通过，退出码 0；OpenSpec 严格校验通过。
|
||||
Reference in New Issue
Block a user