Kinect ハック on Mac OS X：(2) OpenKinect APIの概要

前回(OpenKinect サンプルの実行)に引き続き、今回もOpenKinectについて書いてみます。今回は、現時点で公開されている OpenKinect (正確にはOpenKinectのCモジュール(?)) のAPIについて調べてみました。以下、目次です。

• モジュール構成
• core.c (コア部分)
• camera.c (カメラ情報取得)
• tilt.c (傾斜制御・LED制御・加速度センサ情報)

なお、ここで書くAPIは、随時変わる可能性があると思います。

モジュール構成

3つのモジュール(コア部分、カメラ情報取得、傾斜制御・LED制御・加速度センサ情報)から構成されています。

• core.c：OpenKinectのコア部分のモジュール
• camera.c：Kinectのカメラ情報を取得するモジュール
• tilt.c：Kinectの傾き制御、KinectのLED制御、Kinectの加速度センサに関するモジュール

core.c (コア部分)

Kinectのベースとなる関数が含まれます。実際の処理の流れは次のようになると思います：コンテキストの作成(freenect_init)→デバイスのオープン(freenect_open_device)→処理→デバイスのクローズ(freenect_close_device)→コンテキストの破棄(freenect_shutdown)。また、ログ関連の関数や、ユーザ情報を構造体に設定/取得する関数等も含まれます。

• コンテキストの作成 (コンテキストを作成し、指定されたアドレスへポインタを設定する)：
  int freenect_init(freenect_context **ctx, freenect_usb_context *usb_ctx);
• コンテキストの破棄 (指定されたコンテキストを破棄する)：
  int freenect_shutdown(freenect_context *ctx);
• ログレベルの設定 (指定されたコンテキストのログレベルを設定する。※後注1)：
  void freenect_set_log_level(freenect_context *ctx, freenect_loglevel level);
• ログ出力関数の設定 (指定されたコンテキストにログ出力を行う関数を設定する。※後注2)：
  void freenect_set_log_callback(freenect_context *ctx, freenect_log_cb cb);
• イベント処理の実行 (指定されたコンテキストに溜まっているイベントを処理する)：
  int freenect_process_events(freenect_context *ctx);
• コンテキストに含まれるデバイス数の取得：
  int freenect_num_devices(freenect_context *ctx);
• デバイスのオープン：
  int freenect_open_device(freenect_context *ctx, freenect_device **dev, int index);
• デバイスのクローズ：
  int freenect_close_device(freenect_device *dev);
• ユーザーデータのポインタの設定と取得：
  void freenect_set_user(freenect_device *dev, void *user);
  void *freenect_get_user(freenect_device *dev);
• ログの出力：
  void fn_log(freenect_context *ctx, freenect_loglevel level, const char *fmt, ...)

camera.c (カメラ情報取得)

Kinectから取得できるカメラ情報には、RGB情報と深度情報があります。それぞれの情報は、あらかじめ指定したコールバック関数に、定期的に渡されます。

• コールバック関数の登録 (カメラからの情報を処理するコールバック関数の登録)：
  void freenect_set_{depth,rgb}_callback(freenect_device *dev, freenect_{depth,rgb}_cb cb);
• 取得する情報のフォーマットの設定(後注3)：
  int freenect_set_{depth,rgb}_format(freenect_device *dev, freenect_{depth,rgb}_format fmt);
• 情報取得の開始：
  int freenect_start_{depth,rgb}(freenect_device *dev);
• 情報取得の停止：
  int freenect_stop_{depth,rgb}(freenect_device *dev);

tilt.c (傾斜制御・LED制御・加速度センサ情報)

Kinectは、傾斜を変えたり(±15度)、LEDを点灯(後注4)させることができます。また加速度センサがあります。角度を指定する時には、目的の角度を2倍して(+31〜-31度)指定します。

• 傾斜 (指定された角度にKinectを傾けます)：
  int freenect_set_tilt_degs(freenect_device *dev, double angle);
• LEDの点灯 (指定された方法(後注4)でLEDを光らせます)：
  int freenect_set_led(freenect_device *dev, freenect_led_options option);
• 加速度情報の取得 (Kinect内蔵の素子の加速度情報を取得します)：
  int freenect_get_raw_accel(freenect_device *dev, int16_t* x, int16_t* y, int16_t* z);
• 加速度情報(補正)の取得 (加速度情報をMKS単位系に単位換算して取得します)：
  int freenect_get_mks_accel(freenect_device *dev, double* x, double* y, double* z);

補足

1. ログレベルはlibfreenect.h参照
2. ログコールバックを設定しない場合は、ログは標準エラー出力に出力される。
3. RGB情報のフォーマットは、RGBとベイヤ型配列の2種類。深度情報のフォーマットは、11bit, 10bit, packed-11bit, packed-10bit の4種類。(libfreenect.h参照)
4. LEDの光らせ方は、LED_GREEN, LED_RED, LED_YELLOW, LED_BLINK_YELLOW, LED_BLINK_GREEN, LED_BLINK_RED_YELLOW の6種類。(libfreenect.h参照)

---

次回は、デモプログラム(glview.c)とOpenGLについて調べてみようと思います。