feat: Implement depth surface strip cleanup and organize tool CLI
- Added a proposal for depth surface strip cleanup, detailing the rationale and changes to the depth plane and cutout nodes. - Created specifications for the new cleanup requirements, including scenarios for strip removal and boundary edge detection. - Developed tasks for implementing shared strip detection logic and integrating new interfaces for depth nodes. - Established a new CLI structure for organizing node groups and model commands, replacing old entry points with a more intuitive command structure. - Introduced a prototype for panorama surface generation, including requirements for distance reconstruction and geometry node surfaces. - Added comprehensive tests for depth strip cleanup functionality, ensuring correct behavior for various mesh topologies and edge cases.
This commit is contained in:
2
openspec/changes/organize-tool-cli/.openspec.yaml
Normal file
2
openspec/changes/organize-tool-cli/.openspec.yaml
Normal file
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-09-10
|
||||
44
openspec/changes/organize-tool-cli/design.md
Normal file
44
openspec/changes/organize-tool-cli/design.md
Normal file
@@ -0,0 +1,44 @@
|
||||
## Context
|
||||
|
||||
参见 proposal.md。现有节点入口依次调用 Blender 构建、资产校验及 pytest，预览模块已有 HTML 导出能力。模型入口统一准备模型并按选项上传，包含现成文件下载、普通 ONNX 转换及 PiSA-SR 独立环境转换。
|
||||
|
||||
## Goals
|
||||
|
||||
命令入口负责参数解析与流程调度，业务模块负责产物；复用现有 Blender 启动、模型准备与校验实现。
|
||||
|
||||
## Decisions
|
||||
|
||||
- 在现有两个 cli.py 使用 argparse 子命令，脚本入口为 `node-group` 和 `model`。Python 包继续使用表示业务集合的 `tools/nodes`、`tools/models`。
|
||||
- `node-group build` 保持构建、资产校验、全量 pytest 的顺序；`check` 复用后两步。两者支持 `--blender` 和现有 `--skip-tests`，后者只跳过 pytest。任一步失败立即以非零状态退出。
|
||||
- `preview` 复用 Blender 启动流程及现有预览导出器，默认写入系统临时目录的独立 HTML，输出绝对路径，再由父进程打开浏览器。支持 `--blender`、`--output PATH`、`--no-open`、`--fragment`；fragment 模式仅输出片段且不自动打开。文件保留供查看，资产文件保持原样。
|
||||
- 模型子命令为 `prepare` 和 `sync`。`prepare` 替代 `--prepare-only`，统一下载现成 ONNX 或准备源权重并导出，包含 PiSA-SR；按既有目录输出，复用已校验的缓存及独立转换环境。`sync` 复用全部准备成功后上传的流程。
|
||||
- PiSA-SR 在模型目录下的临时目录导出整组文件，全部通过目录清单校验后再更新正式产物，临时目录随流程退出清理。
|
||||
- 使用延迟导入，使帮助与参数错误可以在未加载 Blender、Torch 和导出环境时返回。无动作时显示帮助并成功退出，非法动作或参数非零退出。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[解析命令] --> B[node-group]
|
||||
A --> C[model]
|
||||
B --> D[build 构建资产]
|
||||
D --> E[校验资产]
|
||||
B --> F[check]
|
||||
F --> E
|
||||
E --> G[pytest]
|
||||
B --> H[preview 内存构建与排列]
|
||||
H --> I[HTML 预览]
|
||||
C --> J[prepare 下载或导出并校验全部模型]
|
||||
C --> K[sync]
|
||||
K --> J
|
||||
J --> L{动作是 sync}
|
||||
L -->|是| M[上传 R2]
|
||||
```
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- CLI 改名影响本地脚本调用 → 删除旧入口并验证新的安装脚本映射，实施时报告命令迁移。
|
||||
- Blender 参数与预览参数共用进程命令行 → 显式传递业务参数，测试参数隔离与失败传播。
|
||||
- 模型导出成本较高 → 保留大小及 SHA-256 校验后的缓存复用；自动测试使用隔离文件和替代执行器验证路由。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
更新入口及子命令后执行 `uv sync` 刷新本地脚本，运行相关测试、帮助命令及节点构建链验证。保留工作区既有修改。
|
||||
24
openspec/changes/organize-tool-cli/proposal.md
Normal file
24
openspec/changes/organize-tool-cli/proposal.md
Normal file
@@ -0,0 +1,24 @@
|
||||
## Why
|
||||
|
||||
节点组和模型工具需要统一为「对象 + 动作」命令，让构建、检查、预览和模型准备的职责直观可见，并能独立执行。
|
||||
|
||||
## What Changes
|
||||
|
||||
- **BREAKING**：将 `build-nodes` 替换为 `node-group build`，将 `sync-models` 替换为 `model sync`，删除旧入口。
|
||||
- 提供 `node-group check`，检查已有资产并运行测试；提供 `node-group preview`，生成当前源码的 HTML 预览并打开浏览器。
|
||||
- 提供 `model prepare`，按模型来源下载现成文件或准备源权重并导出，统一校验全部模型。
|
||||
- 使用统一的小写子命令；未提供动作时显示帮助。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `developer-tool-cli`：节点组和模型命令的路由、执行边界、参数及失败行为。
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
无。
|
||||
|
||||
## Impact
|
||||
|
||||
涉及 `pyproject.toml` 的脚本入口、`tools/nodes`、`tools/models` 和相关命令测试。使用现有 argparse、Blender 与模型转换依赖。实施范围为命令代码与测试；本次产出为 OpenSpec 规划文件。
|
||||
@@ -0,0 +1,81 @@
|
||||
## Purpose
|
||||
|
||||
为 AnyImage 开发者提供按业务对象组织的命令接口，明确节点组构建、检查与预览，以及模型准备与同步的执行边界，将模型下载和导出统一归入准备流程，让每个动作的产物、失败状态和副作用均可验证。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Grouped command entry points
|
||||
|
||||
系统 SHALL 提供 `uv run node-group` 和 `uv run model` 入口，使用小写子命令，并移除旧脚本入口 `build-nodes`、`sync-models`。
|
||||
|
||||
#### Scenario: Display help
|
||||
- **WHEN** 用户未指定子命令或传入 `--help`
|
||||
- **THEN** 命令显示帮助并成功退出，不启动 Blender、模型准备或上传
|
||||
|
||||
#### Scenario: Invalid arguments
|
||||
- **WHEN** 用户传入未知子命令或参数
|
||||
- **THEN** 命令显示参数错误并非零退出，业务动作不执行
|
||||
|
||||
### Requirement: Build and check node groups
|
||||
|
||||
`node-group build` SHALL 依次构建资产、校验保存的资产、运行全量 pytest；`node-group check` SHALL 仅执行后两步。两者 SHALL 支持 `--blender` 选择 Blender，支持 `--skip-tests` 仅跳过 pytest。
|
||||
|
||||
#### Scenario: Build assets
|
||||
- **WHEN** 用户运行 `uv run node-group build`
|
||||
- **THEN** 更新 O_AnyImage.blend，并在资产校验和全量测试成功后成功退出
|
||||
|
||||
#### Scenario: Check existing assets
|
||||
- **WHEN** 用户运行 `uv run node-group check`
|
||||
- **THEN** 检查已有资产并运行全量测试，资产文件内容保持原样
|
||||
|
||||
#### Scenario: Skip Python tests
|
||||
- **WHEN** build 或 check 指定 `--skip-tests`
|
||||
- **THEN** 仍执行资产校验，跳过 pytest
|
||||
|
||||
#### Scenario: Stop after failure
|
||||
- **WHEN** 构建、校验或测试任一步失败
|
||||
- **THEN** 命令非零退出且不执行后续步骤
|
||||
|
||||
### Requirement: Preview node groups
|
||||
|
||||
`node-group preview` SHALL 从当前源码在内存中构建并排列几何节点组，生成 HTML，输出绝对路径并默认打开浏览器，保持资产文件内容原样。默认文件 SHALL 保存于系统临时目录并在命令退出后可供查看。命令 SHALL 支持 `--blender`、`--output PATH`、`--no-open` 和 `--fragment`。
|
||||
|
||||
#### Scenario: Preview current source
|
||||
- **WHEN** 用户运行 `uv run node-group preview`
|
||||
- **THEN** 生成当前源码的可查看 HTML 并尝试打开浏览器
|
||||
|
||||
#### Scenario: Save without opening
|
||||
- **WHEN** 用户指定 `--output PATH --no-open`
|
||||
- **THEN** HTML 写入指定路径且不启动浏览器
|
||||
|
||||
#### Scenario: Export fragment
|
||||
- **WHEN** 用户指定 `--fragment`
|
||||
- **THEN** 输出 HTML 片段及其路径，不自动打开浏览器
|
||||
|
||||
### Requirement: Prepare and sync models
|
||||
|
||||
模型命令 SHALL 提供 `prepare` 和 `sync` 两个子命令。`model prepare` SHALL 准备并校验目录中全部模型，复用有效缓存，按模型来源下载现成 ONNX 或准备源权重并导出（包含 PiSA-SR）；`model sync` SHALL 在全部准备成功后上传 R2。`prepare` SHALL 不上传且不要求上传工具可用。
|
||||
|
||||
#### Scenario: Prepare locally
|
||||
- **WHEN** 用户运行 `uv run model prepare`
|
||||
- **THEN** 全部模型在本地通过既有大小和 SHA-256 校验，不执行上传
|
||||
|
||||
#### Scenario: Sync prepared models
|
||||
- **WHEN** 用户运行 `uv run model sync` 且全部准备成功
|
||||
- **THEN** 上传全部模型到既定 R2 位置
|
||||
|
||||
#### Scenario: Preparation fails
|
||||
- **WHEN** 任一模型准备或校验失败
|
||||
- **THEN** 命令非零退出，sync 不开始上传
|
||||
|
||||
#### Scenario: Download and export models
|
||||
- **WHEN** 用户运行 `uv run model prepare` 且本地缺少有效模型
|
||||
- **THEN** 根据模型来源下载现成文件或准备源权重并导出，产物保存到既有本地目标并通过校验
|
||||
|
||||
#### Scenario: Reuse valid cache
|
||||
- **WHEN** 本地模型已通过大小和 SHA-256 校验
|
||||
- **THEN** prepare 复用该产物，跳过对应下载和导出
|
||||
|
||||
#### Scenario: Export fails
|
||||
- **WHEN** 源权重准备、转换或产物校验失败
|
||||
- **THEN** 命令非零退出，失败产物不替换正式目标
|
||||
19
openspec/changes/organize-tool-cli/tasks.md
Normal file
19
openspec/changes/organize-tool-cli/tasks.md
Normal file
@@ -0,0 +1,19 @@
|
||||
## 1. 命令入口
|
||||
|
||||
- [x] 1.1 将脚本入口替换为 `node-group`、`model`，增加子命令解析并删除旧入口及 `--prepare-only`；更新入口测试，验证帮助、无动作、非法参数均不执行业务操作。
|
||||
|
||||
## 2. 节点组命令
|
||||
|
||||
- [x] 2.1 实现 build 与 check 的公共 Blender 调度，支持 `--blender`、`--skip-tests`；通过命令测试验证顺序、check 不构建和失败即停止。
|
||||
- [x] 2.2 接入 preview，支持默认临时 HTML、`--output`、`--no-open`、`--fragment`，由父进程打开浏览器；验证参数传递、输出内容、片段模式和资产内容保持原样。
|
||||
|
||||
## 3. 模型命令
|
||||
|
||||
- [x] 3.1 实现 prepare 与 sync 两个模型子命令，prepare 统一下载和导出，sync 复用准备后上传逻辑；通过隔离测试验证缓存命中、下载或转换选择、校验失败阻断上传，以及 prepare 不依赖上传工具。
|
||||
- [x] 3.2 验证 prepare 覆盖现成模型下载、普通模型转换与 PiSA-SR 导出，测试源权重准备、产物校验、失败临时文件清理和正式目标保护。
|
||||
|
||||
## 4. 集成验证
|
||||
|
||||
- [x] 4.1 执行 `uv sync` 后检查两组命令及全部子命令的 `--help`，运行相关工具测试，确认安装入口与源码一致。
|
||||
- [x] 4.2 执行 `uv run node-group build` 验证真实 Blender 构建、资产校验和全量 pytest 正常退出；运行 `node-group check` 和 `node-group preview --no-open`，校验资产哈希保持原样及预览文件可查看。
|
||||
- [x] 4.3 检查代码与测试中的旧入口引用、最终差异和测试结果，确认保留工作区既有修改，并简要报告命令迁移及验证结果。
|
||||
Reference in New Issue
Block a user