MediaPipeUnityPlugin 完整安装与配置指南

项目概述

MediaPipeUnityPlugin 是一个 Unity 原生插件，用于在 Unity 引擎中运行 Google 的 MediaPipe 框架。该项目的主要目标是将 MediaPipe API 从 C++ 逐一移植到 C#，以便开发者能够在 Unity 中直接调用 MediaPipe 功能。

通过这个插件，开发者可以：

• 使用 C# 编写 MediaPipe 代码
• 在 Unity 中运行 MediaPipe 的官方解决方案
• 在 Unity 中运行自定义的计算器和计算图

环境要求

系统要求

• Unity 2022.3 或更高版本
• 支持的操作系统：Linux (x86_64)、macOS (x86_64/ARM64)、Windows (x86_64)
• 移动平台：Android、iOS

软件依赖

• Docker（用于构建环境）
• WSL2（Windows 用户必需）
• 相应的开发工具链

安装步骤

步骤 1：获取项目源码

首先需要克隆项目仓库到本地：

git clone https://gitcode.com/gh_mirrors/me/MediaPipeUnityPlugin.git

步骤 2：准备构建环境

项目推荐使用 Docker 进行构建，这样可以确保环境的一致性：

cd MediaPipeUnityPlugin
docker build -t mediapipe-unity .

步骤 3：运行测试环境

构建完成后，可以使用 Docker 运行项目：

docker run -it --rm -v $(pwd):/workspace mediapipe-unity

项目配置

Unity 项目导入

将下载的预构建包导入到 Unity 项目中：

1. 打开 Unity Hub
2. 添加项目，选择 MediaPipeUnityPlugin 目录
3. 确保项目设置正确配置

Android 配置

如果需要为 Android 构建应用，必须确保在 APK 中包含 libstdc++_shared.so，否则会在运行时抛出 DllNotFoundException。

最简单的方法是将 libstdc++_shared.so 放置在项目的 Assets/Plugins/Android 目录中。

资源文件配置

项目包含多个示例场景和资源文件，位于 Assets/MediaPipeUnity/Samples 目录下。这些资源包括：

• 材质文件：如 UV 网格材质和屏幕材质
• 预制体：用于各种标注和可视化
• 着色器：用于渲染效果
• 模型文件：AI 模型资源

UV网格材质

平台支持情况

支持的平台

平台	编辑器	Linux	macOS	Windows	Android	iOS
Linux (AMD64)	✓	✓			✓
Intel Mac	✓		✓		✓	✓
M1 Mac	✓			✓	✓	✓
Windows 10/11	✓				✓

支持的解决方案

项目实现了以下 MediaPipe Tasks 的 C# API：

• 对象检测
• 图像分割
• 手部标志点检测
• 手势识别
• 面部检测
• 面部标志点检测
• 姿态标志点检测
• 音频分类

使用指南

示例场景测试

在将插件用于自己的项目之前，强烈建议先检查示例场景是否能正常工作。

可以测试的解决方案包括：

• 面部检测
• 面部标志点检测
• 手部标志点检测
• 姿态标志点检测
• 图像分割
• 对象检测

推理模式设置

根据构建的本地库选择合适的推理模式：

• 如果本地库是为 CPU 构建的，选择 CPU 推理模式
• 对于发布页面分发的库，Windows 和 macOS 上仅 CPU 可用

资源加载器类型

默认的资源加载器类型设置为 Local，这仅在 Unity 编辑器中工作。要在设备上运行，需要切换到 StreamingAssets 并将所需资源复制到 StreamingAssets 目录下。

技术限制

稳定性问题

由于这个插件在底层使用本地库，如果这些库中存在错误，Unity 编辑器或应用程序可能会在运行时崩溃。

此外，在某些情况下，MediaPipe 可能通过发送 SIGABRT 信号而不是抛出异常来使整个程序崩溃。

图形 API 限制

如果要使用 GPU 进行推理，不能使用 OpenGL Core API，否则会遇到错误。在实践中，这个错误只发生在 PC 独立构建上，在这种情况下，请将图形 API 切换为 Vulkan。

故障排除

常见问题

1. 构建失败：检查 Docker 服务状态和系统资源
2. 运行时错误：验证 Unity 版本兼容性和平台设置
3. 性能问题：优化 MediaPipe 计算图配置

最佳实践

• 使用项目提供的示例场景快速上手
• 根据应用需求定制 MediaPipe 管道
• 充分利用 Unity 的实时渲染能力

许可证信息

本项目采用 MIT 许可证分发。需要注意的是，某些文件根据其他许可证分发：

• MediaPipe：Apache License 2.0
• emscripten：MIT
• FontAwesome：相应许可证

通过本指南，您将能够成功安装和配置 MediaPipeUnityPlugin，并在 Unity 中构建功能强大的多媒体 AI 应用。