Ukawka
204 lines
7.2 KiB
Markdown
204 lines
7.2 KiB
Markdown
# AI Spine 角色拆件与动画管线
|
||
|
||
本项目用于把单张 2D 角色参考图转换为可供 Spine 动画使用的语义部件、透明拆件和骨骼资源。
|
||
|
||
当前正在实现的新管线分为三个核心阶段：
|
||
|
||
1. 视觉 LLM 输出语义、层级、骨骼/附件分类、遮挡、粗框和粗关节；程序用 Alpha 检查 ROI 并生成候选种子。
|
||
2. 使用 SAM 根据语义、粗框和程序候选生成 mask，经语义/几何检查后从原图提取可见像素。
|
||
3. 使用图片编辑模型补全被遮挡的部件，再进行几何验收和 Spine 导出。
|
||
|
||
目前第一阶段已经可以完整运行。SAM 3.1 checkpoint 路径和图片编辑适配器已经接入配置，但 SAM 推理、补全结果合并及新管线的 Spine 导出尚未完成。
|
||
|
||
仓库仍保留旧版“AI 生成白底拆件图 → OpenCV 拆分 → Genielabs 定位 → Spine 导出”流程，用于对照和回归测试。
|
||
|
||
## 文档
|
||
|
||
- [项目修改约定](AGENTS.md)：每次修改都必须遵守，Python 固定使用 `ai-spine` Conda 环境。
|
||
- [第一阶段：视觉 LLM 角色结构理解](docs/1-understanding-stage.md)：执行流程、代码对应关系、数据格式和输出文件。
|
||
- [模型阶段配置与实验说明](docs/model-stages.md)：模型切换、协议适配、图片编辑探针、缓存和错误处理。
|
||
|
||
## 环境准备
|
||
|
||
### Node.js
|
||
|
||
第一阶段要求 Node.js 20 或更高版本，以及下方 Python 几何依赖；没有额外 npm 运行时依赖。
|
||
|
||
```powershell
|
||
node --version
|
||
conda run -n ai-spine npm test
|
||
```
|
||
|
||
### 中转站配置
|
||
|
||
在项目目录复制环境变量模板：
|
||
|
||
```powershell
|
||
Copy-Item .\.env.example .\.env
|
||
```
|
||
|
||
编辑 `.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
|
||
|
||
# 当前只记录 checkpoint；SAM 推理尚未接入
|
||
SAM_MODEL_DIR=F:/Study/sam3.1
|
||
```
|
||
|
||
模型 ID 会原样发送给中转站，不进行隐式别名转换。不要把 API Key 写进 JSON 配置或提交到版本库。
|
||
|
||
### 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` 项目。
|
||
|
||
在 `AI_spine` 目录安装缺失的 Python 依赖（已满足版本要求的包会保留）：
|
||
|
||
```powershell
|
||
conda activate ai-spine
|
||
python -m pip install -r .\requirements.txt
|
||
```
|
||
|
||
不激活终端也可明确指定安装目标：
|
||
|
||
```powershell
|
||
conda run -n ai-spine python -m pip install -r .\requirements.txt
|
||
```
|
||
|
||
检查解释器和依赖：
|
||
|
||
```powershell
|
||
conda run -n ai-spine python -c "import sys, cv2, PIL, numpy; print(sys.executable); print('Dependencies OK')"
|
||
```
|
||
|
||
`spine-animation-ai` 是外部只读依赖，使用时需要遵守其 PolyForm Noncommercial 许可证。
|
||
|
||
## 常用命令
|
||
|
||
以下命令默认在 `AI_spine` 目录、已激活的 `ai-spine` Conda 环境中运行。自动化可使用 `conda run -n ai-spine node ...`。
|
||
|
||
### 查询中转站模型
|
||
|
||
```powershell
|
||
node .\tools\model-check.mjs --list-models
|
||
```
|
||
|
||
### 检查本地配置
|
||
|
||
不请求模型，也不生成付费内容：
|
||
|
||
```powershell
|
||
node .\pipeline.mjs --mode annotated-parts `
|
||
--config .\configs\deepseek-qwen.json `
|
||
--reference ..\spine-animation-ai\demo\character_reference.png `
|
||
--dry-run
|
||
```
|
||
|
||
### 使用 DeepSeek Flash 理解角色结构
|
||
|
||
当前已验证可用的配置是 `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
|
||
```
|
||
|
||
重点检查输出目录中的：
|
||
|
||
- `report.html`：人工复核页面；
|
||
- `semantic-parts.json`：v2 语义计划，包含 `rig_role`、`bind_to`、三项 `completion`；
|
||
- `geometry-validation.json`：原始点诊断、框内前景比例、候选及阻塞原因；
|
||
- `segmentation-prompts.json`：程序生成的 SAM 候选提示；模型原始正负点不会传入；
|
||
- `validation.json`：本地结构校验结果；
|
||
- `manifest.json`：模型、输入、代码版本和产物记录。
|
||
|
||
输入保留画布尺寸。已有透明背景直接保留 Alpha；不透明白底只移除与边界连通的近白区域。其他背景需先提供抠图 PNG。候选来自粗框内前景的距离变换，不能保证属于目标部件，仍需语义复核。关节点不会吸附到前景。
|
||
|
||
已有结果可离线检查，无需再次请求模型：
|
||
|
||
```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` 复用结果。
|
||
|
||
### 测试图片补全接口
|
||
|
||
此命令只验证图片编辑适配器并保存原始候选，不代表补全部件已经验收通过：
|
||
|
||
```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
|
||
```
|
||
|
||
### 运行旧版完整管线
|
||
|
||
```powershell
|
||
node .\pipeline.mjs `
|
||
--reference ..\spine-animation-ai\demo\character_reference.png `
|
||
--out-dir .\output\legacy-character `
|
||
--genielabs-dir ..\spine-animation-ai `
|
||
--image-model qwen-image-3.0 `
|
||
--attempts 1 `
|
||
--animations idle,walk,wave
|
||
```
|
||
|
||
旧流程依赖生成式拆件与传统 CV 定位，对低纹理、低分辨率和生成后外观变化较大的角色不稳定。其输出应通过 `assembled.png` 和 `preview-rigged.html` 人工检查后再导入 Spine。
|
||
|
||
### 运行测试
|
||
|
||
```powershell
|
||
conda run -n ai-spine npm test
|
||
```
|
||
|
||
测试使用本地 mock HTTP 服务或注入响应，不调用真实付费模型。
|