motion_capture_basics v1.0.0

name: motion_capture_basics description: "Motion capture basics for small productions: choose marker, inertial, or markerless capture, set up and calibrate a capture volume, run a clean session, clean jitter, gaps, and foot slide, and retarget the result onto a character rig. Use when someone asks how to do mocap, which mocap system or suit to use, why mocap data slides, jitters, or drifts, how to clean a BVH or FBX take, how to retarget mocap in Blender, Unreal, Unity, or Maya, or whether a shot should be mocap or keyframed."

Motion Capture Basics

Purpose

Take a small production from no mocap to a cleaned, retargeted clip on a character, without renting the wrong system or drowning in cleanup. The method is tool neutral. Vendor steps appear only where a step is truly vendor specific, and each one names its alternative. Read references/route-comparison.md when choosing a system. Read references/cleanup-and-retarget.md during cleanup and retargeting. Run bin/mocap_audit.py on any BVH take before cleaning it by hand.

Workflow

1. Decide mocap or keyframe first

• Mocap wins on realistic human motion in volume: locomotion sets, idle and fidget libraries, dance, sport, stunt and combat base motion, long dialogue body performance, and any job with dozens to hundreds of clips that share one human style.
• Keyframe wins on stylized or impossible motion: creatures, quadrupeds, flight, giant or tiny characters, squash and stretch cartoon timing, precise hand to prop contact on a hero shot, and single short clips where booking a session costs more than animating.
• The normal professional answer is both: mocap for the base, keyframe on a layer on top for face, hands, style, and the beats mocap missed. Plan for that layer from the start and keep the base untouched by it.
• Use this cost test: estimate cleanup minutes per finished second for the route you can afford. If cleanup plus session cost beats keyframe time for the same clip, keyframe it. Small teams get this backwards most often on single camera AI takes, which are cheap to record and expensive to clean.

2. Pick the capture route

• Passive optical (markers, infrared cameras): best precision, best for close contact, several performers, props, and final quality. Needs a stage, suits, and session calibration.
• Inertial (IMU suit or straps): no cameras, works anywhere, fast setup, live preview. Position drifts over a take and floor contact is weak.
• Markerless multi camera: no suits or markers, fast sessions, no drift. Needs cameras, even light, and solving power. Hands and tight contact are weaker than optical.
• Markerless single camera (AI from one video): cheapest, phone only. Depth is guessed, so occlusion, floor work, and contact fail first. Previz and simple frontal moves only, unless cleanup time is free.
• Full comparison, strengths, cleanup load per route, and a one pass decision list live in references/route-comparison.md.

3. Plan the session before anyone puts on a suit

• Write a take list: clip name, performer, action, start pose, end pose, prop, and whether it loops. Loop clips start and end in the same pose.
• Name files at capture time with project, performer, date, action, and take, for example harbor_ana_20261018_walkcycle_t03.fbx. Renaming a folder of Take_047 files later costs more time than naming them now.
• Cast for movement, not looks. The character inherits the performer timing, weight, and habits, not their face.
• Rehearse outside the volume until the move is boring. Session time goes to capture and calibration, not to choreography.
• Plan reset points: a marked start position on the floor, a neutral standing pose at the top of every take, and a spoken slate (clip name and take) that the reference video can hear.
• Record reference video of every take from a fixed camera outside the system. When data looks wrong later, the video settles whether the performer did it or the system invented it.

4. Set up and calibrate the volume

Optical route, in order:

• Pick the space: room for cameras outside the acting area, ceiling height for raised cameras, minimal foot traffic after calibration, no reflective floor (cover it with mats) and no springy floor.
• Place cameras high, angled down, overlapping so every point of the acting area is seen by at least two cameras, three for contact work.
• Prep the room: remove or cover reflective objects, bright windows, and stray infrared sources.
• Mask cameras: run the system auto mask, then check each camera view for leftover bright spots and mask them by hand.
• Wand the volume: select the correct wand size in the software (a wrong size scales the whole volume wrong), then walk a grid through the whole acting space, floor to head height and above, drawing slow figure eights. Coverage in each camera view matters, not raw sample count. Keep going until every camera view is covered edge to edge.
• Calculate, then read the result honestly. High wand error means wand again or move a camera. Do not capture a session on a calibration you already distrust.
• Set ground plane and origin last: place the calibration square where the origin belongs, long leg pointing along positive Z, short leg along positive X, level it, then set the ground plane. Confirm the floor height with a marker resting on the floor before suiting anyone.

Inertial route, in order:

• Charge everything, then check sensor placement against the vendor diagram. A rotated sensor reads as a bent limb all session.
• Clear the area of magnetic trouble where you can: large metal, powered speakers, and motor housings near the acting space.
• Calibrate in the pose the system asks for (straight standing pose or T-pose depending on the system), feet on your start mark, facing the marked forward direction. Hold it steady for the full count.
• Do a 10 second test: walk a square, return to the start mark, stop. If the character is not back where it started, fix setup now, not in cleanup.

Markerless routes:

• Multi camera: calibrate cameras with the vendor wand or board routine, then lock them down. Bumping one camera invalidates its calibration.
• Single camera: locked tripod, camera perpendicular to the performer, 2 to 6 meters back, whole body in frame head to toe, even neutral light, plain background, fitted clothing. Floor moves from a 3/4 angle. No zooms, no camera moves, no one else in frame.

Performer calibration, all routes:

• Measure and enter performer proportions when the system asks. Guessed limb lengths solve as joint errors.
• Record the calibration pose (ROM, T-pose, or neutral pose per system) and save it with the session. Retargeting needs it later.
• Check the live skeleton against the performer on three moves: arms overhead, a deep squat, and a turn. Catch a bad marker or sensor now.

5. Run the capture session

• Slate every take out loud and in the file name. Keep takes short. Several clean 20 second takes beat one long take with drift, fatigue, and one mistake at the end.
• Direct for silhouette: clear shapes, no arms glued to the torso, no hands hidden behind the back on moves the camera or solver must read.
• Watch the live solve on a second screen. Stop on the first sign of a flipped limb, a swapped marker, or drift. Recapturing 10 seconds now beats an hour of cleanup later.
• For contact moves (lifts, grapples, handshakes, sitting), slow the move down slightly and add a beat at the moment of contact. Solvers and animators both need that beat.
• Log takes as you go: good, usable with cleanup, or dead, with one short reason. Pick selects before anyone leaves, while a retake is still possible.
• Back up the session in two places before teardown. Raw takes are the one thing cleanup cannot recreate.

6. Audit the raw take before cleaning

• Export or convert a select to BVH when your pipeline allows it and run the audit script:

python3 bin/mocap_audit.py take.bvh

Add --json for machine readable output. It reports frames, duration, root path, root jump frames (likely pops), the worst joints by jitter, and foot contact frames with slide speed for joints named foot, toe, or ankle.

• Treat the numbers as a map, not a verdict. Units and scale differ per exporter, so compare takes against each other and against a take you already know is clean.
• Open the take beside its reference video. Mark sections in three buckets: clean, cleanable, dead. Price the cleanable sections honestly against a retake using the recapture tests in references/cleanup-and-retarget.md.

7. Clean in order

Full method in references/cleanup-and-retarget.md. The order is:

1. Labels and solve: fix swapped or missing markers and joints first.
2. Gaps: interpolate short occlusion gaps, pose and blend long ones.
3. Pops and bumps: refit the bad section and blend through it. Pops are spikes, jitter is constant shake. They take different fixes.
4. Jitter: lightest filter pass that calms the joint, rotation curves first, hands on a lighter pass or none.
5. Contacts: pin each foot for its planted frames, adjust the root so knees do not lock, release on the lift frame.
6. Root and floor: floor at the planted foot, real travel kept, drift corrected per section between reset points.
7. Polish on a separate animation layer so cleanup stays redoable.

• Save versioned copies before every destructive pass, with the filter or fix named in the file name.
• Check cleanup at full speed, half speed, and frame by frame on the worst second. Each speed exposes a different class of error.

8. Retarget onto the character rig

• Preflight before any tool runs: source and target rest poses match (both T-pose or the same A-pose), both at origin facing the same way, correct scale, pelvis as retarget root, chains defined for spine, head, both arms, and both legs with matching names.
• Unreal Engine 5: build an IK Rig per skeleton (retarget root on the pelvis, named chains), pair them in an IK Retargeter, match the retarget pose, preview a slow walk and one fast action, fix errors at chain or pose level, then batch export. The old Retarget Manager flow is deprecated in UE5 in favor of this system.
• Blender: import BVH or FBX, retarget with a retarget addon or Copy Rotation constraints plus a hip location constraint, bake to the target rig, clean in the Graph Editor, hold foot pins on an additive NLA strip, export FBX with Bake Animation for engine use.
• Unity: use the Humanoid Avatar path for humanoids. Configure the Avatar muscle mapping by hand and check the T-pose in the configure view before trusting any clip.
• Maya and MotionBuilder: define both characters with HumanIK, set source and target, and check characterization on the calibration pose before baking.
• Diagnose by symptom: constant bent arms mean rest pose mismatch, skating feet mean leg chain or root height trouble, twisted forearms mean bone roll mismatch, hands missing a prop mean the target arm is shorter and needs an IK reach fix or a prop moved to the hand.
• Spot check the first, middle, and last clip of every batch on the real character, in the real scene, at game or render camera distance.

9. Deliver and archive

• Deliver cleaned, retargeted clips with a plain text manifest: clip name, source take, performer, route used, cleanup passes applied, and known flaws kept on purpose.
• Archive raw takes, calibration files, the performer calibration pose, reference video, and the take log together. A retarget six months later needs all of them.
• Keep frame rate and units consistent across a project. Convert once, at import, and write the project rate on the manifest.

Output Contract

For a route recommendation, return: the recommended route, the runner up, what each costs in setup, space, and cleanup time, and the one risk that would change the pick.

For a session plan, return: take list with file names, volume or space checklist for the chosen route, calibration steps in order, performer prep, and the backup step.

For cleanup, return: the audit output or a summary of it, the fixes applied in cleanup order, the frames or sections left flawed with a reason, and whether recapture beats further cleanup.

For a retarget, return: the preflight results, the chain mapping used, the symptom checks performed (walk plus one fast action), and the batch spot check results.

Always name the file format at each handoff (BVH, FBX, or C3D) and the frame rate. Never hand over a clip described only as done.

Operating Rules

• Never invent system specs, prices, accuracy figures, or frame rates. State the property that matters (precision rank, drift behavior, occlusion behavior) and tell the user to verify current numbers with the vendor before buying.
• Never promise that a cheap route cleans up into a pricey route result. Say what the route cannot record: depth, contact, fingers, or floor.
• Never filter a whole clip on a setting tested only on a still section. Test on the fastest 2 seconds first.
• Never edit polish into the cleaned base layer. Layers keep cleanup redoable and retargets reusable.
• Never delete raw takes to save space. Raw takes plus calibration are the project. Cleaned clips can always be rebuilt from them.
• If reference video and data disagree, believe the video about what the performer did and believe the data about nothing until labels, scale, and calibration have been rechecked.
• When two performers must touch for most of a shot and the budget only covers single camera AI, say plainly that the shot needs a different route, a rental, or a keyframe plan. Do not schedule the cleanup fantasy version.