Ukawka
231 lines
10 KiB
Markdown
231 lines
10 KiB
Markdown
# AI Spine 角色拆件与动画管线
|
||
|
||
本项目探索将单张 2D 角色图转换为可用于 Spine 动画的部件与骨骼资源。当前主线分为三个阶段：视觉 LLM 理解结构、本地 SAM 分割可见部件、图片编辑模型补全隐藏区域和关节连接。
|
||
|
||
| 阶段 | 输入 → 输出 | 当前状态 |
|
||
| --- | --- | --- |
|
||
| 1. 结构理解 | PNG → v2 语义计划、粗框、pivot、程序候选点 | 可在线理解或离线复检；语义待复核 |
|
||
| 2. SAM 分割 | 第一阶段目录 → mask、原像素透明部件、标注图与拆解图 | 本机 GPU 实测可运行；存在误分与漏分 |
|
||
| 3. 部件补全 | SAM 目录 → 局部编辑候选、几何 QA、通过检查的补全部件 | 已真实调用图片模型；结果质量尚不合格 |
|
||
|
||
第三阶段尚未输出使用补全部件组装的完整角色，新管线 Spine 导出也未完成。执行成功、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)：筛选、局部画布、图片请求、几何验收及补全改进。
|
||
|
||
阶段文档统一采用八节：简介；输入输出与链路；命令参数；输入格式；重要代码原理；职责索引；产物；可改进点。配置与实验说明已归入上述文档。
|
||
|
||
## 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 能力。第三阶段默认只发送白底单部件图；本地 context.png/edit-mask.png 已生成但不默认发送。改进计划见第三阶段文档。
|
||
|
||
查询模型列表和检查配置：
|
||
|
||
```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 归属，错误部件应先修正。
|
||
|
||
### 第三阶段：准备与补全
|
||
|
||
先离线准备任务，不请求模型：
|
||
|
||
```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` 的跳过原因和 `completion-result.json` 的 QA；parts/ 仅包含通过检查的补全部件。所有结果仍需语义复核。
|
||
|
||
旧候选尺寸不符时，可离线导入复检，避免重新生成：
|
||
|
||
```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" `
|
||
--candidate-size-policy uniform
|
||
```
|
||
|
||
uniform 仅恢复同宽高比的整画布尺寸，不纠正物体位移、变形或语义。在线请求现已显式传 size；参数及中转实测边界见[第三阶段文档](docs/3-completion-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，不能据此声称新三阶段已经完成 Spine 导出。
|
||
|
||
测试与命令帮助：
|
||
|
||
```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 只复用完整匹配产物，失败任务另建输出目录。
|