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-22 01:02:21 +08:00
parent e9072aecf2
commit 8080d52a99
10 changed files with 960 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/3-completion-stage.md
+3 -3
View File
@@ -4,7 +4,7 @@
读取 SAM 可见 mask，为需要遮挡补全或关节延伸的部件准备局部画布，调用中转站图片编辑模型，再将允许区域内的新增像素与原可见像素合并。Python 几何处理固定使用 Conda `ai-spine`；图片生成在远端完成，本阶段不加载本地 SAM。
当前已实现准备、真实图片请求、离线候选导入、几何检查与透明补全部件输出。尚未输出使用补全部件组装的完整角色，尚未接入新管线 Spine 导出。几何通过仍为 `needs_review`，不能等同于部件可用。
当前已实现准备、真实图片请求、离线候选导入、几何检查与透明补全部件输出。[第四阶段](4-spine-stage.md) 独立整合 SAM 与补全部件，输出完整角色组装、Spine 骨架和预览。几何通过仍为 `needs_review`，不能等同于部件可用。
## 2. 输入、输出与执行链路
@@ -179,13 +179,13 @@ node .\tools\model-check.mjs --stage completion `
| `completion-result.json` | 每部件状态、候选 QA、原图 crop_xyxy 和路径 |
| `report.html` / `manifest.json` | 人工检查页 / 模式、网络标记、状态、输入/代码/产物哈希 |
parts/ 只含本次选中且通过检查的补全部件，不是全部 SAM 部件集合。无需补全、失败和未选中的部件不会自动复制进来，也没有完整角色组装图。
parts/ 只含本次选中且通过检查的补全部件，不是全部 SAM 部件集合。无需补全、失败和未选中的部件不会自动复制进来；完整角色组装由第四阶段读取 SAM 与本目录后生成。
当前实验：`output/20260918-183532/complete2_gpt` 已真实请求 Tiantoken gpt-image-2 共 12 个部件。旧请求未传 size，返回 1248/1254 方形图，预期为 1024，全部严格尺寸拒绝。`complete2_gpt-size-recheck-v2` 离线复用原候选后，8 个几何通过；head、pants_thigh_l、pants_thigh_r、shoe_l 共 4 个因对齐或无有效新增拒绝。通过项中仍有衣料误分、错误手部和未补全子区域。显式 size 的请求构造已验证，但尚无修复后中转遵守 size 的新实测结论。
## 8. 当前阶段可改进点说明
- **补全后输出使用补全部件的完整角色。** 按原图坐标和遮挡顺序组装，复用无需补全的原拆件，明确标记失败项及回退来源；输出补全前后对比、接缝/重叠诊断。不能只展示少数 parts 文件作为完整结果。
- **完整角色组装已接入第四阶段。** 按原坐标与遮挡约束组装，复用原拆件并记录失败回退，输出补全前后对比、覆盖与重叠诊断及单骨骼旋转检查动画。可靠的接缝与运动质量自动验收仍待实现。
- **把原图或部件相关原图区域交给补全模型参考。** 接入并实测全角色/局部上下文参考和编辑 mask，记录实际发送内容。不能仅把 capabilities 改为 true 就宣称中转支持；需验证图片顺序、mask 语义、返回尺寸和画面保持能力。
- **根据 SAM 实际结果重建需求。** 区分分割缺口修复、遮挡补全、关节延伸、附件底图清理；对应建立保留区域与可编辑区域，避免误分像素被永久保护。
- **改进画布与补全区域。** 固定 32 像素不适配所有部件；小部件在 1024 大白底中占比低。可验证按部件设计区域、显式局部放大并记录逆变换，保证回贴坐标可检查。
docs/4-spine-stage.md
+128
View File
@@ -0,0 +1,128 @@
# 第四阶段：角色组装与 Spine 导出
## 1. 阶段简介
将第二阶段的可见部件与第三阶段通过几何检查的补全部件整合，按原图坐标组装，并依据 v2 语义计划生成 Spine 4.2 骨架、region 附件、图集及预览。所有部件名称、数量、骨骼父子关系和附件绑定来自输入，不使用角色名称或人形比例模板。
生成过程完全离线，不调用图片模型、不运行 SAM。骨架预览页面嵌入资产，但会从 CDN 加载 Spine Player 4.2，打开播放器需要网络。静态报告与 PNG 可离线查看。
导出完成仍标记 `quality_status=needs_review`。当前只有 setup 与单骨骼旋转检查动画；没有成品 idle/walk，也没有 mesh、权重或 IK。关节、语义、接缝及运动质量需人工复核。
## 2. 输入、输出与执行链路
```text
SAM 目录 + 可选补全目录 + 可选绘制顺序覆盖
→ 校验 v2 计划与骨骼关系
→ 对比两阶段 source / 计划 / segmentation / masks 的 SHA-256
→ 合并部件：已选补全 / 原 SAM 像素 / 隐藏无纹理节点
→ 根据遮挡约束稳定拓扑排序，记录没有约束的重叠
→ 按 crop_xyxy 组装，输出来源与覆盖诊断
→ 根据 parent / bind_to / pivot_norm 创建骨架与附件
→ 生成 skeleton.json、图集、播放器、报告与 manifest
```
SAM 原部件直接由 source + mask 重建，保持 RGB/Alpha 和原坐标；无需依赖 SAM 的紧裁剪 parts/。补全部件使用 `completion-result.json` 中选中结果的 `image` 和 `crop_xyxy`，同时检查尺寸及可见 RGBA 是否保持不变。
## 3. 阶段执行命令示例及参数说明
在项目根目录运行；环境统一为 Conda `ai-spine`。以下路径仅是现有输入示例，换角色时替换输入目录，不修改代码。输出目录每次独立。
```powershell
Set-Location F:\Study\taonier\AI_spine
conda activate ai-spine
$samDir = '.\output\20260920-225137\sam'
$completionDir = '.\output\20260920-225137\complete'
$spineOut = '.\output\spine-' + (Get-Date -Format 'yyyyMMdd-HHmmss')
node .\tools\model-check.mjs --stage spine `
--input-dir $samDir `
--completion-dir $completionDir `
--out-dir $spineOut
Start-Process "$spineOut\report.html"
```
| 参数 | 含义 |
| --- | --- |
| `--input-dir DIR` | 必需，SAM 输出目录 |
| `--completion-dir DIR` | 可选，同批输入的补全输出；省略则使用 SAM 资产 |
| `--out-dir DIR` | 独立输出目录；dry-run 时可省略 |
| `--fallback-policy sam/error` | 默认 sam；需要补全但没有通过结果时回退可见像素并记录原因。error 则终止 |
| `--draw-order-file FILE` | JSON 对象，`draw_order` 包含所有可绘制 ID，按从后到前排列，各出现一次 |
| `--check-angle FLOAT` | 单骨骼检查动画正负角度，默认 10，范围 (0,45] |
| `--genielabs-dir DIR` | 默认相邻 `spine-animation-ai`；复用其图集和播放器脚本，保留 PolyForm Noncommercial 约束 |
| `--python FILE` | 仅允许 ai-spine 解释器 |
| `--dry-run` | 完整检查输入、PNG、坐标及依赖脚本，不写输出，不联网 |
| `--resume` | 仅复用输入、参数、代码与产物哈希全部匹配的完整运行 |
该阶段不读取模型配置与密钥，也不接受 `--config`、模型参数或补全请求参数。自动化可用 `conda run --no-capture-output -n ai-spine node ...`。
可选 runtime 复检：将已有的官方 Spine 4.2 core IIFE 文件路径赋给 `$runtimeFile`，执行以下命令。工具不下载或安装依赖；检查图集尺寸、静态附件顶点和正负旋转下的后代跟随，不验证浏览器 WebGL 渲染。
```powershell
$runtimeFile = '.\output\spine-runtime-validation-20260922\spine-core.js'
conda run -n ai-spine node .\tools\verify-spine-runtime.mjs `
--runtime-file $runtimeFile --input-dir $spineOut
```
## 4. 输入格式要求
SAM 目录需含 `source.png`、有效 v2 `semantic-parts.json`、`segmentation.json`、其中记录的全画布二值 masks。可见部件缺少 mask 直接报错；hidden 不得有可见 mask。
补全目录需含相同输入快照、对应 masks 和 `completion-result.json`。只有 `selected_file` 非空、`qa.accepted=true` 且 `status=geometry_passed_needs_review` 的结果会被采用；其 `image` 文件必须存在，裁剪坐标为原画布内的整数半开区间，尺寸与 PNG 一致，可见像素必须逐像素匹配 SAM 源图。输入哈希不一致时拒绝混用。图片路径必须位于相应输入目录内。
补全失败、未处理、未提供或 `NO_ALLOWED_EXTENSION` 的需补全部件遵守 fallback-policy。hidden 保留语义骨骼但不生成纹理，也不因缺纹理触发严格回退错误。
可选绘制顺序文件格式为 `{"draw_order":["部件ID一","部件ID二"]}`。必须列出本次全部可绘制部件，不包含 hidden。显式顺序允许覆盖模型遮挡关系，冲突会在报告中列出。
## 5. 执行链路中重要部分代码文件及原理说明（包括重点说明）
**资产整合。** 按 ID 合并，保留来源、跳过或拒绝原因、补全 QA 与上游告警。通过几何检查的补全仍是待复核资产，失败结果不会当作补全成功使用。缺少图片或非法坐标不会被静默回退掩盖。
**位置与骨骼。** 图像坐标原点为左上角，Spine 原点设为原画布底边中点：`X=x-W/2`，`Y=H-y`。pivot 使用连续坐标 `x=pivot_norm[0]*W`、`y=pivot_norm[1]*H`。所有骨骼 setup 旋转为零、缩放为一，因此子骨骼局部位置是世界 pivot 减父 pivot；附件位置是裁剪中心减绑定骨骼 pivot。骨骼按父先子后输出，hidden bone_part 也创建骨骼。attachment/facial_feature 绑定 bind_to，null 绑定 root，不创建额外独立骨骼。
**绘制顺序。** `A.occluded_by` 包含 B 时，A 排在 B 后方。排序保留隐藏节点的传递约束，最终只输出有纹理的 slot。没有约束时使用计划中的稳定顺序；若这些部件确有 Alpha 重叠，记录 unconstrained_overlaps，不能声称已确定遮挡。循环关系拒绝导出。
**检查动画。** 每个语义骨骼生成 `check__ID`：0→正角度→0→负角度→0，时长 2 秒，子骨骼与附件按层级跟随。setup 是静态姿态。它们供人工检查绑定和露底，不自动判定动作质量。
Spine 字段依据 [官方 JSON 格式说明](https://esotericsoftware.com/spine-json-format)，导出目标为 4.2；旋转时间线使用 4.2 的 `value` 字段。
## 6. 各个代码文件职责索引
| 文件 | 职责 |
| --- | --- |
| `tools/model-check.mjs` | 独立离线入口、参数与其他阶段隔离 |
| `stages/spine-stage.mjs` | 验证计划、Conda 调用、指纹、导出调度与复用 |
| `spine_assembly.py` | 资产核对、顺序、组装、诊断、骨架及报告 |
| `lib/validate-parts.mjs` | v2 Schema、引用、骨骼和遮挡环路校验 |
| `lib/run-artifacts.mjs` | 独立输出目录和产物哈希 |
| 外部 `scripts/make_atlas.py` | 透明 PNG 图集打包，不修改外部依赖 |
| 外部 `scripts/generate_spine_player.py` | 嵌入骨架和图集的 Spine Player HTML |
| `tests/test_spine_assembly.py` / `tests/spine-stage.test.mjs` | 非人形合成数据、坐标、父子绑定、输入身份、回退、CLI 与完整导出回归 |
| `tools/verify-spine-runtime.mjs` | 可选官方 runtime 加载、图集匹配与世界顶点/旋转复检，需提供本地 core IIFE |
## 7. 产物详细说明
| 文件 | 用途 |
| --- | --- |
| `source.png` / `semantic-parts.json` | 原图与语义计划快照 |
| `images/<id>.png` | 完整可绘制部件集合，供 Spine 编辑器导入 |
| `assembly.json` | 坐标、来源、回退、顺序、QA、输入哈希与覆盖诊断 |
| `assembled-sam.png` / `assembled.png` | 同一绘制顺序的原 SAM / 最终资产透明组装图 |
| `comparison.png` | 左原图、中 SAM 组装、右最终组装 |
| `coverage-diagnostic.png` | 红色为原图前景未覆盖，黄色为多部件重叠；重叠不一定是错误 |
| `skeleton.json` | Spine 4.2 骨骼、slot、region、setup 和关节检查动画；images 路径为 `./images/` |
| `atlas/skeleton.atlas` / `atlas/skeleton.png` | 运行时图集 |
| `preview.html` | 真正的骨架预览，可切换检查动画；需要联网加载播放器 |
| `report.html` | 静态对比、诊断、来源列表与预览入口 |
| `manifest.json` | 执行状态、质量状态、输入/代码/产物哈希、计数、依赖及限制 |
2026-09-22 验证记录：`conda run --no-capture-output -n ai-spine npm test` 的 26 项测试全部通过，包含 6 项新增 Python 组装用例。`output/spine-validation-latest-20260922` 和 `output/spine-validation-baseline-20260922` 分别导出 25/22 个 slot、各 16 个骨骼（含 root）；官方 Spine 4.2 runtime 对两者的 setup 顶点与各 30 个旋转采样验证通过。最新导出的播放器另经 headless Chrome 实际加载，显示 Loaded successfully 并渲染角色，截图位于 `output/spine-runtime-validation-20260922/preview.png`。这不代表资产或动作质量合格，现有输入的漏分仍显示在组装对比图中。
## 8. 当前阶段可改进点说明
- 待实现：针对未确定遮挡、pivot 和绑定的交互修正界面；目前可通过语义计划与绘制顺序文件调整。
- 待实现：可靠的接缝、露底与旋转质量自动验收；目前输出检查动画与诊断，质量状态始终 needs_review。
- 待实现：mesh、权重、IK，以及由动作语义驱动的成品动画；不通过固定部件名称硬套人形模板。
- 待验证：不同角色类别与更复杂遮挡关系的资产质量。合成回归只验证数据契约及几何逻辑。
- 待实现：本地播放器资源打包，使骨架预览也可完全离线打开。