文档整理
This commit is contained in:
Ukawka
@@ -1,73 +1,174 @@
|
||||
# Genarrative / Genielabs Spine Animation Pipeline
|
||||
# AI Spine 角色拆件与动画管线
|
||||
|
||||
## 新增：可替换模型与角色结构理解
|
||||
本项目用于把单张 2D 角色参考图转换为可供 Spine 动画使用的语义部件、透明拆件和骨骼资源。
|
||||
|
||||
已新增 `--mode annotated-parts`，默认 GPT6Astra 做结构理解，Qwen Image 3.0 作为独立图片编辑适配器。模型、协议和提示词可分别配置；第一阶段输出 JSON、粗标注 SVG 和检查报告。SAM 分割与补全合并尚未接入。
|
||||
当前正在实现的新管线分为三个核心阶段：
|
||||
|
||||
1. 视觉 LLM 理解角色结构，输出部件语义、层级、遮挡关系、粗框和分割提示点。
|
||||
2. 使用 SAM 根据提示点生成精确 mask，并从原图提取可见像素。
|
||||
3. 使用图片编辑模型补全被遮挡的部件，再进行几何验收和 Spine 导出。
|
||||
|
||||
目前第一阶段已经可以完整运行。SAM 3.1 checkpoint 路径和图片编辑适配器已经接入配置，但 SAM 推理、补全结果合并及新管线的 Spine 导出尚未完成。
|
||||
|
||||
仓库仍保留旧版“AI 生成白底拆件图 → OpenCV 拆分 → Genielabs 定位 → Spine 导出”流程，用于对照和回归测试。
|
||||
|
||||
## 文档
|
||||
|
||||
- [第一阶段：视觉 LLM 角色结构理解](docs/1-understanding-stage.md)：执行流程、代码对应关系、数据格式和输出文件。
|
||||
- [模型阶段配置与实验说明](docs/model-stages.md)：模型切换、协议适配、图片编辑探针、缓存和错误处理。
|
||||
|
||||
## 环境准备
|
||||
|
||||
### Node.js
|
||||
|
||||
第一阶段要求 Node.js 20 或更高版本，不需要 Python，也没有额外 npm 运行时依赖。
|
||||
|
||||
```powershell
|
||||
node .\pipeline.mjs --mode annotated-parts --reference ..\spine-animation-ai\demo\character_reference.png --out-dir .\output\sombrero-astra --stop-after understand
|
||||
node --version
|
||||
npm test
|
||||
```
|
||||
|
||||
完整配置、模型切换、独立图片编辑测试和产物说明见 [docs/model-stages.md](docs/model-stages.md)。以下为旧版拆件管线的说明。
|
||||
### 中转站配置
|
||||
|
||||
这是独立目录，不修改 Genarrative。它只参考 Genarrative 的 VectorEngine 图片生成协议：后端环境变量提供 `VECTOR_ENGINE_BASE_URL` 与 `VECTOR_ENGINE_API_KEY`，使用 OpenAI-compatible `POST /v1/images/edits` multipart 请求。
|
||||
在项目目录复制环境变量模板：
|
||||
|
||||
模型 ID 原样传给中转站，不再进行隐式映射。可通过 `node tools/model-check.mjs --list-models` 查询当前服务实际列出的 ID。
|
||||
```powershell
|
||||
Copy-Item .\.env.example .\.env
|
||||
```
|
||||
|
||||
拆件提示词明确要求保留参考图的原始姿态、左右方向、遮挡关系和非对称结构，禁止镜像、拉直和生成对称备件。图片接口对 429/5xx 会自动重试 3 次；使用新输出目录即可重新生成，旧目录可用 `--resume` 复用已生成的拆件图。
|
||||
编辑 `.env`：
|
||||
|
||||
正式运行默认尝试 3 个通用拆件提示词变体，分别按“严格姿态保持”“Spine 生产拆件”“技术 ground truth”描述同一要求；脚本按前景部件数量选择最接近完整角色的一份。可用 `--attempts 1` 关闭多候选尝试。
|
||||
```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
|
||||
|
||||
```bash
|
||||
node pipeline.mjs \
|
||||
--reference /absolute/path/character.png \
|
||||
--out-dir ./output/character-spine \
|
||||
--genielabs-dir /absolute/path/spine-animation-ai \
|
||||
--env-file /absolute/path/.env \
|
||||
--image-model qwen-image-3.0 \
|
||||
# 当前只记录 checkpoint；SAM 推理尚未接入
|
||||
SAM_MODEL_DIR=F:/Study/sam3.1
|
||||
```
|
||||
|
||||
模型 ID 会原样发送给中转站，不进行隐式别名转换。不要把 API Key 写进 JSON 配置或提交到版本库。
|
||||
|
||||
### Python 与外部项目
|
||||
|
||||
运行第一阶段不需要 Python。
|
||||
|
||||
只有旧版拆件和 Spine 导出流程需要：
|
||||
|
||||
- Python 3；
|
||||
- `Pillow`、`numpy`、`opencv-python`；
|
||||
- 相邻目录中的 `spine-animation-ai` 项目。
|
||||
|
||||
安装旧流程依赖：
|
||||
|
||||
```powershell
|
||||
python -m venv .venv
|
||||
.\.venv\Scripts\Activate.ps1
|
||||
python -m pip install -r .\requirements.txt
|
||||
```
|
||||
|
||||
`spine-animation-ai` 是外部只读依赖，使用时需要遵守其 PolyForm Noncommercial 许可证。
|
||||
|
||||
## 常用命令
|
||||
|
||||
以下命令默认在 `AI_spine` 目录运行。
|
||||
|
||||
### 查询中转站模型
|
||||
|
||||
```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`：后续 SAM 阶段的正式输入；
|
||||
- `validation.json`：本地结构校验结果；
|
||||
- `manifest.json`：模型、输入、代码版本和产物记录。
|
||||
|
||||
### 使用 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。
|
||||
|
||||
1. VectorEngine 图片编辑，生成白底拆件工作图；
|
||||
2. OpenCV 连通域拆件，输出透明部件 PNG；
|
||||
3. 默认调用 Genielabs `position_parts.py`，使用 SIFT/RANSAC、模板匹配回退和 z-order 计算把部件放回参考图；只有显式传入 `--layout-mode anchored` 才启用按画布锚点的保守回退；
|
||||
4. 生成 Spine 配置并运行 `build_spine_json.py`；
|
||||
5. 运行 `make_atlas.py` 和 `generate_spine_player.py`。
|
||||
### 运行测试
|
||||
|
||||
为避免“部件爆炸”，定位后默认只保留 SIFT 高置信部件和模板匹配分数不低于 `0.3` 的部件，最多保留 18 个；可用 `--min-score`、`--max-parts` 调整。若模型仍输出多套角色，先删除输出目录重新生成，不要直接把低质量拆件导入 Spine。
|
||||
|
||||
`matched` 依赖拆件图与参考图保持相同画风和可辨识纹理；低纹理部件会进入模板匹配回退，并进行白底归一化以避免透明像素产生 `NaN/inf`。`anchored` 只按拆件图的行布局做通用兜底，不应作为正式定位结果。
|
||||
|
||||
旧流程的 Python 环境默认探测 `python`、`python3` 和项目 `.venv`；显式 `--python` 时只使用指定环境。要求导入 `cv2`、`PIL`、`numpy`。自动创建虚拟环境时区分 Windows 的 `Scripts/python.exe` 和 Unix 的 `bin/python`。新增的结构理解模式不需要 Python。
|
||||
|
||||
脚本默认只读取本目录 `.env` 和当前 shell 环境，不会自动读取 Genarrative 的 secrets 文件。可以通过 `--env-file` 显式指定一个只在受控后端使用的环境文件。
|
||||
|
||||
输出目录包含 `generated-parts-sheet.png`、`parts/`、`layout.json`、`assembled.png`、`skeleton.json`、`atlas/`、`preview.html` 和 `manifest.json`。`assembled.png` 是按同一 layout 坐标生成的静态 QA 合成图；自动结果是 region attachments，mesh、weights、IK、FFD 和骨骼语义仍需在 Spine 4.2 中校正。
|
||||
|
||||
`preview.html` 现在显示参考图的真实姿态，适合确认形体是否正常；自动拆件结果放在 `preview-rigged.html`。这是因为参考图可能是左右不对称动作，不能用对称锚点强行还原，否则会出现手臂漂浮或错接。
|
||||
|
||||
## 离线多 case 回归
|
||||
|
||||
`run_case_matrix.py` 可以复用已经生成的多个拆件候选，不调用图片 API，只测试 Genielabs 定位和合成：
|
||||
|
||||
```bash
|
||||
python run_case_matrix.py \
|
||||
--reference output/demo-character-final/source.png \
|
||||
--genielabs-dir /absolute/path/spine-animation-ai \
|
||||
--out-dir output/cases-matrix \
|
||||
--candidate final output/demo-character-final/parts \
|
||||
--candidate attempt1 output/demo-character-multi/candidates/attempt-1/parts \
|
||||
--candidate attempt2 output/demo-character-multi/candidates/attempt-2/parts
|
||||
```powershell
|
||||
npm test
|
||||
```
|
||||
|
||||
每个 case 会输出 `layout.json`、`assembled.png` 和 `case-summary.json`，总报告为 `case-report.json`。当前回归中，`final`/`matched` 保留 9 个有效部件，前景 MAE 约 17.68；`attempt1` 只有 7 个部件且出现手臂误拆，MAE 30.28；`attempt2` 有 15 个部件但包含重复/漂浮部件，MAE 27.59。默认候选选择和重叠过滤会优先保留 `final`/`matched` 这类结果。
|
||||
|
||||
Genielabs 以外部只读目录引用，需遵守其 PolyForm Noncommercial 许可证。生产集成时应把输出上传对象存储，只向前端返回 object key 或 asset object id。
|
||||
|
||||
## 外部参考角色
|
||||
|
||||
已下载 5 个 Kenney CC0 参考素材到 `references/characters/`，可直接作为下一轮图片拆件的 `--reference` 输入；来源、许可证和 SHA-256 见 [references/index.json](references/index.json)，原始包及许可证文件见 `references/external/`。缩略图对比见 [references/characters/contact-sheet.jpg](references/characters/contact-sheet.jpg)。
|
||||
测试使用本地 mock HTTP 服务或注入响应，不调用真实付费模型。
|
||||
|
||||
Reference in New Issue
Block a user