opencv-python-asen 4.5.10

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（查看 contrib/extra 模块列表，请参阅OpenCV 文档）

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

   这些包比上面两个包更小，因为它们不包含任何 GUI 功能（未使用 Qt / 其他 GUI 组件编译）。这意味着这些包避免了与 X11 库的复杂依赖链，您将获得更小的 Docker 镜像作为结果。如果您不使用 cv2.imshow 等功能或使用 OpenCV 以外的其他包（如 PyQt）来创建 GUI，则应始终使用这些包。

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

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 install 失败，出现错误 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。

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 媒体功能包。

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

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

如果在检查了所有之前提供的解决方案之后，您仍然遇到错误，请下载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](https://github.com/opencv/opencv/wiki)和官方OpenCV论坛。

问：为什么这些包不包括非免费算法？

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

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

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

opencv-python文档

此存储库的目的是提供一种方法，为最常用的Python版本和平台包装每个新的OpenCV发布版。

CI构建过程

该项目结构像一个正常的Python包，具有标准的setup.py文件。单个条目在构建矩阵中的构建过程如下（例如，请参阅.github/workflows/build_wheels_linux.yml文件）

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

1. 检出存储库和子模块

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

2. 从源中查找OpenCV版本

3. 构建OpenCV

   • 禁用测试，否则构建时间会增加太多
   • 对于每种构建组合，有4个构建矩阵条目：包含和不含贡献模块，包含和不含GUI（无头）
   • Linux构建在许多Linux 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，则设置 export 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

如果需要 contrib 模块或无头版本，只需更改包名（上一节中的步骤 4 不需要）。但是，可以通过环境变量提供任何附加的 Cmake 标志，如手动构建部分的步骤 3 中所述。如果没有提供，OpenCV 的 Cmake 脚本将尝试找到和启用任何合适的依赖项。无头分发具有硬编码的 Cmake 标志，该标志禁用了所有可能的 GUI 依赖项。

在慢速系统（如树莓派）上，完整的构建可能需要几个小时。在 8 核 Ryzen 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。

Manylinux wheels

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

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

支持的Python版本

为官方支持的Python版本（不在EOL）提供了兼容Python 3.x的预构建wheels。

• 3.6
• 3.7
• 3.8
• 3.9

向后兼容性

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

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