Pose Lab

Pose Lab

Measured spatial answers for posing first-person arms and a rifle in Blender.

Models are weak at judging 3D space from pictures: which side of a rifle faces the eye, whether a finger sits inside the receiver, whether any turn of the gun can ever show its ejection port. Pose Lab gives a model numbers instead. It reports positions in named frames and how deep anything clips. It measures how squarely a surface faces the eye and what the eye can see. Its solver searches rifle moves against goals and reports which goals no move can meet. For animation, it scans a clip frame by frame against the same checks and mends what fails.

I built it while hand-making chamber checks for my first-person shooter. One question took me several full Blender runs: can turning the rifle show its ejection port to the eye? With Pose Lab it is one solve call. On my game's AK rig, turning alone met the goal in 0 of 60 samples. That is a fact of the geometry: the eye looks along the barrel. Turning and moving the rifle met each goal on its own, but no sample of 400 met all four goals together. So that check needs a new hand pose, not only a new rifle position. On the built-in sample rig, turning alone also met the port goal in 0 of 60 samples, and turning and moving met every goal in 9 s.

What it gives a model

Frames and signs

Every position goes in and comes out in a named frame, so no one has to guess axes:

• gun: the gun bone as it stands, Unreal-style axes, cm: +X the gun's left, +Y along the barrel, +Z up (the default)
• arms: the arms' space, Unreal-style axes, cm
• view: from the eye, cm: +X right, +Y forward, +Z up

Turns use the player's words: roll + turns the gun's right side up, swing + takes the muzzle left, pitch + the muzzle up. Moves (right, forward, up) are in the view.

A hand round its grip touches the rifle on the idle pose already (a finger on the trigger, fingers round the handguard). Call clearance at pose_idle for that baseline, and leave those segments out with ignore wildcards. On the built-in sample the left thumb sits 2.7 cm inside the handguard at idle. clearance measures to the rifle's surface (inside or out by ray parity), so it sees a body part inside a flat face between the mesh's corner points.

Arm rules (anatomy)

A pose can clear the rifle and still be one no human arm can take. anatomy checks each arm against these limits:

The wrist and elbow ranges are the AAOS normal values, from the AAOS 1965 table as reprinted in Greene and Heckman 1994. Other tables differ, by 10 to 25 degrees for the fingers and thumb. The 30 degree wrist line, the 5 degree elbow minimum and the elbow under the shoulder are working rules for this game's look of a hand on a gun, not joint limits. The wrist rule is stricter than daily tasks: Ryu 1991 found daily tasks use up to 60 degrees of extension and 40 of ulnar deviation. The finger limits allow 10 more flexion than AAOS at the knuckle and the middle joint; docs/ANATOMY.md says why the defaults stay that way. It gives each joint's standard and functional range, the value checked, and the sources (AAOS; Eaton; Morrey 1981; Palmer 1985; Ryu 1991; Hume 1990; Bain 2015; Soucie 2011). arm_ranges returns the same data to a model.

The anatomy reply lists, for each arm, the elbow's height under the shoulder, the elbow's bend, the wrist's bend split into flexion and radial deviation, the wrist's twist, each finger joint's curl and twist, and bad: every rule the pose breaks. Each rule reads the value as reported: angles to the degree, the elbow's height to 0.1 cm. A rig's limits, finger_limits and thumb_limits entries in rigs.json override any value. solve takes {"type": "anatomy"} as a goal.

move_gun, reach and fix_clip place hands with a turn. They move the hand's twist into the forearm, so the wrist joint only bends: a 60 degree rifle roll with the hands kept reads no wrist twist.

Fix a broken rule by moving the rifle, the grip or the elbow's pole. Do not bend a joint further.

The sample rig's idle grip breaks the wrist rule: the left wrist bends 44 degrees off the forearm and the right 58. fix_clip with an anatomy check brings the left to 29. It leaves the right at 58: every turn that mends it puts the rifle inside the back of the palm, so that hand needs a new grip or elbow, not a wrist turn.

Hand contact (grip)

A hand holds the rifle with its palm and the palm sides of its fingers. clearance is usually run with the palms and fingers left out, since a grip touches the rifle there. That also hides a hand on the wrong side. grip checks the contact itself, for each hand:

Each finger segment's palm side is the side it curls toward. The thumb's pad faces sideways, so its contacts count toward the palm side's depth only. The reply gives each hand's touching (some part within hold_within_cm), holding (touching, the palm facing the rifle and its surface within palm_within_cm), palm_gap_cm, palm_faces_rifle, palm_contact_cm, back_contact_cm, where the back contact is, and bad. With hold true, a hand that is not holding breaks a rule.

A hand meant to hold a part (a magazine, a grip) must also pinch it: with grasp true, the thumb and a finger must touch it (skin within contact_cm, 0.3) from opposite sides, their directions from its surface at least 180 - 2 atan(friction) degrees apart (127 at friction 0.5). The reply gives grasping, grasp_opposition_deg and digits_touching. A hand resting on the rifle, or one that hooks a handle, is not meant to pinch: leave grasp off. solve takes {"type": "grip"} as a goal and scan_clip as a check. On the sample rig, a hand turned 180 degrees about its forearm fails it. So does the idle grip: the left thumb sits 2.8 cm inside the handguard, the right palm presses 1.2 cm into the pistol grip, and the trigger finger's back sits 0.8 cm inside the trigger guard. The sample stays as it is, so the benchmark's numbers keep their meaning.

Motion: scan and fix clips

scan_clip plays a clip frame by frame and runs checks on each frame. The checks are the solver's goals (clearance, anatomy, grip, faces_eye, visible, on_screen, barrel) and three more:

• contact: a point of the hand on its mark, such as a fingertip on the charging handle (a, b, max_cm