如何在Cython中cimport cv2？报错解决及高性能替代方案

当cimport cv2因找不到.pxd文件失败时，手动封装OpenCV的C++接口是追求极致性能的可行方案，具体步骤如下：

1. 编写Cython .pxd 文件声明OpenCV C++接口 #

创建对应OpenCV模块的.pxd文件，用来声明你需要调用的C++类、函数和枚举，示例（opencv_core.pxd）：

# 声明OpenCV Core模块的C++接口
cdef extern from "opencv2/core/core.hpp" namespace "cv":
    cdef cppclass Mat:
        Mat()
        Mat(int rows, int cols, int type)
        void release()
        int rows
        int cols
        int type
        uchar* ptr(int i=0)

    cdef enum:
        CV_8UC3 = 16
        CV_8UC1 = 0
        # 按需添加你需要的类型枚举

# 声明Imgproc模块的C++接口
cdef extern from "opencv2/imgproc/imgproc.hpp" namespace "cv":
    void cvtColor(Mat& src, Mat& dst, int code)
    cdef enum:
        COLOR_BGR2GRAY = 6

注意：需匹配你本地OpenCV版本的头文件结构，确保路径和命名空间正确。

2. 在Cython .pyx 文件中实现接口调用与类型转换 #

编写.pyx文件，完成Python对象（如numpy数组）与OpenCV C对象的转换，并调用C函数，示例（cv_wrapper.pyx）：

import numpy as np
cimport numpy as np
from opencv_core cimport *

cdef np.ndarray[np.uint8_t, ndim=2] bgr_to_gray(np.ndarray[np.uint8_t, ndim=3] bgr_img):
    # 将numpy数组转为OpenCV Mat
    cdef Mat src_mat = Mat(bgr_img.shape[0], bgr_img.shape[1], CV_8UC3)
    src_mat.ptr(0) = <uchar*>bgr_img.data

    # 调用OpenCV的C++颜色转换函数
    cdef Mat dst_mat
    cvtColor(src_mat, dst_mat, COLOR_BGR2GRAY)

    # 将Mat转回numpy数组，注意内存生命周期同步
    cdef np.ndarray[np.uint8_t, ndim=2] gray_img = np.empty((dst_mat.rows, dst_mat.cols), dtype=np.uint8)
    gray_img.data = <char*>dst_mat.ptr(0)
    
    # 可选：通过steal机制让numpy接管Mat内存，避免手动release
    # src_mat.release()
    return gray_img

3. 配置编译脚本 setup.py #

编写setup.py指定OpenCV的头文件、库文件路径，完成Cython编译：

from setuptools import setup, Extension
from Cython.Build import cythonize
import numpy as np
import os

# 根据你的系统配置OpenCV路径
opencv_include = ["/usr/include/opencv4"]  # Ubuntu示例路径，Windows可改为"E:/opencv/build/include"
opencv_lib_dir = ["/usr/lib/x86_64-linux-gnu"]
opencv_libs = ["opencv_core", "opencv_imgproc"]

ext = Extension(
    "cv_wrapper",
    sources=["cv_wrapper.pyx"],
    include_dirs=[np.get_include()] + opencv_include,
    library_dirs=opencv_lib_dir,
    libraries=opencv_libs,
    language="c++"
)

setup(
    name="cv_wrapper",
    ext_modules=cythonize(ext)
)

执行编译命令：

python setup.py build_ext --inplace

4. 在Python中调用封装后的函数 #

import cv_wrapper
import cv2

img = cv2.imread("test.jpg")
gray_img = cv_wrapper.bgr_to_gray(img)
cv2.imwrite("gray_result.jpg", gray_img)

关键注意事项 #

• 路径匹配：确保OpenCV的头文件和库文件路径与本地安装路径一致，不同系统（Linux/Windows/macOS）路径差异较大。
• 类型对齐：numpy数组的dtype必须与OpenCV Mat的type严格匹配，避免内存访问错误。
• 内存管理：手动管理Mat的生命周期，避免内存泄漏；可通过让numpy数组接管Mat内存的方式简化管理。
• 函数签名：严格匹配OpenCV C++函数的参数类型（如引用、指针）和返回值，避免编译错误。

内容的提问来源于stack exchange，提问作者Abhik Sarkar