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;
};