94 lines
7.5 KiB
Markdown
94 lines
7.5 KiB
Markdown
# Genarrative / Genielabs Spine Animation Pipeline
|
||
|
||
这是独立目录，不修改 Genarrative。它只参考 Genarrative 的 VectorEngine 图片生成协议：后端环境变量提供 `VECTOR_ENGINE_BASE_URL` 与 `VECTOR_ENGINE_API_KEY`，使用 OpenAI-compatible `POST /v1/images/edits` multipart 请求。
|
||
|
||
当前上游没有 `gpt-image-2.5`，脚本会把它映射为 `gpt-image-2`，并在 manifest 中保留 `requestedModel`。
|
||
|
||
拆件提示词是角色无关的通用模板：以参考图为唯一 ground truth，保留原始注册位置、左右方向、遮挡关系和非对称结构，只在自然关节/遮挡边界切分，禁止镜像、拉直、补全隐藏部件和生成重复备件。图片接口对 429/5xx 会自动重试 3 次；使用新输出目录即可重新生成，旧目录可用 `--resume` 复用已生成的拆件图。
|
||
|
||
正式运行默认尝试 6 个通用拆件提示词变体，分别强调注册位置、关节边界、遮挡审计、保守拆分和像素保真；脚本按微碎片、巨型粘连、前景覆盖率和极端部件数量选择候选，不假定角色必须有固定部件数。可用 `--attempts 1` 只运行一个候选。
|
||
|
||
## 运行
|
||
|
||
```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 gpt-image-2.5 \
|
||
--animations idle,walk,wave
|
||
```
|
||
|
||
脚本会依次执行：
|
||
|
||
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` 的部件，最多保留 28 个；可用 `--min-score`、`--max-parts` 调整。多候选选择还会比较 Genielabs 定位置信度和部件框重叠，降低重复角色层被选中的概率。若模型仍输出多套角色，先删除输出目录重新生成，不要直接把低质量拆件导入 Spine。
|
||
|
||
`matched` 依赖拆件图与参考图保持相同画风和可辨识纹理；低纹理部件会进入模板匹配回退，并进行白底归一化以避免透明像素产生 `NaN/inf`。`anchored` 只按拆件图的行布局做通用兜底，不应作为正式定位结果。
|
||
|
||
Python 环境探测顺序为显式 `--python`、Anaconda、Homebrew Python、系统 Python；要求导入 `cv2`、`PIL`、`numpy`。如果全部不可用，脚本会在本目录创建 `.venv` 并安装 `requirements.txt`。
|
||
|
||
脚本默认只读取本目录 `.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
|
||
```
|
||
|
||
每个 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)。
|
||
|
||
另外新增了高分辨率单角色回归素材，位于 `references/highres-characters/`。其中 `tiddybub-toon/crops-768/` 包含 6 个 768×1024、透明背景、CC0 的 Kenney Toon Characters 单角色图，适合测试头发、手臂、手、腿、鞋和机器人关节等不同结构。
|
||
|
||
## GPT Image 2 prompt 优化回归
|
||
|
||
已对原始 sombrero/cowboy 参考图执行 6 个通用 prompt 变体（每个变体一次请求），并对 6 个高分辨率角色执行最多 3 个候选：female-adventurer、male-adventurer、female-person、male-person、robot、zombie。所有 prompt 都不包含角色名称、左右手硬编码或单个案例的外观描述；候选只由参考图的像素、姿态、遮挡和非对称关系决定。
|
||
|
||
当前离线复评结果保存在被忽略的 `output/prompt-optimization/`：
|
||
|
||
| 参考角色 | 选中候选 | 拆件数 | 定位方式 | 备注 |
|
||
| --- | --- | ---: | --- | --- |
|
||
| cowboy | attempt-4 | 8 | 8 个 SIFT | 当前最佳；平均定位 0.793，重叠惩罚 0 |
|
||
| female-adventurer | attempt-3 | 16 | 2 个 SIFT + 模板回退 | 形体基本完整，仍需检查衣服和手套层 |
|
||
| male-adventurer | attempt-2 | 14 | 1 个 SIFT + 模板回退 | 可用作回归输入，细部依赖模板定位 |
|
||
| male-person | attempt-2 | 17 | 4 个 SIFT + 模板回退 | 需要检查头发、脸和躯干的层级 |
|
||
| robot | attempt-2 | 17 | 5 个 SIFT + 模板回退 | 机械关节拆分较清楚，部分小件会漂浮 |
|
||
| zombie | attempt-2 | 11 | 模板回退 | 仍有明显错层，不能视为通过 |
|
||
| female-person | attempt-1 | 21 | 3 个 SIFT + 模板回退 | 检测到完整人物副本风险，不能直接采用 |
|
||
|
||
综合对照图为 `output/prompt-optimization/reselection-contact-sheet.jpg`，机器报告为 `output/prompt-optimization/reselection-report.json`。这些评分用于缩小人工复核范围，不代表自动通过，也不会把完整人物副本误选为拆件。
|
||
|
||
如需在不调用图片 API 的情况下重新评估已有候选，可运行：
|
||
|
||
```bash
|
||
python reselect_candidates.py \
|
||
--out-root output/prompt-optimization \
|
||
--genielabs-dir /absolute/path/spine-animation-ai
|
||
```
|
||
|
||
本轮新的 GPT Image 请求在 female-person、robot 和 zombie 的后续尝试中收到 VectorEngine `403 user quota is not enough`，因此没有继续重试或伪造新结果。补充额度后，可直接用同一组 `prompts/v2-tested.json` 和 `--attempts 6` 继续 A/B 测试。
|