Pose Lab

Each arm against the human arm's limits. Rules: the elbow stays at least 2 cm below the shoulder while the hand works the gun; the elbow is a hinge bent 5 to 150 degrees; the wrist stays within 30 degrees of the forearm's line and inside its joint range (flexion 80, extension 70, radial 20, ulnar 30: the AAOS normal values); the hand's roll belongs to the forearm, not the wrist joint: the forearm turns at most 80 degrees each way from thumb up (pronation and supination, forearm_rotation_deg), and on a rig with forearm twist bones no link along the forearm rolls more than 50 degrees (forearm_links_deg: the skin wrings there); without twist bones, the wrist's own twist against the idle grip stays within 30 (wrist_twist_deg). Each finger joint curls only toward the palm within its range (knuckle -30..100, middle joint -5..110, end joint -10..90) and stays in the finger's own plane: no hyperextended or twisted finger. The thumb's knuckle bends -10..60 and its end joint -15..90 across the palm; its base spreads at most 80 from the index metacarpal and sits at most 20 behind the palm. A rig's limits, finger_limits and thumb_limits override these. Each rule reads the value as reported (whole degrees). ok false lists every rule a pose breaks. Fix a broken rule by moving the rifle, the grip or the elbow's pole, never by bending a joint further. arm_ranges gives the research behind each limit.

The research behind anatomy's limits: for each joint of the arm (shoulder, elbow, forearm, wrist, finger knuckle, middle and end joints, thumb), the AAOS normal range (the 1965 table; tables_differ shows where other tables disagree), the range daily tasks use (Morrey 1981, Palmer 1985, Ryu 1991, Bain 2015), the value anatomy checks, and why it differs from the standard where it does. Full citations included. Needs no rig.

Every check on a clip in one summary for a gate: the worst clearance and when, the frames that break an arm or finger rule, the frames a hand in hold_sides is not holding, and each frame's numbers.

How deep the rifle sits inside the arms (capsules: forearm 3 cm, palm 1.8 cm, finger segments 0.75 cm). worst_cm 0 means nothing touches. The deepest contacts by segment, with the rifle point in the frame.

What is loaded and the conventions every tool uses.

The distance between two points, cm, and b minus a in the frame.

How squarely a surface faces the eye: facing 1 square on, 0 edge on, below 0 turned away.

Mends a clip against the checks and stores a new clip (out, default <clip>_fixed): pops are blended again from the good frames round them; a hold puts the hand back on its grip; a contact moves the wrist until the point touches its mark; clearance swings each elbow about its shoulder-wrist line (the wrist kept) by the least angle that clears, spread over neighbouring frames; anatomy swings the elbow the same way until it sits under the shoulder inside its bend, then turns the wrist back inside its limits and each finger joint back inside its range. Reports the scan before and after.

How each hand touches the rifle: with the palm or with the back. A hand holds with its palm and the palm sides of its fingers. The back of the hand toward the rifle, or the rifle inside the back of the hand or of a finger, is a physical error; clearance with palms and fingers ignored never shows it. For each hand: touching (some part within hold_within_cm), holding (touching, the palm facing the rifle and its surface within palm_within_cm: palm_gap_cm; a fingertip on the rifle with the palm off it is not holding), palm_faces_rifle (1 square on, below 0 the back of the hand toward it), palm_contact_cm and back_contact_cm (the deepest rifle point inside the hand on each side), and bad: every rule broken. ok false lists them. The palm side may press in up to palm_max_cm (the capsules are rounder than a palm); the back side only up to back_max_cm. hold true: a hand that is not holding breaks a rule (use it to check a hand really holds something). Fix a wrong-side hold by turning the hand or the grip, not by moving a finger through the rifle. grasping: the thumb and a finger pinch the rifle from opposite sides, each within contact_cm of it and their directions from its surface at least 180 - 2 atan(friction) degrees apart (127 at friction 0.5); grasp_opposition_deg is the widest thumb to finger angle, digits_touching the digits on the rifle. grasp true: a hand that is not grasping breaks a rule (use it for a hand meant to hold a part, such as a magazine).

The rigs to load: the built-in sample and those in the rigs file (POSELAB_RIGS).

Adds a clip from a file: .pose.json bone data, an FBX animation, or a BVH (for example a text-to-motion model's output). A relative path is taken from the rigs file's folder. Reports how well its skeleton fits.

Loads a rig: the arms on their idle pose, the rifle on the gun bone, its clips. Returns the frames, sign rules, named points, clips and moving parts. Call first.

Moves the rifle from where it stands: roll + turns its right side up (about the bore); swing + takes the muzzle left, pitch + the muzzle up (about the pivot); right, forward, up move it in the view, cm. The hands in keep_hands keep their hold. Returns how far each hand ended from its hold and the barrel's angle off the view line.

Draws a moving part of the rifle (such as carrier) back along the barrel, cm from home.

The arms as a clip has them at a time in seconds. The rifle follows the gun bone; its parts stay where move_part left them.

The arms back on the idle pose, every rifle part home.

Puts a wrist on a point by arm IK; the hand keeps its turn. Returns how far the wrist ended from the point. Trying poles while the wrist stays put moves only the elbow: a way to clear a forearm.

Builds a clip from poses you set: start (a name), key (the current pose at a time in seconds), stop (bakes the frames, each bone eased from key to key). Between keys the bones blend by rotation, so hands can drift off the rifle between keys.

Renders the pose as one labelled contact sheet: eye is the player's camera (90 degrees, 5 cm near plane); right, left, top and front look at the rifle from outside. Every tile is a Blender view, labelled so.

Plays another rig's clip on this rig with one hand held on this gun's own hold (its rest hold, or mark) by arm IK, fingers mended: shared motion, the gun's own grip. keep_from_s..keep_to_s: a span the hand leaves the gun (a reload), kept as the clip has it. Stores the result as out (default <clip>_retarget).

Writes a clip to the output folder's clips/: pose.json bone data, and fbx for a game engine.

Plays a clip frame by frame and runs each check. Reports for each check whether it passed, the worst value and when, and the time spans where it fails.

Where a point falls on a 90 degree, 16:9 screen from the eye: x and y from -1 to 1, and whether it is on screen.

Moves one hand frame by frame by the given deltas (gun frame, cm): a hand that holds a part whose track changed follows the part's new path. The hand keeps its turn against the gun, its elbow its direction, its fingers their curl; the wrist and fingers are mended.

Saves or loads a named pose (the arms and the rifle's parts).

Searches rifle moves from the current pose for one meeting every goal, and leaves the scene there. Reports each goal at the best move and how often it was met across samples: a goal never met is a fact of the geometry.

Searches a hand's hold on the rifle: the palm on mark (moved along the barrel), the elbow toward each pole. A hold counts when the palm holds the rifle (grip), nothing clips past clearance_max_cm (ignore: declared contacts), every arm and finger rule holds, and the view stays within view_budget. The nearest hold to the mark that counts wins and the rig is left in it; the table shows what failed where.

Turns one bone by degrees about an axis through its head; the bones below it follow and nothing else moves. Use it to bend or straighten a finger joint, turn a wrist, or turn a whole arm at the shoulder. bone: a bone's name (an unknown name lists them all). The two signs of degrees turn opposite ways. The rifle does not move: use move_gun.

The share of the player's view the arms cover (all, its lower left third, its bottom middle third): the arms rendered alone from the eye as a mask. A forearm or sleeve that fills the lower left hides the gun and the world.

The share of a small disc round a point that the eye sees with nothing (arms, rifle) in the way.

Where bones, fingertips (<finger>_tip_<l|r>) and rig points are, in a frame.