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.70.10.xcp37-cp37m
Python 3.80.10.xcp38-cp38
Python 3.90.10.xcp39-cp39
Python 3.100.10.xcp310-cp310

重要提示:

  • 不支持Python 3.14及以上版本
  • 仅支持64位Windows系统
  • 文件名必须完全匹配Python版本

二、whl文件获取指引

步骤1:查找文件源

  1. 在GitHub搜索仓库pythonlibs_whl_mirror
  2. 寻找包含大量Python包whl文件的公开仓库
  3. 使用关键词:meidapipe

步骤2:搜索具体文件

在找到的仓库中:

  1. 使用仓库的搜索功能
  2. 输入关键词:mediapipe
  3. 按文件名排序查找

步骤3:识别正确文件

正确文件名示例:mediapipe-0.10.8-cp39-cp39-win_amd64.whl
组成部分解析:

  • mediapipe:包名
  • 0.10.8:版本号
  • cp39:Python 3.9
  • cp39:再次确认Python版本
  • win_amd64:64位Windows系统
  • .whl:文件扩展名

步骤4:下载注意事项

  1. 确保下载完整的.whl文件
  2. 文件大小通常为100-200MB
  3. 保存到易访问的位置,如桌面或下载目录

三、详细安装步骤

步骤1:打开命令行

  1. 按 Win + R 输入 cmd
  2. 按 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已正确安装并可用。

更多推荐