MediaPipe Pose与Unity集成：虚拟角色控制教程

1. 引言

1.1 学习目标

本文将带你完成一个完整的项目实践：使用 Google MediaPipe Pose 实现高精度人体骨骼关键点检测，并将其数据实时传输至 Unity 引擎，驱动虚拟角色进行动作同步。通过本教程，你将掌握：

如何部署和调用 MediaPipe Pose 模型进行本地化姿态估计
提取 33 个 3D 关键点的坐标数据（x, y, z, visibility）
构建轻量级 Web 服务接口输出姿态数据
在 Unity 中解析并映射关键点到 humanoid 骨骼系统
实现低延迟、高响应的虚拟角色动作控制系统

最终效果可应用于虚拟主播、动作捕捉训练、体感游戏等场景。

1.2 前置知识要求

Python 基础（Flask、OpenCV、MediaPipe）
Unity C# 脚本基础
HTTP 网络请求概念
了解基本的人体骨骼结构（如肩、肘、髋）

1.3 教程价值

不同于依赖昂贵动捕设备或云端 API 的方案，本文提供一套低成本、全本地运行、零依赖外部服务的解决方案。所有计算均在 CPU 上完成，适合边缘设备部署，具备极强的工程落地能力。

2. MediaPipe Pose 核心功能详解

2.1 技术原理简介

MediaPipe Pose 是 Google 开发的一套轻量级、高精度的姿态估计算法框架，基于 BlazePose 模型架构。它能够在单帧图像中检测出33 个 3D 人体关键点，包括：

面部：鼻子、左/右眼、耳
上肢：肩、肘、腕、手部关键点
躯干：脊柱、骨盆
下肢：髋、膝、踝、脚尖

这些关键点以归一化坐标（0~1）表示，在图像空间中形成完整的骨架拓扑结构。

💡技术优势对比传统方法
相比 OpenPose 等基于多人检测+热图回归的方法，MediaPipe Pose 采用“两阶段”设计：
人体检测器先定位人体 ROI（Region of Interest）
姿态回归模型在裁剪区域内精细预测 3D 坐标
这种设计大幅提升了推理速度，尤其适合单人实时应用。

2.2 关键特性分析

特性	描述
模型大小	<5MB，内置于`mediapipe`Python 包
推理平台	支持 CPU / GPU / TPU，本镜像优化为 CPU 版
输出维度	33×(x, y, z, visibility)，z 表示深度相对值
帧率表现	CPU 上可达 30 FPS（640×480 输入）
可视化支持	自带骨架连线绘制函数

2.3 数据格式说明

MediaPipe 返回的关键点是一个landmark列表，每个元素包含以下字段：

{ "x": float, # 归一化横坐标 (0~1) "y": float, # 归一化纵坐标 (0~1) "z": float, # 深度（相对距离，越小越近） "visibility": float # 置信度 (0~1) }

例如，左肩对应索引为 11，右肩为 12，可用于判断手臂抬升角度。

3. 后端服务搭建：暴露姿态数据接口

3.1 环境准备

确保已启动镜像环境，包含以下库：

pip install flask opencv-python mediapipe numpy

创建项目目录结构：

pose_server/ ├── app.py ├── static/ └── templates/index.html

3.2 完整后端代码实现

# app.py import cv2 import json import numpy as np from flask import Flask, request, jsonify, render_template import mediapipe as mp app = Flask(__name__) mp_pose = mp.solutions.pose pose = mp_pose.Pose( static_image_mode=False, model_complexity=1, enable_segmentation=False, min_detection_confidence=0.5 ) @app.route('/') def index(): return render_template('index.html') @app.route('/detect', methods=['POST']) def detect_pose(): file = request.files['image'] img_bytes = np.frombuffer(file.read(), np.uint8) image = cv2.imdecode(img_bytes, cv2.IMREAD_COLOR) rgb_image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB) results = pose.process(rgb_image) if not results.pose_landmarks: return jsonify({"error": "No person detected"}), 400 landmarks = [] for lm in results.pose_landmarks.landmark: landmarks.append({ "x": float(lm.x), "y": float(lm.y), "z": float(lm.z), "visibility": float(lm.visibility) }) # 绘制骨架图 annotated_image = image.copy() mp.solutions.drawing_utils.draw_landmarks( annotated_image, results.pose_landmarks, mp_pose.POSE_CONNECTIONS ) _, buffer = cv2.imencode('.jpg', annotated_image) img_str = buffer.tobytes().hex() return jsonify({ "landmarks": landmarks, "image_hex": img_str # 返回可视化结果 }) if __name__ == '__main__': app.run(host='0.0.0.0', port=5000)

3.3 前端页面模板（简化版）

<!-- templates/index.html --> <!DOCTYPE html> <html> <head><title>Pose Detection</title></head> <body> <h2>上传图片进行姿态检测</h2> <input type="file" id="imageInput" accept="image/*"> <div id="result"></div> <script> document.getElementById('imageInput').onchange = function(e) { const file = e.target.files[0]; const formData = new FormData(); formData.append('image', file); fetch('/detect', { method: 'POST', body: formData }) .then(res => res.json()) .then(data => { if (data.error) { document.getElementById('result').innerHTML = '未检测到人物'; } else { document.getElementById('result').innerHTML = `<img src="data:image/jpg;base64,${btoa(String.fromCharCode(...new Uint8Array( data.image_hex.match(/[\da-f]{2}/gi).map(h => parseInt(h, 16)) )))}" />`; } }); }; </script> </body> </html>

3.4 启动与测试

运行python app.py
浏览器访问http://<your-host>:5000
上传全身照，查看返回的 JSON 数据与骨架图

✅ 成功标志：返回包含 33 个关键点的 JSON 对象，并显示火柴人连线图

4. Unity 客户端开发：接收并驱动虚拟角色

4.1 Unity 工程配置

创建 3D 项目
导入任意 Humanoid 模型（推荐使用 Mixamo 动画角色）
设置 Avatar 类型为Humanoid
添加UnityEngine.Networking和JsonUtility支持

4.2 C# 脚本：HTTP 请求与数据解析

// PoseReceiver.cs using System.Collections; using UnityEngine; using UnityEngine.Networking; using Newtonsoft.Json.Linq; public class PoseReceiver : MonoBehaviour { public Transform[] bodyParts; // 按顺序绑定：Head, LeftShoulder, RightShoulder, ... public string serverUrl = "http://<your-ip>:5000/detect"; private Vector3[] targetPositions; void Start() { targetPositions = new Vector3[bodyParts.Length]; StartCoroutine(FetchPoseData()); } IEnumerator FetchPoseData() { while (true) { yield return new WaitForSeconds(0.1f); // 每 100ms 更新一次 var form = new WWWForm(); var screenshot = ScreenCapture.CaptureScreenshotAsTexture(); byte[] bytes = screenshot.EncodeToJPG(); form.AddBinaryData("image", bytes, "capture.jpg"); using (UnityWebRequest www = UnityWebRequest.Post(serverUrl, form)) { yield return www.SendWebRequest(); if (www.result == UnityWebRequest.Result.Success) { ParseAndApplyPose(www.downloadHandler.text); } } } } void ParseAndApplyPose(string jsonResponse) { JObject json = JObject.Parse(jsonResponse); var landmarks = json["landmarks"].ToArray(); // 映射关键点（示例：仅处理头部和双肩） UpdateBodyPart(0, landmarks[0], Camera.main.pixelWidth, Camera.main.pixelHeight); // Nose UpdateBodyPart(1, landmarks[11], Camera.main.pixelWidth, Camera.main.pixelHeight); // L Shoulder UpdateBodyPart(2, landmarks[12], Camera.main.pixelWidth, Camera.main.pixelHeight); // R Shoulder UpdateBodyPart(3, landmarks[13]); // L Elbow UpdateBodyPart(4, landmarks[14]); // R Elbow } void UpdateBodyPart(int index, JToken landmark, float width = 1920, float height = 1080) { float x = landmark["x"].Value<float>() * width; float y = height - landmark["y"].Value<float>() * height; // Y轴翻转 float z = landmark["z"].Value<float>() * 100; // 缩放深度 targetPositions[index] = new Vector3(x, y, z); // 将屏幕坐标转换为世界坐标并驱动骨骼 Vector3 worldPos = Camera.main.ScreenToWorldPoint(new Vector3(x, y, 5.0f)); bodyParts[index].position = Vector3.Lerp(bodyParts[index].position, worldPos, 0.1f); } }

4.3 关键点映射建议表

MediaPipe 索引	关节名称	Unity 映射骨骼
0	鼻子	Head
11	左肩	LeftUpperArm
12	右肩	RightUpperArm
13	左肘	LeftLowerArm
14	右肘	RightLowerArm
23	左髋	LeftUpperLeg
24	右髋	RightUpperLeg

⚠️ 注意事项：
Unity 使用的是局部骨骼空间，需结合 IK 或动画重定向技术实现自然动作
当前为简易演示，实际项目建议使用 FinalIK 插件提升真实感

5. 性能优化与常见问题

5.1 延迟优化策略

方法	说明
图像降采样	发送前将截图缩放到 640×480 减少传输时间
增加缓存机制	Unity 端插值平滑运动，避免抖动
使用 WebSocket 替代 HTTP	长连接减少握手开销（进阶）
多线程处理	在后台线程执行网络请求