handdraw-video 手绘白板动画视频
把一张插画渲染为三阶段白板动画：白底静置 → 线稿逐区手绘 → 彩稿逐区刷色 → 收尾渐变成品。渲染器与手部素材全部随包自带，不依赖任何绝对路径，可在任意工作目录下运行。
前置依赖
Python 3.10 及以上，安装依赖：
pip install -r requirements.txt
等价于：
pip install opencv-python numpy scikit-image av
> 注意：PyPI 包名是 av（不是 pyav，pyav 不存在会导致安装失败）。Python 3.13 实测可用组合：opencv-python 5.x + numpy 2.x + scikit-image 0.26 + av 18.x。
> 转码依赖为三级降级：系统 ffmpeg → PyAV → mp4v，装了 av 即可保证 H.264 输出。
标准工作流（四步，逐步确认）
第 1 步：分区
对输入图片做自动分区（生成掩码 + 标注 JSON）：
python scripts/auto_segment.py --src "<输入图绝对路径>" --out "<项目目录>" --batch 8 --total-ms 10000
- 产出：
<项目目录>/masks-auto/auto-XX.png、annotation-auto.json、qa/auto-masks-preview.png --batch：分区批次数量，默认 8（画面元素多可加到 10~12）--total-ms：总时长毫秒，默认 10000- 关键约束：脚本只把底图复制为项目目录下的
input-original.jpg一次，之后运行不再覆盖（防底图反复 JPEG 压缩导致骨架漂移）。更换原图时必须先手动删除旧的input-original.jpg。
第 2 步：参数预检（渲染前必做 · 硬性停机点）
铁律：渲染前必须先给用户「执行方式选择」，拿到明确答复后才能进入渲染。禁止跳过选择直接按默认参数渲染——这是本技能最高优先级约束，优先于任何「直接做」的指令。
python scripts/build_config.py --ask choice.md --preset-out pending.json
- 脚本生成
choice.md（执行方式选择单）+pending.json（当前预设） - 把选择单完整展示给用户，二选一：
- 选 1「直接按默认执行」 → 用pending.json直接进入第 3 步
- 选 2「自定义参数」 → 生成完整参数确认单并渲染到回复里：
bash python scripts/build_config.py --ask confirm.md --preset-out pending.json --ask-mode confirm
用户提出修改（如「总时长 15 秒」）→ 落到pending.json→ 重新展示表格再确认 → 确认后才进入第 3 步 - 确认后生成渲染命令：
python scripts/build_config.py --preset pending.json --out cmd.txt \
--image <输入图> --annotation <annotation-auto.json> --output <输出.mp4>
- 防呆机制：不带
--preset且非真人终端时，脚本拒绝生成渲染命令（[block]提示），因此不能绕过确认流程 - 自动校验：四段时长之和 vs 总时长、宽高偶数、
ink_share合法性 - 跨机复用：确认后的
preset.json拷到其他机器即得完全一致的渲染命令
第 3 步：渲染
用预检输出的命令渲染（后台运行，1080p 约需 5~10 分钟）：
python scripts/render_stream_whiteboard.py "<img>" "<annotation>" "<out.mp4>" \
"<技能包>/assets/user-marker-hand.png" \
--ink-path skeleton --color-fill brush --pause off \
--gaze-fade-ms <fade_ms> --draw-start-ms <white_ms> --ink-share <share> \
--ink-budget 0.1 --canvas "#FFFFFF" --fps <fps> --cap-long-edge <long_edge> \
--tip-anchor-x 0.005 --tip-anchor-y 0.363 --hand-height 560
手素材位置参数（第 4 个位置参数）绝不可省略——省略会回退到内置铅笔手。渲染命令末行输出 OUTPUT=<路径>。
第 4 步：验收
抽帧校验：白底帧均亮 ≈251、收尾帧均亮 ≈200、时长 = 总时长 ±0.1s。交付 mp4 给用户目检手部外观是否为马克笔手。
标准配方
| 参数 | 默认值 | 说明 |
|---|---|---|
| 总时长 | 10s | 可按需调整 |
| 白底 | 0.5s | --draw-start-ms 500 |
| 线稿 | 6s | ink_share = 线稿 / (线稿 + 彩稿) |
| 彩稿 | 2.3s | |
| 收尾 | 1.2s | --gaze-fade-ms 1200 |
| 分辨率 | 1920×1080 @30fps | --cap-long-edge 1920 --fps 30 |
| 画布 | #FFFFFF | |
| 笔迹 | skeleton（骨架追踪，含 Chaikin 平顺 + 滑窗平滑） | |
| 染色 | brush（沿轨迹刷 + 墨线浓度软混合） | |
| ink-budget | 0.1 | 笔手写 10% 关键笔画，其余整线浮现 |
| 手素材 | assets/user-marker-hand.png |
1271×940 真透明 |
| 笔尖锚点 | x=0.005, y=0.363 | 手高 560px |
可调参数速查（build_config.py 交互项）
total_s / white_s / ink_s / color_s / fade_s（时间轴五段）、width / height / fps（画质）、canvas / ink_path / color_fill / ink_budget / pause（画法）、tip_anchor_x / tip_anchor_y / hand_height（手素材对齐）。全部参数都有默认值，改动后脚本即时校验合法性。
故障排查
- 线条有颗粒感：确认用的是本包渲染器（含软混合），勿用旧的二值揭示渲染器
- 成片与历史版本不一致：先查底图是否被反复压缩（第 1 步约束），再查渲染器版本
- 手不是马克笔手：渲染命令漏传第 4 个位置参数（手素材路径）
- 输出尺寸异常：宽高须为偶数；
cap_long_edge按长边等比缩放并对齐网格 - 非 16:9 输入图：输出分辨率随源图长宽比缩放（如 4:3 图 → 1920×1440），属正常行为
- 渲染末尾报清理错误（exit=1）：收尾删除临时文件
output_raw.mp4被系统安全钩子拦截，成片output.mp4通常已完整生成——先校验时长/亮度，合格后手动删除output_raw.mp4即可，无需重渲 - 收尾段手不消失：
gaze-fade阶段的设计就是「手部平滑游走 + 彩稿渐显」，最后一帧仍带手属预期行为，不是 bug - QA 时长打印异常：抽帧脚本手动计算时长时若除数是帧率对象而非浮点，可能打出荒谬值；以
帧数 / fps手算为准 - 中文路径读图失败：脚本统一用
cv2.imdecode(np.fromfile(...))读取，若自行改写请注意不要直接用cv2.imread
