Blog

由於這個虛擬裝置模組算是 OpenNI 2 的驅動程式模組的一種（類似之前的 WebCam4OpenNI2），所以如果是要使用現成編譯好的檔案，也只需要下載編譯好的 DLL（VirtualDevice.dll），放到工作目錄下的 \OpenNI2\Drivers 裡面，和 PS1080.dll、Kinect.dll 等檔案放在一起就可以了。

而要在建立一個虛擬裝置的話，則是要在建立 OpenNI Device 的時候，指定特別的 URI：

\\OpenNI2\\VirtualDevice\\<<STRING>>

其中，<<STRING>> 的部分可以自行更換，只要名字不同，就可以建立不同的裝置。下面就是一個範例：

Device  devVirDevice;
devVirDevice.open( "\\OpenNI2\\VirtualDevice\\TEST" );

而在建立出虛擬裝置 devVirDevice 後，接下來則就是按照標準的作法，建立出需要的 VideoStream、用來讀取資料；目前的版本僅支援彩色和深度兩種 Video Stream，不支援紅外線。

在建立出 VideoStream 的物件後，使用前則需要透過 setVideoMode() 來指定要使用的解析度，這樣 VideoStream 才知道之後要產生多大的畫面。

虛擬裝置的 VideoStream 都準備好了之後，如果要給他新的資料的話，基本上是要先透過 VideoStream 的 invoke() 函式、來執行 GET_VIRTUAL_STREAM_IMAGE 這個命令，來要求 VideoStream 配置一個 OniFrame 的物件、讓程式可以填自己的資料進去；而在準備好資料之後，則是再透過 invoke() 執行 SET_VIRTUAL_STREAM_IMAGE 這個命令、把修改好的資料、傳給 VideoStream、告訴他新的畫面已經準備好了。

其中，GET_VIRTUAL_STREAM_IMAGE 和 SET_VIRTUAL_STREAM_IMAGE 這兩個特殊命令，則是定義在 VirtualDevice.h 這個檔案（連結）裡；如果要使用的話，可以直接把那兩行定義加到自己的程式碼裡面，或是直接 include 這個 header 檔。

下面就是一段範例：

// get a frame form virtual video stream
OniFrame* pFrame = NULL;
if( pVStream->invoke( GET_VIRTUAL_STREAM_IMAGE, pFrame )==openni::STATUS_OK )
{
  // type casting
  DepthPixel* pVirData = reinterpret_cast<DepthPixel*>( pFrame->data );
 
  // Fill dummy data
  for( int y = 0; y < pFrame->height;    y )
  {
    for( int x = 0; x < pFrame->width;    x )
    {
      int idx = x   y * pFrame->width;
      pVirData[idx] = 100;
    }
  }
 
  // write data to form virtual video stream
  pVStream->invoke( SET_VIRTUAL_STREAM_IMAGE, pFrame );
}

透過上面這樣的程式，就可以讓 pVStream 這個虛擬的深度影像的 VideoStream 產生一張每一個像素都是 100 的深度影像。

而通常這部分程式，應該是需要另外建立一個新的執行緒來執行的。完整的範例，可以參考 GitHub 上的「BasicSample」這個範例。

不過要注意的是，這邊用的 thread 函式庫是使用 OpenNI 原始碼裡面、XnLib 所提供的功能，所以如果要建置的話，是需要 OpenNI 原始碼的；或者，也可以直接用 C 11 的 Thread，或是其他的執行緒函式庫。

為了讓這個虛擬裝置可以支援各項屬性，所以在 Device 和 VideoStream 裡，都有設計 property pool 的機制，來儲存各種類型的屬性資料。要使用的話，基本上就是透過 OpenNI 提供的各種介面、或是直接使用 setProperty() 來做設定、並透過 getProperty() 來讀取。

不過，除了 ONI_STREAM_PROPERTY_VIDEO_MODE 和 ONI_STREAM_PROPERTY_CROPPING 這兩個屬性會動到 VideoStream 的設定外，其他的所有屬性都只是單純地被儲存下來、並不會對虛擬裝置造成任何影響。像是雖然可以透過 setMirroringEnabled() 來設定 ONI_STREAM_PROPERTY_MIRRORING，但是實際上影像並不會因此產生鏡像效果。

另外，如果是深度影像、而且會用到座標系統轉換（Depth / World）的話，則還需要指定 ONI_STREAM_PROPERTY_VERTICAL_FOV 和 ONI_STREAM_PROPERTY_HORIZONTAL_FOV 這兩個屬性的值， CoordinateConverter 才有辦法進行座標轉換的計算。

如果是需要搭配 OpenNI 現有的感應器、來修改實際感應器讀取到的資料（類似 OpenNI 1 的 mock node）的話，則是可以參考「ExistedDeviceSample」這個範例。

使用方法基本上就是先按照一般的方法，建立出正常的 Device、和需要的 VideoStream；接下來則是建立虛擬的裝置，並透過實際的 VideoStream 的 addNewFrameListener()、來讓真實裝置讀取到新的影像後、就把資料做完處理、丟給虛擬裝置用。

這樣處理後，之後就可以透過虛擬的 VideoStream 來讀取修改過的資料了。

首先要注意的是，雖然 PrimeSense 所提供的 NiTE2 這個 middleware 是可以免費使用的，但是實際上在使用上，他是有一些限制的。其中一個最重要的，就是在它的使用授權裡面、就有明寫、他只能用在「經過授權的硬體」上，而經過授權的硬體，基本上就是採用 PrimeSense 自家感應器的產品（MS Kinect、ASUS Xtion…）了～

c. You shall not (and shall not permit third parties to):
(a) integrate the NITE with any products other than the Authorized Hardware;
(b) distribute the NITE in any manner;
(c) use or make available the NITE pursuant to an open source license;
(d) modify the NITE; or
(e) change, obscure or delete any proprietary notices or legends which appear in the NITE.
You understand and agree that under no circumstances will You (or will You allow distributors, resellers or agents to) distribute stand-alone copies or versions of the NITE.

完整的文件，可以參考：http://www.openni.org/nite-licensing-and-distribution-terms/

所以即使是使用虛擬裝置、也不能在沒有 PrimeSense 感應器的情況下，使用 NiTE。

而如果要是要把 VirtualDevice 拿來當 Mock Node 的形式來使用、也就是用來修改現有感應器的深度資料、給 NiTE 來分析的話，在使用上，也還有幾個要注意的地方。

裝置的 URI

\OpenNI2\VirtualDevice\Kinect

支援的解析度

額外的屬性

XN_STREAM_PROPERTY_CONST_SHIFT  
XN_STREAM_PROPERTY_PARAM_COEFF
XN_STREAM_PROPERTY_SHIFT_SCALE
XN_STREAM_PROPERTY_MAX_SHIFT
XN_STREAM_PROPERTY_S2D_TABLE 
XN_STREAM_PROPERTY_D2S_TABLE 
XN_STREAM_PROPERTY_ZERO_PLANE_DISTANCE
XN_STREAM_PROPERTY_ZERO_PLANE_PIXEL_SIZE
XN_STREAM_PROPERTY_EMITTER_DCMOS_DISTANCE

std::map<int,int>  mapProperties;
mapProperties[XN_STREAM_PROPERTY_CONST_SHIFT]        = 8;
mapProperties[XN_STREAM_PROPERTY_PARAM_COEFF]        = 8;
mapProperties[XN_STREAM_PROPERTY_SHIFT_SCALE]        = 8;
mapProperties[XN_STREAM_PROPERTY_MAX_SHIFT]          = 8;
mapProperties[XN_STREAM_PROPERTY_S2D_TABLE]          = 4096;
mapProperties[XN_STREAM_PROPERTY_D2S_TABLE]          = 20002;
mapProperties[XN_STREAM_PROPERTY_ZERO_PLANE_DISTANCE]    = 8;
mapProperties[XN_STREAM_PROPERTY_ZERO_PLANE_PIXEL_SIZE]    = 8;
mapProperties[XN_STREAM_PROPERTY_EMITTER_DCMOS_DISTANCE]  = 8;

for( auto itProp = mapProperties.begin();
     itProp != mapProperties.end();    itProp )
{
  int iSize = itProp->second;
  char* pData = new char[itProp->second];
  rStream.getProperty( itProp->first, pData, &iSize );
  pStream->setProperty( itProp->first, pData, iSize );
  delete [] pData;
}

openni::VideoStream* CreateVirtualStream( openni::Device& rVDevice,
                                          openni::VideoStream& rStream,
                                          CFrameModifer::TCallback func )

std::function<void(const OniFrame&,OniFrame&)>