Skip to content

dsh-cascadeur-plugin

Verified

dsh-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 | 简体中文

npm version CI license

把 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 重建 → FBX(612 帧击剑 Mocap)

左: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 / converged
  • reduce: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_fcurves
  • gm:cached(是否复用了 GM 缓存)/ path
  • matched_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。

桌面壳读同一个 desktop profile,但装法不同:官方桌面壳在「插件界面」里填包名; 社区桌面壳用 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 会如实报告)