目标

学习

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指示这种能力，并将源类型作为其参数，而不是制作自己的绑定函数。这就是从Mat映射的UMat的情况。最后，如果需要默认参数，但本机C++接口中未提供，您可以为Python端提供它作为CV_WRAP_DEFAULT的参数。根据下面的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;
};