Pose Lab

Pose Lab

为在 Blender 中摆放第一人称手臂和步枪提供经过测量的空间答案。

模型不擅长根据图片判断 3D 空间：步枪的哪一侧朝向眼睛、手指是否陷进机匣，以及无论如何转动枪械都能否让抛壳口显露出来。Pose Lab 为模型提供数字。它会报告物体在指定坐标系中的位置，以及任何部位嵌入的深度。它会测量表面正对眼睛的程度，以及眼睛能看到什么。其求解器会搜索步枪的移动方式以满足目标，并报告哪些目标无论怎样移动都无法实现。对于动画，它会逐帧扫描片段，使用同样的检查项进行检查，并修复未通过的部分。

我在为自己的第一人称射击游戏手工制作膛室检查时开发了它。有个问题让我完整运行 Blender 好几次：转动步枪能否让抛壳口朝向眼睛？用 Pose Lab，只需调用一次 solve。在我游戏的 AK 骨架上，仅靠转动在 60 个采样中有 0 个达成目标。这是几何结构决定的事实：眼睛沿着枪管方向看去。转动并移动步枪时，每个目标都能单独达成，但 400 个采样中没有一个能同时达成全部四个目标。因此，这项检查需要新的手部姿势，而不只是新的步枪位置。在内置示例骨架上，仅靠转动在 60 个采样中同样有 0 个达成抛壳口目标；转动并移动则在 9 s 内达成了所有目标。

它能为模型提供什么

工具	回答的问题
list_rigs、load_rig、describe	有哪些骨架、坐标系、符号规则、命名点、片段和活动部件
pose_idle、pose_clip、move_part、snapshot	将骨架摆成某个姿势：逐次播放片段、拉回枪机、保存姿势
move_gun	滚转、摆动、俯仰并移动步枪；手部通过手臂 IK 保持握持
reach	通过手臂 IK 让手腕触及某个点（可尝试肘部极点来避开前臂）
turn_bone	让一根骨骼绕穿过其头部的轴旋转：手指关节、手腕或整条手臂
where、distance	指定坐标系中的位置
clearance	步枪嵌入前臂、手掌或手指的深度，以及所在位置，按到表面的距离测量
purpose	每只手都作用于一个目标：握住（捏握或环握）、拉动（捏拉或钩拉）、按压、靠放在某个部件上或伸手触及某个部件；不会有手指无故弯曲
anatomy	检查每条手臂是否符合人体手臂的活动限度：肘部、手腕和每个手指关节，并列出姿势违反的所有规则
grip	检查每只手如何接触步枪：用手掌而非手背；手掌本身是否握住步枪；每一侧嵌入的深度
arm_ranges	这些限度的研究依据：每个关节的 AAOS 活动范围、功能活动范围、检查值及来源
faces_eye、visible、screen	表面朝向眼睛的角度、眼睛能看到的表面范围，以及表面在屏幕上的位置
solve	根据目标搜索步枪的移动方式；报告每个目标，以及任意样本满足目标的频率
render	联系表：玩家视角和外部视角，每个图块都标注为 Blender 视图
record_clip、load_clip	由关键姿势生成片段，或从文件加载片段：.pose.json、FBX 或 BVH
scan_clip	检查每一帧；报告最差值、发生时间和未通过检查的时间段
fix_clip	修复未通过项，并报告修复前后的扫描结果，以及无法修复的内容
save_clip	将片段写出为 .pose.json 骨骼数据和供游戏引擎使用的 FBX
view_cover	手臂遮挡玩家视野的程度：全部、左下方和底部中央
solve_grip	搜索手部的握持方式：手掌放在枪管上的标记处、肘部极点和手部旋转；保留能维持握持、避免穿插、符合手臂规则且满足视野预算的结果
retarget_clip	将其他骨架的片段重定向到此骨架，并让手部握住此枪自身的握持点：动作共享，握持适配枪身
check_set	汇总片段的所有检查结果，供关卡使用：最差穿插值、违反规则的帧，以及手部松开的帧

坐标系和符号

所有位置都在指定坐标系中输入和输出，因此无需猜测轴向：

• gun：枪骨骼所在的坐标系，采用 Unreal 风格轴向，单位为 cm：+X 指向枪的左侧，+Y 沿枪管方向，+Z 朝上（默认）
• arms：手臂的坐标系，采用 Unreal 风格轴向，单位为 cm
• view：以眼睛为原点，单位为 cm：+X 向右，+Y 向前，+Z 朝上

旋转使用玩家熟悉的描述：roll + 使枪的右侧抬起，swing + 使枪口向左偏，pitch + 使枪口抬起。移动（right、forward、up）以视角为基准。

在待机姿势中，手部已围绕握持点接触步枪（手指扣在扳机上，手指环绕护木）。在 pose_idle 下调用 clearance 获取基准值，并用 ignore 通配符排除这些身体部位。在内置示例中，待机时左手拇指嵌入护木 2.7 cm。clearance 按到步枪表面的距离测量（通过射线奇偶性判断内外），因此即使身体部位位于平坦表面上、网格角点之间，也能检测到。

手臂规则（anatomy）

姿势即使能避开步枪，也仍可能是人类手臂无法做到的。anatomy 会根据以下限制检查每只手臂：

关节	规则
肩部	手部操作枪械时，肘部至少低于肩部 2 cm
肘部	像铰链一样弯曲 5 到 150 度：绝不能完全伸直
前臂	前臂带动手部旋转（桡骨绕尺骨转动）：从拇指朝上开始，以肘部的铰链平面为基准，旋前和旋后各不超过 80 度
前臂皮肤	在带有前臂扭转骨骼的骨架上，旋转沿前臂分散：任何单个骨骼段（肘部末端、各扭转骨骼、手腕）的旋转都不超过 50 度
手腕	手腕不自行扭转；在没有扭转骨骼的骨架上，手部相对于静止握姿的扭转不超过 30 度
手腕	与前臂轴线的夹角不超过 30 度；活动范围在关节限度内：屈曲 80 度、伸展 70 度、桡偏 20 度、尺偏 30 度
手指	每个关节只朝手掌方向弯曲：指关节 -30 到 100 度，中间关节 -5 到 110 度，末端关节 -10 到 90 度
手指	每根手指都保持在自己的平面内：中间关节偏离自身铰链不超过 15 度，末端关节偏离中间关节的平面不超过 25 度
拇指	指关节横跨手掌弯曲 -10 到 60 度，末端关节弯曲 -15 到 90 度；拇指根部相对于食指掌骨张开不超过 80 度，且位于手掌后方不超过 20 度

手腕和肘部的活动范围采用 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 cm。rigs.json 中骨架的 limits、finger_limits 和 thumb_limits 条目会覆盖任何数值。solve 将 {"type": "anatomy"} 作为目标。

move_gun、reach 和 fix_clip 会在转动手部时调整手部位置。它们会将手部扭转转移到前臂，因此手腕关节只负责弯曲：保持双手位置不变时，步枪旋转 60 度不会显示为手腕扭转。

如果违反了规则，请通过移动步枪、调整握姿或改变肘部的转动轴来修正。不要让关节弯得更多。

示例骨架的静止握姿违反了手腕规则：左手腕偏离前臂 44 度，右手腕偏离 58 度。使用 anatomy 检查的 fix_clip 会将左手腕的偏差降至 29 度。右手腕仍为 58 度：任何能修正它的转动都会让步枪进入手掌后方，因此这只手需要新的握姿或肘部位置，而不是转动手腕。

手部接触（grip）

手掌和手指掌侧握住步枪。通常运行 clearance 时会排除手掌和手指，因为握持时它们会接触步枪。这样也会隐藏位于错误一侧的手。grip 会检查每只手本身的接触情况：

规则	默认值
手放在步枪上时，掌心朝向步枪，而不是手背（palm_faces_rifle 大于 0）	在 hold_within_cm 1.0 范围内
握住步枪的手，掌心贴在步枪上，而不只是指尖接触（palm_gap_cm）	palm_within_cm 1.5
步枪不接触手背和每根手指的背面	back_max_cm 0.1
掌侧可以稍微压入：胶囊体比手掌更圆	palm_max_cm 1.0

每段手指的掌侧，是手指弯曲的一侧。拇指的指腹朝向侧面，因此其接触只计入掌侧深度。返回结果会给出每只手的 touching（有部分位于 hold_within_cm 范围内）、holding（有接触，掌心朝向步枪，且表面位于 palm_within_cm 范围内）、palm_gap_cm、palm_faces_rifle、palm_contact_cm、back_contact_cm、背侧接触位置，以及 bad。当 hold 为 true 时，未能握住步枪的手会违反规则。

用于握持某个部件（弹匣、握把）的手还必须夹住它：当 grasp 为 true 时，拇指和一根手指必须从相对两侧接触该部件（皮肤位于 contact_cm 0.3 范围内），且它们相对于部件表面的方向夹角至少为 180 - 2 atan(friction) 度（friction 为 0.5 时为 127 度）。返回结果会给出 grasping、grasp_opposition_deg 和 digits_touching。搭在步枪上或勾住把手的手不需要夹捏：不要启用 grasp。solve 将 {"type": "grip"} 作为目标，scan_clip 作为检查项。在示例模型上，前臂旋转 180 度的手无法通过检查。空闲握姿也无法通过：左拇指位于护木内 2.8 cm，右掌压入手枪握把 1.2 cm，扳机手指的背面位于扳机护圈内 0.8 cm。示例保持原样，因此基准测试中的数字仍有原本的含义。

Motion：扫描并修复片段

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 会修复片段副本：

• pop：根据跳动帧周围的正常帧重新混合这些帧
• hold：通过手臂 IK 将手放回握持位置
• contact：移动手腕，直到该点接触标记位置
• clearance：保持手腕不动，使每个肘部绕肩部到手腕的连线转动，以刚好满足间隙所需的最小角度，并将这种转动平滑过渡到相邻帧
• anatomy：以相同方式转动肘部，直到肘部位于肩部下方且处于其弯曲范围内。然后将手腕转回其限制范围内，并将每个手指关节转回其活动范围内。它绝不会让手腕转动过度，以致步枪插入手背；无法通过这种方式修复的手腕会保持原样，之后的扫描会报告这一点。转动手腕会使手在握持位置上转动，因此如果握持位置必须完全精确，请添加 hold 检查。
• grip：不会修复；fix_clip 会报告修复前后的情况。握持位置在错误一侧时，需要重新设置握持位置。

它会报告修复前后的扫描结果。它还会列出手部必须到达手臂无法触及位置的帧，因为只有新姿势才能修复这些问题。

examples/motion_test.py 会在示例绑定上录制一个包含两种常见故障的片段。步枪滚转 75 度后又转回，且只在两端设置关键帧，因此两只手会在关键帧之间从步枪上漂移。一帧还会跳动 15 cm。扫描和修复结果如下：

检查项	修复前	修复后
左手在步枪上的漂移	2.27 cm	0.48 cm
右手在步枪上的漂移	1.67 cm	0.45 cm
手部最快速度（pop）	450 cm/s	33 cm/s
间隙	0.93 cm	0.0 cm

修复改动了 43 帧中的 34 帧，之后所有检查项均通过。它还标记了 6 帧，其中左臂与握持位置相差 0.46 cm，仍在 0.5 cm 的限制范围内。（在 0.3.1 之前，间隙读数为 0.0 cm：角点未能检测到步枪内部的前臂。）

安装

你需要 Blender 和 Python 3.10 或更高版本。我在安装了 Blender 5.2.2 和 Python 3.14 的 Windows 10 上进行了测试。目前还未测试 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" }
    }
  }
}

设置

变量	含义
POSELAB_BLENDER	Blender 的可执行文件路径；当它不在 PATH 或常见安装目录中时使用
POSELAB_RIGS	描述自定义绑定的 rigs.json（参见 examples/rigs.example.json）
POSELAB_OUT	Pose Lab 唯一写入的文件夹（渲染结果、保存的片段、工作进程日志）；默认值为 ~/.poselab

绑定

内置示例（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，标准输入/输出）。
• 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 对结果评分。脚本化预言机和什么都不做的对照组会检查评分器。参见 benchmarks/README.md。

benchmarks/runs/2026-10-09-toangtown-m24 在真实游戏骨架上测试这些检查本身：手部放在弹匣上的 8 个姿势，其中 7 个带有已知故障。Pose Lab 0.3.0 检出了 5 个故障，并以 40% 的深度读出穿模；0.3.1 检出了全部 7 个故障，且深度读数准确。

许可证

MIT