如何生成 OpenCV-Python 绑定？

在 OpenCV 中，所有算法都是用 C ++实现的。但是这些算法可以用于不同的语言，如 Python，Java 等。这可以通过绑定生成器实现。这些生成器在 C++和 Python 之间架起了一座桥梁，使用户能够从 Python 调用 C++函数。要全面了解后台发生的情况，需要熟悉 Python / C 的 API。有关将 C++函数扩展到 Python 的简单示例可以在官方 Python 文档中找到[1]。因此，通过手动编写包装函数将 OpenCV 中的所有函数扩展到 Python 是一项非常耗时的任务。所以 OpenCV 以更智能的方式完成它。 OpenCV 使用一些位于modules/python/src2中的 Python 脚本从 C++头文件自动生成这些包装函数。我们将研究他们的工作。

首先，modules/python/CMakeFiles.txt是一个 CMake 脚本，它检查要扩展到 Python 的模块。它会自动检查所有要扩展的模块并获取它们的头文件。这些头文件包含该特定模块的所有类、函数、常量等的列表。

其次，将这些头文件传递给 Python 脚本modules/python/src2/gen2.py。这是 Python 绑定生成器脚本。它调用另一个 Python 脚本modules/python/src2/hdr_parser.py。这是头解析器脚本。此标头解析器将完整的头文件拆分为小的 Python 列表。因此，这些列表包含有关特定函数、类等的所有详细信息。例如，将解析函数以获取包含函数名称，返回类型，输入参数，参数类型等的列表。最终列表包含所有函数的详细信息，枚举该头文件中的结构、类、等等。

但是头解析器不解析头文件中的所有函数/类。开发人员必须指定应将哪些函数导出到 Python。为此，在这些声明的开头添加了某些宏，这使得标头解析器能够识别要解析的函数。这些宏由编程特定功能的开发人员添加。简而言之，开发人员决定哪些函数应该扩展到 Python，哪些不是。这些宏的详细信息将在下一个会话中给出。

因此，头解析器返回解析函数的最终大列表。我们的生成器脚本（gen2.py）将为头解析器解析的所有函数/类/枚举/结构创建包装器函数（您可以在build/modules/python/文件夹中编译这些头文件作为 pyopencvgenerated*.h 文件）。但是可能有一些基本的 OpenCV 数据类型，如 Mat，Vec4i，Size。它们需要手动扩展。例如，Mat 类型应该扩展为 Numpy 数组，Size 应该扩展为两个整数的元组等。类似地，可能有一些复杂的结构/类/函数等需要手动扩展。所有这些手动包装函数都放在modules/python/src2/cv2.cpp中。

所以现在唯一剩下的就是编译这些包装文件，它们为我们提供了 cv2 模块。所以当你在 Python 中调用一个函数，比如res = equalizeHist（img1，img2）时，你会传递两个 numpy 数组，你期望另一个 numpy 数组作为输出。所以这些 numpy 数组转换为 cv::Mat，然后在 C++中调用 equalizeHist() 函数。最终结果，res 将被转换回 Numpy 数组。简而言之，几乎所有操作都是用 C++完成的，这使我们的速度几乎与 C++相同。

所以这是 OpenCV-Python 绑定生成方式的基本版本。

如何将新模块扩展到 Python？

头解析器基于添加到函数声明中的一些包装器宏来解析头文件。枚举常量不需要任何包装器宏。它们是自动包装的。但是剩余的函数、类等需要包装器宏。

函数使用CV_EXPORTS_W宏进行扩展。下面是一个例子。

  1. CV_EXPORTS_W void equalizeHist( InputArray src, OutputArray dst );

头解析器可以理解关键字 InputArray、OutputArray 等的输入和输出参数。但有时，我们可能需要硬编码输入和输出。为此，使用了诸如CV_OUT、CV_IN_OUT等宏。

  1. CV_EXPORTS_W void minEnclosingCircle( InputArray points,
  2.                                      CV_OUT Point2f& center, CV_OUT float& radius );

对于大型类，也使用CV_EXPORTS_W。要扩展类方法，使用CV_WRAP。类似地，CV_PROP用于类字段。

  1. class CV_EXPORTS_W CLAHE : public Algorithm
  2. {
  3. public:
  4.     CV_WRAP virtual void apply(InputArray src, OutputArray dst) = 0;
  5.     CV_WRAP virtual void setClipLimit(double clipLimit) = 0;
  6.     CV_WRAP virtual double getClipLimit() const = 0;
  7. }

重载的函数可以使用 CV_EXPORTS_AS 进行扩展。但是我们需要传递一个新名称，以便在 Python 中每个函数都使用这个名称来调用。以下面的积分函数为例。有三个函数可用，因此在 Python 中每个函数都有一个后缀。类似地，CV_WRAP_AS可以用于包装重载的方法。

  1. CV_EXPORTS_W void integral( InputArray src, OutputArray sum, int sdepth = -1 );
  3. CV_EXPORTS_AS(integral2) void integral( InputArray src, OutputArray sum,
  4.                                         OutputArray sqsum, int sdepth = -1, int sqdepth = -1 );
  6. CV_EXPORTS_AS(integral3) void integral( InputArray src, OutputArray sum,
  7.                                         OutputArray sqsum, OutputArray tilted,
  8.                                         int sdepth = -1, int sqdepth = -1 );

使用CV_EXPORTS_W_SIMPLE扩展小类/结构。这些结构体通过值传递给 c++函数。例子有关键点，匹配等。它们的方法由CV_WRAP扩展，字段由CV_PROP_RW扩展。

  1. class CV_EXPORTS_W_SIMPLE DMatch
  2. {
  3. public:
  4.     CV_WRAP DMatch();
  5.     CV_WRAP DMatch(int _queryIdx, int _trainIdx, float _distance);
  6.     CV_WRAP DMatch(int _queryIdx, int _trainIdx, int _imgIdx, float _distance);
  7.     CV_PROP_RW int queryIdx; // query descriptor index
  8.     CV_PROP_RW int trainIdx; // train descriptor index
  9.     CV_PROP_RW int imgIdx;   // train image index
  10.     CV_PROP_RW float distance;
  11. };

其他一些小类/结构可以使用CV_EXPORTS_W_MAP导出，并将其导出到 Python 本地字典。矩()就是一个例子。

  1. class CV_EXPORTS_W_MAP Moments
  2. {
  3. public:
  4.     CV_PROP_RW double  m00, m10, m01, m20, m11, m02, m30, m21, m12, m03;
  5.     CV_PROP_RW double  mu20, mu11, mu02, mu30, mu21, mu12, mu03;
  6.     CV_PROP_RW double  nu20, nu11, nu02, nu30, nu21, nu12, nu03;
  7. };

这些是 OpenCV 中可用的主要扩展宏。通常，开发人员必须将适当的宏放到适当的位置。Rest 由生成器脚本完成。有时，可能会出现生成器脚本无法创建包装器的异常情况。这类函数需要手动处理，为此编写您自己的pyopencv_*.hpp扩展头文件，并将它们放到模块的 misc/python 子目录中。但是大多数情况下，根据 OpenCV 编码指南编写的代码将被生成器脚本自动包装。

更高级的情况涉及为 Python 提供 c++接口中不存在的额外特性，如额外的方法、类型映射或提供默认参数。稍后我们将以UMat数据类型作为此类情况的一个示例。首先，要提供特定于 python 的方法，CV_WRAP_PHANTOM的使用方式与CV_WRAP类似，不同之处是它以方法头作为参数，您需要在自己的 pyopencv_*中提供方法体。进行扩展。queue()和UMat::context()就是这种虚方法的一个例子，这种虚方法在 c++接口中不存在，但是在 Python 端处理 OpenCL 功能时需要用到。其次，如果已经存在的数据类型可以映射到您的类，那么最好使用CV_WRAP_MAPPABLE(以源类型作为参数)来表示这种容量，而不是构建您自己的绑定函数。最后，如果需要一个默认参数，但在本机 c++接口中没有提供，那么可以将其作为CV_WRAP_DEFAULT参数提供给 Python 端。根据下面的UMat::getMat示例:

  1. class CV_EXPORTS_W UMat
  2. {
  3. public:
  4.     // You would need to provide `static bool cv_mappable_to(const Ptr<Mat>& src, Ptr<UMat>& dst)`
  5.     CV_WRAP_MAPPABLE(Ptr<Mat>);
  6.     /! returns the OpenCL queue used by OpenCV UMat.
  7.     // You would need to provide the method body in the binder code
  8.     CV_WRAP_PHANTOM(static void* queue());
  9.     // You would need to provide the method body in the binder code
  10.     CV_WRAP_PHANTOM(static void* context());
  11.     CV_WRAP_AS(get) Mat getMat(int flags CV_WRAP_DEFAULT(ACCESS_RW)) const;
  12. };