Kinect for Windows SDK v2 C++ API 簡介


在上一篇《Kinect for Windows SDK v2 基本介紹》裡,基本上已經簡單地介紹了 Kinect for Windows SDK v2 了~而這一篇,就簡單介紹一下 K4W v2 的 C++ API 吧!

不過,這邊也先提一下,說實話 Heresy 個人不是很喜歡 K4W v2 SDK API 的設計概念…

其一是他的介面不但大量地使用了指標(pointer)、而且還需要要用他自己的介面風格來做資源的管理,並非使用 C++ 標準的 new / delete;這點算是讓 Heresy 最討厭的地方,感覺上,一不小心就會有 memory leak…

其二就是他的錯誤處理基本上都還是靠回傳值來做,雖然這是個很簡單的方法,但是結果就是連要取得一個最基本的資料,都必須要透過傳參數的方法來做…某方面來說,也算是相對麻煩。

不過,這算是個人喜好的問題了,下面還是來看一下到底他是怎麼設計的吧。



專案基本設定

在開始之前,這邊還是先提一下,要建立一個使用 K4W SDK v2 的 C++ 專案,要進行那些設定。

基本上在 C++ 裡面要使用外部函式庫,大多都是先 include 必要的 header 檔、並連結對應 lib 檔,這樣才能使用外部的函式庫。而對於基本的 K4W v2 程式來說,所需要的 Header 檔只有「Kinect.h」一個,而要 link 的函式庫檔也只有「Kinect20.lib」這個檔案。理論上專案只要針對這兩項做好設定就可以了。(註一)

首先,之前有提過,SDK 預設會被安裝在「C:\Program Files\Microsoft SDKs\Kinect\v2.0_1409」這個目錄下。而「Kinect.h」就是放在他的「inc」目錄,「Kinect20.lib」則是放在「Lib」目錄;不過根據不同的平台,「Lib」目錄下還有一層子目錄要選擇(x86 或 x64)。

而為了方便專案的設定,K4W SDK v2 在安裝的時候,會在電腦裡加入一個巨集「$(KINECTSDK20_DIR)」,代表 SDK 的安裝路徑。所以在 Visual C++ 裡面要針對 K4W v2 做設定的話,基本上在專案屬性的「組態屬性」裡,要修改的地方會有三個:

  • 在「C/C++」的「一般」裡,「其他 Include 目錄」要加上「$(KINECTSDK20_DIR)\inc
    (英文版是「C/C++」、「General」、「Additional Include Directories」)

  • 在「連結器」的「一般」裡,「其他程式庫目錄」要加上「Kinect20.lib」所在路徑
    (英文版是「Linker」、「General」、「Additional Library Directories」)
    如果是要建置 32 位元的程式的話是「$(KINECTSDK20_DIR)\Lib\x86」 ,如果是 64 位元的程式則是「$(KINECTSDK20_DIR)\Lib\x64」。

  • 在「連結器」的「輸入」裡,「其他相依性」要加上「kinect20.lib
    (英文版是「Linker」、「Input」、「Additional Dependencies」)

而之後,則就是在程式碼裡面,去 include kinect.h,然後就可以使用 K4W v2 的 C++ API 了~


C++ API 概述

上面基本上是簡單的說明,接下來,則大概來講一下 Kinect for Windows SDK v2 的 C++ API 基本概念。

首先,K4W SDK v2 的 C++ API 沒有使用 namespace,所以所有的函式、類別、結構等等,都是全域(global)的。而在官方的 C++ Reference(連結)裡,也有針對「介面」(Interface)、「函式」(Function)、「結構」(structure)以及「列舉型別」(Enumeration)各自做條列。

其中,在函式(function)的部分,他所提供的全域函式只有一個,就是用來取得感應器的 GetDefaultKinectSensor()MSDN);雖然 MSDN 上還有列另一個函式 GetKinectSensorCollection()連結),但是實際上應該是舊的預覽版才有的,在現行的 SDK 版本裡應該不存在。

而在介面(interface)的部分,則就是提供了 K4W v2 SDK 主要的物件的類別,也就是在開發 Kinect for Windows v2 的程式時,主要要用來操作的物件了~這類的類別在 SDK 裡面,都統一是大寫「I」開頭,完整的列表可以參考 MSDN

其中,可能要稍微注意一下的是,和上面提到的函式一樣,有部分的 Interface 雖然有列出來,但是實際上並不存在於現行的 SDK 版本裡。

在結構(structure)的部分,則是針對某些特定的資料、定義了專屬的資料型別,來簡化程式的開發。

函式

K4Wv2 SDK 所提供的函式(包含類別的成員函式),介面的一致性相當地高;所有的函式都會回傳一個一個型別定義成「HRESULT」(實際上是 long)的執行結果;如果回傳值是「S_OK」的話,就代表執行成功,否則就是有問題。

由於回傳值已經被用來回傳執行結果了,所以如果是要取得資訊的話,基本上就需要把數值/物件的指標當作參數傳進去、讓函式去修改他的值。

比如說,如果是要使用 GetDefaultKinectSensor() 這個函式來取得預設的感應器、並檢查是否正確執行的話,則是可以寫成:

IKinectSensor* pSensor = nullptr;
if (GetDefaultKinectSensor(&pSensor) == S_OK)
{
    cout << "Get Sensor OK" << endl;
}
else
{
    cerr << "Get Sensor failed" << endl;
}

這段程式的功能,就是透過 GetDefaultKinectSensor() 這個函式、來取得系統預設的感應器;而取得的結果,就是 pSensor。而要知道是否有成功取得,也只要像上面的程式一樣,判斷函式回傳值是否為 S_OK 就可以了。

而如果是要透過 Frame Description 來取得畫面寬度時,則會寫成:

int        iWidth = 0;
pFrameDescription->get_Width(&iWidth);

透過上面的程式,就可以取得 pFrameDescription(其型別為 IFrameDescription,是用來描述畫面的資訊的)裡面紀錄的畫面寬度資訊、並將之記錄到 iWidth 這個變數了。基本上在 K4W SDK v2 裡面要取得畫面的資訊、大致上都是要這樣做。

在開發 K4W SDK v2 的程式的時候,基本上所有的函式都是這樣使用的。說實話,個人是覺得這樣有點麻煩啦…

介面

由於 K4W SDK v2 在概念上是採取物件導向的設計,所以其他的操作,都是要透過「介面」(Interface)的類別來做操作,像是前面例子裡面、對應到感應器實體的 IKinectSensor 就是一個 interface;而如同前面提過的,這類的類別在 SDK 裡面,都統一是大寫「I」開。

這些 Interface 的類別,在 K4Wv2 SDK 的設計概念下,都是需要透過特定的函式來取得他們的指標、以進行操作;在使用結束後,也不是使用 delete、而是要使用 Release() 函式、來進行資源的釋放。

像是上面例子裡面所使用的 IKinectSensor,就是要透過 GetDefaultKinectSensor() 來取得。

而由於 K4W SDK 基本上就是以 Kinect 感應器為主來設計的,所以他提供的其他 Interface,絕大部分都是屬於 Kinect 感應器的功能;也因此在架構上,這些 Interface 都是透過 IKinectSensor 的成員函式來取得、或是透過所取得的物件一路拿出來的。

以直接可以透過 IKinectSensor 取得的 interface 來說,包括了:

  • IKinectSensor (對應到感應器)
    • get_DepthFrameSource() -> IDepthFrameSource (深度影像來源)
    • get_ColorFrameSource() -> IColorFrameSource (彩色影像來源)
    • get_InfraredFrameSource() -> IInfraredFrameSource (紅外線影像來源)
    • get_LongExposureInfraredFrameSource() -> ILongExposureInfraredFrameSource (長時間曝光紅外線影像來源)
    • get_AudioSource() -> IAudioSource (聲音的來源)
    • get_BodyFrameSource() -> IBodyFrameSource (人體骨架資訊的來源)
    • get_BodyIndexFrameSource() -> IBodyIndexFrameSource (人體在深度影像所佔位置的資料來源)
    • OpenMultiSourceFrameReader() -> IMultiSourceFrameReader (多來源讀取器)
    • get_CoordinateMapper() -> ICoordinateMapper (座標系統轉換)

其中,前面七個都是以「Source」作結尾的、代表都是某種資料的來源。而這些資料來源的類別,基本上大多不會直接被用來讀取資料,而是要透過 OpenReader() 這個函式、來取得對應的「Frame Reader」,用來讀取資料。

像是以 IDepthFrameSource 來說,就可以透過 OpenReader() 這個函式來取得 IDepthFrameReader,並透過他來做資料的讀取。而在「Frame Reader」裡,則是有提供 AcquireLatestFrame() 這類的函式,用來讀取最新的資料。

所以以深度影像來說,這樣一路下來,要取得畫面的呼叫紀錄,大致上就會變成是:

  • GetDefaultKinectSensor()IKinectSensor
    • get_DepthFrameSource()IDepthFrameSource
      • OpenReader()IDepthFrameReader
        • AcquireLatestFrame()IDepthFrame

這樣的形式。而其他類型的資料雖然在細節上可能有些差異,但是大致上也都是這樣對應的~所以,基本上應該可以靠 interface 的名稱,來判斷出它的用途。(聲音的部分因為本身資料性質的差異,所以比較不一樣。)

另外,IMultiSourceFrameReader 是用來同時讀取多種資料用的,而 ICoordinateMapper 則是用來做座標系統轉換的。其他,像是「Frame Reference」和「Frame Arrived Event Args」這類的介面,則是用在事件導向的程式開發時才會用到的,這部分以後有機會會再提。


基本使用概念

而在資料讀取的架構上,K4W SDK v2 提供了「事件導向」(event)和「輪詢」(polling)兩種操作模式。而基本上,「輪詢」(polling)也算是比較單純的,所以,這邊就先以這個模式來做說明。(註二)

在這個模式下。要開發 K4W SDK v2 的程式,基本上的使用概念,就是:

  1. 透過 GetDefaultKinectSensor() 取得系統內的感應器、IKinectSensor
  2. 透過 IKinectSensor 的成員函式,取得所需要資料的資料來源物件(Frame Source、例如 IDepthFrameSource
  3. 針對資料來源物件,取得其資料讀取器(Frame Reader、例如 IDepthFrameReader
  4. 進入主迴圈,並不停地透過資料讀取器,試著去讀取新的資料(例如 IDepthFrame
    • 檢查資料是否讀取成功,如果讀取成功的話,就針對取得的資料作處理


這篇就先寫到這裡了。接下來下一篇,就是開始寫範例程式、真的來讀取資料了~


附註

  1. 如果要用到 Kinect Fusion、Face 等其他進階功能,由於並不屬於 K4W SDK v2 核心功能,所以就需要額外的 header 和 lib 檔。

  2. 說實話,個人是覺得他所提供的事件導向模型很難用…和 Heresy 碰過、其他 C++ 框架的事件導向架構也不大一樣。他並非採用 callback 或是 signal – slot 的形式,而是採取去等待 event handle 的方式來做,基本上就像是比較麻煩的 polling。


Kinect for Windows v2 C++ 程式開發目錄

關於 Heresy
https://kheresy.wordpress.com

21 Responses to Kinect for Windows SDK v2 C++ API 簡介

  1. 通告: 讓函式回傳多個值:std::tuple | Heresy's Space

  2. yentse 說道:

    Heresy你好~
    請問出現error
    LNK2019:無法解析的外部符號
    _GetDefaultKinectSensor@4
    在函式_main中被參考,
    請問是組態屬性的地方有錯誤嗎?
    (因為我是照著上面的教學修改,
    並引用下一篇的程式碼來做測試的)

    best regard!

    喜歡

    • Heresy 說道:

      「無法解析的外部符號」的錯誤,通常是沒有正確設定連結所需的 .lib 檔(在這邊是 kinect20.lib)所造成的。
      請確認你的專案設定都有按照文章中的進行,並確認你是在建置 32 位元還是 64 位元的程式。

      喜歡

  3. You-Sheng 說道:

    Heresy您好,請問,專案設定好後,在讀取深度影像時,出現錯誤 error LNK1104:無法開啟檔案’opencv_calib3d2412d.lib’這個錯誤,想請教是哪邊出了問題呢,感謝您的回答。

    喜歡

    • Heresy 說道:

      請確認你有下載 OpenCV,並請專案設定中 OpenCV 的相關設定是正確的。
      Heresy 的範例是使用 OpenCV 2.4.12,如果你是使用其他版本也需要做對應的修改。

      喜歡

發表迴響

在下方填入你的資料或按右方圖示以社群網站登入:

WordPress.com Logo

你正使用 WordPress.com 帳號留言。 登出 / 變更 )

Twitter picture

你正使用 Twitter 帳號留言。 登出 / 變更 )

Facebook照片

你正使用 Facebook 帳號留言。 登出 / 變更 )

Google+ photo

你正使用 Google+ 帳號留言。 登出 / 變更 )

連結到 %s

%d 位部落客按了讚: