ws6-moto-shooter-v24 白疤老六摩托摄手v2.4
摩托车摄影 RAW 一键后期：RAF 进、风格化 JPG 成片出。
作者：白疤老六 / WhiteScarSixth（作者抖音：白疤骑士老六）
环境（首次使用先装一次）
一键建 venv + 装全部依赖（脚本无可移植性问题，默认装到用户家目录）：
python "<skill_dir>\scripts\setup_env.py"
- 有 NVIDIA GPU → 自动装 CUDA 版 torch；没有 → 自动退回 CPU 版。
- 想省下载量 / 只用 CPU：加
--cpu。 - 想启用 ONNX/NPU 抠图后端（轻薄本、Intel Core Ultra 的 NPU）：
加--with-onnx；Intel NPU 还需在装好的 venv 里补一句
pip install onnxruntime-openvino。 - 自定义位置：
--venv D:\envs\ws6 --hf-cache D:\cache\hf。 - 国内网络可加
--pypi https://mirrors.aliyun.com/pypi/simple/。 - 脚本最后一行会打印
PY=<venv 里的 python 绝对路径>，后面所有命令都用它。
装好后：
- Python 解释器：上面打印的
PY（Windows 默认
%USERPROFILE%\.workbuddy\envs\ws6-moto-shooter-v24\Scripts\python.exe） - HF 模型缓存：由
setup_env.py指定（Windows 默认
%USERPROFILE%\.workbuddy\cache\hf）；pipeline.py 也会自动兜底设置 HF_HOME - 脚本入口：
scripts/pipeline.py（本 skill 目录下） - 首次运行会自动下载模型（BiRefNet_lite ≈178MB，选 full 则 ≈444MB；
Depth-Anything-V2-Small ≈100MB）。endpoint 默认已是 hf-mirror.com，且加载
时先查本地缓存；权重已在本地时完全不联网。有 NVIDIA GPU 时自动用 CUDA。 - 显存/内存：全尺寸 6016×4014 出图建议 ≥8GB 显存、≥16GB 内存。
标准用法（全自动）
PY="<上面 setup_env.py 打印的 python 路径>"
"$PY" "<skill_dir>\scripts\pipeline.py" all <照片.RAF> --motion auto
- 输出：
<照片目录>\WS6_final\<DSCF####>_WS6.jpg（全尺寸、JPG q95、sRGB） - 中间产物与预览：
<照片名>_ws6_work\（含previews\各阶段小图、
state.json参数记录） - 绝不覆盖原始 RAF/JPG 文件，只新增输出目录。
批量用法（多文件，模型常驻）
"$PY" "<skill_dir>\scripts\pipeline.py" batch "<RAW 目录>" --motion auto
# inputs 可以是文件、目录、glob 的任意组合
- 单进程跑完整个批次：BiRefNet/深度模型只加载一次（每张省约 35s 权重加载）。
- 困难件挂起机制：某张图的主体识别或运动方向置信度不足时，该张
跳过不猜（保留previews\03_matte.jpg供人工判断），批次继续处理
后续文件。全部跑完后写出<目录>\ws6_batch_review.json并打印
WS6_REVIEW_FILE=<路径>。 - 得到复核清单后，agent 必须：逐个读取清单中 deferred/failed 文件的
预览图，向用户展示并请求人工协助（如「这张车头朝哪边？」「主体是否
完整？」），再用显式参数单张重跑：
"$PY" pipeline.py all <该文件> --motion L（等用户给的参数）。 - 在用户给出协助之前不得停等：先把其余文件处理完，这是硬要求。
- 若用户明确要求全自动不打扰：
--no-defer（一律按 auto 假设出片）。
收尾清理（先问用户）
批量后期完成后，必须询问用户是否删除中间文件以节省硬盘空间
（每张 24MP 的 workdir 约 1~2GB）。用户同意后执行：
"$PY" "<skill_dir>\scripts\pipeline.py" clean "<RAW 目录>"
只删除 *_ws6_work\ 与复核清单，成片 WS6_final 与原始 RAW 一律保留。
RAW 已被改名或移走后遗留的孤儿 workdir 也会一并扫掉；若某个目录因被
占用删不掉，日志会写 FAILED to remove，不会谎报成功。
二次构图规则（v2.6 标定 / v2.7 增补兜底）
- 竖屏优先（数据集 74.5% 竖屏）：高宽比 1.18~1.38（≈4:5~3:4），
目标 1.28；竖屏放不下才降级横屏（宽高比 1.30~1.50，目标 1.38），
再不行自由画幅。主体完整是硬约束，绝不切头切尾。 - 满幅主体：竖屏主体宽占画面 0.72~0.82（目标 0.80），横屏主体高
占 0.82。 - 水平居中：主体放正中央，左右留白对称——不按行驶方向多留白
（数据集实测前后留白 0.099/0.103 对称），也不再使用黄金分割偏移。 - 垂直居中略偏上留白：上方比下方多留约 2%，主体视觉质心因此落在
画面中心偏下约 5%（与作者成片一致）。 - 兜底与告警（v2.7）：竖屏、横屏都装不下主体时（典型是迎面/追尾机位，
主体 bbox 长宽比 > 1.6），改用自由画幅把主体宽占比拉回 0.72，并打印
WARNING recompose、把细节写进state.json的crop_meta。横屏候选若
主体宽占比 < 0.60 直接弃用——旧版没有这道守卫，会静默输出主体只占 0.31
的画面。主体占比是硬指标，出现 WARNING 必须看previews\04_crop.jpg。 - 依据：
references\pipeline-details.md「二次构图数据标定（v2.6）」。
必须做的质量复核（即使全自动模式）
agent 是多模态的，流程跑完后必须亲自看图复核，而非盲信脚本：
- 读取
previews\03_matte.jpg：确认主体被完整抠出（车轮、旗杆、飘带、
风挡/镜片半透明区域应呈棋盘格半透效果）。缺部件时向用户说明并讨论
补救（如局部重抠）。 - 读取
previews\04_crop.jpg：确认运动方向判断正确（车头朝向）。
若--motion auto猜错（auto 默认假设车头朝右），用--motion L
（车头朝左）等显式重跑。车头车尾判断方法见 references。 - 读取最终 JPG：检查通透度、拖影是否只出现在车尾后方、前方轮廓是否锐利。
不满意时调参重跑（参数见下）。 - 读
state.json核对有没有降级：depth_source应为model，
crop_meta.warning应为null。有降级时日志会以WARNING打头，
别只看最后那句DONE。
常用参数
| 参数 | 说明 |
|---|---|
--motion L\|R\|U\|D\|auto |
车头朝向。复核后显式指定最可靠 |
--style <path> |
风格 JSON，默认 assets\style_default.json |
--aspect portrait\|landscape\|auto |
构图画幅，默认 auto（竖屏优先；主体放不下时自动降级横屏/自由画幅，主体完整是硬约束） |
style JSON 的 subject_median_target |
主体细节恢复的目标中位亮度，默认 0.24；主体被压死时按 gamma 重扩展提亮到此值，已够亮的主体不动 |
style JSON 的 subject_gamma_cap |
gamma 下限封顶，默认 0.35；越小救得越狠，0.25 会明显变灰 |
style JSON 的 subject_clarity |
主体纹理增强（unsharp），默认 0.25 |
--blur-len N |
运动模糊核长度(px)，默认 1.8% 图宽 |
--blur-passes N |
模糊迭代次数，默认 6；低于 5 会被钳到 5（规格要求 ≥5） |
--max-dim N |
抠图前降采样提速，正式出图不要用 |
--matte-model lite\|full |
抠图模型，默认 lite（Swin-T，下载 178MB/内存占用小）；full 为 Swin-L（≈444MB）。实测两者 CPU 速度接近、精度几乎一致（IoU 0.98） |
--matte-backend torch\|onnx |
默认 torch（HF 权重+CUDA）。无独显机器强烈建议 onnx：实测 CPU 抠图 48s→3~6s（约 10×），provider 自动按 NPU→CPU 回退（需 setup_env --with-onnx） |
--onnx-provider auto\|npu\|cpu |
仅 onnx 后端有效，默认 auto |
--out <path> |
自定义输出路径（仅单张 all） |
风格标定（从历史成片学习参数）
准备一个目录，里面成对的「原始 RAW ↔ 你手动修好的成片 JPG」，命名形如
DSCF####.RAF ↔ DSCF#### 拷贝.jpg（同一主文件名 + 一个 JPG 后缀变体）。
然后执行：
"$PY" "<skill_dir>\scripts\pipeline.py" calibrate \
--dataset "<你的配对数据集目录>" \
--style-out "<skill_dir>\assets\style_calibrated.json"
（作者本人的数据集是 200 对 Fuji RAF/成片；随技能分发的
style_calibrated.json 已改用全部可用配对（198 对，200 对中 2 对无法配对）
标定，参数更稳。）
完成后用 --style assets\style_calibrated.json 出片。标定会拟合色调曲线、
饱和度比、暗部/高光响应（取全部配对的中位数，抗离群）。
assets\style_calibrated.json 里那份就是作者本人的风格，可直接拿来试效果。
七阶段流水线细节
各阶段算法、参数含义与调参经验详见
references/pipeline-details.md。
调 grade/motion 行为前先读它。
常见问题快速问答
Q1 批量跑到一半停住不动，最后一行日志之后再无输出？
卡在联网加载模型。skill 会先查本地缓存（v2.7 起），本机没有权重时才去
hf-mirror.com，而该域名在部分网络会「连上但不回包」。稳妥做法是先备好本地权重：
export WS6_DEPTH_DIR="D:\models\Depth-Anything-V2-Small-hf" # 深度模型
export HF_HOME="D:\cache\hf" # BiRefNet 缓存
深度模型加载有 180 秒硬上限（WS6_DEPTH_TIMEOUT 可调）：超时就一次性
降级并把原因写进 state.json 的 depth_source，整批共用、不再逐张重试
（v2.7 修复）。成片仍然可用，只是空气透视变粗略。被放弃的加载线程可能仍在后台
把权重写进缓存，所以再跑一次往往就能拿到真深度。
Q2 每张成片主体都很小，而且是横屏？
主体 bbox 长宽比 > 1.6，典型是迎面 / 追尾机位。v2.7 起会自动改用自由画幅，把
主体宽占比拉回 0.72 并打印 WARNING recompose。仍不理想就显式指定
--aspect portrait。
Q3 拖影全加在车头前方了？
--motion auto 假设车头朝右。同一路段同向拍摄时统一指定 --motion L（朝左）
或 R（朝右），不要逐张等 auto。
Q4 成片宽度不到抖音竖屏 1080？
原片像素不够（如索尼 S RAW 约 8MP），裁切后更小。先看 WS6_final 里的实际
尺寸：低于 1080 宽需要超分，或改用 L RAW 重拍。
Q5 主体发灰、像蒙了一层「幽灵面纱」？
那是 v2.3 的老问题，v2.4 起用黑位锚定解决。若仍出现，检查 style JSON 的
subject_gamma_cap 是否偏大（越小救得越狠，0.25 会明显变灰）。
Q6 抠图漏掉旗杆 / 飘带 / 拉烟？
1024px 输入下极细结构会断。可试 --matte-model full，或对个别图局部重抠。
正式出图不要加 --max-dim。
Q7 怎么确认这一批有没有「悄悄降级」？
读每张的 state.json：depth_source 为 model 才是真深度模型；
crop_meta.mode / crop_meta.warning 说明构图用了哪套规则、主体占比多少。
Q8 无独显的轻薄本太慢？
--matte-backend onnx（需先 setup_env.py --with-onnx），CPU 抠图 48s → 3~6s。
Intel Core Ultra 再补 pip install onnxruntime-openvino 以启用 NPU。
Q9 想省 C 盘空间？
建环境时就把位置挪到别的盘：
python setup_env.py --venv D:\envs\ws6 --hf-cache D:\cache\hf
Q10 中间产物占多大、能删吗？
全尺寸每张约 1~2GB（与像素量成正比，8MP 的原片只需约 130MB）。确认成片无误后
执行 pipeline.py clean "<RAW 目录>"，只删 *_ws6_work，成片与原始 RAW 不动。
Q11 想完全无人值守跑完？
--no-defer：不再挂起困难件，一律按 auto 假设出片（运动方向可能猜错）。
Q12 手动下载了权重，怎么让 skill 用上？
深度模型用 WS6_DEPTH_DIR 指到目录；BiRefNet 把 HF_HOME 指向 HF 缓存目录。
两者都在加载时优先使用，不需要改动 skill 源码。
失败处理
- BiRefNet 下载失败 → 确认本机能否访问 hf-mirror.com（默认 endpoint），或先
在别处下好权重放进 HF 缓存；本机已有 full 权重时可用--matte-model full兜底。 --matte-backend onnx报 no NPU execution provider → 说明没装对应 EP：
Intel 装onnxruntime-openvino，AMD 走 Ryzen AI / Windows ML；
或退回--onnx-provider cpu/--matte-backend torch。- 抠图为空（empty subject mask）→ 读
previews\02_graded.jpg确认解码正常，
再向用户报告该图不适合全自动流程。 - RAW 曝光严重异常 → 脚本已带 auto_bright 兜底；仍异常则在报告中说明。
作者：白疤老六 / WhiteScarSixth（作者抖音：白疤骑士老六）。
风格参数 assets\style_calibrated.json 由作者本人 200 对素材标定，随技能分发。
