Pose Lab：通过 MCP 在 Blender 中测量人体手臂姿态

Pose Lab

在 Blender 中通过 MCP 为第一人称手臂和步枪摆姿势提供可测量的空间答案。

模型很难从图片判断 3D 空间：步枪的哪一面朝向眼睛、手指是否位于机匣内部、枪的任何转动能否露出抛壳口。Pose Lab 给模型提供数字。它报告在命名坐标系中的位置以及任何物体的穿模深度。它测量表面正对眼睛的程度以及眼睛能看到什么。它的求解器针对目标搜索步枪动作，并报告哪些目标没有任何动作能满足。对于动画，它逐帧对照相同的检查扫描一段剪辑，并修复失败之处。

我在为我的第一人称射击游戏手工制作枪膛检查时构建了它。有一个问题花了我好几次完整的 Blender 运行：转动步枪能否让眼睛看到它的抛壳口？用 Pose Lab 只需一次 solve 调用。在我的游戏的 AK 骨架上，仅靠转动在 60 个样本中有 0 个满足目标。这是几何事实：眼睛沿着枪管看。转动并移动步枪各自能满足每个目标，但 400 个样本中没有一个能同时满足全部四个目标。所以这项检查需要新的手部姿势，而不仅仅是新的步枪位置。在内置示例骨架上，仅靠转动在 60 个样本中也有 0 个满足抛壳口目标，而转动并移动在 9 秒内满足了每个目标。

它给模型提供什么

坐标系与符号

每个位置都以命名坐标系输入和输出，因此无需猜测轴：

• gun：枪骨骼的当前状态，Unreal 风格轴，厘米：+X 为枪的左侧，+Y 沿枪管，+Z 向上（默认）
• arms：手臂空间，Unreal 风格轴，厘米
• view：从眼睛出发，厘米：+X 向右，+Y 向前，+Z 向上

转动使用玩家的说法：roll + 将枪的右侧向上转，swing + 将枪口向左转，pitch + 将枪口向上转。移动（right、forward、up）在视图中。

手握住握把时已经触及待机姿势中的步枪（一根手指扣在扳机上，手指环绕 护木）。在 pose_idle 处调用 clearance 获取该基准，并用 ignore 通配符将这些片段排除。 在内置示例中，待机时左拇指位于护木内侧 2.7 厘米处。clearance 测量到步枪 表面（按射线奇偶性判断在内或在外），因此它看到的是网格角点之间平面内的身体部位。

手臂规则（anatomy）

一个姿势可以避开步枪，却仍然不是人类手臂能做出的姿势。anatomy 会对照以下限制检查每条手臂：

腕和肘的范围是 AAOS 正常值，来自 AAOS 1965 年表格，转载于 Greene 和 Heckman 1994。其他表格有所不同，手指和拇指相差 10 到 25 度。30 度腕线、5 度肘 最小值以及肘部位于肩下，是本游戏手放在枪上外观的工作规则，而非关节限制。 腕部规则比日常任务更严格：Ryu 1991 发现日常任务使用最多 60 度伸展和 40 度 尺偏。手指限制在掌指关节和中节指间关节处比 AAOS 多允许 10 度屈曲； docs/ANATOMY.md 说明了默认值为何保持如此。它给出了每个关节的标准和功能性 范围、所检查的值以及来源（AAOS；Eaton；Morrey 1981；Palmer 1985；Ryu 1991；Hume 1990；Bain 2015； Soucie 2011）。arm_ranges 将相同数据返回给模型。

anatomy 回复会为每条手臂列出：肘部在肩下的高度、肘部弯曲度、腕部弯曲拆分为 屈曲和桡偏、腕部扭转、每个手指关节的弯曲和扭转，以及 bad：姿势 违反的每条规则。每条规则按报告值读取：角度精确到度，肘部高度精确到 0.1 厘米。绑定中的 limits、finger_limits 和 thumb_limits 条目在 rigs.json 中会覆盖任何值。solve 将 {"type": "anatomy"} 作为目标。

move_gun、reach 和 fix_clip 通过旋转来放置手。它们将手的扭转移入前臂，因此腕 关节只弯曲：步枪旋转 60 度而手保持不动时，读数为无腕部扭转。

通过移动步枪、握把或肘部极向来修复违反的规则。不要进一步弯曲关节。

示例绑定的待机握把违反了腕部规则：左手腕偏离前臂弯曲 44 度，右手 58 度。 使用 anatomy 检查的 fix_clip 将左侧降至 29。它让右侧保持在 58：任何能修复它的旋转都会 让步枪进入手掌背面，因此那只手需要新的握把或肘部，而不是腕部旋转。

手部接触（grip）

一只手用掌心及手指的掌侧握住步枪。clearance 通常在运行时会忽略手掌和手指，因为握持处会接触步枪。这也会隐藏位于错误一侧的手。grip 会检查每只手的接触本身：

每根手指节段的掌侧就是它弯曲所朝向的那一侧。拇指的指腹朝向侧面，因此其接触只计入掌侧的深度。回复给出每只手的 touching（hold_within_cm 内的某部分）、holding（接触，掌心朝向步枪且其表面在 palm_within_cm 以内）、palm_gap_cm、palm_faces_rifle、palm_contact_cm、back_contact_cm、背面接触的位置以及 bad。当 hold 为真时，未握持的手会违反规则。solve 以 {"type": "grip"} 为目标，以 scan_clip 为检查。在示例装配上，一只手绕其前臂旋转 180 度会使其失败。闲置握持也会如此：左拇指位于护木内侧 2.8 厘米处，右掌压入握把 1.2 厘米，扣扳机手指的背面位于扳机护圈内侧 0.8 厘米处。示例保持原样，因此基准测试的数值保持其含义。

运动：扫描并修复片段

scan_clip 逐帧播放片段并对每一帧运行检查。这些检查是求解器的目标（clearance、anatomy、grip、faces_eye、visible、on_screen、barrel）以及另外三项：

• contact：手在其标记点上的一个点，例如指尖在拉机柄上（a、b、max_cm）
• hold：手在步枪上相对于其在 ref_s 处握持位置的漂移距离（side、max_cm）
• pop：突然跳动，即帧间最快的骨骼速度（bones、max_cm_per_s）

任何检查都接受 during: [from_s, to_s]。然后 fix_clip 修复片段的副本：

• 跳变：它根据周围的好帧重新混合跳变的帧
• 保持：它通过手臂 IK 将手放回其握持位置
• 接触：它移动手腕直到该点接触其标记
• 间隙：它绕肩到腕的连线以最小角度摆动每个肘部以避开，保持手腕不动，并将该摆动在相邻帧上缓动
• 解剖：它以相同方式摆动肘部，直到肘部位于肩部下方且在其弯曲范围内。然后它将手腕转回其限制范围内，并将每个手指关节转回其活动范围内。它绝不会将手腕转到步枪进入手背的程度；无法以这种方式修复的手腕保持原样，之后的扫描会说明这一点。转动手腕会转动手在其握持位置上的朝向，因此当握持必须保持精确时，添加一个 hold 检查。
• 握持：不修复；fix_clip 在修复前后报告它。错误一侧的握持需要新的握持。

它报告修复前后的扫描。它还列出那些手必须位于其手臂无法到达的位置的帧，因为只有新的姿势才能修复这些。

examples/motion_test.py 在示例装配上记录了一个带有两个常见故障的片段。步枪滚动 75 度然后返回，仅在其两端设置关键帧，因此手在关键帧之间偏离步枪。有一帧还跳动了 15 厘米。扫描和修复给出了以下数值：

该修复改动了 43 帧中的 34 帧，之后所有检查都通过了。它还标记出 6 帧，其中左臂比其抓握位置短了 0.46 cm。这仍然通过了 0.5 cm 的限制。（在 0.3.1 之前，间隙读数为 0.0 cm：角点错过了步枪内部的前臂。）

安装

你需要 Blender 和 Python 3.10 或更新版本。我在 Windows 10 上用 Blender 5.2.2 和 Python 3.14 测试过。我还没有测试 macOS、Linux 或更旧的 Blender 版本。

uvx poselab-mcp

或 pip install poselab-mcp 并运行 poselab-mcp。

将其添加到 Claude Code：

claude mcp add poselab -- uvx poselab-mcp

或添加到任何 MCP 客户端的配置中：

{
  "mcpServers": {
    "poselab": {
      "command": "uvx",
      "args": ["poselab-mcp"],
      "env": { "POSELAB_BLENDER": "C:/Program Files/Blender Foundation/Blender 5.2/blender.exe" }
    }
  }
}

设置

绑定

内置示例（load_rig {"rig": "sample"}）不需要任何文件。Pose Lab 在 Blender 中从代码构建它：两条带有 Unreal 人形骨骼名称的手臂握着一把 AR 式步枪，其拉机柄可以向后滑动。

你自己的绑定来自 FBX 文件：手臂网格、一个空闲姿势、步枪和片段。在一个 rigs.json 中描述它们（复制 examples/rigs.example.json）并将 POSELAB_RIGS 指向它。片段可以是同一骨骼上的 FBX 动画，或 <clip>.pose.json 骨骼数据：{"fps": 30, "frames": [{"bone": [[x, y, z], [w, x, y, z]], ...}, ...]}，即空闲骨架中每根骨骼的局部位置和旋转。（Blender 在重新导入自己导出的 FBX 动画时会误读它；骨骼数据避免了这一点。describe 报告每个 FBX 片段的骨骼匹配情况。）

安全

• Pose Lab 只读取你的绑定和片段文件。它写入渲染、保存的片段及其日志，且仅在 POSELAB_OUT 内。
• Blender 工作进程仅监听 127.0.0.1，使用一个空闲端口，并且只应答携带会话随机令牌的请求。它只运行 Pose Lab 自己的命令。

工作原理

• poselab_mcp/server.py：MCP 服务器（官方 Python SDK，stdio）。
• poselab_mcp/worker_client.py：在第一次调用时启动一个无头 Blender 并保持绑定加载。
• poselab_mcp/blender/lab.py：在 Blender 内部：绑定、帧、测量、IK、求解器、渲染。
• poselab_mcp/blender/sample.py：内置示例绑定。

测试

python examples/selftest.py

它像 MCP 客户端那样启动服务器并加载示例绑定。然后它重放上面的问题：仅转动永远不会显示端口，而转动并移动则会显示。联系表落在 ~/.poselab/renders/sheet.png 中。

python examples/motion_test.py

它记录上述有缺陷的片段，扫描它，修复它，并将 roll_fixed.pose.json 和 roll_fixed.fbx 保存在 ~/.poselab/clips/ 中。

blender -b -P examples/anatomy_faults.py

它在示例上每次放置一个已知缺陷，如果某项检查漏掉它则失败：一根手指向侧面弯折、一只手相对于其前臂扭转、一只手位于一个平面内、仅指尖接触，以及一个带有字节顺序标记的绑定文件。这些来自一个真实绑定的基准测试（见下文）。

基准测试

benchmarks/ 询问一个模型使用 Pose Lab 的测量是否比仅使用渲染更好地为绑定摆姿势。它在示例绑定上运行五个任务，并用 Pose Lab 对它们评分。一个脚本化的 oracle 和一个什么都不做的对照检查评分器。参见 benchmarks/README.md。

benchmarks/runs/2026-10-09-toangtown-m24 在一个真实游戏绑定上测试检查本身：8 个手放在弹匣上的姿势，其中 7 个带有已知缺陷。Pose Lab 0.3.0 捕获了 5 个，并以其深度的 40% 读取穿模；0.3.1 捕获了全部 7 个，且深度精确。

许可证

MIT