简介基于Python和MediaPipe在Unity中实现姿态追踪的高分毕业设计项目核心解决跨平台人体姿态捕捉与三维应用联动的需求面向计算机相关专业正在准备毕业设计的学生以及需要真实项目来练手的开发者同时适合作为课程设计或期末大作业。压缩包共7个文件包含2个Python脚本分别承担姿态识别与Unity通信任务、1个文本说明、1个7z配套资源、1个PNG示意图、1个Markdown笔记和1段FLV演示视频整体大小71.26MB结构层次清楚可按文档指引快速定位。目前已有144人学习下载项目经导师指导并严格调试确保环境配置后可以运行。读者可以拿到完整可用的源码、双端联调思路、注释笔记和演示录屏既能直接运行观察姿态追踪效果也能结合代码理解MediaPipe关键点提取、坐标数据传输与Unity端接收处理的完整链路便于二次开发和答辩展示。1. 为什么把姿态追踪从 Python 搬到 Unity最近在做 Unity 中的虚拟人驱动 demo对比了 Kinect、OpenPose、MediaPipe 几条技术路线最后选了 MediaPipe 做姿态估计、UDP 把关键点坐标喂给 Unity。选择 MediaPipe 的核心原因很直接单人姿态检测在 CPU 上就能跑到 30 FPS 以上不需要 GPU 推理而 OpenPose 在这个精度档位上要重得多。Kinect 硬件方案在毕设和课程设计场景里成本太高而且 Unity 侧的 SDK 接入并不比自己写 UDP 解析简单多少。这篇文章要拆的项目是一套完整的 Python 与 Unity 姿态追踪源码包含unity.py、udptracker.py两个核心脚本外加一个Track - 副本.7z的 Unity 工程包。unity.py负责在 Unity 侧接收并解析骨骼点数据udptracker.py是 Python 端的 MediaPipe 检测与数据发送脚本AnimationFile.txt里记录了 Unity 动画片段与骨骼节点的对应关系。适合正在做毕业设计、课程设计或者想快速在 Unity 里拿到人体骨骼数据的开发者如果你是第一次接触 MediaPipe 和 Unity 的跨语言通信这套代码的拆解过程基本能覆盖从环境配置到联调踩坑的完整链路。2. Python 端 MediaPipe 姿态检测与 UDP 数据包装2.1 MediaPipe Pose 模型的关键点定义与选型逻辑MediaPipe Pose 输出 33 个人体关键点每个点包含归一化的 x、y、z 坐标和可见性分数 visibility。坐标系以图像左上角为原点x 向右、y 向下z 是深度估计值范围大致在 -1 到 1 之间数值越小代表离镜头越近。33 个点的索引顺序固定0 是鼻子11 和 12 是左右肩13 和 14 是左右肘15 和 16 是左右腕23 和 24 是左右髋27 和 28 是左右踝这个索引表在 Unity 侧映射时极其关键建议直接打印一遍确认顺序再写死到代码里。项目里udptracker.py用的就是 MediaPipe 的mp.solutions.pose.Pose类而不是 Holistic 或 FaceMesh。原因在于 Holistic 多出人脸和手势关键点数据量大了将近一倍对 UDP 传输带宽和 Unity 侧的解析效率都不友好。如果只做肢体姿态追踪Pose 模型是性能和精度最平衡的选项。下面的代码是udptracker.py的核心检测循环压缩了文件读写和异常处理部分保留完整的推理与发送逻辑import cv2 import mediapipe as mp import socket import json import time mp_pose mp.solutions.pose pose mp_pose.Pose( static_image_modeFalse, model_complexity1, smooth_landmarksTrue, enable_segmentationFalse, min_detection_confidence0.5, min_tracking_confidence0.5 ) cap cv2.VideoCapture(0) sock socket.socket(socket.AF_INET, socket.SOCK_DGRAM) server_addr (127.0.0.1, 12345) while cap.isOpened(): ret, frame cap.read() if not ret: break frame_rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) results pose.process(frame_rgb) if results.pose_landmarks: landmarks [] for lm in results.pose_landmarks.landmark: landmarks.append({ x: lm.x, y: lm.y, z: lm.z, v: lm.visibility }) data json.dumps(landmarks) sock.sendto(data.encode(utf-8), server_addr) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()这段代码把每一帧的 33 个关键点的 x、y、z、v 四个字段包装成 JSON 数组发送。x和y是归一化坐标范围 0 到 1z是相对髋部中心的深度估计值v是可见性置信度。json.dumps在这里把 list of dict 直接序列化成字符串Unity 侧用JsonUtility或Newtonsoft.Json解析都方便。需要注意model_complexity1是性能与精度的折中如果你的机器是纯 CPU 跑改成 0 可以提升 FPS但肩肘腕的抖动会明显增加。2.2 UDP 发送策略与数据格式设计选择 UDP 而不是 TCP 的原因在这类实时姿态追踪场景里非常明确。TCP 有粘包和重传机制一旦网络抖动旧数据会阻塞新数据的到达导致 Unity 里的虚拟人动作出现明显延迟和卡顿。UDP 丢帧后直接跳到下一帧视觉上反而更流畅因为姿态追踪本身就是逐帧计算的丢一两帧对最终效果影响不大。socket 用的是SOCK_DGRAM没有建立连接的过程每次sendto都是独立的数据报。发送频率默认等于摄像头帧率常见 webcam 是 30 FPS。如果你在 Unity 里做了插值平滑可以每两帧发一次数据把 FPS 降到 15减少网络和序列化开销。数据报大小需要算一下33 个点 × 4 个字段 × 单个浮点数字符串平均长度约 8 字节JSON 格式下总共大约 3 到 4 KB远小于 UDP 理论最大 65507 字节不存在分片问题。但要注意如果后续加了 Holistic 的 468 个面部关键点包体尺寸会膨胀到 50 KB 以上那时候就必须考虑二进制协议或只传输选定关键点否则会因为 IP 分片触发丢包率急速上升。2.3 摄像头输入与坐标系对齐的坑Python 端读取摄像头默认是 BGR 格式MediaPipe 的process方法要求 RGB 输入所以每次都要cv2.cvtColor。这一步如果漏掉姿态检测的准确率会大幅下降尤其是肩部关键点的稳定性会变得很差因为 MediaPipe 模型的训练数据是基于 RGB 色彩空间的。翻转问题也要处理如果你的摄像头是前置摄像头画面是镜像的Unity 侧接收到的 x 坐标会和真实方向相反。常见做法是拍摄时做cv2.flip(frame, 1)或者在 Unity 侧对 x 做1 - x映射项目里unity.py用的是后者这样 Python 端代码改动最少。还有一个人体方向的问题MediaPipe 输出的坐标永远是图像坐标系而不是世界坐标系。意思是当人侧身对着摄像头时左右手的 x 坐标会重叠z 的深度值能部分区分但精度有限。这个问题在单目摄像头方案里无法彻底解决你只能在 Unity 侧加一个简单的朝向判断用左右肩的 x 坐标差值符号来决定是否翻转左右手映射。我一般会在 shoulder_x_left shoulder_x_right 时认为人背对镜头切换左右手的关键点索引绑定。3. Unity 侧 UDP 接收与骨骼映射实现3.1 unity.py 的网络接收与 JSON 解析unity.py这个名字有迷惑性它不是 Python 脚本而是 Unity 工程里的 C# 脚本文件。整个项目的文件结构是Python 端负责推理和发送Unity 端负责接收、解析和驱动角色骨骼。unity.py内部实际是一个继承MonoBehaviour的 C# 类用UdpClient在独立线程里接收数据避免阻塞主线程的渲染循环。下面这段是核心接收与解析逻辑注意我做了 JSON 字段的容错处理因为 MediaPipe 的 visibility 字段在 Unity 的JsonUtility里不能直接映射到 float 类型需要用Newtonsoft.Json.Linq或自己写字符串解析using System; using System.Net; using System.Net.Sockets; using System.Text; using System.Threading; using UnityEngine; using Newtonsoft.Json.Linq; public class PoseReceiver : MonoBehaviour { private UdpClient udpClient; private Thread receiveThread; private JArray latestLandmarks; void Start() { udpClient new UdpClient(12345); receiveThread new Thread(ReceiveData); receiveThread.IsBackground true; receiveThread.Start(); } void ReceiveData() { IPEndPoint remoteEndPoint new IPEndPoint(IPAddress.Any, 0); while (true) { try { byte[] data udpClient.Receive(ref remoteEndPoint); string jsonString Encoding.UTF8.GetString(data); latestLandmarks JArray.Parse(jsonString); } catch (Exception e) { Debug.LogError(UDP receive error: e.Message); } } } void Update() { if (latestLandmarks ! null) { // 在这里读取 latestLandmarks 并驱动角色骨骼 JToken hip latestLandmarks[23]; float hipX hip[x].Valuefloat(); float hipY hip[y].Valuefloat(); float hipZ hip[z].Valuefloat(); Debug.Log($Hip position: ({hipX}, {hipY}, {hipZ})); } } void OnDestroy() { if (receiveThread ! null) receiveThread.Abort(); if (udpClient ! null) udpClient.Close(); } }这里Newtonsoft.Json.Linq是 Unity 的 JSON.NET 包在 Package Manager 里搜索com.unity.nuget.newtonsoft-json可以安装。JArray直接按索引访问关键点索引和 Python 端 MediaPipe 的 33 个点顺序一一对应。Update里每帧读取最新一次的数据做到最新数据覆盖旧数据这是 UDP 接收线程的标准写法。有一个关键细节是receiveThread.IsBackground true这样当场景退出时线程不会阻塞 Unity 关闭流程否则经常出现 Play 模式停了但编辑器卡死的情况。3.2 关键点与 Unity Humanoid 骨骼的映射方案Unity 的 Humanoid 动画系统自带骨骼重定向能力Avatar 会帮你把骨骼映射到标准的人形骨架。但如果你用的是 Generic 模式或者模型骨骼命名不规范就需要手动把 33 个 MediaPipe 关键点绑定到 Transform。最省事的方案是找一个标准 T-pose 模型开启 Humanoid Avatar 后直接操作Animator.GetBoneTransform。我的做法是在 Awake 阶段把骨骼引用缓存成字典绑定一次Update 里直接查字典用避免每帧多次调用GetBoneTransform。下面是被测过多次的映射片段重点覆盖了上肢和下肢共 24 个点头部的额外点可以留给后续加面部情绪识别用private Dictionaryint, Transform boneMap; void Awake() { Animator animator GetComponentAnimator(); boneMap new Dictionaryint, Transform(); // MediaPipe 索引 → HumanBodyBones 枚举 boneMap.Add(11, animator.GetBoneTransform(HumanBodyBones.LeftShoulder)); boneMap.Add(13, animator.GetBoneTransform(HumanBodyBones.LeftUpperArm)); boneMap.Add(15, animator.GetBoneTransform(HumanBodyBones.LeftLowerArm)); boneMap.Add(17, animator.GetBoneTransform(HumanBodyBones.LeftHand)); boneMap.Add(12, animator.GetBoneTransform(HumanBodyBones.RightShoulder)); boneMap.Add(14, animator.GetBoneTransform(HumanBodyBones.RightUpperArm)); boneMap.Add(16, animator.GetBoneTransform(HumanBodyBones.RightLowerArm)); boneMap.Add(18, animator.GetBoneTransform(HumanBodyBones.RightHand)); boneMap.Add(23, animator.GetBoneTransform(HumanBodyBones.Hips)); boneMap.Add(25, animator.GetBoneTransform(HumanBodyBones.LeftUpperLeg)); boneMap.Add(27, animator.GetBoneTransform(HumanBodyBones.LeftLowerLeg)); boneMap.Add(29, animator.GetBoneTransform(HumanBodyBones.LeftFoot)); boneMap.Add(24, animator.GetBoneTransform(HumanBodyBones.RightUpperLeg)); boneMap.Add(26, animator.GetBoneTransform(HumanBodyBones.RightLowerLeg)); boneMap.Add(28, animator.GetBoneTransform(HumanBodyBones.RightFoot)); }核心思路是直接用骨骼 Transform 的rotation属性而不是 position。MediaPipe 给出的是 2D 图像上的关键点位置直接映射到 3D 空间会导致角色模型严重变形。正确做法是计算每个骨骼段的朝向向量然后用Quaternion.FromToRotation把骨骼从初始朝向旋转到目标朝向。比如左前臂的朝向向量是left_elbow.position - left_wrist.position用这个向量和目标向量做插值。3.3 旋转计算的数学基础与 Unity 四元数陷阱从关键点坐标到骨骼旋转的转换是整个项目的核心难点。常见的错误是直接用Quaternion.Euler设置欧拉角结果角色动作完全扭曲。正确的路径是先用两个关键点的世界坐标差求出骨骼段的归一化方向向量再把向量转换为四元数。Vector3 direction (wristPos - elbowPos).normalized; Quaternion targetRotation Quaternion.LookRotation(direction, Vector3.up); // 混合插值避免旋转突变 transform.rotation Quaternion.Slerp( transform.rotation, targetRotation, smoothFactor );这里smoothFactor在 5 到 15 之间取值对应Time.deltaTime * smoothFactor的插值速度。这个值太小动作会显得迟钝太大会产生高频抖动。MediaPipe 的 landmark 本身已经做了时序平滑但 Unity 侧仍然需要二级插值因为 UDP 传输存在帧率波动直接赋值会让模型出现肉眼可见的抖动。另外注意Quaternion.LookRotation的前方和上方向量参数需要根据模型的 T-pose 方向调整大部分模型的前方是 Z 轴正方向但也有一些模型是 Y 轴或负 Z 轴这个参数不对的话整个骨架会翻转。4. 联调流程、参数调优与常见故障排除4.1 端到端联调的检查顺序安装环境时最容易踩坑的是版本兼容。MediaPipe 的solutions.pose在 0.8.x 到 0.10.x 版本之间 API 没有破坏性变更但如果你的 Python 版本是 3.11 以上建议直接用pip install mediapipe --upgrade拉最新版。Unity 侧需要 .NET 4.x 运行时在 Player Settings 里把 Api Compatibility Level 改成.NET Framework才能用 Newtonsoft.Json。下面是完整联调顺序表步骤检查内容预期结果失败时的排查手段1摄像头能被 OpenCV 打开窗口弹出、画面正常换cv2.VideoCapture(1)或检查驱动权限2MediaPipe 检测到站立人体终端打印 33 个点坐标调低min_detection_confidence到 0.33Python 端 UDP 发送Wireshark 或netstat看到 12345 端口有数据检查防火墙是否拦截 Python 进程4Unity 端能收到数据Console 打印 Hip position确认同为 127.0.0.1 或同一局域网 IP5骨骼绑定成功模型跟随人体动作检查boneMap中 Transform 是否为空这个顺序建议严格按编号来因为大多数问题出在摄像头权限和防火墙拦截上。Windows 系统第一次运行 Python 的 UDP 发送会被防火墙弹窗拦截如果没点击允许Unity 侧永远收不到数据。更隐蔽的问题是 Python 端用的127.0.0.1而 Unity 运行在 Android 或 WebGL 平台这时候要用局域网 IP并且 Unity 工程需要申请网络权限。4.2 参数调节对追踪效果的影响在udptracker.py里有三个参数直接决定效果。min_detection_confidence控制初始检测的置信度阈值默认 0.5如果你在光线较暗的环境下检测不到人降这个值到 0.3 通常能解决。min_tracking_confidence控制跟踪阶段的置信度阈值降到 0.5 以下会减少跟丢的情况但关键点抖动会增加。model_complexity从 0 调到 1 会让肩肘腕的精度明显提升代价是 CPU 占用率高 30% 左右。Unity 侧的smoothFactor是另一个关键参数。我测试过 3 到 30 的范围5 以下动作跟手但抖动明显15 以上动作平滑但延迟感强。推荐初始值 10然后根据实际动作表现微调。如果你的项目是做实时交互而不是离线录制smoothFactor不超过 8 比较合适因为插值本身会引入 1 到 2 帧的额外延迟。提示AnimationFile.txt里记录了 Unity 动画片段与 MediaPipe 骨骼索引的对应关系如果你的模型动作完全乱掉优先检查这个文件的映射表而不是代码逻辑。这个文件是作者调试时记录的映射参考不是运行时的配置文件。4.3 高频问题的定位方法与修复问题一身体部分关节翻转。这是因为Quaternion.LookRotation无法处理向量共线的情况当目标方向和Vector3.up平行时四元数计算会退化。修复方式是在计算旋转前检查方向向量的magnitude和与up的夹角如果夹角小于 10 度就跳过这一帧的旋转更新。我一般记录连续跳过的帧数超过 30 帧就保留最后一次有效旋转避免模型瞬间扭成奇怪姿势。问题二Unity 中角色的手和脚位置对不上。这通常是因为 MediaPipe 的关键点是相对于图像尺寸的归一化坐标而你在 Unity 里直接把它当世界坐标使用。正确的做法是给姿态数据一个固定的缩放比例把归一化坐标乘以人的身高估计值再映射到 Unity 的 Y 轴高度系统。常见做法是以髋部点 23 为原点其他点做相对坐标计算这样即使人站在距离摄像头不同位置虚拟角色的手臂长度比例也不会失真。问题三UDP 数据丢失严重。先确认发送频率和接收频率是否匹配如果 Unity 的主线程阻塞导致Update变卡UdpClient.Receive所在的独立线程不受影响但数据缓存会越来越大。我的做法是在接收线程里只保留最新的一帧数据丢弃之前的旧帧代码里用lock语句保护latestLandmarks的读写。如果你的丢包率仍然高于 5%检查是否有多个程序同时占用 12345 端口或者把端口改成 9000 以上的高位端口减少和其他服务的冲突概率。5. 进阶应用IK 反向动力学融合与多平台发布细节5.1 用 Animation Rigging 包解决脚部穿透问题MediaPipe 的 33 个关键点没有脚趾和手指的细粒度数据直接在 Unity 里驱动骨骼会导致脚步滑动、手部穿透物体。项目包里没有包含 IK 方案但在实际部署中这几乎是必须的步骤。Unity 的 Animation Rigging 包提供 TwoBoneIK 约束可以把 MediaPipe 的腕部和踝部坐标作为 IK 目标让 Unity 的 IK 算法自动计算肘部和膝盖的弯曲角度。// 在 Animation Rigging 中配置 TwoBoneIK 约束后 // 用 MediaPipe 的 15/16手腕和 27/28脚踝驱动 IK target ikTarget.position wristWorldPos; ikTarget.rotation Quaternion.LookRotation( (elbowWorldPos - wristWorldPos).normalized, Vector3.up );IK 方案的核心优势是解决了关键点遮挡时的关节扭曲。当手被身体挡住时MediaPipe 的腕部点仍然会被预测出来但精度暴跌IK 约束会自动把手臂拉回到一个合理的姿态而不是像直接绑定 Transform 那样出现反关节。在 30 FPS 的输入下Animation Rigging 的开销大约等于几毫秒的 CPU 时间完全可以接受。5.2 WebGL 发布时 UDP 不可用的替代方案如果项目目标是 WebGL 平台Unity 的 WebGL 构建不支持传统 UDP Socket。一个已测试可行的方案是把 Python 端改成 WebSocket ServerUnity 用ClientWebSocket连接。Python 端用websockets库实现异步服务器发送 MediaPipe 关键点的二进制压缩数据。二进制格式推荐直接拼接 132 个 float33 点 × 4 字节用struct.pack序列化接收端用Buffer.BlockCopy反序列化性能和 JSON 相比快 10 倍以上。import asyncio import struct import websockets async def send_pose(websocket, path): while True: if results.pose_landmarks: packed b.join( struct.pack(4f, lm.x, lm.y, lm.z, lm.visibility) for lm in results.pose_landmarks.landmark ) await websocket.send(packed) await asyncio.sleep(1 / 30) start_server websockets.serve(send_pose, 127.0.0.1, 8765) asyncio.get_event_loop().run_until_complete(start_server) asyncio.get_event_loop().run_forever()字节序用4f小端模式Unity 端BinaryReader默认也是小端两边对齐。每帧 132 字节加上 WebSocket 的 2 字节头部带宽占用不到 4 KB/s比 JSON 的 30 KB/s 低一个量级。这套方案在局域网内的延迟实测可以稳定在 5 到 10 毫秒比 UDP 方案还稳定因为它避开了防火墙对 UDP 的干扰。竞速游戏、虚拟主播、体感交互这些场景都可以直接用这套方案改造成品项目。本文还有配套的精品资源点击获取