为使用 OpenCV 的 C++ 代码编写 Python 绑定

Posted 2023-02-23

【中文标题】为使用 OpenCV 的 C++ 代码编写 Python 绑定

【英文标题】：Writing Python bindings for C++ code that use OpenCV

【发布时间】：2012-10-09 01:53:37

【问题描述】：

我正在尝试为一些使用 OpenCV 的 C++ 代码编写 python 包装器，但我在将结果（OpenCV C++ Mat 对象）返回给 python 解释器时遇到了困难。

我查看了 OpenCV 的源代码并找到了文件 cv2.cpp，它具有在 PyObject* 和 OpenCV 的 Mat 之间执行来回转换的转换函数。我使用了这些转换函数，但在尝试使用它们时遇到了分段错误。

我基本上需要一些关于如何连接使用 OpenCV 的 python 和 C++ 代码的建议/示例代码/在线参考，特别是能够将 OpenCV 的 C++ Mat 返回到 python 解释器，或者关于如何/从哪里开始的建议调查分段错误的原因。

目前我正在使用 Boost Python 来包装代码。

提前感谢任何回复。

相关代码：

// This is the function that is giving the segmentation fault.
PyObject* ABC::doSomething(PyObject* image)

    Mat m;
    pyopencv_to(image, m);  // This line gives segmentation fault.

    // Some code to create cppObj from CPP library that uses OpenCV
    cv::Mat processedImage = cppObj->align(m);

    return pyopencv_from(processedImage);

以下是取自 OpenCV 源代码的转换函数。转换代码在带有“if (!PyArray_Check(o)) ...”的注释行中给出分段错误。

static int pyopencv_to(const PyObject* o, Mat& m, const char* name = "<unknown>", bool allowND=true)

    if(!o || o == Py_None)
    
        if( !m.data )
            m.allocator = &g_numpyAllocator;
        return true;
    

    if( !PyArray_Check(o) ) // Segmentation fault inside PyArray_Check(o)
    
        failmsg("%s is not a numpy array", name);
        return false;
    

    int typenum = PyArray_TYPE(o);
    int type = typenum == NPY_UBYTE ? CV_8U : typenum == NPY_BYTE ? CV_8S :
               typenum == NPY_USHORT ? CV_16U : typenum == NPY_SHORT ? CV_16S :
               typenum == NPY_INT || typenum == NPY_LONG ? CV_32S :
               typenum == NPY_FLOAT ? CV_32F :
               typenum == NPY_DOUBLE ? CV_64F : -1;

    if( type < 0 )
    
        failmsg("%s data type = %d is not supported", name, typenum);
        return false;
    

    int ndims = PyArray_NDIM(o);
    if(ndims >= CV_MAX_DIM)
    
        failmsg("%s dimensionality (=%d) is too high", name, ndims);
        return false;
    

    int size[CV_MAX_DIM+1];
    size_t step[CV_MAX_DIM+1], elemsize = CV_ELEM_SIZE1(type);
    const npy_intp* _sizes = PyArray_DIMS(o);
    const npy_intp* _strides = PyArray_STRIDES(o);
    bool transposed = false;

    for(int i = 0; i < ndims; i++)
    
        size[i] = (int)_sizes[i];
        step[i] = (size_t)_strides[i];
    

    if( ndims == 0 || step[ndims-1] > elemsize ) 
        size[ndims] = 1;
        step[ndims] = elemsize;
        ndims++;
    

    if( ndims >= 2 && step[0] < step[1] )
    
        std::swap(size[0], size[1]);
        std::swap(step[0], step[1]);
        transposed = true;
    

    if( ndims == 3 && size[2] <= CV_CN_MAX && step[1] == elemsize*size[2] )
    
        ndims--;
        type |= CV_MAKETYPE(0, size[2]);
    

    if( ndims > 2 && !allowND )
    
        failmsg("%s has more than 2 dimensions", name);
        return false;
    

    m = Mat(ndims, size, type, PyArray_DATA(o), step);

    if( m.data )
    
        m.refcount = refcountFromPyObject(o);
        m.addref(); // protect the original numpy array from deallocation
                    // (since Mat destructor will decrement the reference counter)
    ;
    m.allocator = &g_numpyAllocator;

    if( transposed )
    
        Mat tmp;
        tmp.allocator = &g_numpyAllocator;
        transpose(m, tmp);
        m = tmp;
    
    return true;


static PyObject* pyopencv_from(const Mat& m)

    if( !m.data )
        Py_RETURN_NONE;
    Mat temp, *p = (Mat*)&m;
    if(!p->refcount || p->allocator != &g_numpyAllocator)
    
        temp.allocator = &g_numpyAllocator;
        m.copyTo(temp);
        p = &temp;
    
    p->addref();
    return pyObjectFromRefcount(p->refcount);

我的python测试程序：

import pysomemodule # My python wrapped library.
import cv2

def main():
    myobj = pysomemodule.ABC("faces.train") # Create python object. This works.
    image = cv2.imread('61.jpg')
    processedImage = myobj.doSomething(image)
    cv2.imshow("test", processedImage)
    cv2.waitKey()

if __name__ == "__main__":
    main()

【参考方案1】：

我希望这可以帮助人们寻找一种快速简便的方法。

这里是github repo 和我为使用 OpenCV 的 Mat 类以尽可能少的痛苦公开代码而编写的开放 C++ 代码。

[更新] 此代码现在适用于 OpenCV 2.X 和 OpenCV 3.X。现在还提供对 Python 3.X 的 CMake 和 实验性 支持。

【讨论】：

3.x 版本的代码很棒！一开始我以为它有 memleak，但最后发现我的代码中有 bug ;) 对于 2.xi 版本，推荐这个github.com/spillai/numpy-opencv-converter - 带有许多类型转换器的好代码（如 Mat、Mat3f , Point2d 等 - 上帝保佑模板 :) ).

我在使用您的代码时也遇到了分段错误。在我自己的库导入之前在我的 Python 代码中添加import pbcvt 终于修复了它。 （对我来说，为什么这是必要的并不直观。）

@ManuCJ，你说得对，这真的很奇怪。 pbcvt 真正被设计为您自己的库的代码模板。因此，我会看看 pbcvt 有什么你的代码没有的（其中一些定义在头文件和 cpp 文件中，也许？）。如果您仍然受到该问题的影响，我建议您在 GitHub 上提交，并附上一个最小的代码示例。

@GregKramida，这可能是因为我使用它的特殊方式。我用 C++ 和 Python Boost 创建了我自己的共享库，它是来自 pyboostcvconverter 的 .so 文件上的 C++ 代码引用。也许这是错误的做法；但是因为我自己的代码很大并且以自己的方式结构化，所以我不想把它放在 pyboostcvconverter/src 中。

【参考方案2】：

一种选择是将代码直接实现到 modules/python/src2/cv2.cpp 作为 python 绑定的自定义分支。

'OpenCV 构建系统会将其捆绑到单个“cv2”中。贡献模块的示例是here。' https://github.com/opencv/opencv/issues/8872#issuecomment-307136942

【参考方案3】：

我解决了这个问题，所以我想我会在这里与可能有同样问题的其他人分享。

基本上，为了摆脱分段错误，我需要调用 numpy 的 import_array() 函数。

从 python 运行 C++ 代码的“高级”视图是这样的：

假设您在 python 中有一个函数foo(arg)，它是某个 C++ 函数的绑定。当您调用foo(myObj) 时，必须有一些代码将python 对象“myObj”转换为您的C++ 代码可以操作的形式。此代码通常是使用 SWIG 或 Boost::Python 等工具半自动创建的。 （我在下面的示例中使用 Boost::Python。）

现在，foo(arg) 是一些 C++ 函数的 python 绑定。此 C++ 函数将接收通用 PyObject 指针作为参数。您需要使用 C++ 代码将此 PyObject 指针转换为“等效”C++ 对象。在我的例子中，我的 python 代码将 OpenCV 图像的 OpenCV numpy 数组作为参数传递给函数。 C++ 中的“等价”形式是 OpenCV C++ Mat 对象。 OpenCV 在 cv2.cpp（转载如下）中提供了一些代码，用于将 PyObject 指针（表示 numpy 数组）转换为 C++ Mat。更简单的数据类型如 int 和 string 不需要用户编写这些转换函数，因为它们是由 Boost::Python 自动转换的。

PyObject 指针转换为合适的 C++ 形式后，C++ 代码可以对其进行操作。当数据必须从 C++ 返回到 python 时，会出现类似的情况，需要 C++ 代码将数据的 C++ 表示形式转换为某种形式的PyObject。 Boost::Python 将负责将PyObject 转换为相应的python 形式。当foo(arg)在python中返回结果时，它是python可以使用的形式。就是这样。

下面的代码展示了如何包装一个 C++ 类“ABC”并公开其方法“doSomething”，该方法从 python 中获取一个 numpy 数组（用于图像），将其转换为 OpenCV 的 C++ Mat，进行一些处理，将结果到 PyObject *，并将其返回给 python 解释器。您可以公开任意数量的函数/方法（参见下面代码中的 cmets）。

abc.hpp:

#ifndef ABC_HPP
#define ABC_HPP

#include <Python.h>
#include <string>

class ABC

  // Other declarations 
    ABC();
    ABC(const std::string& someConfigFile);
    virtual ~ABC();
    PyObject* doSomething(PyObject* image); // We want our python code to be able to call this function to do some processing using OpenCV and return the result.
  // Other declarations
;

#endif

abc.cpp:

#include "abc.hpp"
#include "my_cpp_library.h" // This is what we want to make available in python. It uses OpenCV to perform some processing.

#include "numpy/ndarrayobject.h"
#include "opencv2/core/core.hpp"

// The following conversion functions are taken from OpenCV's cv2.cpp file inside modules/python/src2 folder.
static PyObject* opencv_error = 0;

static int failmsg(const char *fmt, ...)

    char str[1000];

    va_list ap;
    va_start(ap, fmt);
    vsnprintf(str, sizeof(str), fmt, ap);
    va_end(ap);

    PyErr_SetString(PyExc_TypeError, str);
    return 0;


class PyAllowThreads

public:
    PyAllowThreads() : _state(PyEval_SaveThread()) 
    ~PyAllowThreads()
    
        PyEval_RestoreThread(_state);
    
private:
    PyThreadState* _state;
;

class PyEnsureGIL

public:
    PyEnsureGIL() : _state(PyGILState_Ensure()) 
    ~PyEnsureGIL()
    
        PyGILState_Release(_state);
    
private:
    PyGILState_STATE _state;
;

#define ERRWRAP2(expr) \
try \
 \
    PyAllowThreads allowThreads; \
    expr; \
 \
catch (const cv::Exception &e) \
 \
    PyErr_SetString(opencv_error, e.what()); \
    return 0; \


using namespace cv;

static PyObject* failmsgp(const char *fmt, ...)

  char str[1000];

  va_list ap;
  va_start(ap, fmt);
  vsnprintf(str, sizeof(str), fmt, ap);
  va_end(ap);

  PyErr_SetString(PyExc_TypeError, str);
  return 0;


static size_t REFCOUNT_OFFSET = (size_t)&(((PyObject*)0)->ob_refcnt) +
    (0x12345678 != *(const size_t*)"\x78\x56\x34\x12\0\0\0\0\0")*sizeof(int);

static inline PyObject* pyObjectFromRefcount(const int* refcount)

    return (PyObject*)((size_t)refcount - REFCOUNT_OFFSET);


static inline int* refcountFromPyObject(const PyObject* obj)

    return (int*)((size_t)obj + REFCOUNT_OFFSET);


class NumpyAllocator : public MatAllocator

public:
    NumpyAllocator() 
    ~NumpyAllocator() 

    void allocate(int dims, const int* sizes, int type, int*& refcount,
                  uchar*& datastart, uchar*& data, size_t* step)
    
        PyEnsureGIL gil;

        int depth = CV_MAT_DEPTH(type);
        int cn = CV_MAT_CN(type);
        const int f = (int)(sizeof(size_t)/8);
        int typenum = depth == CV_8U ? NPY_UBYTE : depth == CV_8S ? NPY_BYTE :
                      depth == CV_16U ? NPY_USHORT : depth == CV_16S ? NPY_SHORT :
                      depth == CV_32S ? NPY_INT : depth == CV_32F ? NPY_FLOAT :
                      depth == CV_64F ? NPY_DOUBLE : f*NPY_ULONGLONG + (f^1)*NPY_UINT;
        int i;
        npy_intp _sizes[CV_MAX_DIM+1];
        for( i = 0; i < dims; i++ )
        
            _sizes[i] = sizes[i];
        

        if( cn > 1 )
        
            /*if( _sizes[dims-1] == 1 )
                _sizes[dims-1] = cn;
            else*/
                _sizes[dims++] = cn;
        

        PyObject* o = PyArray_SimpleNew(dims, _sizes, typenum);

        if(!o)
        
            CV_Error_(CV_StsError, ("The numpy array of typenum=%d, ndims=%d can not be created", typenum, dims));
        
        refcount = refcountFromPyObject(o);

        npy_intp* _strides = PyArray_STRIDES(o);
        for( i = 0; i < dims - (cn > 1); i++ )
            step[i] = (size_t)_strides[i];
        datastart = data = (uchar*)PyArray_DATA(o);
    

    void deallocate(int* refcount, uchar*, uchar*)
    
        PyEnsureGIL gil;
        if( !refcount )
            return;
        PyObject* o = pyObjectFromRefcount(refcount);
        Py_INCREF(o);
        Py_DECREF(o);
    
;

NumpyAllocator g_numpyAllocator;

enum  ARG_NONE = 0, ARG_MAT = 1, ARG_SCALAR = 2 ;

static int pyopencv_to(const PyObject* o, Mat& m, const char* name = "<unknown>", bool allowND=true)

    //NumpyAllocator g_numpyAllocator;
    if(!o || o == Py_None)
    
        if( !m.data )
            m.allocator = &g_numpyAllocator;
        return true;
    

    if( !PyArray_Check(o) )
    
        failmsg("%s is not a numpy array", name);
        return false;
    

    int typenum = PyArray_TYPE(o);
    int type = typenum == NPY_UBYTE ? CV_8U : typenum == NPY_BYTE ? CV_8S :
               typenum == NPY_USHORT ? CV_16U : typenum == NPY_SHORT ? CV_16S :
               typenum == NPY_INT || typenum == NPY_LONG ? CV_32S :
               typenum == NPY_FLOAT ? CV_32F :
               typenum == NPY_DOUBLE ? CV_64F : -1;

    if( type < 0 )
    
        failmsg("%s data type = %d is not supported", name, typenum);
        return false;
    

    int ndims = PyArray_NDIM(o);
    if(ndims >= CV_MAX_DIM)
    
        failmsg("%s dimensionality (=%d) is too high", name, ndims);
        return false;
    

    int size[CV_MAX_DIM+1];
    size_t step[CV_MAX_DIM+1], elemsize = CV_ELEM_SIZE1(type);
    const npy_intp* _sizes = PyArray_DIMS(o);
    const npy_intp* _strides = PyArray_STRIDES(o);
    bool transposed = false;

    for(int i = 0; i < ndims; i++)
    
        size[i] = (int)_sizes[i];
        step[i] = (size_t)_strides[i];
    

    if( ndims == 0 || step[ndims-1] > elemsize ) 
        size[ndims] = 1;
        step[ndims] = elemsize;
        ndims++;
    

    if( ndims >= 2 && step[0] < step[1] )
    
        std::swap(size[0], size[1]);
        std::swap(step[0], step[1]);
        transposed = true;
    

    if( ndims == 3 && size[2] <= CV_CN_MAX && step[1] == elemsize*size[2] )
    
        ndims--;
        type |= CV_MAKETYPE(0, size[2]);
    

    if( ndims > 2 && !allowND )
    
        failmsg("%s has more than 2 dimensions", name);
        return false;
    

    m = Mat(ndims, size, type, PyArray_DATA(o), step);

    if( m.data )
    
        m.refcount = refcountFromPyObject(o);
        m.addref(); // protect the original numpy array from deallocation
                    // (since Mat destructor will decrement the reference counter)
    ;
    m.allocator = &g_numpyAllocator;

    if( transposed )
    
        Mat tmp;
        tmp.allocator = &g_numpyAllocator;
        transpose(m, tmp);
        m = tmp;
    
    return true;


static PyObject* pyopencv_from(const Mat& m)

    if( !m.data )
        Py_RETURN_NONE;
    Mat temp, *p = (Mat*)&m;
    if(!p->refcount || p->allocator != &g_numpyAllocator)
    
        temp.allocator = &g_numpyAllocator;
        m.copyTo(temp);
        p = &temp;
    
    p->addref();
    return pyObjectFromRefcount(p->refcount);


ABC::ABC() 
ABC::~ABC() 
// Note the import_array() from NumPy must be called else you will experience segmentation faults.
ABC::ABC(const std::string &someConfigFile)

  // Initialization code. Possibly store someConfigFile etc.
  import_array(); // This is a function from NumPy that MUST be called.
  // Do other stuff


// The conversions functions above are taken from OpenCV. The following function is 
// what we define to access the C++ code we are interested in.
PyObject* ABC::doSomething(PyObject* image)

    cv::Mat cvImage;
    pyopencv_to(image, cvImage); // From OpenCV's source

    MyCPPClass obj; // Some object from the C++ library.
    cv::Mat processedImage = obj.process(cvImage);

    return pyopencv_from(processedImage); // From OpenCV's source

使用 Boost Python 创建 python 模块的代码。我从 http://jayrambhia.wordpress.com/tag/boost/ 获取了这个和以下 Makefile：

pysomemodule.cpp:

#include <string>    
#include<boost/python.hpp>
#include "abc.hpp"

using namespace boost::python;

BOOST_PYTHON_MODULE(pysomemodule)

    class_<ABC>("ABC", init<const std::string &>())
      .def(init<const std::string &>())
      .def("doSomething", &ABC::doSomething) // doSomething is the method in class ABC you wish to expose. One line for each method (or function depending on how you structure your code). Note: You don't have to expose everything in the library, just the ones you wish to make available to python.
    ;

最后是 Makefile（在 Ubuntu 上成功编译，但在其他地方可能只需稍作调整即可工作）。

PYTHON_VERSION = 2.7
PYTHON_INCLUDE = /usr/include/python$(PYTHON_VERSION)

# location of the Boost Python include files and library
BOOST_INC = /usr/local/include/boost
BOOST_LIB = /usr/local/lib

OPENCV_LIB = `pkg-config --libs opencv`
OPENCV_CFLAGS = `pkg-config --cflags opencv`

MY_CPP_LIB = lib_my_cpp_library.so

TARGET = pysomemodule
SRC = pysomemodule.cpp abc.cpp
OBJ = pysomemodule.o abc.o

$(TARGET).so: $(OBJ)
    g++ -shared $(OBJ) -L$(BOOST_LIB) -lboost_python -L/usr/lib/python$(PYTHON_VERSION)/config -lpython$(PYTHON_VERSION) -o $(TARGET).so $(OPENCV_LIB) $(MY_CPP_LIB)

$(OBJ): $(SRC)
    g++ -I$(PYTHON_INCLUDE) -I$(BOOST_INC) $(OPENCV_CFLAGS) -fPIC -c $(SRC)

clean:
    rm -f $(OBJ)
    rm -f $(TARGET).so

成功编译库后，目录中应该有一个文件“pysomemodule.so”。将此 lib 文件放在 python 解释器可以访问的位置。然后，您可以导入此模块并创建上述“ABC”类的实例，如下所示：

import pysomemodule

foo = pysomemodule.ABC("config.txt") # This will create an instance of ABC

现在，给定一个 OpenCV numpy 数组图像，我们可以使用以下方法调用 C++ 函数：

processedImage = foo.doSomething(image) # Where the argument "image" is a OpenCV numpy image.

请注意，您将需要 Boost Python、Numpy 开发以及 Python 开发库来创建绑定。

以下两个链接中的 NumPy 文档对于帮助理解转换代码中使用的方法以及为什么必须调用 import_array() 非常有用。特别是，官方的 numpy 文档有助于理解 OpenCV 的 python 绑定代码。

http://dsnra.jpl.nasa.gov/software/Python/numpydoc/numpy-13.html http://docs.scipy.org/doc/numpy/user/c-info.how-to-extend.html

希望这会有所帮助。

【讨论】：

嗨，光炼金术士，感谢您发布您的解决方案。我已经使用 OpenCV 2.4.3（从 cv2.cpp 中获取 pyopencv_to 和 pyopencv_from 函数）找到了针对相同问题的类似解决方案，并公开了一个函数。该模块在 ipython 中加载正常，该函数在那里可见，它可以解析参数，但一旦到达 PyEnsureGIL 就会崩溃。我试过你的解决方案，旧的 pyopencv_to 函数工作（它执行），但在尝试输出时崩溃。我将发布一个单独的问题并在几秒钟内为您提供一个链接，以防您认为您可以看到问题所在。

这是我的问题的链接：***.com/questions/13745265/…