这是独立目录，不修改 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。

拆件提示词明确要求保留参考图的原始姿态、左右方向、遮挡关系和非对称结构，禁止镜像、拉直和生成对称备件。图片接口对 429/5xx 会自动重试 3 次；使用新输出目录即可重新生成，旧目录可用 --resume 复用已生成的拆件图。

正式运行默认尝试 3 个通用拆件提示词变体，分别按“严格姿态保持”“Spine 生产拆件”“技术 ground truth”描述同一要求；脚本按前景部件数量选择最接近完整角色的一份。可用 --attempts 1 关闭多候选尝试。

运行

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

脚本会依次执行：

VectorEngine 图片编辑，生成白底拆件工作图；
OpenCV 连通域拆件，输出透明部件 PNG；
默认调用 Genielabs position_parts.py，使用 SIFT/RANSAC、模板匹配回退和 z-order 计算把部件放回参考图；只有显式传入 --layout-mode anchored 才启用按画布锚点的保守回退；
生成 Spine 配置并运行 build_spine_json.py；
运行 make_atlas.py 和 generate_spine_player.py。

为避免“部件爆炸”，定位后默认只保留 SIFT 高置信部件和模板匹配分数不低于 0.3 的部件，最多保留 18 个；可用 --min-score、--max-parts 调整。若模型仍输出多套角色，先删除输出目录重新生成，不要直接把低质量拆件导入 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 定位和合成：

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/external/。缩略图对比见 references/characters/contact-sheet.jpg。

README.md Unescape Escape

Genarrative / Genielabs Spine Animation Pipeline

运行

离线多 case 回归

外部参考角色

README.md