opencv-contrib-python-rolling 5.0.0.20221015

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 轮子。然而，由于源构建不懂得 pyproject.toml 中的构建依赖项，因此也会失败。要使用新的 manylinux2014 预构建轮子（或从源构建），您的 pip 版本必须 >= 19.3。请使用 pip install --upgrade pip 升级 pip。

Q：在 Windows 上导入失败：ImportError: DLL load failed: The specified module could not be found.？

A：如果在 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 存在一个导致错误的错误，请参阅此问题以获取手动修复方法。

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

问：我有一些其他导入错误？

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

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

答：此存储库仅包含 OpenCV-Python 软件包构建脚本，但不包含 OpenCV 本身。OpenCV 的 Python 绑定在官方 OpenCV 存储库中开发，因此这是报告问题的最佳位置。在提交新错误之前，请先查看 {OpenCV wiki](https://github.com/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 更容易，并且这使得使用搜索引擎查找包更容易。在旧版本的 OpenCV 中，旧接口的名称是 cv，OpenCV 开发者在创建绑定生成器时选择了 cv2 的名称。为了与互联网上的各种教程保持一致，将其保留为导入名称。更改导入名称或行为可能会让习惯于使用 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 构建 在 manylinux Docker 容器（CentOS 5）中运行
   • 源代码分布是构建矩阵中的单独条目

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

5. Linux 和 macOS 的 wheel 文件分别通过 auditwheel 和 delocate 进行转换

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 以构建 contrib 和/或无头版本
• 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. 您将在 dist 文件夹中找到 wheel 文件，您可以对其进行任何操作
   • 可选：在 Linux 上，如果需要最大可移植性，请使用某些 manylinux 图像作为构建主机，并在构建后运行 auditwheel 对 wheel 进行处理
   • 可选：在 macOS 上，使用 delocate（与 auditwheel 相同，但适用于 macOS）以获得更好的可移植性

手动调试构建

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

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

如果您希望构建产生所有编译器命令，则以下组合的标志和环境变量已在 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

源分布

从 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核心锐龙7 3700X上，构建大约需要6分钟。

许可证

此存储库中的OpenCV-python软件包（脚本）可在MIT许可证下获得。

OpenCV本身可在Apache 2许可证下获得。

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

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

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

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

版本控制

find_version.py脚本从OpenCV源中搜索版本信息，并将特定于此存储库的修订号添加到版本字符串中。除了其他一些标志外，它还将版本信息保存到cv2目录下的version.py文件中。

发布

当将新标签推送到主分支时，会进行发布并将它们上传到PyPI。这些标签区分软件包（此存储库可能进行了修改，但OpenCV版本保持不变）并且应按顺序递增。实际上，发布版本号看起来像这样

cv_major.cv_minor.cv_revision.package_revision 例如 3.1.0.0

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

开发构建

对此存储库主分支的每次提交都将进行构建。可能的构建工件使用本地版本标识符

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

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

许多Linux轮子

Linux轮子使用manylinux2014构建。由于它们针对旧版本的glibc进行构建，因此这些轮子应该可以在大多数使用GNU C标准库的发行版（例如，使用旧版glibc的发行版）中直接使用。

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

支持的Python版本

提供与官方支持的Python版本兼容的预构建轮子（不在EOL）

• 3.6
• 3.7
• 3.8
• 3.9
• 3.10

向后兼容性

从4.2.0和3.4.9版本开始，macOS Travis构建环境更新到XCode 9.4。此更改实际上取消了旧于10.13的macOS版本的支持。

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