白模预演台 · 本地实验模块

可编辑的本地三维白模预演台：排分镜、挂动作、摆道具、检查镜头，并导出白模动画。 输入提示词或参考图自动建立场景尚未接入（提示词编译只处理已经写出的镜头词，见下）。

完整用法与边界写在怎么生成一条白模动画；本页只讲这个模块本身。

场景合同

这个模块读写 previs-scene/1.0（Z 轴向上，单位米）。详见 scene-v1.js：

playback：fps / duration_s / resolution
scene.geometry[]：grid_plane 区域地面或 box；可带 motion（道具动画）或 attach（挂到角色手/背/胯）
cast[]：motion 走位、clips 动作片段（带混合）、gait 步速步幅、pose 逐关节覆盖
camera.rigs[]：多条机位，每条一组关键帧，支持 linear / smooth / step 缓动
timeline.shots[]：分镜必须无缝铺满总时长，切点即真实切镜
timeline.beats[] / effects[] / tethers[]：事件与接触标记
compile：每个补齐值的来源（assumptions）、未解决项（unresolved）与警告

旧的 previs-workbench/0.3 场景会在载入时自动迁移（坐标轴、朝向、切点都会转换），也可以先用命令行迁移：

python3 pipeline/previs_cli.py convert old-scene.json --out migrated.json

能编辑什么

分镜：镜头列表（名称、起止、所属机位）、在当前位置切分镜、每条机位独立调整位置/观察点/焦段/缓动
人物：走位节点（位置、朝向、节点动作）、动作片段（动作名、起止、混合时长）、步速步幅、逐关节覆盖值
道具：位置与尺寸、道具动画关键帧（门、抽屉、车辆）、或改为持握并选择挂点
导出：整条时间线、单镜，或「逐镜导出后拼合成一条序列 MP4」

动作库

idle / walk / run / turn / sit / stand / reach / point / carry / open_door，打戏调度代理 dash / guard / slash / slash_hold / block / thrust / recoil。

这些是单轴关节的姿势与节奏代理（actions.js）：看机位、走位、动作次序和接触时机够用；没有蒙皮、IK、柔体或接触求解，不代表表演或武术。用打戏片段时必须声明可读性门，否则校验报错。

门禁

导出前会跑：脚底支撑（悬空/陷入）、净空（人物与实体、人物与人物）、逐角色取景与遮挡、接触可读性、分镜连续性、接触事件的前中后帧窗口。数值门只判断几何与时间； 好不好看、读不读得懂、能不能接受仍然要人看。

启动

python -B server.py --data-dir "<数据目录>" [--ffmpeg "<ffmpeg 路径>"] [--port 8766]
python -B launcher.py --data-dir "<数据目录>"          # 图形启动 / 文件夹选择
python -B pipeline/previs_cli.py kits                  # 命令行：模板、编译、校验、渲染、验证

依赖：Python 3.10+、支持 WebGL 的现代浏览器；导出 MP4 需要已有 FFmpeg（含 libx264）。 Node.js 只用于开发测试。离线渲染需要已安装的 Blender 5.x，见 previs build --backend blender。

服务只监听 127.0.0.1，不扫描用户资料、不安装软件、不连接模型、不读取凭据。保存场景和导出视频都写入 --data-dir；场景与视频分别限 1 MB、180 秒与 1920×1080 像素量以内，帧必须按序提交，最多 2 个并发出任务。

验证

node engine-test.mjs                        # 引擎与契约（含夹具一致性）
node fixtures-check.mjs                     # 只用 JS 校验器跑一遍共享夹具
node gate-check.mjs <scene.json>            # 对整条时间线跑门禁，输出 JSON
python -B backend_test.py                   # 真实 FFmpeg 编码/解码（无 FFmpeg 时跳过）
python -B compiler_test.py                  # 编译合同与「不得返回替代场景」
python -B portability_test.py               # 目录、依赖、回环绑定等可移植性检查
python3 pipeline/previs_cli.py verify <scene.json> --mp4 <out.mp4> --out record.json

仓库根目录另有 python -m unittest discover -s tests，覆盖合同夹具、动作与门禁、模板与提示词编译、序列拼接与离线桥接。引擎、后端、门禁通过都不等于有人看过成片：验证记录里连续观看、视觉复核与用户接受永远保持 pending。

许可

本模块原创代码、演示与文档按仓库根目录 Apache-2.0 发布；vendor/ 下的 Three.js 文件保留 MIT 许可。