3D 定格角色转台
把一张真人照片，做成定格动画电影里的木偶角色，并给出可以拖着转一圈的 3D 展示页。
这套流程解决什么
单张角色图谁都能出一张，但要做成"能转起来的 3D 视图"必须解决三件事：
- 同一个人的 8 个角度，角度不能错、服装不能变、脸不能换人
- 8 张图的构图必须能对齐，否则旋转时人物忽大忽小、左右乱跳
- 交付物要能单独打开，不能依赖一堆散落的图片
脚本解决第 2、3 件事，第 1 件事靠 references/prompt-templates.md 里验证过的写法。
动手前：先报价
这一步必须做，因为要调图像生成。
- 角色设定图 2 版 ≈ 10–20 积分
- 转台 8 帧 ≈ 40–80 积分（每帧 5–10）
先告诉用户总数，再开始。用户只想先看效果，就只出 2 版设定图。
工作流
Step 1 · 读图，列特征清单
用 ViewImage 看用户给的照片，把能锁定的外貌特征写成一份可复用的清单：
发型与分缝方向、眼镜框型与颜色、肤色、上衣款式颜色与袖口状态、裤子、鞋、
常拿的东西、身形、站姿。
这份清单要逐项写进之后每个 prompt。漏一项，模型就会自己编。
Step 2 · 生成 2 版角色设定图
用 references/prompt-templates.md 第一节的两段 prompt，图生图
（image1 = 用户照片），size: 1024x1536、quality: high。
两版只在姿态上分岔，设计语言完全一致 —— 用户是在挑姿态，不是在挑两个不同的人。
Step 3 · 把背景处理干净
python scripts/isolate_subject.py --in 原图.png --out 成品.png
水印和浅灰背景在这一步一起解决（原理见 references/pipeline-notes.md 第 7 节）。
需要更紧凑的构图加 --crop。
验收：背景均匀 255、脚下有柔和椭圆阴影、水印消失、头发/手指/鞋底没被啃掉。
Step 4 · 生成 8 帧转台
严格按 references/prompt-templates.md 第二节：
- 先出 0° 基准帧，它定下来之后不许再改
- 之后每帧都传
image1= 0° 基准帧，image2= 相邻已知帧 - 45° 必须用"取两帧正中"的写法，否则出来的还是正面
姿势统一用「双臂抱夹克」，正/侧/背三个方向都成立。不要用「一手扶眼镜」——
那个姿势转到 90° 手臂会横在脸前，180° 完全讲不通。
每出一帧检查四项：角度对不对、是不是同一个人、衣服有没有变、手脚有没有畸形。
宁可重生成那一帧，也不要指望后处理修构图。
> 重生成时文件名带上同一个三位角度（如 ..._135_...png），
> normalize_frames.py 会自动取修改时间最新的那张。
Step 5 · 标准化序列帧
python scripts/normalize_frames.py --dir ./raw --out ./frames
做五件事：透明底、统一身高、脚底基线对齐、按头部中心水平对齐、烘焙倒影。
必须看 frames/_contact_sheet.png —— 8 帧并排、带中轴线。要满足：
- 头部都落在中轴线上
- 脚底在同一条水平线
- 身高一致
- 边缘没有白边、残缺、灰色残块
不满足就调 --target-h / --width-ratio 重跑，不要手改单张图。
Step 6 · 生成转台页面
python scripts/build_turntable.py --frames ./frames --out ./角色3D转台.html \
--title "定格木偶角色" --subtitle "STOP-MOTION PUPPET · 男 · 25" \
--meta "头身比|1 : 5.5" --meta "材质|羊毛 / 棉 / 绒面 / 黄铜"
一次出两个文件：分文件版（读同级 frames/，便于改样式）和单文件版
（图片内嵌，便于分发）。
Step 7 · 自动验收
python scripts/verify_turntable.py --html ./角色3D转台_单文件.html --shot ./qa
断言两件事：页面没停在 Loading、没有 JS 错误。再截几个角度供人工核对。
输出 {"ok": true} 才算过。
没跑通这一步就不算交付。 卡 Loading 肉眼看截图会以为是"动画没播完"。
Step 8 · 交付
用 present_files 打开单文件版。回复里说清：
- 每个文件是什么、放哪
- 怎么操作（拖拽旋转、滚轮缩放、双击复位、空格开关自动旋转、
?a=135指定角度） - 8 帧的角度顺序
- 这是图像转台而非真 3D 模型，旋转按 45° 一档
文件清单
scripts/normalize_frames.py 序列帧标准化（透明底/对齐/倒影）
scripts/build_turntable.py 生成转台页面（分文件版 + 单文件版）
scripts/isolate_subject.py 单图纯白背景 + 去水印 + 接地阴影
scripts/verify_turntable.py 无头浏览器验收（加载状态 / JS 错误 / 多角度截图）
assets/turntable_template.html 页面模板，占位符由 build_turntable.py 填充
references/prompt-templates.md 全部实测过的 prompt（角色设定 2 版 + 转台 8 帧）
references/pipeline-notes.md 实现决策与踩坑记录
常见返工原因
| 现象 | 原因 | 处理 |
|---|---|---|
| 旋转时人物忽大忽小 | 没跑 normalize_frames.py，用 AI 原图直接进球 |
必须标准化后再建页面 |
| 45° 帧是正面 | prompt 只写了 "45 degrees" | 改用"两个参考帧取正中"的写法 |
| 转到背面时他穿上了夹克 | 没显式否定 | prompt 加 He is NOT wearing the jacket |
| 页面白屏停在 Loading | 加载门槛用了 img.decode() |
见 pipeline-notes.md 第 4 节 |
| 转台环和脚底错位 | 手写了 --baseline / aspect-ratio |
让 build_turntable.py 从 meta.json 生成 |
| 脚下有碎灰块 | 用亮度阈值刷白背景 | 改 isolate_subject.py 整块重绘 |
| 人物像纸片浮在阴影上 | 倒影/阴影没和脚底对齐 | 检查 meta.json 的 baseline_ratio |
边界
- 旋转是 45° 一档的图像转台，不是可旋转的真 3D 模型。要连续旋转得补到
22.5°（16 帧），工作量翻倍。 - 写实人物不要试图走文生 3D —— 五官会散。
- 8 帧一致性取决于 AI 每次生成，脚本只能对齐"位置和尺寸"，对齐不了"姿势和表情"。
