目标

学习

OpenCV-Python 绑定是如何生成的？
如何将新的 OpenCV 模块扩展到 Python？

OpenCV-Python 绑定是如何生成的？

在 OpenCV 中，所有算法都使用 C++ 实现。但是这些算法可以被不同的语言，例如 Python、Java 等使用。这是通过绑定生成器实现的。这些生成器在 C++ 和 Python 之间架起了一座桥梁，使用户能够从 Python 调用 C++ 函数。为了全面了解后台发生的情况，需要具备 Python/C API 的良好知识。在 Python 官方文档[1]中可以找到一个关于将 C++ 函数扩展到 Python 的简单示例。因此，通过手动编写包装函数将 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/ 文件夹中找到这些头文件，名为 pyopencv_generated_*.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 绑定生成的基本版本。

注意: numpy.ndarray 和cv::Mat之间没有 1:1 的映射关系。例如，cv::Mat 有 channels 字段，它被模拟为 numpy.ndarray 的最后一维并隐式转换。但是，这种隐式转换在将 3D numpy 数组传递到 C++ 代码时存在问题（最后一维被隐式地重新解释为通道数）。如果您需要处理 3D 数组或具有通道的 ND 数组，请参考此问题以了解解决方法。OpenCV 4.5.4+ 有一个从numpy.ndarray派生的cv.Mat包装器来显式处理通道行为。

如何将新的模块扩展到 Python？

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

使用CV_EXPORTS_W宏扩展函数。下面显示一个示例。

CV_EXPORTS_W void equalizeHist( InputArray src, OutputArray dst );

CV_EXPORTS_W

#define CV_EXPORTS_W

定义 cvdef.h:472

头文件解析器可以从 InputArray、OutputArray 等关键字理解输入和输出参数。参数语义保留在 Python 中：在 C++ 中修改的任何内容都将在 Python 中修改。反之亦然，如果只读 Python 对象用作输出，则不能被 OpenCV 修改。这种情况将导致 Python 异常。有时，在 C++ 中按引用传递的参数可以用作输入、输出或两者兼而有之。宏CV_OUT、CV_IN_OUT允许解决歧义并生成正确的绑定。

CV_EXPORTS_W void minEnclosingCircle( InputArray points,

CV_OUT Point2f& center, CV_OUT float& radius );

CV_OUT

#define CV_OUT

定义 cvdef.h:478

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

class CV_EXPORTS_W CLAHE : public Algorithm
{
public:
    CV_WRAP virtual void apply(InputArray src, OutputArray dst) = 0;
 
    CV_WRAP virtual void setClipLimit(double clipLimit) = 0;
    CV_WRAP virtual double getClipLimit() const = 0;
}

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

 
CV_EXPORTS_W void integral( InputArray src, OutputArray sum, int sdepth = -1 );
 
CV_EXPORTS_AS(integral2) void integral( InputArray src, OutputArray sum,
OutputArray sqsum, int sdepth = -1, int sqdepth = -1 );
 
CV_EXPORTS_AS(integral3) void integral( InputArray src, OutputArray sum,
OutputArray sqsum, OutputArray tilted,
                                        int sdepth = -1, int sqdepth = -1 );

小型类/结构体使用`CV_EXPORTS_W_SIMPLE`扩展。这些结构体按值传递给C++函数。例如`KeyPoint`、`Match`等。它们的方法由`CV_WRAP`扩展，字段由`CV_PROP_RW`扩展。

class CV_EXPORTS_W_SIMPLE DMatch
{
public:
    CV_WRAP DMatch();
    CV_WRAP DMatch(int _queryIdx, int _trainIdx, float _distance);
    CV_WRAP DMatch(int _queryIdx, int _trainIdx, int _imgIdx, float _distance);
 
    CV_PROP_RW int queryIdx; // 查询描述符索引
    CV_PROP_RW int trainIdx; // 训练描述符索引
    CV_PROP_RW int imgIdx; // 训练图像索引
 
    CV_PROP_RW float distance;
};

一些其他的小型类/结构体可以使用`CV_EXPORTS_W_MAP`导出，其中它被导出到Python原生字典。`Moments()`就是一个例子。

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

所以这些是OpenCV中可用的主要扩展宏。通常，开发人员必须将其合适的宏放在相应的位置。其余工作由生成器脚本完成。有时，生成器脚本可能无法创建包装器，这属于例外情况。此类函数需要手动处理，为此，请编写您自己的`pyopencv_*.hpp`扩展头文件，并将它们放入模块的misc/python子目录中。但在大多数情况下，根据OpenCV编码指南编写的代码将由生成器脚本自动包装。

更高级的情况包括为Python提供C++接口中不存在的其他功能，例如额外的方法、类型映射或提供默认参数。稍后我们将以`UMat`数据类型为例说明此类情况。首先，为了提供Python特定的方法，`CV_WRAP_PHANTOM`的使用方式与`CV_WRAP`类似，不同之处在于它采用方法头作为参数，并且您需要在您自己的`pyopencv_*.hpp`扩展中提供方法体。`UMat::queue()`和`UMat::context()`就是这类幻影方法的例子，它们在C++接口中不存在，但在Python端需要处理OpenCL功能。其次，如果现有数据类型可映射到您的类，则强烈建议使用`CV_WRAP_MAPPABLE`及其源类型作为参数来指示此功能，而不是创建您自己的绑定函数。`UMat`就是一个例子，它从`Mat`映射而来。最后，如果需要默认参数，但在本机C++接口中未提供，则可以将其作为`CV_WRAP_DEFAULT`的参数为Python端提供。如下面的`UMat::getMat`示例所示

class CV_EXPORTS_W UMat
{
public:
    // 您需要提供`static bool cv_mappable_to(const Ptr<Mat>& src, Ptr<UMat>& dst)`
    CV_WRAP_MAPPABLE(Ptr<Mat>);
 
// 返回OpenCV UMat使用的OpenCL队列。
    // 您需要在绑定代码中提供方法体
    CV_WRAP_PHANTOM(static void* queue());
 
    // 您需要在绑定代码中提供方法体
    CV_WRAP_PHANTOM(static void* context());
 
    CV_WRAP_AS(get) Mat getMat(int flags CV_WRAP_DEFAULT(ACCESS_RW)) const;
};