OpenCV  4.10.0
开源计算机视觉
正在载入...
正在搜索...
没有匹配项
OpenCV-Python 绑定是如何工作的?

目标

了解

  • 如何生成 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+ 具有 cv.Mat 包装器,它派生自 numpy.ndarray 以明确处理 channels 行为。

如何将新模块扩展到 Python?

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

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

CV_EXPORTS_W void equalizeHist( InputArray src, OutputArray dst );
#define CV_EXPORTS_W
定义 cvdef.h:472

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

CV_EXPORTS_W void minEnclosingCircle( InputArray points,
CV_OUT Point2f& center, CV_OUT float& radius );
#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;
}
#define CV_WRAP
定义 cvdef.h:481

过载函数可以使用 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 );
#define CV_EXPORTS_AS(synonym)
定义 cvdef.h:474

小型类/结构体使用 CV_EXPORTS_W_SIMPLE 扩展。这些结构体按值传递给 C++ 函数。示例有 KeyPointMatch 等。其方法由 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;
};
#define CV_EXPORTS_W_SIMPLE
定义 cvdef.h:473
#define CV_PROP_RW
定义 cvdef.h:480

一些其他小型类/结构体可以使用 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;
};
#define CV_EXPORTS_W_MAP
定义 cvdef.h:475

因此,这些是 OpenCV 中可用的主要扩展宏。一般而言,开发人员必须将其合适的宏放在其合适的位置。其余的由生成器脚本完成。有时候,可能有一些特殊情况,在这些情况下生成器脚本无法创建封装器。此类函数需要手动处理,为此,请编写自己的 pyopencv_*.hpp 扩展头并将其放入模块的 misc/python 子目录中。但是,大多数时候,根据 OpenCV 编码规则编写的代码会自动由生成器脚本封装。

进阶的情况涉及用额外的 C++ 接口中不存在的功能为 Python 提供功能,例如额外的使用方法、类型映射或提供默认参数。稍后我们将以 UMat 数据类型为例来说明此类情况。首先,要提供 Python 特定方法,在类似于 CV_WRAP 的方式中使用 CV_WRAP_PHANTOM,但这里将方法头作为参数,并且需要在自己的 pyopencv_*.hpp 扩展中提供方法主体。UMat::queue()UMat::context() 是此类幻象方法的一个示例,在 C++ 接口中不存在,但在 Python 端需要处理 OpenCL 功能。其次,如果现有的数据类型可以映射到自己的类,则最好使用 CV_WRAP_MAPPABLE 来指示这种容量,并且源类型作为其参数,而不是自己制作绑定函数。这是从 Mat 映射的 UMat 的情况。最后,如果需要默认参数,但它的本机 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;
};
#define CV_WRAP_AS(synonym)
定义 cvdef.h:482
#define CV_WRAP_PHANTOM(phantom_header)
定义 cvdef.h:484
#define CV_WRAP_DEFAULT(val)
定义 cvdef.h:485
#define CV_WRAP_MAPPABLE(mappable)
定义 cvdef.h:483