dsh-cascadeur-plugin
Verifieddsh-cascadeur-plugin · v0.4.4 · MIT
Move Cascadeur .casc animations into Blender / UE5: reads per-joint Global Matrix through Cascadeur's official MCP script server, rebuilds the pose in Blender on the original FBX and exports FBX (0.000 cm per-vertex error). Ships error-driven keyframe red
Install
dsh plugin add dsh-cascadeur-plugin Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Creators
Readme
dsh-cascadeur-plugin
English | 简体中文
把 Cascadeur 的 .casc 动画搬进 Blender / UE5。
dsh plugin --profile web add dsh-cascadeur-plugin
原理:通过 Cascadeur 内置的 MCP 脚本服务器(
127.0.0.1:8765)读取每个关节的Global Matrix,在 Blender 里用原版 FBX 重建姿势,再导出 FBX。 不修改、不破解 Cascadeur 的任何授权机制。精度:逐顶点误差 0.000 cm(与 Cascadeur 自己的
calc_skinned_mesh对比)。 这个数字不是口头保证:verify/verify_rebuild.py会把它变成可执行断言(见 §验证)。
English tl;dr — A DSH plugin that converts Cascadeur .casc animations to
Blender / UE5 FBX by reading per-joint Global Matrix through Cascadeur's MCP
script server and rebuilding the pose on the original FBX (0.000 cm vertex
error, asserted by verify/verify_rebuild.py). Ships error-driven keyframe
reduction (angle + position thresholds, Bezier AUTO_CLAMPED), Mocap single-frame
glitch repair, and unit tests (npm test, python tests/*.py).
左:Cascadeur 播放 .casc(小窗是驱动它的参考视频) · 右:Blender 里重建后的 .blend / 导出的 .fbx
同一段 612 帧击剑 Mocap,逐帧同步。完整 30 fps 版:docs/demo.mp4
一、前置条件
| 项 | 要求 |
|---|---|
| Cascadeur | 2026.2.3 实测通过(含免费版);其他版本未验证——见下方实测环境。需要开脚本服务器(可自动化,见下) |
| Blender | 5.4 实测通过;其他 5.x 预期可用但未验证(Python 需带 zstandard) |
| 原版模型 FBX | 当初导入 Cascadeur 用的那个 FBX(不要用改过的) |
| DSH | 0.1.7+ |
实测环境
下表是完整链路实际跑过的组合。其他版本大概率也能用,但没有验证过——如果在别的 版本上遇到问题,带上版本信息开 issue,我们会补进这张表。
| 组件 | 实测版本 | 备注 |
|---|---|---|
| 操作系统 | Windows 11(10.0.26200) | 开发机;macOS / Linux 未验证 |
| Cascadeur | 2026.2.3(Free 版) | MCP 脚本服务器 127.0.0.1:8765 |
| Blender | 5.4(5.4.0 Alpha,2026-10-17) | 自带 Python 3.13,含 numpy + zstandard;其他 5.x 预期可用 |
| DSH | 宿主 API [email protected](engines.dsh >= 0.1.7) |
在桌面 profile 里实际加载验证 |
| Node.js | 24.21.0(开发机)/ 20 与 24(CI) | engines.node >= 20 |
README 里 612 帧击剑 Mocap 的数据,就是在上面这套环境下跑出来的。
开 Cascadeur 脚本服务器
方式 A(手动,最快)
Cascadeur 菜单栏 → Scripts → MCP → Start script server
方式 B(自动,一次配置永久生效)
把 cascadeur_autostart/autostart.py 复制到
<Cascadeur安装目录>\resources\scripts\python\scripts\mcp\,
之后每次启动 Cascadeur 都会自动开 8765(约 60 秒后就绪)。
详见 cascadeur_autostart/README.md。
没开的话工具会明确提示你怎么开。
二、工具
| 工具 | 用途 |
|---|---|
casc_status |
环境自检:Cascadeur 是否可达 / Blender 路径 / 当前设置 |
casc_inspect |
只读读取 .casc 元数据:角色、骨骼、帧范围、LOD、分层。不需要开 Cascadeur |
casc_dump |
只导出动画数据(Global Matrix → JSON) |
casc2blend |
一条龙:读 → 重建 → .blend(可开启关键帧简化) |
casc2fbx |
一条龙:读 → 重建 → .fbx(可直接进 UE5) |
casc_verify |
验证:骨骼位置 vs Cascadeur 数据(正常 < 0.01 cm) |
casc_config |
读写默认设置(持久化,后续导出默认用它) |
三、典型用法
1. 先配置一次(之后一直生效)
casc_config({ set: {
modelFbx: "D:\\path\\to\\your_original_model.fbx",
outDir: "D:\\path\\to\\output",
lod: "0"
}})
modelFbx必须是当初导入 Cascadeur 用的那个原始 FBX(不要用后来改过的)。outDir留空则默认输出到<casc 所在目录>/casc_out。
设置存在 ~/.dsh/cascadeur-settings.json,不改变就一直按它来。
2. 看一眼 .casc 里有什么
casc_inspect({ casc_path: "D:\\path\\to\\scene.casc" })
返回:角色列表(含顶点数、蒙皮骨骼数)、关节数、帧范围、FPS、动画分层。
3. 一条龙导出
casc2fbx({ casc_path: "D:\\path\\to\\scene.casc" })
返回:帧数、关节数、LOD、rest_err_cm(应 ~0.0001)、
bone_pos_err_cm(应 ~0.0001)、FBX 路径与大小。
开启关键帧简化(推荐用于 Mocap 结果):
casc2fbx({
casc_path: "D:\\path\\to\\scene.casc",
reduce_keys: true, // 只写误差驱动选出的关键帧 + Bezier(AUTO_CLAMPED)
key_angle: 2.0, // 允许的最大平均角度误差(度)
key_pos: 2.0, // 允许的最大平均位置误差(厘米)
min_gap: 1, // 关键帧最小间隔
despike: true // 先修掉 Mocap 的单帧跳变
})
返回里会多出:
despike:fixed_frames(被修复的跳变帧号)/rounds/convergedreduce:dense/keys/ratio_pct/key_angle_deg/key_pos_cm/min_gap/violations(真实超标帧数)/mean_angle_err/max_angle_err/mean_pos_err_cm/max_pos_err_cm/bezier_fcurvesgm:cached(是否复用了 GM 缓存)/pathmatched_bones/missing_bones/unmatched_fbx_bones(骨骼名对不上时会显式报告)
violations = 0才代表"所有帧都满足阈值"。
4. 验证
casc_verify({ casc_path: "D:\\...\\scene.casc" })
它会断言 rest_err_cm 与 bone_pos_err_max_cm ≤ 0.01 cm,并检查骨骼名是否全部匹配
(缺骨时 ok=false)。同样的断言也能独立跑:
blender -b --factory-startup --python verify/verify_rebuild.py -- \
--casc scene.casc --gm scene_gm.json --model-fbx Model.fbx --tolerance-cm 0.01
输出 markdown 表格 + 非 0 退出码,可直接进 CI。
四、设置项
| 键 | 说明 | 默认 |
|---|---|---|
blenderExe |
Blender 路径 | 自动探测(复用 dsh-blender-plugin 的配置) |
modelFbx |
原版模型 FBX | 空(必须先配置) |
lod |
网格 LOD:0 / all / 0,2 |
0 |
outDir |
默认输出目录 | <casc 同目录>/casc_out |
frames |
帧范围:auto / 0-10 |
auto(用场景时间轴范围) |
reduceKeys |
默认是否开启关键帧简化 | false |
keyAngleDeg |
允许的最大平均角度误差(度) | 2.0 |
keyPosCm |
允许的最大平均位置误差(厘米) | 2.0 |
keyMinGap |
两个关键帧的最小间隔(1 = 允许相邻帧) | 1 |
despike |
自动修复 Mocap 单帧跳变 | true |
fps |
导出帧率(Mocap 视频通常是 25) | 30 |
五、核心公式(不要改)
B4 = [[1,0,0,0],[0,0,-1,0],[0,1,0,0],[0,0,0,1]] # Y-up → Z-up
W_rest[joint] = W_rest[parent] @ (T(pos) @ Euler(rot,'ZYX').to_matrix())
A(t) = B4 @ M_global(t) # ⚠️ 只左乘!@ B4.T 会多转 90°,整模扭曲
D(t) = A(t) @ inv(W_rest[joint])
pose_bone.matrix = D(t) @ bone.matrix_local
踩过的坑:
B4 @ M @ B4.T(相似变换)会给每根骨加 90° roll, 表现是"每个关节都在扭",但所有位置检查都通过(位置永远是对的)—— 这个 bug 曾让整个项目卡了十几个小时。诊断方法:rest(stastics) ↔ Blender bind = ~0° ← 正常 GM(绑定帧) ↔ Blender bind = 90° ← 说明 B4 用错了
六、关键帧简化(Mocap 结果必备)
Cascadeur 的 Video-mocap 写的是逐帧关键帧(示例:612 帧),带有人体估计的抖动。 直接用手感很差、也难编辑。插件内置了误差驱动的关键帧简化:
从 [首帧, 末帧] 开始
→ 每帧算"用相邻关键帧插值后"的误差(角度 + 位置分开算)
→ 挑归一化违约度最大的帧加入关键帧
→ 重复,直到所有帧 max(角度/阈值, 位置/阈值) ≤ 1
比"只看速度"稳:慢速但有关节的段落(缓慢收剑)不会被误删。
实测(612 帧击剑 Mocap,先修复 5 帧跳变)
| 角度阈值 | 位置阈值 | 关键帧 | 占比 | 实测最大误差 | 超标 |
|---|---|---|---|---|---|
| 1.0° | 0.5 cm | 355 | 58% | 0.97° / 0.49 cm | 0 |
| 1.5° | 1.0 cm | 257 | 42% | 1.47° / 0.99 cm | 0 |
| 2.0° | 2.0 cm | 184 | 30% | 1.97° / 1.97 cm | 0 |
| 3.0° | 3.0 cm | 142 | 23% | 2.96° / 2.78 cm | 0 |
| 5.0° | 5.0 cm | 100 | 16% | 4.88° / 4.98 cm | 0 |
(min_gap=1;min_gap 调大能进一步减少帧数,但会牺牲精度——它是硬约束。)
Mocap 跳变修复
Mocap 偶尔会有单帧追踪失败:该帧姿势瞬间跳几十厘米再回来, 不修的话 FBX 里会看到明显的抽搐。
detect_spikes: 逐帧位移 vs 局部滚动中位数,比值 > 4 且持续 ≤ 8 个帧间 → 判为跳变
repair_spikes: 用前后帧插值替换,迭代至收敛
上述 612 帧样例里检出并修复了 257, 258, 259, 597, 598 五帧
(修复前最大角度误差 27.7°,修复后 1.97°)。修复帧号写在回执的
despike.fixed_frames 里,不会偷偷改。
开启方式:
casc2fbx({ casc_path: "...", reduce_keys: true, key_angle: 2.0, key_pos: 2.0, despike: true })
或写进默认设置:casc_config({set:{reduceKeys:true, keyAngleDeg:2.0, keyPosCm:2.0}})。
.blend里是稀疏的 Bezier 关键帧(可手改);.fbx会按帧烘焙(引擎友好),但烘焙结果是沿 Bezier 曲线的,所以依然平滑。
七、把视频喂给 Cascadeur 的 Mocap(踩坑记录)
坑 1:视频时间基导致"只有第一帧正常"
QuickTime 视频的 time_base 常常是 1/12800,25fps 时每帧 = 512 个时间单位。
Cascadeur 抽帧时按时间码命名(000000.jpg, 000512.jpg, 001024.jpg ...),
但读取时按帧序号找(000001.jpg, 000002.jpg ...)→ 只有第 0 帧对得上。
修复:导入前重编码,把时间基改成 fps:
ffmpeg -i 原视频.mp4 -c:v libx264 -crf 16 -r 25 -video_track_timescale 25 -an 修复后.mp4
坑 2:场景里可能有「没有几何数据」的网格对象
导入的参考视频会以普通网格对象的形式出现(几个顶点、没有蒙皮)。插件会自动跳过它们, 只导出真正带几何的网格,而不是直接崩掉。
坑 3:Mocap 是本地 CPU 推理,吃内存
模型 787 MB(resources\mocap.pt),首次使用需下载;
700 帧约 23 分钟(i5-10500H,6 核),峰值内存 9 GB+,可能触发
Cascadeur 的 6 GB 限制并清空撤销历史。长片建议分段处理。
八、安装 / 卸载
从 npm 安装(推荐) —— 一条命令,dsh plugin 会自动把它加进 profile 的 bundles:
dsh plugin --profile web add dsh-cascadeur-plugin
# 其他 profile 把 web 换掉即可(例如 headless)
装完重启 dsh web。升级:dsh plugin --profile web update dsh-cascadeur-plugin。
桌面壳读同一个
desktopprofile,但装法不同:官方桌面壳在「插件界面」里填包名; 社区桌面壳用dsh plugin --profile desktop add dsh-cascadeur-plugin。 如果你的dsh没有plugin子命令,用下面的离线方式。
从本地仓库安装(离线 / 开发用) —— 不依赖 npm:
# 1. profile 的 package.json 里加依赖 + bundle(脚本会自动备份)
# 2. node_modules 里建 junction 指向本目录
# 3. 重启 DSH
.\install.ps1
卸载:dsh plugin --profile web remove dsh-cascadeur-plugin,或跑 .\uninstall.ps1。
九、验证与测试
# Node 侧纯逻辑(28 项断言,不需要 DSH / Blender)
node tests/test_core.mjs # 或 npm test
# 关键帧简化(12 项;--bench 可跑真实 612 帧数据)
python tests/test_keyreduce.py
# 场景元数据读取(25 项;需要 numpy + zstandard,或用 Blender 自带 Python)
python tests/test_casc_core.py
精度验收(需要真实的 .casc + 原版 FBX,不进 CI):
blender -b --factory-startup --python verify/verify_rebuild.py -- \
--casc scene.casc --gm scene_gm.json --model-fbx Model.fbx --tolerance-cm 0.01
CI:.github/workflows/ci.yml(Windows runner)跑上面三套测试 + 全脚本 ast.parse。
改代码前请先读
AGENTS.md—— 里面把「会咬人」的约定按 「症状 → 代码位置」列了一遍(B4 只左乘、骨骼名匹配、帧范围语义、 keyreduce 单位不能混、Mocap 跳变、BOM 禁令等)。
十、限制
- Windows 11 是实测平台;macOS / Linux 尚未验证
- 不跨机器:读的是本机 Cascadeur 的实时数据
- 一个
.casc里多个角色时,当前导出所有蒙皮网格(lod只影响带 LOD 后缀的网格, 道具网格始终保留;MeshObject(N)且 ≤4 顶点的参考视频平面会被自动跳过) - 动画节奏按 30fps 假设(Cascadeur 默认);非 30fps 场景从场景自身设置读取
- 不做 IK 重解算:直接使用 Cascadeur 求值后的
Global Matrix(这就是精确的原因) keyreduce的min_gap是硬约束:设得过大会让阈值承诺失效(回执里violations会如实报告)