OpenNI 的手勢偵測

首先，先來看主程式的部分。這部分大部分的程式和其他 OpenNI 的程式一樣，都是先產生 OpenNI 的 context，並進行初始化的動作，然後再建立所需要的 node；而在這邊是要做手勢的偵測，所以需要的 node 是 xn::DepthGenerator 和 xn::GestureGenerator 這兩者（實際上 xn::DepthGenerator 應該也是可以省略、不用手動產生的，OpenNI 會自己在內部處理）。

由於這部分的程式碼基本上都一樣，所以就不額外提了（註 1）；程式碼裡不同的部分，應該就只有「5. Setting gesture」和「6. Register callback functions of gesture generator」這兩段、針對 xn::GestureGenerator 做設定的部分了。

在「5. Setting gesture」的部分，是透過 AddGesture() 這個函示針對 gesture generator 去做設定，控制要處理那些手勢；這個函式的第一個參數就是手勢的名稱（註 2），第二個參數則是針對要去偵測的區域做限制（真實空間座標軸），讓他只在指定的範圍內去找這個手勢，而不要找整個空間。

不過由於這邊 Heresy 並不想針對手勢的位置做限制，所以就直接給他 NULL，就可以設定成整個空間了。如果有需要限定範圍的話，則可以透過兩個三度空間座標（型別為 XnBoundingBox3D），來做限制的條件。

「6. Register callback functions of gesture generator」的部分，則是透過 RegisterGestureCallbacks() 這個函式，來登記 xn::GestureGenerator 的兩個主要的 callback function：GestureRecognized 和 GestureProgress；前者代表他偵測到一個已經完成的手勢，後者則是代表抓到手勢正在進行中。而當手勢被偵測到的時候，xn::GestureGenerator 就會執行這兩個 callback function，對偵測到的手勢進行處理。

使用 RegisterGestureCallbacks() 時要傳入四個參數，前兩個依序就是 GestureRecognized 和 GestureProgress 這兩個最主要的 callback function；第三個參數的型別則是 void*，可以傳入任何型別的指標，用來給 callback funcion 當作額外的資料使用。最後一個參數則是型別為 XnCallbackHandle 的物件參考，是用來記錄、管理這組 callback function 用的；如果之後有可能要取消現在的 callback function 的話，就得把它紀錄下來。

而這邊所使用的 callback function，就是在主程式前所定義的兩個函式：GRecognized() 和 GProgress()；在這兩個函示裡，Heresy 都是透過 C 的 output stream 把得到的資訊做輸出，拿來當作程式執行的結果。而為了方便輸出 OpenNI 所定義的 3D 座標資料 XnPoint3D，這邊也先定義了他的 output operator（operator<<()），來方便輸出。

在所有的東西都設定完成後，接下來就是開始產生資料（7. start generate data ）、並用一個無窮迴圈去不停地讀取新的資料了∼而如果在讀取資料的過程中，OpenNI 有偵測到指定的手勢的話，就會去呼叫所登記的 callback function，執行我們所寫的程式碼了∼

接下來，大概來講一下這兩個 callback function 比較細東西。首先先看 GRecognized() 的介面：

void (XN_CALLBACK_TYPE* GestureRecognized)( GestureGenerator& generator,
                                            const XnChar* strGesture,
                                            const XnPoint3D* pIDPosition,
                                            const XnPoint3D* pEndPosition,
                                            void* pCookie);

他有五個參數，分別為：

• 是發現這個手勢的 xn::GestureGenerator 物件（generator）
• 手勢的名稱（strGesture）
• 發現手勢時手的位置（pIDPosition）
• 手勢結束時手的位置（pEndPosition）
• 使用者自定義的額外資料（pCookie）

其中，儲存手勢名稱的參數 strGesture 型別雖然是 OpenNI 自己定義的 XnChar 的指標，但實際上它的意義就是一般的 C 字串。而代表位置的 pIDPosition 和 pEndPosition 的型別則是 OpenNI 為了 3D 座標定義的 XnPoint3D，儲存了 x / y / z 的位置資訊。

而這邊 Heresy 所定義的函式內容也相當簡單，就是直接用 cout 把上述的三個參數都印出來而已。

GProgress() 也是類似的，他的介面是：

void (XN_CALLBACK_TYPE* GestureProgress)( GestureGenerator& generator,
                                          const XnChar* strGesture,
                                          const XnPoint3D* pPosition,
                                          XnFloat fProgress,
                                          void* pCookie);

他的參數基本上和 GestureRecognized 差不多，唯一不同的是第三個和第四個參數，也就是 pPosition 以及 fProgress；前者是代表現在手所在的位置，而後者則是代表目前這個手勢的進度。

而在函式的內容部分，Heresy 一樣是簡單地把參數透過 iostream 做輸出而已。

基本上目前所支援的四種手勢都有可能是這兩種狀態，不過實際上 Heresy 在測試的時候，有下面一些發現：

• Wave 和 MovingHand 這兩種動作似乎比較容易會觸發到 GestureProgress、觸發到 GestureRecognized 的機會則相對低許多。
• RaiseHand 則是反過來，絕大部分都是觸發到 GestureRecognized。
• Click，基本上兩種都有可能。
• 感覺上 RaiseHand 和 MovingHand 的觸發條件似乎比較容易達成，而 Wave 和 Click 的成功率似乎就沒這麼高了。
• GestureProgress 所得到的 fProgress 這個值，Heresy 好像沒看過 0.5 以外的數字？

不過這些都只是 Heresy 自己玩出來的一些結果，也有可能是 Heresy 這邊其他因素造成的，在別的地方試起來會不會也得到同樣的結果，Heresy 就不知道了。

另外 Heresy 覺得比較可惜的是，OpenNI / NITE 目前所提供的 xn::GestureGenerator 並不能自己新定義手勢，而只能針對目前有的這四種手勢進行操作；如果真的需要額外的手勢的話，似乎是得自己去寫新的 xn::GestureGenerator middleware 了…

1. 在這個範例裡 Heresy 刻意省略了以往範例程式都有、針對 depth generator 或 image generator 做輸出模式設定的步驟（SetMapOutputMode()，也就是程式碼中缺少的「2」的段落）！這是由於 OpenNI 1.1（介紹）開始可以自己去抓他的輸出模式，所以如果是採用裝置的預設值的話，就可以省略這部分的設定了。

2. 可以用的手勢名稱，可以透過 xn::GestureGenerator 的函式 EnumerateGestures() 來取得；下面是簡單的範例：

   // pre-allocate data
   XnUInt16 uNum = 10;
   XnChar** asName = new XnChar*[uNum];
   for( unsigned int i = 0; i < uNum;    i )
     asName[i] = new XnChar[100];
   
   // get data
   eRes = mGesture.EnumerateGestures( *asName, uNum );
   
   // output data
   cout << "There are " << uNum << " available gestures:" << endl;
   for( unsigned int i = 0; i < uNum;    i )
     cout << asName[i] << endl;