OpenCV Python Bindings

【目标】

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

【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/文件夹中找到这些头文件作为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没有1:1 将cv::Mat映射为ndarray。例如，cv::Mat具有channels字段，该字段被模拟为numpy的最后一个维度。Ndarray和隐式转换。然而，这种隐式转换在将3D numpy数组传递到c++代码时存在问题(最后一个维度隐式地重新解释为通道数)。如果需要处理带有通道的3D数组或nd -数组，请参阅此问题以获得解决方法。OpenCV 4.5.4+ 有 cv.mat 从numpy派生的包装器。Ndarray显式地处理通道行为。

【新模块添加到 Python】

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

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

CV_EXPORTS_W void equalizeHist( InputArray src, OutputArray dst );

头解释器可以理解输入和输出参数，如： InputArray 和 OutputArray 等，但有时，我们可能需要硬解 inputs 和 outputs 。如宏 CV_OUT, CV_IN_OUT

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

对于大型的类也是一样的，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; // query descriptor index
    CV_PROP_RW int trainIdx; // train descriptor index
    CV_PROP_RW int imgIdx;   // train image index
    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_mapable并将源类型作为参数来指示这种容量，而不是创建自己的绑定函数。UMat就是这样，它从Mat映射过来。最后，如果需要一个默认参数，但在原生c++接口中没有提供，你可以为Python端提供它作为CV_WRAP_DEFAULT的参数。如下面的UMat::getMat例子所示:

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

【参考】

1. OpenCV: How OpenCV-Python Bindings Works?