python模块安装系列之mediapipe的whl文件下载和安装教程
·
MediaPipe whl文件安装详细教程
一、安装前准备工作
1. 检查系统兼容性
# 检查Python版本(关键)
python --version
# 查看完整版本信息
python -c "import sys; print(f'Python {sys.version}')"
print(f'系统类型: {platform.system()} {platform.architecture()[0]}')
2. 版本匹配指南
MediaPipe的whl文件有严格版本限制:
| Python版本 | MediaPipe版本 | 文件名关键部分 |
|---|---|---|
| Python 3.7 | 0.10.x | cp37-cp37m |
| Python 3.8 | 0.10.x | cp38-cp38 |
| Python 3.9 | 0.10.x | cp39-cp39 |
| Python 3.10 | 0.10.x | cp310-cp310 |
重要提示:
- 不支持Python 3.14及以上版本
- 仅支持64位Windows系统
- 文件名必须完全匹配Python版本
二、whl文件获取指引
步骤1:查找文件源
- 在GitHub搜索仓库pythonlibs_whl_mirror
- 寻找包含大量Python包whl文件的公开仓库
- 使用关键词:meidapipe
步骤2:搜索具体文件
在找到的仓库中:
- 使用仓库的搜索功能
- 输入关键词:
mediapipe - 按文件名排序查找
步骤3:识别正确文件
正确文件名示例:mediapipe-0.10.8-cp39-cp39-win_amd64.whl
组成部分解析:
mediapipe:包名0.10.8:版本号cp39:Python 3.9cp39:再次确认Python版本win_amd64:64位Windows系统.whl:文件扩展名
步骤4:下载注意事项
- 确保下载完整的.whl文件
- 文件大小通常为100-200MB
- 保存到易访问的位置,如桌面或下载目录
三、详细安装步骤
步骤1:打开命令行
- 按
Win + R输入cmd - 按
Ctrl + Shift + Enter以管理员身份运行
步骤2:基础环境准备
:: 1. 升级pip到最新版
python -m pip install --upgrade pip
:: 2. 检查当前已安装的mediapipe
pip list | findstr mediapipe
:: 3. 如果有旧版本,先卸载
pip uninstall mediapipe -y
步骤3:进入下载目录
:: 假设文件在下载目录
cd %USERPROFILE%\Downloads
:: 列出所有whl文件,确认存在
dir *.whl
步骤4:正式安装
:: 方法1:直接安装(推荐)
pip install mediapipe-0.10.8-cp39-cp39-win_amd64.whl
:: 方法2:如果权限不足,使用用户安装
pip install --user mediapipe-0.10.8-cp39-cp39-win_amd64.whl
:: 方法3:指定完整路径
pip install "C:\Users\你的用户名\Downloads\mediapipe-0.10.8-cp39-cp39-win_amd64.whl"
:: 方法4:使用绝对路径且跳过依赖检查(极端情况)
pip install "C:\完整路径\mediapipe.whl" --no-deps --force-reinstall
步骤5:安装验证
:: 验证安装是否成功
pip show mediapipe
:: 查看版本信息
python -c "import mediapipe; print('成功导入,版本:', mediapipe.__version__)"
四、安装辅助脚本
创建 verify_install.py 验证脚本:
"""
MediaPipe安装验证脚本
运行此脚本确认安装是否成功
"""
import sys
import subprocess
import importlib
def check_python_version():
"""检查Python版本兼容性"""
print("=" * 50)
print("MediaPipe安装验证")
print("=" * 50)
version_info = sys.version_info
print(f"Python版本: {version_info.major}.{version_info.minor}.{version_info.micro}")
# MediaPipe仅支持Python 3.7-3.10
if version_info.major != 3:
print("❌ 需要Python 3.x")
return False
if version_info.minor < 7:
print("❌ 需要Python 3.7或更高版本")
return False
if version_info.minor > 10:
print("⚠️ MediaPipe官方whl仅支持到Python 3.10")
print(" 你可能需要从源码编译")
print("✅ Python版本检查通过")
return True
def check_mediapipe_import():
"""尝试导入MediaPipe"""
print("\n尝试导入MediaPipe...")
try:
# 尝试导入主要模块
import mediapipe
# 获取版本信息
if hasattr(mediapipe, '__version__'):
print(f"✅ MediaPipe导入成功,版本: {mediapipe.__version__}")
else:
print("✅ MediaPipe导入成功(无法获取版本)")
# 检查关键子模块
modules_to_check = [
'solutions.face_detection',
'solutions.hands',
'solutions.pose',
'solutions.drawing_utils'
]
print("\n检查子模块...")
for module_path in modules_to_check:
try:
module = importlib.import_module(f'mediapipe.{module_path}')
module_name = module_path.split('.')[-1]
print(f" ✅ {module_name} 可用")
except ImportError as e:
print(f" ⚠️ {module_path} 导入失败: {e}")
return True
except ImportError as e:
print(f"❌ MediaPipe导入失败: {e}")
print("\n可能的原因:")
print("1. whl文件版本与Python版本不匹配")
print("2. 缺少依赖项")
print("3. 文件损坏或未完全下载")
return False
except Exception as e:
print(f"❌ 导入时发生意外错误: {e}")
return False
def check_pip_package():
"""检查pip中的包信息"""
print("\n检查pip包信息...")
try:
result = subprocess.run(
[sys.executable, '-m', 'pip', 'show', 'mediapipe'],
capture_output=True,
text=True,
timeout=10
)
if result.returncode == 0:
print("✅ pip包信息获取成功")
# 解析输出
info_lines = result.stdout.strip().split('\n')
for line in info_lines[:10]: # 显示前10行
if line.strip():
print(f" {line}")
else:
print("⚠️ 无法通过pip获取包信息")
except subprocess.TimeoutExpired:
print("⚠️ pip查询超时")
except Exception as e:
print(f"⚠️ pip检查错误: {e}")
def main():
"""主验证函数"""
# 1. 检查Python版本
if not check_python_version():
return False
# 2. 检查pip包信息
check_pip_package()
# 3. 尝试导入
if not check_mediapipe_import():
return False
print("\n" + "=" * 50)
print("✅ MediaPipe安装验证通过!")
print("=" * 50)
return True
if __name__ == "__main__":
success = main()
if not success:
print("\n❌ 安装验证失败")
print("\n建议:")
print("1. 确认whl文件名与Python版本完全匹配")
print("2. 重新下载whl文件")
print("3. 尝试以管理员身份运行安装")
print("4. 检查Python环境变量设置")
input("\n按Enter键退出...")
五、有且只有一个的完整测试示例
# mediapipe_single_demo.py
"""
MediaPipe 单一完整功能演示
手部关键点检测与可视化
"""
print("=" * 60)
print("MediaPipe 手部关键点检测演示")
print("=" * 60)
try:
import cv2
import mediapipe as mp
import numpy as np
import sys
print("✅ 依赖库导入成功")
# 初始化MediaPipe手部检测
print("初始化手部检测模块...")
mp_hands = mp.solutions.hands
mp_drawing = mp.solutions.drawing_utils
mp_drawing_styles = mp.solutions.drawing_styles
# 创建手部检测器
hands = mp_hands.Hands(
static_image_mode=True, # 静态图像模式
max_num_hands=2, # 最多检测2只手
min_detection_confidence=0.5, # 检测置信度阈值
min_tracking_confidence=0.5 # 跟踪置信度阈值
)
print("✅ 手部检测器创建成功")
# 创建一个模拟的手部图像
print("\n生成测试图像...")
image_height = 480
image_width = 640
# 创建空白图像(浅灰色背景)
image = np.ones((image_height, image_width, 3), dtype=np.uint8) * 180
# 在图像中心画一个手部轮廓(简化版)
center_x, center_y = image_width // 2, image_height // 2
# 绘制手掌区域(圆形)
cv2.circle(image, (center_x, center_y), 120, (200, 150, 100), -1)
# 绘制五个手指的简化表示
finger_positions = [
(center_x - 40, center_y - 120), # 拇指
(center_x - 20, center_y - 150), # 食指
(center_x, center_y - 160), # 中指
(center_x + 20, center_y - 150), # 无名指
(center_x + 40, center_y - 120) # 小指
]
for i, (x, y) in enumerate(finger_positions):
cv2.circle(image, (x, y), 15, (100, 150, 200), -1)
cv2.putText(image, str(i+1), (x-5, y+5),
cv2.FONT_HERSHEY_SIMPLEX, 0.5, (255, 255, 255), 1)
cv2.putText(image, "模拟手部图像", (center_x-80, center_y+180),
cv2.FONT_HERSHEY_SIMPLEX, 0.8, (50, 50, 50), 2)
print(f"图像尺寸: {image_width} x {image_height}")
# 转换为RGB格式(MediaPipe要求)
print("\n进行手部关键点检测...")
image_rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
# 处理图像,检测手部关键点
results = hands.process(image_rgb)
# 绘制检测结果
image_with_landmarks = image.copy()
if results.multi_hand_landmarks:
print(f"检测到 {len(results.multi_hand_landmarks)} 只手")
for hand_landmarks in results.multi_hand_landmarks:
# 绘制关键点和连接线
mp_drawing.draw_landmarks(
image_with_landmarks,
hand_landmarks,
mp_hands.HAND_CONNECTIONS,
mp_drawing_styles.get_default_hand_landmarks_style(),
mp_drawing_styles.get_default_hand_connections_style()
)
# 获取并显示关键点坐标
print("\n手部关键点坐标(归一化坐标 0-1):")
landmarks = []
for idx, landmark in enumerate(hand_landmarks.landmark):
x = landmark.x
y = landmark.y
z = landmark.z
# 转换为像素坐标
px = int(x * image_width)
py = int(y * image_height)
landmarks.append((px, py, z))
# 显示前几个关键点的信息
if idx < 5: # 只显示前5个关键点
print(f" 关键点{idx}: ({x:.3f}, {y:.3f}, {z:.3f}) -> 像素({px}, {py})")
# 计算手掌中心
if len(landmarks) >= 1:
palm_center = landmarks[0] # 手腕点作为参考
cv2.circle(image_with_landmarks, (palm_center[0], palm_center[1]),
10, (0, 255, 0), -1)
cv2.putText(image_with_landmarks, "Palm Center",
(palm_center[0]+15, palm_center[1]),
cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 255, 0), 1)
print("\n✅ 手部关键点检测成功完成")
else:
print("⚠️ 未检测到手部关键点")
print("注意:这是一个模拟图像,实际图像效果更好")
# 释放资源
hands.close()
# 显示结果
print("\n显示检测结果...")
# 创建对比显示
comparison = np.hstack([image, image_with_landmarks])
# 添加标题
title_height = 40
title_image = np.ones((title_height, comparison.shape[1], 3), dtype=np.uint8) * 255
cv2.putText(title_image, "原始图像 检测结果",
(50, title_height-15), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 0, 0), 2)
final_image = np.vstack([title_image, comparison])
# 显示图像
cv2.imshow('MediaPipe Hands Demo - 原始 vs 检测结果', final_image)
print("\n窗口说明:")
print("- 左侧:原始模拟手部图像")
print("- 右侧:MediaPipe检测结果(关键点和连接线)")
print("- 绿色圆点:手掌中心参考点")
print("\n按任意键关闭窗口...")
# 等待按键
cv2.waitKey(0)
cv2.destroyAllWindows()
# 保存结果图像
output_filename = "mediapipe_hands_demo_result.jpg"
cv2.imwrite(output_filename, final_image)
print(f"\n✅ 结果已保存为: {output_filename}")
print("\n" + "=" * 60)
print("演示完成!MediaPipe安装和基本功能正常")
print("=" * 60)
except ImportError as e:
print(f"\n❌ 导入失败: {e}")
print("\n可能的原因:")
print("1. MediaPipe未正确安装")
print("2. OpenCV未安装(运行: pip install opencv-python)")
print("3. Python版本不兼容")
except Exception as e:
print(f"\n❌ 运行过程中出现错误: {e}")
import traceback
traceback.print_exc()
finally:
print("\n演示程序结束")
if 'cv2' in sys.modules:
cv2.destroyAllWindows()
六、安装后验证步骤
1. 运行测试脚本
python mediapipe_single_demo.py
2. 预期结果
- 显示一个分割窗口,左侧为原始图像,右侧为检测结果
- 控制台输出关键点坐标信息
- 自动保存结果图像到当前目录
- 出现手部关键点和连接线的可视化结果
3. 常见问题处理
问题1:ModuleNotFoundError
ModuleNotFoundError: No module named 'mediapipe'
解决:确保whl文件正确安装,检查Python版本匹配
问题2:OpenCV相关错误
ModuleNotFoundError: No module named 'cv2'
解决:安装OpenCV
pip install opencv-python
问题3:版本兼容性警告
UserWarning: The detected Python version X.X is not supported
解决:安装与Python版本完全匹配的whl文件
这个单一示例演示了MediaPipe的核心功能,避免了复杂的多示例混淆。测试成功后,即可确认MediaPipe已正确安装并可用。
更多推荐


所有评论(0)