Ukawka
255 lines
13 KiB
Markdown
255 lines
13 KiB
Markdown
# AI Spine 角色拆件与动画管线
|
||
|
||
本项目探索将单张 2D 角色图转换为可用于 Spine 动画的部件与骨骼资源。当前主线分为四个阶段：视觉 LLM 理解结构、本地 SAM 分割可见部件、图片编辑模型补全隐藏区域和关节连接、离线组装与 Spine 导出。
|
||
|
||
| 阶段 | 输入 → 输出 | 当前状态 |
|
||
| --- | --- | --- |
|
||
| 1. 结构理解 | PNG → v2 语义计划、粗框、pivot、程序候选点 | 可在线理解或离线复检；语义待复核 |
|
||
| 2. SAM 分割 | 第一阶段目录 → mask、原像素透明部件、标注图与拆解图 | 本机 GPU 实测可运行；存在误分与漏分 |
|
||
| 3. 部件补全 | SAM 目录 → 局部编辑候选、几何 QA、通过检查的补全部件 | 已真实调用图片模型；结果质量尚不合格 |
|
||
| 4. Spine 导出 | SAM + 可选补全目录 → 完整资产、原位组装、骨骼、图集、预览 | 通用离线入口；含单骨骼旋转检查动画，资产与动作质量需复核 |
|
||
|
||
第三阶段输出通过几何检查的补全部件；第四阶段整合所有可绘制部件、组装并导出 Spine 4.2。执行成功、mask 覆盖率高、几何检查通过，均不等于动画资产可用。
|
||
|
||
仓库保留旧版“生成白底拆件图 → OpenCV 拆分 → Genielabs 定位 → Spine 导出”作为对照；它与当前四阶段主线并存，产物不能直接混用。
|
||
|
||
## 文档入口
|
||
|
||
- [AGENTS.md](AGENTS.md)：修改约定、跨会话上下文、当前基线及后续优先级。
|
||
- [第一阶段](docs/1-understanding-stage.md)：理解、数据契约、Alpha 候选与粗标注。
|
||
- [第二阶段](docs/2-segmentation-stage.md)：本地 SAM、mask 选择、拆件与质量边界。
|
||
- [第三阶段](docs/3-completion-stage.md)：筛选、局部画布、图片请求、几何验收及补全改进。
|
||
- [第四阶段](docs/4-spine-stage.md)：通用资产整合、坐标与骨骼、绘制顺序、Spine 导出与回退策略。
|
||
|
||
阶段文档统一采用八节：简介；输入输出与链路；命令参数；输入格式；重要代码原理；职责索引；产物；可改进点。配置与实验说明已归入上述文档。
|
||
|
||
## Conda 环境准备
|
||
|
||
所有 Python 操作固定使用 **ai-spine**，不使用 `.venv`、其他虚拟环境、Conda base 或系统 Python。Node.js 要求 20 或以上；项目没有额外 npm 运行时依赖。
|
||
|
||
在 PowerShell 中进入实际项目根目录。本工作区路径如下；若本机使用其他目录，仅替换这一行：
|
||
|
||
```powershell
|
||
Set-Location F:\Study\taonier\AI_spine
|
||
node --version
|
||
conda env list
|
||
```
|
||
|
||
仅在没有 ai-spine 环境的新机器上，手动创建一次；当前机器已有环境则跳过：
|
||
|
||
```powershell
|
||
conda create -n ai-spine python=3.11 -y
|
||
```
|
||
|
||
补齐项目依赖。以下是本机已验证的 CUDA 12.6 组合；已有匹配 PyTorch 时可跳过第一条安装命令。代码不会自动安装依赖或创建环境。
|
||
|
||
```powershell
|
||
conda activate ai-spine
|
||
python -m pip install torch==2.7.1 torchvision==0.22.1 --index-url https://download.pytorch.org/whl/cu126
|
||
python -m pip install -r .\requirements.txt
|
||
python -m pip install --no-deps --no-build-isolation -e F:\Study\SAM3\sam3
|
||
```
|
||
|
||
不激活终端时，明确指定目标环境：
|
||
|
||
```powershell
|
||
conda run -n ai-spine python -m pip install -r .\requirements.txt
|
||
```
|
||
|
||
本地 SAM 代码和权重由用户提供，当前位置为：
|
||
|
||
```text
|
||
F:/Study/SAM3/sam3/ 源码仓库
|
||
F:/Study/SAM3/sam3.1checkpoint/sam3.1_multiplex.pt 权重
|
||
```
|
||
|
||
检查解释器、基础依赖与 GPU：
|
||
|
||
```powershell
|
||
conda run -n ai-spine python -c "import sys, cv2, PIL, numpy, torch; print(sys.executable); print('torch', torch.__version__); print('CUDA', torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'No CUDA GPU')"
|
||
```
|
||
|
||
第二阶段要求可用 CUDA GPU。本机已验证 RTX 3060 Laptop 6 GB；默认 BF16 推理保留模型参数和缓冲区所需精度。第一、三阶段的本地几何处理不运行 SAM。Node 入口会验证 Python 属于 ai-spine；`--python` 也不能绕过此约定。
|
||
|
||
## 中转站配置
|
||
|
||
仅在本地 `.env` 不存在时复制模板，随后自行填写密钥：
|
||
|
||
```powershell
|
||
if (-not (Test-Path .\.env)) { Copy-Item .\.env.example .\.env }
|
||
```
|
||
|
||
```dotenv
|
||
# 原中转站
|
||
VECTOR_ENGINE_BASE_URL=https://router.genarrative.world/v1
|
||
VECTOR_ENGINE_API_KEY=填写你的令牌
|
||
|
||
# Tiantoken 独立配置
|
||
TIANTOKEN_BASE_URL=https://api.tiantoken.com
|
||
TIANTOKEN_API_KEY=填写你的令牌
|
||
|
||
# 本地 SAM
|
||
SAM_MODEL_DIR=F:/Study/SAM3
|
||
SAM_CODE_DIR=F:/Study/SAM3/sam3
|
||
```
|
||
|
||
不要把密钥写入文档、JSON 配置或提交到版本库；不要输出 `.env` 内容。
|
||
|
||
| 配置文件 | 第一阶段 | 第三阶段 | 模型环境变量 |
|
||
| --- | --- | --- | --- |
|
||
| [deepseek-qwen.json](configs/deepseek-qwen.json) | deepseek-flash，Chat Completions，非流式 | qwen-image-3.0，images/edits | SPINE_UNDERSTANDING_MODEL / SPINE_COMPLETION_MODEL |
|
||
| [astra-qwen.json](configs/astra-qwen.json) | gpt-6-astra，Responses，流式 | qwen-image-3.0，images/edits | 同上 |
|
||
| [tiantoken.json](configs/tiantoken.json) | gpt-6-astra，Responses，流式 | gpt-image-2，images/edits | TIANTOKEN_UNDERSTANDING_MODEL / TIANTOKEN_COMPLETION_MODEL |
|
||
|
||
CLI > 配置 stage.model > 对应模型环境变量 > default_model；shell 环境变量优先于 `.env`。不指定配置时入口默认 astra-qwen.json，建议实验始终显式指定。模型 ID 原样发送，中转能力以实际请求为准。Tiantoken 图片编辑已真实执行；第三阶段尚未适配 Astra Responses 图片生成工具。
|
||
|
||
三个配置当前仍关闭原生多图与编辑 mask 能力。第三阶段默认 adaptive：实际 mask 重建需求、自适应半径和可逆缩放；当前配置下 auto 会发送含目标、局部参考、完整角色参考的单张参考板。只有支持原生多图时才独立发送参考图；mask 是否发送由配置和 completion-mask 决定，未发送时明确标记 local_only。不能把本地裁剪与恢复当成模型遵循 mask 的证据。
|
||
|
||
查询模型列表和检查配置：
|
||
|
||
```powershell
|
||
node .\tools\model-check.mjs --config .\configs\tiantoken.json --list-models
|
||
node .\tools\model-check.mjs --config .\configs\tiantoken.json --dry-run
|
||
```
|
||
|
||
前者联网，后者不请求模型；列表存在某个 ID 不代表其所有能力已验证。
|
||
|
||
## 四阶段执行命令
|
||
|
||
以下命令按顺序在同一个 PowerShell 会话执行。反引号后不能带空格。每次实验使用新的 runId；分阶段重开终端时，将路径变量设置成已有的对应目录。
|
||
|
||
```powershell
|
||
conda activate ai-spine
|
||
$runId = Get-Date -Format "yyyyMMdd-HHmmss"
|
||
$runRoot = ".\output\$runId"
|
||
$reference = ".\output\20260918-183532\sam\source.png"
|
||
```
|
||
|
||
示例复用现有角色原图，可替换 `$reference` 为自己的 PNG。不要混用不同实验的 source、计划和 mask。
|
||
|
||
### 第一阶段：理解角色结构
|
||
|
||
此命令调用视觉模型：
|
||
|
||
```powershell
|
||
node .\tools\model-check.mjs --stage understanding `
|
||
--config .\configs\deepseek-qwen.json `
|
||
--reference $reference `
|
||
--out-dir "$runRoot\understand"
|
||
```
|
||
|
||
检查 `understand/report.html`、`semantic-parts.json`、`geometry-validation.json`。程序候选点来自 Alpha 距离变换，落在前景不代表属于正确部件。
|
||
|
||
已有计划可离线重新检查；输出独立目录，不重跑模型：
|
||
|
||
```powershell
|
||
node .\tools\model-check.mjs --stage understanding `
|
||
--reference .\output\20260918-183532\sam\source.png `
|
||
--parts-file .\output\20260918-183532\sam\semantic-parts.json `
|
||
--out-dir "$runRoot\understand-offline"
|
||
```
|
||
|
||
### 第二阶段：本地 SAM 分割
|
||
|
||
```powershell
|
||
node .\tools\model-check.mjs --stage segmentation `
|
||
--input-dir "$runRoot\understand" `
|
||
--out-dir "$runRoot\sam" `
|
||
--sam-dir F:/Study/SAM3
|
||
```
|
||
|
||
若使用前面的离线计划，input-dir 改为 understand-offline。该命令只运行本地临时 GPU 子进程；添加 `--dry-run` 可探测环境而不加载模型。检查 `sam/report.html`、`annotated.png`、`parts-sheet.png`、漏分图和 mask 归属，错误部件应先修正。
|
||
|
||
### 第三阶段：准备与补全
|
||
|
||
默认 `--completion-profile adaptive` 会重新检查实际 SAM 缺口、骨骼连接和附件重叠，即使旧计划 needs_completion=false 也可能生成修复任务。先检查 preparation 报告的区域与参考图，再请求模型；缺口归属和附件底图仍需语义复核。
|
||
|
||
先离线准备任务，不请求模型：
|
||
|
||
```powershell
|
||
node .\tools\model-check.mjs --stage completion `
|
||
--config .\configs\tiantoken.json `
|
||
--input-dir "$runRoot\sam" `
|
||
--out-dir "$runRoot\complete-prepare" `
|
||
--prepare-only
|
||
```
|
||
|
||
复核允许区域后，按实际存在的 ID 试一个部件；下面会调用图片模型：
|
||
|
||
```powershell
|
||
node .\tools\model-check.mjs --stage completion `
|
||
--config .\configs\tiantoken.json `
|
||
--input-dir "$runRoot\sam" `
|
||
--out-dir "$runRoot\complete-head" `
|
||
--part head
|
||
```
|
||
|
||
处理所有具备可见 mask、补全需求和允许区域的部件：
|
||
|
||
```powershell
|
||
node .\tools\model-check.mjs --stage completion `
|
||
--config .\configs\tiantoken.json `
|
||
--input-dir "$runRoot\sam" `
|
||
--out-dir "$runRoot\complete"
|
||
```
|
||
|
||
省略 part 不意味着强制补全全部 mask。检查 `completion-plan.json` 的 assessments/跳过原因、每个任务的 input.png、request-plan.json 和编辑区域；parts/ 仅包含通过检查的补全部件。所有结果仍需语义复核。`--completion-review FILE` 可按 ID 提供修复/替换/移除区域及部件半径，格式见[第三阶段文档](docs/3-completion-stage.md)。
|
||
|
||
`--completion-reference auto` 默认在原生多图可用时发送主图→局部参考→全角色参考，否则使用 board；可显式选择 board/local/full/both/none。`--completion-mask auto|required|off` 控制 mask 请求，auto 遵循配置。`--probe-edit-capabilities --part ID` 是一次真实多图+mask 小样，固定 n=1、无 HTTP 重试，保存原候选及能力证据，不自动启用 capabilities。该实测会产生费用；当前实现只完成离线验证。
|
||
|
||
旧候选尺寸不符时，可离线导入复检，避免重新生成：
|
||
|
||
```powershell
|
||
node .\tools\model-check.mjs --stage completion `
|
||
--config .\configs\tiantoken.json `
|
||
--input-dir .\output\20260918-183532\sam `
|
||
--candidates-dir .\output\20260918-183532\complete2_gpt `
|
||
--out-dir "$runRoot\complete-size-recheck" `
|
||
--completion-profile legacy `
|
||
--candidate-size-policy uniform
|
||
```
|
||
|
||
旧画布候选必须指定 legacy。adaptive 候选需匹配源图、masks、profile、参考布局、半径和复核文件哈希；不能把旧候选直接映射到新画布。uniform 仅恢复同宽高比整画布尺寸，不纠正物体位移、变形或语义。在线请求显式传 size；参数及中转实测边界见[第三阶段文档](docs/3-completion-stage.md)。
|
||
|
||
### 第四阶段：离线组装与 Spine 导出
|
||
|
||
接续本轮 SAM 与补全目录，无需模型配置、密钥或 GPU：
|
||
|
||
```powershell
|
||
node .\tools\model-check.mjs --stage spine `
|
||
--input-dir "$runRoot\sam" `
|
||
--completion-dir "$runRoot\complete" `
|
||
--out-dir "$runRoot\spine"
|
||
```
|
||
|
||
省略 `--completion-dir` 可只用 SAM 资产；加 `--dry-run` 完整检查输入而不写输出。默认补全失败回退 SAM 并记录原因；`--fallback-policy error` 要求需补全的可见部件全部有通过结果。可见部件缺 mask、混用不同输入或非法补全坐标会直接报错。
|
||
|
||
检查 `report.html`、`comparison.png` 和 `assembly.json`；`preview.html` 显示真实骨架，setup 为静态姿态，`check__骨骼ID` 为单关节旋转检查动画。生成过程离线；播放器页面从 CDN 加载 Spine Player，需要网络。`skeleton.json` 配合 `images/` 供编辑器导入，`atlas/` 用于运行时。
|
||
|
||
部件数量、名称、父子关系均由 v2 计划驱动；隐藏骨骼保留，附件按 bind_to 绑定。第四阶段只复用外部只读 `spine-animation-ai` 的图集和播放器脚本，保留其 PolyForm Noncommercial 约束。完整参数、输入契约和绘制顺序覆盖见[第四阶段文档](docs/4-spine-stage.md)。
|
||
|
||
## 旧管线与验证
|
||
|
||
旧版依赖相邻 `spine-animation-ai` 外部项目，使用时遵守其 PolyForm Noncommercial 许可证；不要修改外部依赖。旧版命令会调用图片生成并尝试定位、导出：
|
||
|
||
```powershell
|
||
node .\pipeline.mjs `
|
||
--reference $reference `
|
||
--out-dir "$runRoot\legacy" `
|
||
--genielabs-dir ..\spine-animation-ai `
|
||
--image-model qwen-image-3.0 `
|
||
--attempts 1 `
|
||
--animations idle,walk,wave
|
||
```
|
||
|
||
`segment.py` 为旧版拆件分割，`compose_preview.py` 组装预览，`run_case_matrix.py` 对照定位方案；当前 SAM 入口为 sam_segment.py。旧产物检查 assembled.png 和 preview-rigged.html；新管线导出使用独立的第四阶段入口。
|
||
|
||
测试与命令帮助：
|
||
|
||
```powershell
|
||
conda run --no-capture-output -n ai-spine npm test
|
||
node .\tools\model-check.mjs --help
|
||
```
|
||
|
||
测试使用本地 mock 或注入响应，不请求真实付费模型。自动化运行任一阶段可用 `conda run --no-capture-output -n ai-spine node ...`。保留旧实验；resume 只复用完整匹配产物，失败任务另建输出目录。
|