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 绑定的基本生成方式。

注意事项
在 cv::Mat 上没有 numpy.ndarray 的 1:1 映射。例如，cv::Mat 有 channels
字段，它被模拟为 numpy.ndarray 的最后一个维度并进行隐式转换。然而，这种隐式转换在将 3D numpy 数组传递到 C++
代码时会出现问题（最后一维被隐式地重新解释为通道数）。如果您需要处理三维数组或带有通道的 ND
数组，请参阅该问题以获取变通方法。OpenCV 4.5.4+ 中的 cv.Mat wrapper 源自
numpy.ndarray，可明确处理通道行为。

如何将新模块扩展到 Python？
头文件解析器会根据添加到函数声明中的一些封装宏来解析头文件。枚举常量不需要任何包装宏。它们会被自动封装。但其余的函数、类等需要包装宏。

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

CV_EXPORTS_W void equalizeHist( InputArray src, OutputArray dst );

头文件解析器可以通过 InputArray、OutputArray 等关键字理解输入和输出参数。但有时，我们可能需要对输入和输出进行硬编码。为此，需要使用 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; // 查询描述符索引
    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++ 接口中没有提供，可以将其作为 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;
};

这是官方文档OpenCV中OpenCV-Python的最后一篇文章。