ziyu/AI_spine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

文档整理

Browse Source
This commit is contained in:
Ukawka
2026-09-21 00:23:16 +08:00
parent fe4ee1a08e
commit e9072aecf2
6 changed files with 643 additions and 866 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+141 -170
View File
@@ -1,83 +1,45 @@
# AI Spine 角色拆件与动画管线
本项目用于把单张 2D 角色参考图转换为可供 Spine 动画使用的语义部件、透明拆件和骨骼资源。
本项目探索将单张 2D 角色图转换为可用于 Spine 动画的部件与骨骼资源。当前主线分为三个阶段：视觉 LLM 理解结构、本地 SAM 分割可见部件、图片编辑模型补全隐藏区域和关节连接。
当前正在实现的新管线分为三个核心阶段：
| 阶段 | 输入 → 输出 | 当前状态 |
| --- | --- | --- |
| 1. 结构理解 | PNG → v2 语义计划、粗框、pivot、程序候选点 | 可在线理解或离线复检；语义待复核 |
| 2. SAM 分割 | 第一阶段目录 → mask、原像素透明部件、标注图与拆解图 | 本机 GPU 实测可运行；存在误分与漏分 |
| 3. 部件补全 | SAM 目录 → 局部编辑候选、几何 QA、通过检查的补全部件 | 已真实调用图片模型；结果质量尚不合格 |
1. 视觉 LLM 输出语义、层级、骨骼/附件分类、遮挡、粗框和粗关节；程序用 Alpha 检查 ROI 并生成候选种子。
2. 使用 SAM 根据语义、粗框和程序候选生成 mask，经语义/几何检查后从原图提取可见像素。
3. 使用图片编辑模型补全被遮挡的部件，再进行几何验收和 Spine 导出。
第三阶段尚未输出使用补全部件组装的完整角色，新管线 Spine 导出也未完成。执行成功、mask 覆盖率高、几何检查通过，均不等于动画资产可用。
目前第一、二阶段可运行，第三阶段已接入部件画布准备、图片编辑请求、候选几何检查及可见像素恢复。第二阶段在 `ai-spine` Conda 环境的临时子进程中加载本地 SAM 3.1 权重，使用 GPU 分割并生成半透明标注图、白底拆解图和透明部件。分割与补全结果仍需语义复核；新管线的 Spine 导出尚未完成。第三阶段已通过离线及 mock 接口验证，真实图片编辑质量尚待验证。
仓库保留旧版“生成白底拆件图 → OpenCV 拆分 → Genielabs 定位 → Spine 导出”作为对照；它与当前三阶段主线并存，产物不能直接混用。
仓库仍保留旧版“AI 生成白底拆件图 → 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)：筛选、局部画布、图片请求、几何验收及补全改进。
- [项目修改约定](AGENTS.md)：每次修改都必须遵守，Python 固定使用 `ai-spine` Conda 环境。
- [第一阶段：视觉 LLM 角色结构理解](docs/1-understanding-stage.md)：执行流程、代码对应关系、数据格式和输出文件。
- [第二阶段：本地 SAM 分割](docs/2-segmentation-stage.md)：环境、运行命令、权重适配、输出和质量边界。
- [第三阶段：部件补全](docs/3-completion-stage.md)：局部画布、遮挡/关节延展区域、生成调用、可见像素恢复及几何检查。
- [模型阶段配置与实验说明](docs/model-stages.md)：模型切换、协议适配、图片编辑探针、缓存和错误处理。
阶段文档统一采用八节：简介；输入输出与链路；命令参数；输入格式；重要代码原理；职责索引；产物；可改进点。配置与实验说明已归入上述文档。
## 环境准备
## Conda 环境准备
### Node.js
所有 Python 操作固定使用 **ai-spine**，不使用 `.venv`、其他虚拟环境、Conda base 或系统 Python。Node.js 要求 20 或以上；项目没有额外 npm 运行时依赖。
第一阶段要求 Node.js 20 或更高版本，以及下方 Python 几何依赖；没有额外 npm 运行时依赖。
在 PowerShell 中进入实际项目根目录。本工作区路径如下；若本机使用其他目录，仅替换这一行：
```powershell
Set-Location F:\Study\taonier\AI_spine
node --version
conda run -n ai-spine npm test
conda env list
```
### 中转站配置
在项目目录复制环境变量模板：
仅在没有 ai-spine 环境的新机器上，手动创建一次；当前机器已有环境则跳过：
```powershell
Copy-Item .\.env.example .\.env
conda create -n ai-spine python=3.11 -y
```
编辑 `.env`：
```dotenv
VECTOR_ENGINE_BASE_URL=https://router.genarrative.world/v1
VECTOR_ENGINE_API_KEY=你的令牌
# 可选：覆盖配置文件中的默认模型
SPINE_UNDERSTANDING_MODEL=deepseek-flash
SPINE_COMPLETION_MODEL=qwen-image-3.0
# 本地 SAM 根目录和源码仓库；分割结束后子进程退出
SAM_MODEL_DIR=F:/Study/SAM3
SAM_CODE_DIR=F:/Study/SAM3/sam3
```
模型 ID 会原样发送给中转站，不进行隐式别名转换。不要把 API Key 写进 JSON 配置或提交到版本库。
另一个中转站 Tiantoken 使用独立配置 [configs/tiantoken.json](configs/tiantoken.json)。在本地 `.env` 设置 `TIANTOKEN_BASE_URL=https://api.tiantoken.com` 和 `TIANTOKEN_API_KEY`，运行时增加 `--config .\configs\tiantoken.json`；原中转站配置保持独立。
```powershell
node .\tools\model-check.mjs --config .\configs\tiantoken.json --list-models
node .\tools\model-check.mjs --config .\configs\tiantoken.json --dry-run
```
该配置默认第一阶段使用 `gpt-6-astra`（Responses），第三阶段使用 `gpt-image-2`（images/edits），可通过 `TIANTOKEN_UNDERSTANDING_MODEL`、`TIANTOKEN_COMPLETION_MODEL` 或对应 CLI 参数覆盖。2026-09-20 已验证认证与模型列表访问，返回 113 个模型，含上述两个 ID；尚未验证实际理解、图片编辑或 Responses 图片生成工具能力。此配置不等于已接入 Astra 主导的第三阶段图片生成。
### Python 与外部项目
本项目固定使用 **Conda 环境 `ai-spine`**，不使用或创建 `.venv`。第一阶段的 Alpha 校验需要 Python 3、`Pillow`、`numpy`、`opencv-python`。
执行项目命令前先 `conda activate ai-spine`。Node 管线会检查 Python 属于该 Conda 环境；`--python` 也只能指定该环境的解释器。未激活环境或缺少依赖时会报错，不会自动创建环境或安装依赖。
旧版拆件和 Spine 导出还需要：
- Python 3；
- `Pillow`、`numpy`、`opencv-python`；
- 相邻目录中的 `spine-animation-ai` 项目。
当前本机验证组合为 Python 3.11、PyTorch 2.7.1 + CUDA 12.6、torchvision 0.22.1。在 `AI_spine` 目录补全依赖；已有此 CUDA 版本时跳过第一条安装命令：
补齐项目依赖。以下是本机已验证的 CUDA 12.6 组合；已有匹配 PyTorch 时可跳过第一条安装命令。代码不会自动安装依赖或创建环境。
```powershell
conda activate ai-spine
@@ -86,174 +48,183 @@ 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 代码和权重由用户提供，当前位置为：
```powershell
conda run -n ai-spine python -c "import sys, cv2, PIL, numpy; print(sys.executable); print('Dependencies OK')"
```text
F:/Study/SAM3/sam3/ 源码仓库
F:/Study/SAM3/sam3.1checkpoint/sam3.1_multiplex.pt 权重
```
`spine-animation-ai` 是外部只读依赖，使用时需要遵守其 PolyForm Noncommercial 许可证。
## 常用命令
以下命令默认在 `AI_spine` 目录、已激活的 `ai-spine` Conda 环境中运行。自动化可使用 `conda run -n ai-spine node ...`。
### 查询中转站模型
检查解释器、基础依赖与 GPU：
```powershell
node .\tools\model-check.mjs --list-models
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
node .\pipeline.mjs --mode annotated-parts `
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 ..\spine-animation-ai\demo\character_reference.png `
--dry-run
--reference $reference `
--out-dir "$runRoot\understand"
```
### 使用 DeepSeek Flash 理解角色结构
检查 `understand/report.html`、`semantic-parts.json`、`geometry-validation.json`。程序候选点来自 Alpha 距离变换，落在前景不代表属于正确部件。
当前已验证可用的配置是 `deepseek-flash + chat-completions + stream=false`：
已有计划可离线重新检查；输出独立目录，不重跑模型：
```powershell
node .\pipeline.mjs --mode annotated-parts `
--config .\configs\deepseek-qwen.json `
--reference ..\spine-animation-ai\demo\character_reference.png `
--out-dir .\output\sombrero-understand-deepseek `
--stop-after understand
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"
```
重点检查输出目录中的：
- `report.html`：人工复核页面；
- `semantic-parts.json`：v2 语义计划，包含 `rig_role`、`bind_to`、三项 `completion`；
- `geometry-validation.json`：原始点诊断、框内前景比例、候选及阻塞原因；
- `segmentation-prompts.json`：程序生成的 SAM 候选提示；模型原始正负点不会传入；
- `validation.json`：本地结构校验结果；
- `manifest.json`：模型、输入、代码版本和产物记录。
输入保留画布尺寸。已有透明背景直接保留 Alpha；不透明白底只移除与边界连通的近白区域。其他背景需先提供抠图 PNG。候选来自粗框内前景的距离变换，不能保证属于目标部件，仍需语义复核。关节点不会吸附到前景。
已有结果可离线检查，无需再次请求模型：
### 第二阶段：本地 SAM 分割
```powershell
node .\tools\model-check.mjs `
--reference .\output\sombrero-understand-deepseek-flash\source.png `
--parts-file .\output\sombrero-understand-deepseek-flash\semantic-parts.json `
--out-dir .\output\sombrero-grounding-review
```
旧版 v1 计划会保守迁移到 v2，迁移推断写入 notes，仍需复核；原文件不覆盖。
### 使用 GPT-6 Astra 做对照实验
```powershell
node .\pipeline.mjs --mode annotated-parts `
--config .\configs\astra-qwen.json `
--reference ..\spine-animation-ai\demo\character_reference.png `
--out-dir .\output\sombrero-understand-astra `
--stop-after understand
```
当前中转站的 Astra 通道要求 Responses 协议和流式响应。若中转站返回 overloaded，应使用新的输出目录稍后重试。
### 临时覆盖理解模型
```powershell
node .\pipeline.mjs --mode annotated-parts `
--config .\configs\deepseek-qwen.json `
--understanding-model YOUR_EXACT_MODEL_ID `
--understanding-protocol chat-completions `
--stream false `
--reference .\reference.png `
--out-dir .\output\model-experiment `
--stop-after understand
```
每组模型实验应使用独立的输出目录，避免覆盖对照结果。只有输入、配置、代码和产物哈希全部一致时，才可以通过 `--resume` 复用结果。
### 使用本地 SAM 生成标注和拆解图
复用已有第一阶段结果，不重新请求 DeepSeek，也不需要中转站密钥：
```powershell
conda run --no-capture-output -n ai-spine node .\tools\model-check.mjs `
--stage segmentation `
--input-dir .\output\sombrero-grounding-v2 `
--out-dir .\output\sombrero-sam-local `
node .\tools\model-check.mjs --stage segmentation `
--input-dir "$runRoot\understand" `
--out-dir "$runRoot\sam" `
--sam-dir F:/Study/SAM3
```
打开输出目录的 `report.html`：`annotated.png` 是原图上的不同半透明颜色标注，`parts-sheet.png` 是白底拆解图，`parts/` 保存原像素透明部件。运行期间加载 GPU 权重，完成后子进程退出，不启动常驻服务。
若使用前面的离线计划，input-dir 改为 understand-offline。该命令只运行本地临时 GPU 子进程；添加 `--dry-run` 可探测环境而不加载模型。检查 `sam/report.html`、`annotated.png`、`parts-sheet.png`、漏分图和 mask 归属，错误部件应先修正。
加入 `--dry-run` 可检查环境与本地路径，不加载权重推理。输入必须含 `source.png`、v2 `semantic-parts.json`、`segmentation-prompts.json`。完整参数与质量检查见[第二阶段文档](docs/2-segmentation-stage.md)。
### 第三阶段：准备与补全
### 第三阶段：按部件补全
先从已有 SAM 输出准备画布、允许新增区域和提示词，不请求模型：
先离线准备任务，不请求模型：
```powershell
node .\tools\model-check.mjs --stage completion `
--input-dir .\output\sombrero-sam31-v3 `
--out-dir .\output\sombrero-completion-prepare `
--completion-model qwen-image-3.0 `
--config .\configs\tiantoken.json `
--input-dir "$runRoot\sam" `
--out-dir "$runRoot\complete-prepare" `
--prepare-only
```
打开 `report.html` 检查部件和允许新增区域。以下命令对 `head` 发起一次部件编辑任务，再检查候选并恢复原图可见像素；会调用中转站图片模型：
复核允许区域后，按实际存在的 ID 试一个部件；下面会调用图片模型：
```powershell
node .\tools\model-check.mjs --stage completion `
--input-dir .\output\sombrero-sam31-v3 `
--out-dir .\output\sombrero-completion-head `
--completion-model qwen-image-3.0 `
--config .\configs\tiantoken.json `
--input-dir "$runRoot\sam" `
--out-dir "$runRoot\complete-head" `
--part head
```
`--part` 可重复；省略则处理所有具备可见 mask、补全需求和允许区域的部件。当前 SAM 示例仍有错分，应先复核。补全不会自动纠正上游语义；通过几何检查的 PNG 保存到 `parts/`，仍需人工复核。完整参数、离线候选导入与限制见[第三阶段文档](docs/3-completion-stage.md)。
第三阶段请求会显式发送与局部画布一致的 `size`（默认 `1024x1024`）。如果中转站仍返回其他尺寸，可使用 `--candidates-dir 旧补全目录 --candidate-size-policy uniform` 离线复查：只允许同宽高比的画布等比例缩放，保留原候选，继续检查位置与新增区域并恢复原像素。默认 strict 模式仍拒绝尺寸不符；详细命令见第三阶段文档。
### 单独测试图片补全接口
此命令只验证图片编辑适配器并保存原始候选，不代表补全部件已经验收通过：
处理所有具备可见 mask、补全需求和允许区域的部件：
```powershell
node .\tools\model-check.mjs --stage completion `
--image .\local-part.png `
--prompt-file .\task.txt `
--out-dir .\output\qwen-edit-test `
--completion-model qwen-image-3.0
--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 ..\spine-animation-ai\demo\character_reference.png `
--out-dir .\output\legacy-character `
--reference $reference `
--out-dir "$runRoot\legacy" `
--genielabs-dir ..\spine-animation-ai `
--image-model qwen-image-3.0 `
--attempts 1 `
--animations idle,walk,wave
```
旧流程依赖生成式拆件与传统 CV 定位，对低纹理、低分辨率和生成后外观变化较大的角色不稳定。其输出应通过 `assembled.png` 和 `preview-rigged.html` 人工检查后再导入 Spine。
`segment.py` 为旧版拆件分割，`compose_preview.py` 组装预览，`run_case_matrix.py` 对照定位方案；当前 SAM 入口为 sam_segment.py。旧产物需检查 assembled.png 和 preview-rigged.html，不能据此声称新三阶段已经完成 Spine 导出。
### 运行测试
测试与命令帮助：
```powershell
conda run -n ai-spine npm test
conda run --no-capture-output -n ai-spine npm test
node .\tools\model-check.mjs --help
```
测试使用本地 mock HTTP 服务或注入响应，不调用真实付费模型。
测试使用本地 mock 或注入响应，不请求真实付费模型。自动化运行任一阶段可用 `conda run --no-capture-output -n ai-spine node ...`。保留旧实验；resume 只复用完整匹配产物，失败任务另建输出目录。