什么是 imutils？

imutils 是一个由 Adrian Rosebrock（PyImageSearch 博主）创建的、用于简化计算机视觉（CV）操作的 Python 包，它封装了 OpenCV 和其他一些库的常用功能，提供了一套更简洁、更易用的 API,让你能用更少的代码完成常见的图像处理任务。

主要功能包括：

• 图像/视频 I/O: 方便地显示、读取、保存图像和视频流。
• 图像变换: 便捷的旋转、平移、缩放、翻转等。
• 尺寸调整: 智能的“保持宽高比”的图像缩放。
• 路径/边界框操作: 计算两点距离、获取边界框中心点等。
• 人脸检测: 封装了 OpenCV 和 dlib 的人脸检测器。
• 视频流处理: 轻松搭建实时视频流处理管道。

安装方法

安装 imutils 非常简单，主要使用 pip 包管理器。

标准安装

这是最直接的方法，会安装 imutils 及其所有依赖项（主要是 opencv-python）。

打开你的终端或命令行工具（Windows 是 CMD 或 PowerShell，macOS/Linux 是 Terminal）,然后输入以下命令：

pip install imutils

推荐使用虚拟环境： 为了避免与系统 Python 或其他项目的依赖冲突,最佳实践是先创建一个虚拟环境。

# 1. 创建虚拟环境 (名为 venv)
python -m venv venv
# 2. 激活虚拟环境
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate
# 3. 在虚拟环境中安装 imutils
pip install imutils

升级到最新版本

如果你已经安装过 imutils，但想升级到最新版本，可以使用 --upgrade 标志。

pip install --upgrade imutils

从源码安装

如果你想获取最新的开发版本或进行自定义修改，可以从 GitHub 仓库源码安装。

# 克隆仓库
git clone https://github.com/PyImageSearch/imutils.git
# 进入项目目录
cd imutils
# 安装
pip install .

安装后如何验证？

安装完成后，你可以通过一个简单的 Python 脚本来验证是否安装成功。

1. 准备一张图片，test.jpg,放在和脚本相同的目录下。
2. 创建一个名为 verify_imutils.py 的文件,并粘贴以下代码：

import cv2
import imutils
# --- 验证 1: 导入是否成功 ---
print("imutils 安装成功！")
# --- 验证 2: 尝试使用一个简单功能 ---
# 读取一张图片
# 你需要自己准备一张图片，或者从网络下载一张
image_path = "test.jpg" 
try:
    # 使用 OpenCV 读取图片
    image = cv2.imread(image_path)
    # 如果图片不存在，会抛出异常
    if image is None:
        raise FileNotFoundError(f"错误：找不到图片文件 '{image_path}'，请确保图片路径正确。")
    # 使用 imutils 调整图片大小（保持宽高比）
    # 将图片的宽度调整为 400 像素
    resized = imutils.resize(image, width=400)
    # 打印调整前后的尺寸
    print(f"原始图片尺寸: {image.shape[1]}x{image.shape[0]}")
    print(f"调整后图片尺寸: {resized.shape[1]}x{resized.shape[0]}")
    # 显示图片
    cv2.imshow("Original Image", image)
    cv2.imshow("Resized Image (via imutils)", resized)
    # 等待按键
    cv2.waitKey(0)
    cv2.destroyAllWindows()
    print("\nimutils 功能验证成功！")
except Exception as e:
    print(f"验证失败: {e}")

运行脚本： 在终端中运行这个 Python 脚本：

python verify_imutils.py

如果一切正常，你应该会看到两张图片弹出来，一张是原始尺寸，一张是宽度为 400 像素的调整后图片,并且终端会打印出相应的尺寸信息。

常见问题与解决方案 (FAQ)

问题：pip install imutils 失败，提示 Could not find a version that satisfies the requirement imutils 或 No matching distribution found for imutils

原因分析： 这通常不是 imutils 包本身的问题，而是其依赖项 opencv-python 的问题。opencv-python 是一个非常庞大的包，安装或下载时可能会因为网络问题、Python 版本不兼容或系统架构问题而失败。

解决方案：

• 尝试国内镜像源： 这是最有效的解决方法之一，使用清华大学的镜像源。

  pip install imutils -i https://pypi.tuna.tsinghua.edu.cn/simple

• 升级 pip： 确保 pip 是最新版本。

  pip install --upgrade pip

• 单独安装 opencv-python： 先尝试单独安装 opencv-python。

  pip install opencv-python

  如果这个成功了，再安装 imutils 通常也会成功。

  pip install imutils

• 检查 Python 版本： 确保你的 Python 版本与 opencv-python 的版本兼容，通常建议使用 Python 3.6+。

问题：ModuleNotFoundError: No module named 'cv2' 或 ImportError: cannot import name 'imutils'

原因分析：

• cv2 模块找不到： imutils 依赖于 opencv-python，这个错误说明 opencv-python 没有被正确安装。
• imutils 模块找不到： imutils 本身没有被安装。

解决方案：

• 确认安装： 运行 pip list 查看是否在已安装的包列表中看到了 opencv-python 和 imutils。
• 重新安装：
  1. 卸载现有包：pip uninstall opencv-python imutils
  2. 重新安装：pip install opencv-python imutils
  3. 或者使用国内镜像：pip install opencv-python imutils -i https://pypi.tuna.tsinghua.edu.cn/simple

问题：在 Jupyter Notebook 或 Google Colab 中无法显示图片

原因分析： 在 Notebook 环境中，cv2.imshow() 不会像在桌面应用中那样弹出窗口，你需要使用 Notebook 的特殊方法来显示图像。

解决方案： 使用 matplotlib 库来显示 OpenCV 读取的图像，注意 OpenCV 默认读取的是 BGR 格式，而 matplotlib 期望的是 RGB 格式,需要转换。

import cv2
import imutils
import matplotlib.pyplot as plt
# 读取图片
image = cv2.imread("test.jpg")
# 使用 imutils 调整大小
resized = imutils.resize(image, width=400)
# --- 在 Notebook 中显示图片 ---
# 1. 显示原始图片
# BGR to RGB conversion
plt.imshow(cv2.cvtColor(image, cv2.COLOR_BGR2RGB))"Original Image")
plt.axis('off') # 关闭坐标轴
plt.show()
# 2. 显示调整后的图片
plt.imshow(cv2.cvtColor(resized, cv2.COLOR_BGR2RGB))"Resized Image (via imutils)")
plt.axis('off')
plt.show()

1. 安装：pip install imutils (推荐使用虚拟环境和国内镜像源)。
2. 验证：通过一个简单的 imutils.resize() 功能测试来确认安装。
3. 遇到问题：大多数问题都与 opencv-python 的安装有关，解决方法是使用国内镜像源或单独安装 opencv-python。
4. 在 Notebook 中使用：使用 matplotlib 和 cv2.cvtColor() 来正确显示图像。

希望这份详细的指南能帮助你成功安装并开始使用 imutils！