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.

openspec/changes/add-moge3-model/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-10

openspec/changes/add-moge3-model/design.md

@@ -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
+
+先基于已完成原型验证动态尺寸、分辨率等级、精度与性能，再完成转换工具和模型登记。沿用现有设置与默认模型，只增加新模型选择及必要分派。实施更新相关测试，检查依赖与打包内容一致性。

openspec/changes/add-moge3-model/proposal.md

@@ -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 与现有后处理依赖。正式接入以动态尺寸、分辨率等级及完整流程验收通过为前提。

openspec/changes/add-moge3-model/specs/moge3-model/spec.md

@@ -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** 给出明确状态，不应用部分结果，并允许后续重新运行

openspec/changes/add-moge3-model/tasks.md

@@ -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，确认正常退出及最终差异范围。

openspec/changes/add-moge3-model/validation.md

@@ -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 实机验收。