AnyImage/openspec/specs/two-times-upscale/spec.md

two-times-upscale Specification

Purpose

TBD - created by archiving change add-pisa-sr-two-times-upscale. Update Purpose after archive.

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 处理规则和最终尺寸一致