opencv-contrib-python 4.10.0.84

让OpenCV免费

OpenCV正在筹集资金以使库对所有人免费，我们需要整个社区的支持来实现这一点。请通过在Github上捐赠给OpenCV来展示您的支持。

• OpenCV on Wheels
  • 安装和使用
• 常见问题解答
• opencv-python文档
  • CI构建过程
  • 手动构建
    • 手动调试构建
    • 源代码发行版
  • 许可
  • 版本控制
  • 发布
  • 开发构建
  • Manylinux wheels
  • 支持的Python版本
  • 向下兼容性

OpenCV on Wheels

为Python预构建的仅CPU OpenCV软件包。

如果您希望从源代码编译绑定以启用如CUDA等附加模块，请查看手动构建部分。

安装和使用

1. 如果您已安装之前的/其他手动安装（非通过pip安装）的OpenCV版本（例如Python的site-packages根目录中的cv2模块），则在安装之前请将其删除以避免冲突。

2. 请确保您的pip版本是最新的（最低支持版本为19.3）：pip install --upgrade pip。使用pip -V检查版本。例如，Linux发行版通常带有非常旧的pip版本，这会导致许多意外问题，尤其是在manylinux格式中。

3. 选择适合您环境的正确包

   有四种不同的包（参见下述选项1、2、3和4），您应该只选择其中之一。不要在同一环境中安装多个不同的包。没有插件架构：所有包都使用相同的命名空间（cv2）。如果您在同一环境中安装了多个不同的包，请使用pip uninstall卸载所有包，然后只重新安装一个包。

   a. 标准桌面环境（Windows、macOS、几乎任何GNU/Linux发行版）的包

   • 选项1 - 主要模块包：pip install opencv-python
   • 选项2 - 完整包（包含主要模块和contrib/extra模块）：pip install opencv-contrib-python（请从OpenCV文档中检查contrib/extra模块列表）

   b. 服务器（无头）环境（如Docker、云环境等）的包，没有GUI库依赖

   这些包比上面的两个包都要小，因为它们不包含任何GUI功能（没有使用Qt/其他GUI组件编译）。这意味着这些包避免了到X11库的沉重依赖链，例如，您将获得更小的Docker镜像。如果您不使用cv2.imshow等函数或使用其他包（如PyQt）而不是OpenCV来创建GUI，则应始终使用这些包。

   • 选项3 - 无头主要模块包：pip install opencv-python-headless
   • 选项4 - 无头完整包（包含主要模块和contrib/extra模块）：pip install opencv-contrib-python-headless（请从OpenCV文档中检查contrib/extra模块列表）

4. 导入包

   import cv2

   所有包都包含Haar级联文件。cv2.data.haarcascades可以用于快速访问数据文件夹。例如

   cv2.CascadeClassifier(cv2.data.haarcascades + "haarcascade_frontalface_default.xml")

5. 阅读OpenCV文档

6. 在提交新问题之前，请阅读以下常见问题解答并查看已打开的其他问题。

常见问题解答

Q：我需要单独安装OpenCV吗？

A：不需要，这些包是特殊的wheel二进制包，它们已经包含了静态构建的OpenCV二进制文件。

Q：使用pip安装失败，出现ModuleNotFoundError: No module named 'skbuild'错误？

自 opencv-python 版本 4.3.0.* 以来，manylinux1 轮子已被 manylinux2014 轮子所替代。如果你的 pip 版本太旧，它将尝试使用 4.3.0.38 中引入的新源分发版来手动构建 OpenCV，因为它不知道如何安装 manylinux2014 轮子。然而，由于 pip 版本太旧而不理解 pyproject.toml 中的构建依赖项，源构建也将失败。为了使用新的 manylinux2014 预构建轮子（或从源代码构建），你的 pip 版本必须 >= 19.3。请使用 pip install --upgrade pip 升级 pip。

问：在 Windows 上导入失败：ImportError: DLL 加载失败：找不到指定的模块。？

答：如果在 Windows 上导入失败，请确保已安装 Visual C++ redistributable 2015。如果你使用的是比 Windows 10 更旧的 Windows 版本，并且未安装最新系统更新，可能还需要 通用 C 运行时。

Windows N 和 KN 版本不包含 OpenCV 所需的媒体功能包。如果你使用的是 Windows N 或 KN 版本，请安装 Windows 媒体功能包。

如果你有 Windows Server 2012+，媒体 DLL 可能也丢失；请通过服务器管理器安装名为“媒体基础”的功能。请注意，一些帖子建议安装“Windows Server Essentials Media Pack”，但它需要“Windows Server Essentials Experience”角色，这将严重影响你的 Windows Server 配置（通过强制活动目录集成等）；所以只安装“媒体基础”应该是一个更安全的选择。

如果上述方法都不起作用，请检查你是否在使用 Anaconda。旧版本的 Anaconda 存在一个导致错误的bug，有关手动修复方法，请参阅 此问题。

如果你在检查了所有前面的解决方案后仍然遇到错误，请下载 Dependencies 并使用它打开 cv2.pyd 文件（通常位于 C:\Users\username\AppData\Local\Programs\Python\PythonXX\Lib\site-packages\cv2），以调试缺少 DLL 的问题。

问：我有其他导入错误？

答：请确保你已经删除了旧的 OpenCV Python 绑定（位于 site-packages 中的 cv2.so 或 cv2.pyd）的手动安装。

问：函数 foo() 或方法 bar() 返回错误的结果，抛出异常或导致解释器崩溃。我应该怎么办？

答：该存储库只包含 OpenCV-Python 软件包构建脚本，但不包含 OpenCV 本身。OpenCV 的 Python 绑定是在官方 OpenCV 存储库中开发的，因此这是报告问题的最佳位置。在提交新错误报告之前，请检查 OpenCV wiki 和 官方 OpenCV 论坛。

问：为什么包不包含非自由算法？

答：由于非自由算法（如 SURF）是受专利保护和非自由的，因此它们不包含在这些包中，因此不能作为构建的二进制文件分发。请注意，由于专利到期，自 OpenCV 版本 4.3.0 和 3.4.10 以来，SIFT 已包含在构建中。有关更多信息，请参阅此问题：https://github.com/skvark/opencv-python/issues/126

问：为什么包和导入不同（opencv-python 与 cv2）？

答：对于用户来说，理解 opencv-python 比理解 cv2 更容易，并且它使得通过搜索引擎查找包更容易。cv2（旧版本 OpenCV 中的旧接口命名为 cv）是 OpenCV 开发者在创建绑定生成器时选择的名字。为了与互联网上各种教程保持一致，它被保留为导入名称。更改导入名称或行为可能会让习惯于 import cv2 的经验用户感到困惑。

opencv-python文档

本仓库的目的是提供一种方法，为最常用的Python版本和平台打包每个新的OpenCV版本。

CI构建过程

该项目结构类似于普通的Python包，具有标准的setup.py文件。构建矩阵中单个条目的构建过程如下（例如，参见.github/workflows/build_wheels_linux.yml文件）

0. 在Linux和MacOS构建中：获取我们针对编译的OpenCV的可选C依赖项

1. 检出仓库和子模块

   • OpenCV作为子模块包含在内，版本由维护者手动更新，当发布新的OpenCV版本时
   • 贡献模块也作为子模块包含在内

2. 从源代码中查找OpenCV版本

3. 构建OpenCV

   • 禁用测试，否则构建时间会增加太多
   • 对于每个构建组合，有4个构建矩阵条目：有无贡献模块，有无GUI（无头）
   • Linux构建在许多Linux Docker容器（CentOS 5）中运行
   • 源代码分发在构建矩阵中是单独的条目

4. 重新排列OpenCV的构建结果，添加我们的自定义文件并生成wheel

5. 使用auditwheel和delocate相应地将Linux和macOS wheel进行转换

6. 安装生成的wheel

7. 测试Python是否可以导入库并运行一些基本的检查

8. 使用twine将生成的wheel上传到PyPI（仅在发布构建中）

步骤1--4由pip wheel处理。

可以使用环境变量自定义构建。除了OpenCV构建接受的任何变量外，我们还认可

• CI_BUILD。设置为1以模拟CI环境构建行为。仅在CI构建中使用，以在setup.py中强制某些构建标志。除非您知道自己在做什么，否则请勿使用此变量。
• ENABLE_CONTRIB和ENABLE_HEADLESS。设置为1以构建贡献和/或无头版本
• ENABLE_JAVA，设置为1以启用Java客户端构建。默认情况下是禁用的。
• CMAKE_ARGS。OpenCV CMake调用的附加参数。您可以使用此参数进行自定义构建。

有关CI环境之外的手动构建的更多信息，请参阅下一节。

手动构建

如果某些依赖项在预构建的wheel中没有启用，您还可以在本地运行构建以创建自定义wheel。

1. 克隆此仓库：git clone --recursive https://github.com/opencv/opencv-python.git
2. cd opencv-python
   • 如果需要，您可以使用git在opencv和opencv_contrib子模块中检出其他版本的OpenCV
3. 如果需要，添加自定义Cmake标志，例如：export CMAKE_ARGS="-DSOME_FLAG=ON -DSOME_OTHER_FLAG=OFF"（在Windows上，您需要根据命令行或PowerShell设置不同的环境变量）
4. 选择您希望构建的包风味，使用ENABLE_CONTRIB和ENABLE_HEADLESS：即，如果希望构建opencv-contrib-python，则将ENABLE_CONTRIB设置为1
5. 运行pip wheel . --verbose。注意：请确保您有最新的pip版本，pip wheel命令替换了旧的python setup.py bdist_wheel命令，该命令不支持pyproject.toml。
   • 这可能需要从5分钟到2小时以上，具体取决于您的硬件
6. Pip将在构建过程结束时打印出新鲜wheel的位置。如果您使用旧的带有setup.py文件的构建方法，wheel包将放置在dist文件夹中。包已准备好，您可以随心所欲地处理它。
   • 可选：在Linux上，如果需要最大可移植性，请使用某些manylinux镜像作为构建主机，并在构建后运行auditwheel
   • 可选：在macOS上，使用delocate（与auditwheel相同，但适用于macOS）以提高可移植性

手动调试构建

为了在不优化的调试构建中构建opencv-python，您需要稍微绕过正常流程。

1. 通过pip安装scikit-build和numpy包。
2. 运行以下命令：python setup.py bdist_wheel --build-type=Debug。
3. 使用以下命令在dist/文件夹中安装生成的wheel文件：pip install dist/wheelname.whl。

如果您希望构建过程生成所有编译命令，以下标志和环境变量的组合已在Linux上测试过，可以正常工作：

export CMAKE_ARGS='-DCMAKE_VERBOSE_MAKEFILE=ON'
export VERBOSE=1

python3 setup.py bdist_wheel --build-type=Debug

有关更多讨论，请参阅此问题：[https://github.com/opencv/opencv-python/issues/424](https://github.com/opencv/opencv-python/issues/424)

源代码发行版

从OpenCV版本4.3.0开始，PyPI也提供了源分发。这意味着如果您的系统与PyPI上的任何wheel不兼容，pip将尝试从源代码构建OpenCV。如果您需要PyPI上没有作为源分发的OpenCV版本，请按照上述手动构建指南进行操作，而不是本指南。

您还可以强制pip从源分发构建wheel。以下是一些示例：

• pip install --no-binary opencv-python opencv-python
• pip install --no-binary :all: opencv-python

如果您需要贡献模块或无头版本，只需更改包名（上节中的第4步不需要）。但是，任何额外的CMake标志都可以通过环境变量提供，如手动构建部分的第3步所述。如果没有提供，OpenCV的CMake脚本将尝试查找和启用任何合适的依赖项。无头分发有硬编码的CMake标志，禁用所有可能的GUI依赖项。

在像树莓派这样的慢速系统上，完整的构建可能需要几个小时。在8核心的Ryzen 7 3700X上，构建大约需要6分钟。

许可

Opencv-python包（此存储库中的脚本）在MIT许可下可用。

OpenCV本身在Apache 2许可下可用。

第三方包的许可证在LICENSE-3RD-PARTY.txt中。

所有wheel都包含FFmpeg，许可协议为LGPLv2.1。

非无头Linux wheel包含Qt 5，许可协议为LGPLv3。

包还包括其他二进制文件。完整的许可证列表可以在LICENSE-3RD-PARTY.txt中找到。

版本控制

find_version.py脚本从OpenCV源中查找版本信息，并将特定于此存储库的修订号添加到版本字符串中。它将版本信息保存到cv2下的version.py文件中，以及一些其他标志。

发布

当向master分支推送新的标签时，就会制作和上传到PyPI。这些标签区分包（此存储库可能会有修改，但OpenCV版本保持不变）并应顺序递增。实际上，发布版本号看起来像这样：

cv_major.cv_minor.cv_revision.package_revision，例如3.1.0.0

master分支遵循OpenCV master分支的发布。3.4分支遵循OpenCV 3.4的错误修复发布。

开发构建

此存储库的master分支上的每个提交都会进行构建。可能的构建工件使用本地版本标识符

cv_major.cv_minor.cv_revision+git_hash_of_this_repo，例如3.1.0+14a8d39

这些工件不能，也不会上传到PyPI。

Manylinux wheels

Linux wheel使用manylinux2014构建。由于它们针对旧的glibc版本构建，因此这些wheel应适用于大多数distros（使用GNU C标准库），无需额外操作。

默认的manylinux2014镜像已扩展了一些OpenCV依赖项。有关更多信息，请参阅Docker文件夹。

支持的Python版本

为官方支持的Python版本（非已淘汰版本）提供了Python 3.x兼容的预构建wheels。

• 3.7
• 3.8
• 3.9
• 3.10
• 3.11
• 3.12

向下兼容性

从4.2.0和3.4.9版本开始，macOS Travis构建环境更新到XCode 9.4。此更改实际上取消了对于10.13以下macOS版本的兼容性。

从4.3.0和3.4.10版本开始，Linux构建环境从manylinux1更新到manylinux2014。这取消了旧Linux发行版的兼容性。

从版本4.7.0开始，Mac OS GitHub Actions构建环境更新到版本11。Mac OS 10.x支持已被弃用。请参阅https://github.com/actions/runner-images/issues/5583

从版本4.9.0开始，Mac OS GitHub Actions构建环境更新到版本12。Mac OS 10.x支持已被Brew和大多数常用软件包弃用。