Add cutout shell and volume node assets for depth volume processing

- Implemented `cutout_shell.py` to build front normals and shell positions for balloon geometry.
- Created `cutout_volume.py` to establish smooth center fields and manage balloon surface attributes.
- Introduced `pisa_sr_export.py` for exporting PiSA-SR components with dependencies and asset finalization.

openspec/changes/add-pisa-sr-two-times-upscale/.openspec.yaml

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

openspec/changes/add-pisa-sr-two-times-upscale/design.md

@@ -0,0 +1,74 @@
+## Context
+
+当前 `onnx_upscale.py` 用 256 像素 tile 执行三个 4× 模型，`models/upscale.py` 负责输入尺寸限制和 alpha 回填，`ModelManager` 缓存单个 Upscale Session。Operator 的倍率和提示均为 4×。
+
+本地实验位于 `build/upscale-explore/pisa-research/`。已验证固定 512×512 的 PiSA-SR FP16 ONNX 全流程在 DirectML 上出图，0.7 预设对应像素强度 1.0、语义强度 0.7、空提示词和 seed 42。两套 UNet 常驻时，512 输出约 1.57–2.37 秒；默认强度 1.0 的单 UNet 速度不代表 0.7。分块和跨设备部署尚待验证。
+
+## Goals / Non-Goals
+
+**Goals:** 四个选项统一 2× 输出；复现已选定的 PiSA-SR 0.7 观感；通过已有 ONNX 运行时服务图片和逐帧任务。
+
+**Non-Goals:** 本次范围限定为固定预设与既有 Upscale 操作，强度滑杆、提示词编辑和视频时序增强属于独立能力。
+
+## Decisions
+
+### 1. 最终倍率与模型原生倍率分别定义
+
+```mermaid
+flowchart TD
+    A[读取并限制输入尺寸] --> B{模型}
+    B -->|现有三个模型| C[原生 4× 分块推理]
+    C --> D[Lanczos 缩至输入宽高的 2 倍]
+    B -->|PiSA-SR| E[Bicubic 放大至 2×]
+    E --> F[VAE 编码与固定噪声采样]
+    F --> G[像素与完整 UNet 预测]
+    G --> H[按语义强度 0.7 组合并解码]
+    H --> I[AdaIN 颜色校正与裁切]
+    D --> J[按最终尺寸回填原始 alpha]
+    I --> J
+    J --> K[保存结果并替换图片]
+```
+
+公共结果倍率为 2，旧 ONNX 图的 shape 校验仍为原生 4。先实现完整 4× 拼接后一次 Lanczos 缩小，作为明确的像素基线；避免先逐 tile 缩小引入新的滤波接缝。最终尺寸相对于 `limit_image()` 之后的输入，沿用 Operator 对输入长边的既有限制。
+
+保留三个模型的 key、原生名称和默认选择，说明文字明确最终输出 2×。新增 key `PISA_SR`、显示名 `PiSA-SR`，说明固定细节强度 0.7；生产和 Debug 复用相同输出入口。
+
+### 2. 固定 0.7 的定义与实验一致
+
+使用同一采样 latent 计算 `pixel + 0.7 * (full - pixel)`，再按已验证的公式解码。空提示词 embedding 与 timestep 固定在资产中，seed 固定为 42；采样算法、精度和噪声布局通过测试锁定。保留实验中的 Bicubic 输入插值、VAE scaling、输出量化和 AdaIN 颜色校正。
+
+该强度是在预测结果上插值。将 LoRA 权重乘以 0.7 或插值两套 UNet 权重，不能视为等价的单 UNet 优化；任何这样的优化必须另行通过效果对照。
+
+### 3. PiSA-SR 使用独立适配器与多文件资产
+
+新增 `server/models/onnx_pisa_sr.py` 承担 VAE、UNet、采样及分块。`ModelManager` 按模型类型创建单 Session 或 PiSA-SR 管线，并统一缓存 key、释放和状态展示。Session 创建和运行复用 `onnx_runtime.py`，补齐 DirectML 所需的 sequential execution 与禁用 memory pattern 配置。
+
+资产以 encoder、decoder、pixel UNet、full UNet 为明确文件集合，通过既有 catalog 下载与完整性校验。实验包约 3.63 GB，发布清单必须使用最终导出文件的尺寸和 SHA256。导出工具固定 PiSA 源码 commit、基础模型 revision、LoRA 校验值和导出环境；训练依赖仅用于离线工具。实验目录仅作为参考，不作为运行时路径。
+
+### 4. 分阶段执行限制模型常驻
+
+优先采用按阶段处理全部 tile 的调度：编码并把 latent 存入主机内存，运行像素 UNet 保存预测，释放该 Session 后运行完整 UNet并组合，最后解码。GPU 上同一时刻只常驻一套 UNet；切换在整图阶段边界发生。大图中间数组可落入任务临时目录，结束或取消后清理。
+
+此方案以降低显存峰值为优先，代价是阶段加载成本；实施时同时测冷启动、连续图片和多帧耗时。任务结束按实际 Session 最后使用点释放临时推理内存，资源错误使整个 PiSA 管线缓存失效，Clear Models 释放全部组件。
+
+### 5. 固定尺寸 ONNX 通过重叠分块覆盖任意输入
+
+以已验证的 512×512 输出 tile 为初始部署尺寸，采用重叠区域加权融合，边缘填充后裁回精确的 2× 尺寸。噪声按整图 latent 坐标生成并切片，重叠区域共享噪声；AdaIN 在拼接完成后按整图执行。单 tile 情况保持实验基线，多 tile 的重叠宽度通过接缝对照确定并固化为内部常量。
+
+alpha 从受尺寸限制的源图直接 Lanczos 放大到最终 2×，独立于生成模型；透明 RGB 的处理沿用现有输入语义，并加入半透明边缘目视验收。多帧逐帧处理并复用固定噪声规则，支持取消；生成纹理的时序稳定性列入验收观察。
+
+## Risks / Trade-offs
+
+- [分块改变生成纹理或形成接缝] → 对两张实验样图及跨 tile 的纹理、渐变、透明边缘做完整图与局部对照；接缝未通过时继续调整分块方案。
+- [分阶段 Session 加载拖慢连续任务] → 记录端到端冷暖耗时、峰值显存和主机内存；不将单 UNet 默认模式的数字作为 0.7 性能承诺。
+- [FP16 图在 CPU/CoreML 上兼容性未知] → 实测项目支持的设备路径；需要时导出匹配的精度资产，并在 catalog 中表达准确支持范围。不可运行的设备返回明确原因。
+- [新细节改变原始图案或引起逐帧闪动] → 保留已有模型选择，验收脸部、文字、纹理和短序列样例，界面说明生成型细节补充。
+- [多 GB 权重分发与依赖来源] → 发布前核对基础模型和 PiSA 权重的分发条款，登记固定来源及最终文件校验信息。
+
+## Migration Plan
+
+先准备与验证 PiSA 资产及分块管线，再接入 catalog、模型管理器和界面，统一最终 2× 结果并运行测试。现有用户保存的模型 key 继续有效，后续执行采用 2×；已有图片产物无需迁移。回退时同步回退模型选项和推理入口，已下载资产可由已有缓存管理处理。
+
+## Open Questions
+
+实施实验需确定分块重叠宽度、阶段加载的可接受耗时，以及 CPU/CoreML 的实际精度与支持范围。这些验证不改变 0.7 和最终 2× 的产品约定。

openspec/changes/add-pisa-sr-two-times-upscale/proposal.md

@@ -0,0 +1,27 @@
+## Why
+
+现有 Upscale 每次把宽高放大 4 倍，尺寸增长过快。PiSA-SR 在已测试的 0.7 细节强度下能够补充更丰富的纹理，适合作为新的生成型选项；所有模型统一每次输出 2×，方便逐步放大。
+
+## What Changes
+
+- 新增 `PiSA-SR` 模型选项，固定 `lambda_pix=1.0`、`lambda_sem=0.7`，输出宽高各为输入的 2 倍。
+- **BREAKING**：现有 General WDN x4v3、SAFMN Real x4、Real-ESRGAN x4plus 仍使用已有 4× 权重，完成推理后以 Lanczos 缩小至一半，最终输出 2×。
+- Upscale 的尺寸计算、界面说明、生产与调试任务统一采用最终 2× 语义；保留现有默认模型。
+- PiSA-SR 通过 ONNX Runtime 接入模型下载、设备选择、缓存、取消和资源释放流程，支持任意合法输入尺寸与透明度保留。
+
+## Capabilities
+
+### New Capabilities
+
+- `two-times-upscale`: 四个模型的统一 2× 输出、PiSA-SR 固定细节预设及模型资源生命周期。
+
+### Modified Capabilities
+
+无已发布的对应 capability。
+
+## Impact
+
+- `server/model_catalog.py`、模型下载与导出工具：增加 PiSA-SR 多文件模型资产及校验信息。
+- `server/models/`、`server/model_manager.py`：PiSA-SR 推理、分块及多 Session 生命周期；旧模型结果缩小。
+- `operators/upscale.py`、模型选择与相关界面：模型选项和最终倍率。
+- 生产、调试、透明图片和多帧处理相关测试。运行时沿用 ONNX Runtime；PyTorch 等仅用于离线导出与数值验证。

openspec/changes/add-pisa-sr-two-times-upscale/specs/two-times-upscale/spec.md

@@ -0,0 +1,74 @@
+## ADDED Requirements
+
+### Requirement: Unified two-times output
+
+系统 SHALL 对全部 Upscale 模型返回处理输入宽高各 2 倍的结果，并将该倍率用于界面说明和尺寸计算；处理输入为应用已有最大输入尺寸限制后的图像。
+
+#### Scenario: Existing models produce two-times images
+- **WHEN** 任一现有模型处理 W×H 输入
+- **THEN** 系统先得到原生 4W×4H 结果，再使用 Lanczos 缩小到 2W×2H
+- **AND** 使用已有 4× 权重
+
+#### Scenario: Repeated upscale
+- **WHEN** 用户对一次 2× 结果再次执行 Upscale 且输入尺寸仍满足限制
+- **THEN** 新结果宽高各为本次输入的 2 倍，即最初输入的 4 倍
+
+### Requirement: Fixed PiSA-SR preset
+
+系统 SHALL 提供 `PISA_SR` 模型选项，使用固定像素强度 1.0、语义强度 0.7、空提示词和 seed 42，通过 ONNX Runtime 生成 2× 结果。现有默认模型 SHALL 保持有效。
+
+#### Scenario: Selected preset is executed
+- **WHEN** 用户选择 PiSA-SR 并执行 Upscale
+- **THEN** 模型对同一 latent 的预测按 `pixel + 0.7 * (full - pixel)` 组合
+- **AND** 输入插值、采样、解码与颜色校正遵循已验证的实验基线
+
+#### Scenario: Repeatable inference
+- **WHEN** 相同图像在相同运行环境重复执行 PiSA-SR
+- **THEN** 系统使用相同噪声和处理规则，结果在该设备的数值容差内一致
+
+### Requirement: Arbitrary dimensions and alpha preservation
+
+系统 SHALL 支持合法输入范围内的小图、非方形图、奇数尺寸和跨 tile 图像，输出精确 2× 尺寸；有 alpha 的生产输入 SHALL 保留由源 alpha 插值而来的透明度。
+
+#### Scenario: Tiled PiSA-SR image
+- **WHEN** 输入需要多个 PiSA-SR tile
+- **THEN** 系统融合重叠区域并裁去填充，输出无多余边缘的 2W×2H 图像
+- **AND** 连续纹理与渐变测试图的 tile 边界不出现可辨识拼接线
+
+#### Scenario: Transparent input
+- **WHEN** 输入包含全透明和半透明像素
+- **THEN** 输出 alpha 等于源 alpha 直接 Lanczos 放大到最终尺寸的结果
+- **AND** RGB 生成过程不生成或覆盖 alpha
+
+### Requirement: Model readiness and resource lifecycle
+
+系统 SHALL 对 PiSA-SR 全部必需资产完成下载及校验后才判定就绪，按所选设备创建管线；其模型切换、取消、资源错误和显式清理 SHALL 覆盖全部组件。
+
+#### Scenario: Incomplete model package
+- **WHEN** PiSA-SR 任一必需文件缺失或校验失败
+- **THEN** 系统提示准备模型并阻止使用不完整管线进行推理
+
+#### Scenario: Bounded UNet residency
+- **WHEN** PiSA-SR 执行像素与完整预测阶段
+- **THEN** GPU 同时常驻的 UNet 至多一套，阶段间中间数据被保留以完成 0.7 组合
+
+#### Scenario: Cancel or resource failure
+- **WHEN** 推理被取消或发生资源错误
+- **THEN** 系统停止后续阶段并清理任务中间文件
+- **AND** 资源错误释放整个 PiSA-SR 管线并报告可理解的失败原因
+
+#### Scenario: Unsupported device
+- **WHEN** 所选设备无法执行已分发的 PiSA-SR 资产
+- **THEN** 系统报告明确的设备支持原因或执行已验证并明确呈现的回退路径
+
+### Requirement: Consistent job behavior
+
+系统 SHALL 在生产与调试任务采用同一模型预设和最终倍率，并对多帧输入逐帧应用该约定。
+
+#### Scenario: Multiple frames
+- **WHEN** Upscale 处理多帧输入
+- **THEN** 每帧输出均为其处理输入的 2× 尺寸，帧顺序正确且阶段之间可以取消
+
+#### Scenario: Debug matches production
+- **WHEN** 相同 RGB 输入、模型和设备分别通过生产与 Debug 入口处理
+- **THEN** 两者的 RGB 处理规则和最终尺寸一致

openspec/changes/add-pisa-sr-two-times-upscale/tasks.md

@@ -0,0 +1,26 @@
+## 1. PiSA-SR 资产与数值基线
+
+- [x] 1.1 将实验的固定来源、revision、LoRA 校验信息与离线依赖纳入正式导出工具，核对分发条款并实现四个 ONNX 组件的可复现导出。
+- [x] 1.2 固化 0.7 预测组合、seed 42 采样、空提示词、插值、量化和 AdaIN 规则；对两张样图验证 PyTorch 与 ONNX 0.7 的最终 RGB 平均绝对误差不超过 1 个 8-bit 灰度级，并目视确认细节。
+- [x] 1.3 验证 DirectML、CUDA 及 CPU/CoreML 的实际支持路径，确定精度资产与设备支持信息，记录不可用路径的明确处理方式。
+
+## 2. 分块与资源管理
+
+- [x] 2.1 实现 PiSA-SR 独立 ONNX 适配器，复用共享运行时，补齐 DirectML Session 配置并覆盖其他模型配置回归。
+- [x] 2.2 实现编码、像素预测、完整预测、解码的分阶段调度，GPU 至多常驻一套 UNet；覆盖阶段切换、中间数据保存及临时文件清理。
+- [x] 2.3 实现固定尺寸重叠分块、共享坐标噪声、加权拼接与最终裁切；用单 tile 基线、奇数尺寸、小图、渐变和跨边界纹理确定重叠参数并确认无可辨识接缝。
+- [x] 2.4 接入模型管理器的管线缓存、切换、Clear Models、取消与 OOM 释放；验证完整任务各组件的最后使用点和多帧行为。
+- [x] 2.5 实测 0.7 的 512、1024 和多 tile 输出，记录加载时间、端到端冷暖耗时、连续帧耗时及峰值显存/主机内存，确认阶段调度消除双 UNet 常驻。
+
+## 3. 模型选项与统一倍率
+
+- [x] 3.1 将最终 PiSA-SR 文件及 SHA256、尺寸、来源加入 catalog 和模型同步工具，覆盖多文件下载、损坏校验与就绪判定。
+- [x] 3.2 将三个旧模型的完整原生 4× 输出以 Lanczos 缩至 2×，保留原生 shape 校验；测试结果与先完整 4× 再缩半的基线一致。
+- [x] 3.3 在公共 Upscale 入口按模型分派，统一输入限制及最终 alpha 回填，覆盖生产与 Debug 两种路径。
+- [x] 3.4 新增 PiSA-SR 选项和 0.7 说明，更新 Operator 最终倍率、尺寸计算及所有相关 4× 行为提示，保留现有模型 key 与默认选择。
+
+## 4. 验收
+
+- [x] 4.1 覆盖四模型最终尺寸、连续两次 2×、输入限制、透明度、帧顺序、取消与资源错误的必要回归测试。
+- [x] 4.2 在 Blender 中验证模型选择、准备模型、图片替换与撤销，对样图、文字、半透明边缘和短序列目视检查细节、接缝及闪动。
+- [x] 4.3 运行相关测试及 `uv run pytest`；依赖或 Manifest 如有变更，核对锁文件与打包测试。记录实际设备验证范围及未解决问题。

openspec/changes/add-pisa-sr-two-times-upscale/validation.md

@@ -0,0 +1,32 @@
+## 实施结果
+
+四个 Upscale 选项统一输出 2×。PiSA-SR 固定像素强度 1.0、语义强度 0.7；旧模型完成原生 4× 拼接后使用 Lanczos 缩半。默认模型与现有 key 保持有效。
+
+PiSA-SR 使用 512 输出 tile、128 像素重叠。固定 seed 42 的 64×64 latent 噪声作为 noise.npy 分发，按整图坐标周期索引，重叠区域使用相同噪声。中间 latent 与像素预测存入任务临时目录，GPU 同时只加载一个组件；最终颜色校正在整图拼接后执行。
+
+正式导出器从固定源码、基础权重和 LoRA 重新生成的四个 ONNX 文件与实验图逐文件 SHA256 相同。发布资产另外写入许可和修改元数据，并随包提供 Apache 2.0、CreativeML Open RAIL++-M 与 NOTICE。最终 8 个文件已上传 R2；远端大小核对零差异，应用实际下载函数完成 noise.npy 的下载与 SHA256 校验。
+
+## 验证
+
+- `uv run --no-sync pytest -q`：680 passed、2 xfailed、60 subtests passed。
+- 两张 0.7 样图，DirectML 与 PyTorch 最终成品平均绝对差异分别为 0.693、0.596 个 8-bit 灰度级；CPU 为 0.257、0.569。
+- DirectML 测试覆盖 1024×1024、1114×1518、1026×514 和 2×6 输出；完整主体、渐变的目视检查未见明显拼接线。
+- 三帧轻微平移、文字和半透明边缘通过生产入口验证；alpha 与源 alpha 直接 Lanczos 放大完全一致。细纹理随帧有变化，文字出现生成型模型的笔画变化。
+- Blender 4.5.3 实际 Python 接口验证四个模型枚举、Operator 注册、结果尺寸与图片替换；真实 Undo 测试恢复原图尺寸和像素。窗口菜单未通过鼠标操作，菜单与请求参数由接口测试覆盖。
+
+## 速度与设备
+
+RTX 5070 Ti、其他 GPU 应用同时运行。计时包含阶段加载、采样、拼接和颜色校正；不含模型下载。
+
+| DirectML 输出 | 完整耗时 |
+| --- | --- |
+| 512 首次 | 5.24 秒 |
+| 512 重复 | 4.67 秒 |
+| 1024 | 5.55 秒 |
+| 三帧逐帧 | 每帧 4.79–5.05 秒 |
+
+采样进程 RSS 峰值约 437 MiB；显卡总占用从约 7985 MiB 到峰值 11930 MiB，包含其他应用，不能视作本进程独占显存。阶段加载约占单张 512 耗时的大部分。
+
+DirectML 和 CPU 完整出图。独立 CUDA ONNX Runtime 1.24.4 配合 torch 2.7.1 的 cuDNN 9.7.1 在本机 VAE 卷积上报 `No valid engine configs for ConvFwd`；该组合未通过 CUDA 验收，运行错误明确提示改选 DirectML 或 CPU，关闭 Session 的运行中隐式回退。CoreML 无可用测试设备，当前 PiSA-SR 明确提示选择 CPU。Windows 的既有生产路径使用 DirectML。
+
+实验日志、输出图片和各阶段计时在 `build/upscale-explore/pisa-research/`。项目运行时依赖与 Manifest 未修改。