目標(biāo)

在本章中，將了解：

• 如何生成OpenCV-Python bindings
• 如何將新的OpenCV模塊擴(kuò)展到Python

OpenCV-Python bindings如何生成

在OpenCV中，所有算法均以C ++實(shí)現(xiàn)。但是這些算法可以以不同的語(yǔ)言（Python、Java等）中使用，這是通過(guò)綁定生成器（binding generator）實(shí)現(xiàn)的。這些生成器在C ++和Python之間建立了橋梁，使用戶(hù)能夠在Python中調(diào)用C ++函數(shù)。為了全面了解后臺(tái)發(fā)生的事情，需要對(duì)Python/C API有充分的了解。在官方Python文檔中可以找到一個(gè)有關(guān)將C ++函數(shù)擴(kuò)展到Python的簡(jiǎn)單示例。因此，通過(guò)手動(dòng)編寫(xiě)包裝函數(shù)將OpenCV中的所有函數(shù)擴(kuò)展到Python是一項(xiàng)耗時(shí)的任務(wù)。因此，OpenCV以更智能的方式進(jìn)行操作。 OpenCV使用位于modules/python/src2 中的一些Python腳本，從C++頭自動(dòng)生成這些包裝器函數(shù)。

首先， modules/python/CMakeFiles.txt 是一個(gè)CMake腳本，用于檢查要擴(kuò)展到Python的模塊，它將自動(dòng)檢查所有要擴(kuò)展的模塊并獲取其頭文件。這些頭文件包含該特定模塊的所有類(lèi)、函數(shù)、常量等的列表。

其次，將這些頭文件傳遞到Python腳本 modules/python/src2/gen2.py 。這是Python Binding生成器腳本，它調(diào)用另一個(gè)Python腳本module/python/src2/hdr_parser.py ，這是頭文件解析器腳本。

此頭文件解析器將完整的頭文件拆分為較小的Python列表。因此，這些列表包含有關(guān)特定函數(shù)、類(lèi)等的所有詳細(xì)信息。例如，將對(duì)一個(gè)函數(shù)進(jìn)行解析以獲取一個(gè)包含函數(shù)名稱(chēng)、返回類(lèi)型、輸入?yún)?shù)、參數(shù)類(lèi)型等的列表。最終列表包含所有函數(shù)、枚舉的詳細(xì)信息，頭文件中的structs、classs等。

但是頭文件解析器不會(huì)解析標(biāo)頭文件中的所有函數(shù)/類(lèi)，開(kāi)發(fā)人員必須指定應(yīng)將哪些函數(shù)導(dǎo)出到Python。為此，在這些聲明的開(kāi)頭添加了某些宏，這些宏使頭文件夾解析器可以標(biāo)識(shí)要解析的函數(shù)。這些宏由對(duì)特定功能進(jìn)行編程的開(kāi)發(fā)人員添加。簡(jiǎn)而言之，開(kāi)發(fā)人員決定哪些功能應(yīng)該擴(kuò)展到Python，哪些不應(yīng)該。這些宏的詳細(xì)信息將在下一個(gè)會(huì)話(huà)中給出。

因此頭文件解析器將返回已解析函數(shù)的最終大列表。生成器腳本（gen2.py）將為頭文件解析器解析的所有函數(shù)/類(lèi)/枚舉/結(jié)構(gòu)創(chuàng)建包裝函數(shù)（可以在編譯期間在 build/modules/python/ 文件夾中以pyopencv_genic_*.h文件找到這些頭文件）。但是可能會(huì)有一些基本的OpenCV數(shù)據(jù)類(lèi)型，例如Mat、Vec4i、Size，它們需要手動(dòng)擴(kuò)展。例如，Mat類(lèi)型應(yīng)擴(kuò)展為Numpy數(shù)組，Size應(yīng)擴(kuò)展為兩個(gè)整數(shù)的元組等等。類(lèi)似地，可能會(huì)有一些復(fù)雜的結(jié)構(gòu)/類(lèi)/函數(shù)等需要手動(dòng)擴(kuò)展。所有這些手動(dòng)包裝函數(shù)都放在 modules/python/src2/cv2.cpp 中。

所以現(xiàn)在剩下的就是這些包裝文件的編譯，這給了cv2模塊。因此，當(dāng)調(diào)用函數(shù)時(shí)，例如在Python中 res = equalizeHist(img1, img2) ，將傳遞兩個(gè)numpy數(shù)組，并期望另一個(gè)numpy數(shù)組作為輸出。因此，將這些numpy數(shù)組轉(zhuǎn)換為cv::Mat，然后在C++中調(diào)用equalizeHist()函數(shù)。最終結(jié)果將res轉(zhuǎn)換回Numpy數(shù)組。簡(jiǎn)而言之，幾乎所有操作都是在C++中完成的，這使得Python幾乎與C++具有相同的速度。

因此，這是OpenCV-Python bindings生成方式的基本形式。

注意

cv::Mat映射到numpy.ndarray可能是無(wú)法達(dá)到1:1的映射。例如，cv::MAT具有頻道字段，它被仿真為Numpy.ndarray的最后一維并隱式轉(zhuǎn)換。但是，這種隱式轉(zhuǎn)換具有將3D Numpy陣列傳遞到C ++代碼的問(wèn)題（最后一維被隱式重新解釋為頻道）。如果需要使用頻道處理3D陣列或ND-陣列，請(qǐng)參閱解決方法。OpenCV 4.5.4+具有從Numpy.ndarray派生的cv.MAT包裝器，明確地處理通道行為。

如何擴(kuò)展新的模塊到Python？

頭文件解析器(Header parser )根據(jù)添加到函數(shù)聲明中的一些包裝宏來(lái)解析頭文件。 枚舉常量不需要任何包裝宏，它們會(huì)自動(dòng)包裝。 但是其余的函數(shù)、類(lèi)等需要包裝宏。

使用CV_EXPORTS_W 宏擴(kuò)展函數(shù)， 一個(gè)例子如下所示：

CV_EXPORTS_W void equalizeHist(InputArray src, OutputArray dst );

頭文件解析器可以理解諸如InputArray，OutputArray等關(guān)鍵字的輸入和輸出參數(shù)。但是有時(shí)候，可能需要對(duì)輸入和輸出進(jìn)行硬編碼。 為此，使用了 CV_OUT , CV_IN_OUT 等宏。

CV_EXPORTS_W void minEnclosingCircle(
    InputArray points, CV_OUT Point2f& center, CV_OUT float& radius );

對(duì)于大類(lèi)，也使用CV_EXPORTS_W。為了擴(kuò)展類(lèi)方法，使用CV_WRAP 。同樣， CV_PROP 用于類(lèi)字段。

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 擴(kuò)展重載的函數(shù)。 但是需要傳遞一個(gè)新名稱(chēng)以便在Python中使用該名稱(chēng)調(diào)用每個(gè)函數(shù)。 以下面的整數(shù)函數(shù)（ integral function）為例，提供了三個(gè)函數(shù)，因此每個(gè)函數(shù)在Python中都帶有一個(gè)后綴。 類(lèi)似地， `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 );

小的類(lèi)/結(jié)構(gòu)使用 CV_EXPORTS_W_SIMPLE 進(jìn)行擴(kuò)展，這些結(jié)構(gòu)按值傳遞給C ++函數(shù)。 示例包括KeyPoint , Match 等。它們的方法由 CV_WRAP 擴(kuò)展，而字段由 CV_PROP_RW 擴(kuò)展。

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 導(dǎo)出其他一些小的類(lèi)/結(jié)構(gòu)，并將其導(dǎo)出到Python本機(jī)字典中。Moments()就是一個(gè)例子。

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中可用的主要擴(kuò)展宏。通常，開(kāi)發(fā)人員必須將適當(dāng)?shù)暮攴旁谶m當(dāng)?shù)奈恢茫溆嗟挠缮善髂_本完成。有時(shí)，在某些特殊情況下，生成器腳本無(wú)法創(chuàng)建包裝，此類(lèi)函數(shù)需要手動(dòng)處理，為此，需要編寫(xiě)自己的 pyopencv_*.hpp 擴(kuò)展頭文件，并將其放入模塊的misc/python子目錄中。但是大多數(shù)時(shí)候，根據(jù)OpenCV編碼指南編寫(xiě)的代碼將由生成器腳本自動(dòng)包裝。

更高級(jí)的情況涉及為Python提供C++接口中不存在的其他功能，例如額外的方法，類(lèi)型映射或提供默認(rèn)參數(shù)。稍后，將以UMat 數(shù)據(jù)類(lèi)型為例。首先，要提供特定于Python的方法，CV_WRAP_PHANTOM 的用法與 CV_WRAP 相似，不同之處在于它以方法頭文件作為參數(shù)，并且需要在自己的pyopencv_*.hpp 擴(kuò)展名中提供方法主體。 UMat::queue() 和 UMat::context() 是此類(lèi)方法的示例，這些方法在C++接口中不存在，但在Python端處理OpenCL功能時(shí)需要使用。其次，如果一個(gè)已經(jīng)存在的數(shù)據(jù)類(lèi)型可以映射到自定義的類(lèi)，則最好使用 CV_WRAP_MAPPABLE 以源類(lèi)型作為其參數(shù)來(lái)表明這種能力，而不是精心設(shè)計(jì)自己的binding函數(shù)。從Mat映射的UMat就是這種情況。最后，如果需要默認(rèn)參數(shù)，但本機(jī)C++接口中未提供，則可以在Python端將其作為CV_WRAP_DEFAULT 的參數(shù)提供。按照下面的 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;
};

附加資源

• github.com/opencv/open…
• docs.opencv.org/4.5.5/da/d4…

以上就是OpenCV-Python Bindings如何生成的詳細(xì)內(nèi)容，更多關(guān)于OpenCV-Python Bindings的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！