Live Mocap - Real-Time Motion Capture for Blender

Real-time webcam-based motion capture for Blender using MediaPipe and OpenCV

Transform your webcam into a motion capture studio! Live Mocap captures your body movements in real-time and retargets them to any Blender armature — no expensive suits or sensors required.

✨ Features

🎥 Real-Time Capture — Non-blocking, live motion tracking at 30 FPS
🦴 Auto Bone Mapping — Automatic detection for Rigify, Unity, and common rigs
💾 Save/Load Mappings — Reuse bone configurations across projects
🎚️ Smoothing Filters — EWMA smoothing for natural, jitter-free motion
📊 Confidence Gating — Reject low-quality tracking data automatically
🦶 Foot Lock Filter — Reduce foot sliding in animations
⏺️ Live Recording — Insert keyframes in real-time
🎬 Bake to Action — Export captured motion as reusable Actions
📷 Camera Feed Overlay — Optional viewport preview of webcam feed
🔧 Modular Design — Easy to extend and customize

📦 Installation

Prerequisites

Blender 3.6 or higher (4.x recommended)
Webcam (built-in or USB)

Step 1: Install Python Dependencies

Open a terminal/command prompt and navigate to Blender's Python directory:

Windows:

cd "C:\Program Files\Blender Foundation\Blender 4.x\4.x\python\bin"
python.exe -m pip install opencv-python mediapipe

macOS:

cd /Applications/Blender.app/Contents/Resources/4.x/python/bin
./python3.11 -m pip install opencv-python mediapipe

Linux:

cd /path/to/blender/4.x/python/bin
./python3.11 -m pip install opencv-python mediapipe

Step 2: Install the Add-on

Option A: Install as Folder (Recommended for Development)

Copy the live_mocap_addon folder to your Blender add-ons directory:
- Windows: %APPDATA%\Blender Foundation\Blender\4.x\scripts\addons\
- macOS: ~/Library/Application Support/Blender/4.x/scripts/addons/
- Linux: ~/.config/blender/4.x/scripts/addons/
Restart Blender

Option B: Install as ZIP

Zip the live_mocap_addon folder
In Blender: Edit → Preferences → Add-ons → Install
Select the .zip file
Restart Blender

Step 3: Enable the Add-on

Go to Edit → Preferences → Add-ons
Search for "Live Mocap"
Enable Animation: Live Mocap

🚀 Quick Start

1. Open the Panel

In the 3D Viewport, press N to open the sidebar
Click the Mocap tab

2. Set Up Your Rig

Select your armature in the scene
Click Select Target in the Mocap panel
Click Auto-Fill Bone Map to automatically map landmarks to bones

3. Start Capturing

Click Start Capture
Your webcam will activate and your character will mirror your movements!

4. Record Animation

Click Start Recording to insert keyframes
Perform your movements
Click Stop Recording when done
Click Bake to Action to create a reusable Action

🎛️ Panel Overview

Section	Description
Target	Select armature, adjust scale and offset
Bone Mapping	Configure landmark → bone assignments
Capture	Camera settings, FPS, module toggles
Record	Start/stop keyframing, bake to Action
Filters	Smoothing, confidence threshold, foot lock
Utilities	Reset pose, help dialog, dependency check

🦴 Bone Mapping

Auto-Mapping

Works out of the box with:

Rigify rigs
Unity Humanoid rigs
Standard naming conventions (spine, arm, leg, etc.)

Manual Mapping

Click + to add a mapping
Select a MediaPipe landmark (e.g., LEFT_SHOULDER)
Select the target bone
Enable the checkbox to activate

Save/Load Mappings

Save Map: Export your bone configuration as JSON
Load Map: Import a saved configuration

⚙️ Settings & Filters

Capture Settings

Setting	Default	Description
Camera Index	0	Webcam device number
Target FPS	30	Capture frame rate
Pose Module	✓	Enable body tracking
Hands Module	✗	Enable hand tracking
Face Module	✗	Enable face tracking

Filters

Filter	Default	Description
Smoothing	0.5	EWMA smoothing factor (0 = no smoothing, 1 = max)
Confidence	0.5	Minimum confidence threshold
Foot Lock	✓	Reduce foot sliding artifacts

📁 Project Structure

live_mocap_addon/
├── __init__.py           # Blender add-on entry point
├── addon_prefs.py        # User preferences
├── properties.py         # Data models (PropertyGroups)
│
├── operators/            # User actions (15 operators)
│   ├── capture_start.py  # ⭐ Main modal operator
│   ├── autofill_map.py   # Auto bone mapping
│   ├── record_start.py   # Start keyframing
│   └── ...
│
├── panels/               # UI components
│   ├── main.py           # Main N-panel
│   └── ...
│
├── runtime/              # Live capture systems
│   ├── capture.py        # OpenCV camera
│   ├── trackers.py       # MediaPipe tracking
│   ├── retarget.py       # Landmark → bone math
│   ├── filters.py        # Smoothing, confidence, foot lock
│   └── ...
│
├── io/                   # File operations
│   ├── json_maps.py      # Save/load bone mappings
│   └── export.py         # FBX export
│
└── utils/                # Shared utilities
    ├── coords.py         # Coordinate transforms
    └── naming.py         # Bone name matching

🔧 Troubleshooting

Dependencies Not Found

Click Help / Dependency Check in the panel
If OpenCV or MediaPipe shows ✗, reinstall using the commands above
Make sure you're using Blender's bundled Python, not system Python

Camera Not Opening

Check that no other application is using the webcam
Try a different camera index (0, 1, 2...)
Verify camera permissions (especially on macOS)

Tracking Quality Issues

Ensure good lighting (natural light works best)
Stand back so your full body is visible
Wear contrasting colors against your background
Increase smoothing factor for jittery motion

Performance Issues

Lower target FPS to 24 or 20
Disable unused modules (hands, face)
Close other resource-intensive applications

🎯 Use Cases

Animation Pre-viz — Quick blocking and movement reference
Indie Game Dev — Affordable motion capture for characters
Education — Learn animation and rigging concepts
Content Creation — VTuber-style live animation
Prototyping — Rapidly test animation ideas

🗺️ Roadmap

📚 Documentation

Document	Description
QUICKSTART.md	10-minute setup guide
STRUCTURE.md	Code architecture
DEVELOPMENT.md	Developer guide
PROJECT_OVERVIEW.md	Complete project overview

🤝 Contributing

Contributions are welcome! Here's how to get started:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

See DEVELOPMENT.md for extension points and code guidelines.

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

🙏 Acknowledgments

MediaPipe — Google's ML framework for real-time pose detection
OpenCV — Open source computer vision library
Blender — The free and open-source 3D creation suite
Rokoko Studio Live — Inspiration for plugin architecture

Built with ❤️ for the Blender community
Happy Motion Capturing! 🎬✨

Name		Name	Last commit message	Last commit date
live_mocap_addon		live_mocap_addon
rokoko-studio-live-blender-master		rokoko-studio-live-blender-master
.gitattributes		.gitattributes
.gitignore		.gitignore
ARCHITECTURE_DIAGRAM.md		ARCHITECTURE_DIAGRAM.md
CAMERA_FEED_QUICKSTART.md		CAMERA_FEED_QUICKSTART.md
CAMERA_FEED_VISUALIZATION.md		CAMERA_FEED_VISUALIZATION.md
CURRENT_STATUS.md		CURRENT_STATUS.md
FIX_NO_OVERLAY.md		FIX_NO_OVERLAY.md
IMPLEMENTATION_SUMMARY.md		IMPLEMENTATION_SUMMARY.md
LICENSE		LICENSE
Pose.ipynb		Pose.ipynb
QUICK_REFERENCE.md		QUICK_REFERENCE.md
README.md		README.md
TESTING_CAMERA_FEED.md		TESTING_CAMERA_FEED.md
TROUBLESHOOTING_NO_OVERLAY.md		TROUBLESHOOTING_NO_OVERLAY.md
debug_viewport.py		debug_viewport.py
live_mocap_addon.zip		live_mocap_addon.zip
pose.py		pose.py
pose_landmarker_heavy.task		pose_landmarker_heavy.task
prompt.md		prompt.md

Latest commit

History

Folders and files

Repository files navigation