APIリファレンス

ContactGlove C++/C/Rust SDK V2は、ContactGloveデバイスとやり取りするためのC++ライブラリです。

セットアップと組込み

対応OS・CPU、実行時とビルド時の要件、配布物の導入、CMake/C/Rust組込み、 トラブルシュートはSDKガイドを参照してください。

使用例

DivingStationへの接続と切断

DivingStationへの接続には ConnectToHost を使います。

ConnectToHost に渡す接続情報は、ホスト名、IPアドレス、DivingStationの受信ポート、SDKの受信ポートからなります。ホスト名は、ホストを区別するための任意のラベルです。IPアドレスは、DivingStationを実行しているPCに割り当てられたものです。DivingStationの受信ポートは、SDKからのOSCリクエストを受け付けます。通常は25791ですが、DivingStationで変更できます。変更した場合は、その値を使ってください。SDKの受信ポートは、DivingStationからのデータストリームを受け付けます。

DivingStationからの切断には Disconnect を使います。

#include <chrono>
#include <iostream>
#include <thread>

#include "contactglove/ContactGloveSDKv2.hpp"

int main() {
    ContactGloveSDKv2::SDK sdk;

    // Set the connection information.
    ContactGloveSDKv2::Host host{"localhost", "127.0.0.1", 25791, 25788};

    // Connect to DivingStation.
    sdk.ConnectToHost(host);

    // Perform application-specific work.

    // Disconnect from DivingStation.
    sdk.Disconnect(host);

    return(0);
}

データの取得

次の関数で、グローブに関連する情報を取得できます。どの関数も、呼び出した時点で得られる値を返します。

取得できる値関数
グローブの情報GetDataForGlove
グローブが振動に対応しているかDoesGloveSupportHaptics
各指関節の開き角と曲げ角GetErgonomicsDataForGlove
各指関節の位置と回転GetSkeletonDataForGlove
センサーの生の位置と回転GetRawSensorTransformsForGlove
グローブに付けたコントローラーの入力GetControllerDataForGlove
接続中のすべてのグローブのIDGetIdsOfAvailableGloves
接続中のグローブの数GetNumberofAvailableGloves

グローブのデータは非同期に届きます。ConnectToHost の成功はローカルセッションの開始を示すもので、接続承認やデータの受信を確認するものではありません。データの取得には、DivingStationから受信したグローブIDを使ってください。複数のグローブがある場合は、IDや isLeft などの属性で対象を選びます。

同梱の share/ContactGloveSDKv2/examples/basic_usage.cpp は、同じPC上のDivingStation（127.0.0.1）を使ったコールバックとポーリングの例です。最初に受信したIDを取得対象とし、約5秒後に切断します。

LAN接続に承認が必要な場合は、承認とデータを待つ間、同じセッションを維持してください。Disconnect を呼ぶと承認待ちや承認済みの状態が失われることがあります。接続要求の成功は承認完了を意味しません。

更新を自動で受け取る

グローブに関連する値が変わったときに自動で更新を受け取るには、コールバック関数を登録します。

コールバックはSDKの受信スレッドで実行され、キャッシュされたデータを読み取れます。あるコールバックが例外を投げても、残りのコールバックとレコードの配信は続きます。コールバック内でこのSDKの接続・切断・破棄を行わず、別のスレッドで処理してください。Disconnectは実行中のコールバックが終わるまで待機します。SDKへアクセスするコールバックは、SDKの破棄を始める前に完了させてください。

コールバックが呼ばれる更新関数
グローブの情報RegisterCallbackForGloveDataStream
各指関節の開き角と曲げ角RegisterCallbackForErgonomicsStream
各指関節の位置と回転RegisterCallbackForSkeletonStream
センサーの生の位置と回転RegisterCallbackForRawSensorTransformsStream
グローブに付けたコントローラーの入力RegisterCallbackForControllerDataStream

コールバックとポーリングの完全な例は、同梱の share/ContactGloveSDKv2/examples/basic_usage.cpp を参照してください。この例は約5秒で終了します。

C ABIとRust Binding

include/contactglove/ContactGloveSDKv2C.h は、ContactGlove C++/C/Rust SDK V2のC++/C/Rust FFIヘッダーです。追加のヘッダーなしで、C言語から直接使えます。C ABI v2は、不透明ハンドル、固定幅の数値型、UTF-8の文字列ビュー、呼び出し側が用意するバッファ、購読トークンを提供します。

C ABIのデータ構造の多くはこのページで説明するC++の型に対応しますが、ライフタイムとメモリの取り決めが異なります。文字列を含むポーリング結果では、呼び出し側が cg_string_buffer_t でバッファを渡します。CG_RESULT_BUFFER_TOO_SMALL が返った場合でも、length には必要な文字数が入ります。十分な領域を確保して、同じ関数を呼び直してください。SDKが返したメモリを解放する必要はありません。

ストリームの購読は cg_sdk_subscribe_* と cg_sdk_unsubscribe で管理します。コールバックに渡されるビューは、そのコールバックの呼び出し中だけ有効です。cg_sdk_unsubscribe が成功した時点で、そのコールバックは実行中ではありません。コールバックの中から切断すること、SDKを破棄すること、購読を解除することには対応していません。

v2の更新では、デバイスのフィールド is_external_power_present と無効値 battery_percentage=-1、エルゴノミクスデータとスケルトンデータの tracking_state、リターゲット済みスケルトンデータの profile_uuid、HandSkeletonRaw、リターゲットプロファイル情報の要求・応答メッセージが公開されます。Rust Bindingも、同じ問い合わせとコールバックの機能を提供します。C ABIとRustの数値フィールド color は、デバイスの表示色設定を表すDeviceColorの値です。数値フィールド tracking_state はTrackingStateの値で、IkFailedとNotAttemptedには同じく表示・診断用途の制約があります。接続中、SDKは30秒ごとにConnectを再送し、Connect・Disconnect・振動の要求に同じ送信ソケットを使い回します。

公式のRustワークスペースは、配布物の rust/ に含まれています。contactglove-sdk-v2-sys はC ABIの層を、contactglove-sdk-v2 は所有権を持つ型とRAIIによる購読を提供します。

定義されている型と関数

このSDKでは、次の型と関数が定義されています。

クラス

名前説明
SDKContactGlove SDKのメインクラス。
GloveDataグローブデバイスの情報を保持する構造体。
HostDivingStationのホストを表す構造体。
Vec33次元ベクトル。
Quaternion回転を表すクォータニオン。
Transform位置と回転を組み合わせた変換。
ControllerDataコントローラーの入力状態を保持する構造体。
ErgonomicsData指の開き角と曲げ角のデータを保持する構造体。
SkeletonData手のスケルトンデータ（関節の位置と回転）を保持する構造体。
RawSkeletonDataリターゲット前の手のスケルトンデータ。
RetargetProfileInfoリターゲットプロファイルの情報を含む応答。
RawSensorTransformsData片手分のセンサーの生の変換データを保持する構造体。

列挙型

名前説明
DeviceFamilyTypeデバイスファミリーの列挙型。
DeviceColorデバイスの表示色設定の列挙型。
DeviceConnectedStateデバイスの接続状態の列挙型。
TrackingStateIKで求めたデータのトラッキング状態。
SDKReturnCodeSDKの関数が使う戻り値のコード。
ButtonStatusボタンの状態の列挙型。
ErgonomicsDataTypeエルゴノミクスデータの各要素が表す関節を識別する列挙型。
SkeletonDataTypeスケルトンデータの各要素が表す関節を識別する列挙型。

DeviceFamilyType

enum DeviceFamilyType

デバイスファミリーの列挙型です。

主な対象はContactGlove3です。

値説明
ContactGloveContactGlove。
ContactSheetContactSheet。
ContactGlove2ContactGlove2。
ContactGlove3ContactGlove3。

DeviceColor

enum DeviceColor

デバイスの表示色設定の列挙型です。

表示色の型名の移行

公開型名はDeviceColorです。LedColor::Greenなどの参照をDeviceColor::Greenへ変更して再ビルドしてください。 LedColorはC++のDeviceColor互換エイリアスとして残るため、既存ソースも引き続きコンパイルできます。 新しいコードではDeviceColorを使ってください。GloveData.colorのメンバー名と色の数値は同じです。 C ABIのバージョンは2のままです。C ABIとRustのcolor整数フィールド、OSCの通信形式も変わりません。

値説明
Magentaマゼンタ。
Red赤。
Orangeオレンジ。
Yellow黄。
Green緑。
Cyanシアン。
Blue青。
Achromatic無彩色。

DeviceConnectedState

enum DeviceConnectedState

デバイスの接続状態の列挙型です。

値説明
Unknown状態が不明。
Connected接続済み。
Unconnected未接続。
Pairing接続を試行中。

TrackingState

enum TrackingState

IKで求めたデータのトラッキング状態です。

NotAttemptedは、必要なIK処理が実行されなかったことを表します。前段の処理失敗や入力不足のほか、更新間隔の制御で既存の姿勢を再利用するなど、姿勢計算が不要と判断された場合も含みます。この状態自体はIKの失敗を意味しません。

IkFailedとNotAttemptedの値は表示や診断には使えますが、制御・速度推定・補間には使わないでください。これらの用途で有効なのはTrackedの値だけです。

SkeletonDataはリターゲットIK、RawSkeletonDataとErgonomicsDataはソーススケルトンIKの状態を表し、同じ時刻でも状態が異なる場合があります。リターゲットIKのNotAttemptedにも、姿勢計算が不要と判断された場合が含まれます。

値説明
Tracked今回のIK処理で得られた有効な結果。
IkFailedIK処理を試みたが失敗した。
NotAttempted更新間隔による意図的な省略などでIK処理を実行しなかった。

SDKReturnCode

enum SDKReturnCode

SDKの関数が使う戻り値のコードです。

関数呼び出しの結果、またはエラーの種類を示します。

値説明
Success処理が正常に完了しました。
SdkNotAvailableSDK、または要求した機能が利用できません。
NotConnectedDivingStationに接続していません。
InvalidID指定したIDが存在しません。
InvalidArgument引数が有効な範囲外です。

ButtonStatus

enum ButtonStatus

ボタンの状態の列挙型です。

値説明
Unpressed押されていない。
Touchingタッチセンサーが接触を検出した。
Pressed押されている。

ErgonomicsDataType

enum ErgonomicsDataType

エルゴノミクスデータの各要素が表す関節を識別する列挙型です。

左手の値は0〜19、右手の値は20〜39ですが、ErgonomicsData::data が保持するのは常に片手分（20要素）だけです。値を ErgonomicsData::data のインデックスとして使うには、static_cast<uint32_t>(type) % ERGONOMICS_DATA_COUNT を使います。値の単位は度です。

命名規則：(Left|Right){finger name}{joint name}{motion type}。

値説明
LeftThumbCMCFlex左手親指のCMC関節の屈曲角。
LeftThumbMCPFlex左手親指のMCP関節の屈曲角。
LeftThumbIPFlex左手親指のIP関節の屈曲角。
LeftThumbMCPTilt左手親指のMCP関節の傾き角。
LeftIndexMCPFlex左手人差し指のMCP関節の屈曲角。
LeftIndexPIPFlex左手人差し指のPIP関節の屈曲角。
LeftIndexDIPFlex左手人差し指のDIP関節の屈曲角。
LeftIndexMCPTilt左手人差し指のMCP関節の傾き角。
LeftMiddleMCPFlex左手中指のMCP関節の屈曲角。
LeftMiddlePIPFlex左手中指のPIP関節の屈曲角。
LeftMiddleDIPFlex左手中指のDIP関節の屈曲角。
LeftMiddleMCPTilt左手中指のMCP関節の傾き角。
LeftRingMCPFlex左手薬指のMCP関節の屈曲角。
LeftRingPIPFlex左手薬指のPIP関節の屈曲角。
LeftRingDIPFlex左手薬指のDIP関節の屈曲角。
LeftRingMCPTilt左手薬指のMCP関節の傾き角。
LeftLittleMCPFlex左手小指のMCP関節の屈曲角。
LeftLittlePIPFlex左手小指のPIP関節の屈曲角。
LeftLittleDIPFlex左手小指のDIP関節の屈曲角。
LeftLittleMCPTilt左手小指のMCP関節の傾き角。
RightThumbCMCFlex右手親指のCMC関節の屈曲角。
RightThumbMCPFlex右手親指のMCP関節の屈曲角。
RightThumbIPFlex右手親指のIP関節の屈曲角。
RightThumbMCPTilt右手親指のMCP関節の傾き角。
RightIndexMCPFlex右手人差し指のMCP関節の屈曲角。
RightIndexPIPFlex右手人差し指のPIP関節の屈曲角。
RightIndexDIPFlex右手人差し指のDIP関節の屈曲角。
RightIndexMCPTilt右手人差し指のMCP関節の傾き角。
RightMiddleMCPFlex右手中指のMCP関節の屈曲角。
RightMiddlePIPFlex右手中指のPIP関節の屈曲角。
RightMiddleDIPFlex右手中指のDIP関節の屈曲角。
RightMiddleMCPTilt右手中指のMCP関節の傾き角。
RightRingMCPFlex右手薬指のMCP関節の屈曲角。
RightRingPIPFlex右手薬指のPIP関節の屈曲角。
RightRingDIPFlex右手薬指のDIP関節の屈曲角。
RightRingMCPTilt右手薬指のMCP関節の傾き角。
RightLittleMCPFlex右手小指のMCP関節の屈曲角。
RightLittlePIPFlex右手小指のPIP関節の屈曲角。
RightLittleDIPFlex右手小指のDIP関節の屈曲角。
RightLittleMCPTilt右手小指のMCP関節の傾き角。

SkeletonDataType

enum SkeletonDataType

スケルトンデータの各要素が表す関節を識別する列挙型です。

この列挙型は SkeletonData::transforms のインデックスとして使います。片手分のSKELETON_NODE_COUNT個の要素に対応します。

命名規則：Skeleton{finger}{joint name} または Skeleton{finger}Tip。

値説明
SkeletonWrist手首。
SkeletonThumbCMC親指のCMC関節。
SkeletonThumbMCP親指のMCP関節。
SkeletonThumbIP親指のIP関節。
SkeletonThumbTip親指の先端。
SkeletonIndexCMC人差し指のCMC関節。
SkeletonIndexMCP人差し指のMCP関節。
SkeletonIndexPIP人差し指のPIP関節。
SkeletonIndexDIP人差し指のDIP関節。
SkeletonIndexTip人差し指の先端。
SkeletonMiddleCMC中指のCMC関節。
SkeletonMiddleMCP中指のMCP関節。
SkeletonMiddlePIP中指のPIP関節。
SkeletonMiddleDIP中指のDIP関節。
SkeletonMiddleTip中指の先端。
SkeletonRingCMC薬指のCMC関節。
SkeletonRingMCP薬指のMCP関節。
SkeletonRingPIP薬指のPIP関節。
SkeletonRingDIP薬指のDIP関節。
SkeletonRingTip薬指の先端。
SkeletonLittleCMC小指のCMC関節。
SkeletonLittleMCP小指のMCP関節。
SkeletonLittlePIP小指のPIP関節。
SkeletonLittleDIP小指のDIP関節。
SkeletonLittleTip小指の先端。

型の別名

戻り値名前説明
uint64_tTimestampUnix時間をミリ秒で表す整数型。
std::stringGloveIdグローブデバイスの識別子。
DeviceColorLedColorDeviceColorの互換エイリアス。新しいコードではDeviceColorを使用。
std::function< void(const GloveData &)>GloveDataStreamCallback_tグローブのデータが更新されたときに呼ばれるコールバック関数の型。
std::function< void(const ControllerData &)>ControllerDataStreamCallback_tコントローラーのデータが更新されたときに呼ばれるコールバック関数の型。
std::function< void(const ErgonomicsData &)>ErgonomicsStreamCallback_tエルゴノミクスデータが更新されたときに呼ばれるコールバック関数の型。
std::function< void(const SkeletonData &)>SkeletonStreamCallback_tスケルトンデータが更新されたときに呼ばれるコールバック関数の型。
std::function< void(const RawSkeletonData &)>RawSkeletonStreamCallback_t
std::function< void(const RawSensorTransformsData &)>RawSensorTransformsStreamCallback_tセンサーの生の変換データが更新されたときに呼ばれるコールバック関数の型。
std::function< void(const RetargetProfileInfo &)>RetargetProfileInfoCallback_t

Timestamp

uint64_t Timestamp()

Unix時間をミリ秒で表す整数型です。

GloveId

std::string GloveId()

グローブデバイスの識別子です。

LedColor

DeviceColor LedColor()

DeviceColorの互換エイリアスです。新しいコードではDeviceColorを使ってください。

GloveDataStreamCallback_t

std::function< void(const GloveData &)> GloveDataStreamCallback_t()

グローブのデータが更新されたときに呼ばれるコールバック関数の型です。

ControllerDataStreamCallback_t

std::function< void(const ControllerData &)> ControllerDataStreamCallback_t()

コントローラーのデータが更新されたときに呼ばれるコールバック関数の型です。

ErgonomicsStreamCallback_t

std::function< void(const ErgonomicsData &)> ErgonomicsStreamCallback_t()

エルゴノミクスデータが更新されたときに呼ばれるコールバック関数の型です。

SkeletonStreamCallback_t

std::function< void(const SkeletonData &)> SkeletonStreamCallback_t()

スケルトンデータが更新されたときに呼ばれるコールバック関数の型です。

RawSkeletonStreamCallback_t

std::function< void(const RawSkeletonData &)> RawSkeletonStreamCallback_t()

RawSensorTransformsStreamCallback_t

std::function< void(const RawSensorTransformsData &)> RawSensorTransformsStreamCallback_t()

センサーの生の変換データが更新されたときに呼ばれるコールバック関数の型です。

RetargetProfileInfoCallback_t

std::function< void(const RetargetProfileInfo &)> RetargetProfileInfoCallback_t()

変数

戻り値名前説明
uint32_tERGONOMICS_DATA_COUNT片手あたりのエルゴノミクスデータの要素数（5本の指×4関節）。
uint32_tSKELETON_NODE_COUNT片手あたりのスケルトンのノード数（手首、親指の4ノード、ほかの4本の指の各5ノード）。
uint32_tSKELETON_DATA_COUNT片手あたりのスケルトンの変換の数。
uint32_tRAW_SENSOR_TRANSFORM_COUNT片手あたりのセンサーの生の変換の数。

ERGONOMICS_DATA_COUNT

uint32_t ERGONOMICS_DATA_COUNT = 20

片手あたりのエルゴノミクスデータの要素数（5本の指×4関節）です。

SKELETON_NODE_COUNT

uint32_t SKELETON_NODE_COUNT = 25

片手あたりのスケルトンのノード数（手首、親指の4ノード、ほかの4本の指の各5ノード）です。

SKELETON_DATA_COUNT

uint32_t SKELETON_DATA_COUNT = SKELETON_NODE_COUNT

片手あたりのスケルトンの変換の数です。

RAW_SENSOR_TRANSFORM_COUNT

uint32_t RAW_SENSOR_TRANSFORM_COUNT = 5

片手あたりのセンサーの生の変換の数です。

SDK

#include <contactglove/ContactGloveSDKv2.hpp>

ContactGlove SDKのメインクラスです。

公開メソッド

戻り値名前説明
SDK
SDK削除されたコンストラクタ。
SDKReturnCodeConnectToHostDivingStationに接続し、データストリームを開始します。
SDKReturnCodeDisconnectDivingStationから切断します。
SDKReturnCodeDoesGloveSupportHaptics constグローブが振動に対応しているかを問い合わせます。
SDKReturnCodeGetDataForGlove constグローブIDを指定して、グローブの情報を取得します。
SDKReturnCodeGetControllerDataForGlove constグローブIDを指定して、コントローラーの入力データを取得します。
SDKReturnCodeGetErgonomicsDataForGlove constグローブIDを指定して、指の開き角と曲げ角のデータを取得します。
SDKReturnCodeGetSkeletonDataForGlove constグローブIDを指定して、関節の位置と回転のデータを取得します。
SDKReturnCodeGetRawSkeletonDataForGlove constグローブIDを指定して、リターゲット前の手のスケルトンデータを取得します。
SDKReturnCodeGetRawSensorTransformsForGlove constグローブIDを指定して、センサーの生の変換データを取得します。
SDKReturnCodeGetIdsOfAvailableGloves const現在認識しているすべてのグローブのIDを取得します。
SDKReturnCodeGetNumberofAvailableGloves const現在認識しているグローブの総数を取得します。
SDKReturnCodeVibrateGloveグローブを振動させます。
SDKReturnCodeRequestRetargetProfileInfoリターゲットプロファイルの情報の要求を送ります。
SDKReturnCodeRegisterCallbackForGloveDataStreamグローブの情報が更新されたときに呼ばれるコールバックを登録します。
SDKReturnCodeRegisterCallbackForControllerDataStreamコントローラーのデータが更新されたときに呼ばれるコールバックを登録します。
SDKReturnCodeRegisterCallbackForErgonomicsStreamエルゴノミクスデータが更新されたときに呼ばれるコールバックを登録します。
SDKReturnCodeRegisterCallbackForSkeletonStreamスケルトンデータが更新されたときに呼ばれるコールバックを登録します。
SDKReturnCodeRegisterCallbackForRawSkeletonStream
SDKReturnCodeRegisterCallbackForRawSensorTransformsStreamセンサーの生の変換データが更新されたときに呼ばれるコールバックを登録します。
SDKReturnCodeRegisterCallbackForRetargetProfileInfoStream

SDK

SDK()

SDK

SDK(const SDK &) = delete

削除されたコンストラクタです。

ConnectToHost

SDKReturnCode ConnectToHost(const Host & p_Host)

DivingStationに接続し、データストリームを開始します。

同じエンドポイントとポートで再び呼び出すと、既存のソケットを使ってConnectを再送します。sendPortが0の場合は、OSが選んだ送信元ポートもそのまま使います。LANでの承認を待つ間の自動リトライや、データが途絶えたときの復旧に使ってください。Successは要求を開始したことを意味し、LANでの承認を確認するものではありません。Disconnectはセッションを明示的に終了し、承認を取り消すことがあります。

引数

  • p_Host 接続先のDivingStationインスタンスのホスト情報。

戻り値

SDKReturnCode::Success — 接続を開始しました。

戻り値

SDKReturnCode::SdkNotAvailable — ソケットを開けませんでした。

戻り値

SDKReturnCode::InvalidArgument — p_Host.sendPort が65535より大きい値です。

戻り値

SDKReturnCode::InvalidArgument — 受信ポートが、IPアドレス・送信先ポート・送信ポートのいずれかが異なる接続ですでに使われています。

Disconnect

SDKReturnCode Disconnect(const Host & p_Host)

DivingStationから切断します。

引数

  • p_Host 切断するホスト情報。ConnectToHost() に渡した値と一致している必要があります。

戻り値

SDKReturnCode::Success — 切断しました。

戻り値

SDKReturnCode::NotConnected — 指定したポートの接続がありません。

DoesGloveSupportHaptics

const

SDKReturnCode DoesGloveSupportHaptics(const std::string & id, bool * p_IsHaptics) const

グローブが振動に対応しているかを問い合わせます。

引数

  • id 問い合わせるグローブのID。

  • p_IsHaptics 振動に対応しているかどうかの出力先。nullにはできません。

戻り値

SDKReturnCode::Success — 値を取得しました。

戻り値

SDKReturnCode::InvalidID — 指定したグローブが存在しません。

GetDataForGlove

const

SDKReturnCode GetDataForGlove(const std::string & id, GloveData * p_GloveData) const

グローブIDを指定して、グローブの情報を取得します。

引数

  • id 取得するグローブのID。

  • p_GloveData 取得したデータの出力先。nullにはできません。

戻り値

SDKReturnCode::Success — データを取得しました。

戻り値

SDKReturnCode::InvalidID — 指定したグローブが存在しません。

GetControllerDataForGlove

const

SDKReturnCode GetControllerDataForGlove(const std::string & id, ControllerData * p_Controller) const

グローブIDを指定して、コントローラーの入力データを取得します。

引数

  • id 取得するグローブのID。

  • p_Controller 取得したデータの出力先。nullにはできません。

戻り値

SDKReturnCode::Success — データを取得しました。

戻り値

SDKReturnCode::InvalidID — 指定したIDのデータが存在しないか、p_Controller がnullです。

GetErgonomicsDataForGlove

const

SDKReturnCode GetErgonomicsDataForGlove(const std::string & id, ErgonomicsData * p_ErgonomicsData) const

グローブIDを指定して、指の開き角と曲げ角のデータを取得します。

引数

  • id 取得するグローブのID。

  • p_ErgonomicsData 取得したデータの出力先。nullにはできません。

戻り値

SDKReturnCode::Success — データを取得しました。

戻り値

SDKReturnCode::InvalidID — 指定したIDのデータが存在しないか、p_ErgonomicsData がnullです。

GetSkeletonDataForGlove

const

SDKReturnCode GetSkeletonDataForGlove(const std::string & id, SkeletonData * p_SkeletonData) const

グローブIDを指定して、関節の位置と回転のデータを取得します。

引数

  • id 取得するグローブのID。

  • p_SkeletonData 取得したデータの出力先。nullにはできません。

戻り値

SDKReturnCode::Success — データを取得しました。

戻り値

SDKReturnCode::InvalidID — 指定したIDのデータが存在しないか、p_SkeletonData がnullです。

GetRawSkeletonDataForGlove

const

SDKReturnCode GetRawSkeletonDataForGlove(const std::string & id, RawSkeletonData * p_RawSkeletonData) const

グローブIDを指定して、リターゲット前の手のスケルトンデータを取得します。

GetRawSensorTransformsForGlove

const

SDKReturnCode GetRawSensorTransformsForGlove(const std::string & id, RawSensorTransformsData * p_RawSensorTransforms) const

グローブIDを指定して、センサーの生の変換データを取得します。

引数

  • id 取得するグローブのID。

  • p_RawSensorTransforms 取得したデータの出力先。nullにはできません。

戻り値

SDKReturnCode::Success — データを取得しました。

戻り値

SDKReturnCode::InvalidID — 指定したIDのデータが存在しないか、p_RawSensorTransforms がnullです。

GetIdsOfAvailableGloves

const

SDKReturnCode GetIdsOfAvailableGloves(GloveId * p_IdsOfAvailableGloves, uint32_t p_NumberOfIdsThatFitInArray) const

現在認識しているすべてのグローブのIDを取得します。

出力先の配列が小さすぎる場合は、先頭の p_NumberOfIdsThatFitInArray 個のIDだけを書き込みます。総数は事前に GetNumberofAvailableGloves() で問い合わせてください。

引数

  • p_IdsOfAvailableGloves 出力先のID配列の先頭要素へのポインタ。nullにはできません。

  • p_NumberOfIdsThatFitInArray 出力先の配列の容量（要素数）。

戻り値

SDKReturnCode::Success — データを取得しました。

戻り値

SDKReturnCode::InvalidID — p_IdsOfAvailableGloves がnullです。

GetNumberofAvailableGloves

const

SDKReturnCode GetNumberofAvailableGloves(uint32_t * n) const

現在認識しているグローブの総数を取得します。

引数

  • n 数の出力先。nullにはできません。

戻り値

SDKReturnCode::Success — データを取得しました。

戻り値

SDKReturnCode::InvalidID — n がnullです。

VibrateGlove

SDKReturnCode VibrateGlove(const std::string & id, float frequency, float amplitude, float duration)

グローブを振動させます。

引数

  • id 振動させるグローブのID。

  • frequency 振動の周波数（Hz、100.0〜500.0）。

  • amplitude 振動の振幅（0.0〜1.0）。

  • duration 振動の持続時間（秒、0.001〜1.0）。

戻り値

SDKReturnCode::Success — 要求を送信しました。

戻り値

SDKReturnCode::InvalidID — 指定したグローブが存在しません。

戻り値

SDKReturnCode::InvalidArgument — 引数が有効な範囲外です。

RequestRetargetProfileInfo

SDKReturnCode RequestRetargetProfileInfo(const std::string & profileUuid, int32_t requestId)

リターゲットプロファイルの情報の要求を送ります。

RegisterCallbackForGloveDataStream

SDKReturnCode RegisterCallbackForGloveDataStream(GloveDataStreamCallback_t p_Callback)

グローブの情報が更新されたときに呼ばれるコールバックを登録します。

コールバックは引数として GloveData を受け取ります。

引数

  • p_Callback 登録するコールバック関数。

戻り値

SDKReturnCode::Success — 登録しました。

RegisterCallbackForControllerDataStream

SDKReturnCode RegisterCallbackForControllerDataStream(ControllerDataStreamCallback_t p_Callback)

コントローラーのデータが更新されたときに呼ばれるコールバックを登録します。

引数

  • p_Callback 登録するコールバック関数。

戻り値

SDKReturnCode::Success — 登録しました。

RegisterCallbackForErgonomicsStream

SDKReturnCode RegisterCallbackForErgonomicsStream(ErgonomicsStreamCallback_t p_Callback)

エルゴノミクスデータが更新されたときに呼ばれるコールバックを登録します。

引数

  • p_Callback 登録するコールバック関数。

戻り値

SDKReturnCode::Success — 登録しました。

RegisterCallbackForSkeletonStream

SDKReturnCode RegisterCallbackForSkeletonStream(SkeletonStreamCallback_t p_Callback)

スケルトンデータが更新されたときに呼ばれるコールバックを登録します。

引数

  • p_Callback 登録するコールバック関数。

戻り値

SDKReturnCode::Success — 登録しました。

RegisterCallbackForRawSkeletonStream

SDKReturnCode RegisterCallbackForRawSkeletonStream(RawSkeletonStreamCallback_t p_Callback)

RegisterCallbackForRawSensorTransformsStream

SDKReturnCode RegisterCallbackForRawSensorTransformsStream(RawSensorTransformsStreamCallback_t p_Callback)

センサーの生の変換データが更新されたときに呼ばれるコールバックを登録します。

引数

  • p_Callback 登録するコールバック関数。

戻り値

SDKReturnCode::Success — 登録しました。

RegisterCallbackForRetargetProfileInfoStream

SDKReturnCode RegisterCallbackForRetargetProfileInfoStream(RetargetProfileInfoCallback_t p_Callback)

GloveData

#include <contactglove/ContactGloveSDKv2.hpp>

グローブデバイスの情報を保持する構造体です。

OSCアドレス /DS2/HC/Device で受信したデータに対応します。

公開属性

戻り値名前説明
std::stringidデバイスID。
std::stringpairIdペアになっているグローブのID。ペアがない場合は空。
int32_tbatteryPercentageバッテリー残量（%）[0 - 100]。無効な場合は-1。
boolisHaptics振動に対応しているかどうか。
boolisLeft左手用のグローブかどうか。
DeviceFamilyTypefamilyTypeデバイスファミリー。
DeviceColorcolorデバイスの表示色設定。
DeviceConnectedStateconnectedState接続状態。
std::stringnameデバイス名。
boolisExternalPowerPresent外部給電を検出しているかどうか。

id

std::string id

デバイスIDです。

pairId

std::string pairId

ペアになっているグローブのIDです。ペアがない場合は空です。

batteryPercentage

int32_t batteryPercentage = -1

バッテリー残量（%）[0 - 100]です。無効な場合は-1です。

isHaptics

bool isHaptics = false

振動に対応しているかどうかです。

isLeft

bool isLeft = false

左手用のグローブかどうかです。

familyType

DeviceFamilyType familyType = DeviceFamilyType::ContactGlove

デバイスファミリーです。

color

DeviceColor color = DeviceColor::Achromatic

デバイスの表示色設定です。

connectedState

DeviceConnectedState connectedState = DeviceConnectedState::Unknown

接続状態です。

name

std::string name

デバイス名です。

isExternalPowerPresent

bool isExternalPowerPresent = false

外部給電を検出しているかどうかです。

Host

#include <contactglove/ContactGloveSDKv2.hpp>

DivingStationのホストを表す構造体です。

この構造体は ConnectToHost() と Disconnect() に渡します。port はDivingStation側のOSC受信ポートです。receivePort はSDK側のOSC受信ポートです。sendPort はSDK側のOSC送信ポートで、0 の場合はOSが空いているポートを選びます。

公開属性

戻り値名前説明
std::stringhostNameホストを区別するための任意のラベル。例："localhost"。
std::stringipAddressIPアドレス。例："127.0.0.1"。
uint32_tportDivingStation側のOSC受信ポート。
uint32_treceivePortSDK側のOSC受信ポート。
uint32_tsendPortSDK側のOSC送信ポート。0ならOSが空いているポートを選びます。

hostName

std::string hostName

ホスト名です。例："localhost"。

ipAddress

std::string ipAddress

IPアドレスです。例："127.0.0.1"。

port

uint32_t port = 25791

DivingStation側のOSC受信ポートです。

receivePort

uint32_t receivePort = 25788

SDK側のOSC受信ポートです。

sendPort

uint32_t sendPort = 0

SDK側のOSC送信ポートです。0ならOSが空いているポートを選びます。

Vec3

#include <contactglove/ContactGloveSDKv2.hpp>

3次元ベクトルです。

公開属性

戻り値名前説明
floatxX成分。
floatyY成分。
floatzZ成分。

x

float x = 0.0f

X成分です。

y

float y = 0.0f

Y成分です。

z

float z = 0.0f

Z成分です。

Quaternion

#include <contactglove/ContactGloveSDKv2.hpp>

回転を表すクォータニオンです。

公開属性

戻り値名前説明
floatwスカラー成分。
floatxX成分。
floatyY成分。
floatzZ成分。

w

float w = 1.0f

スカラー成分です。

x

float x = 0.0f

X成分です。

y

float y = 0.0f

Y成分です。

z

float z = 0.0f

Z成分です。

Transform

#include <contactglove/ContactGloveSDKv2.hpp>

位置と回転を組み合わせた変換です。

SkeletonData::transforms の各要素として使われます。

公開属性

戻り値名前説明
Vec3position位置。
Quaternionrotation回転。

position

Vec3 position

位置です。

rotation

Quaternion rotation

回転です。

ControllerData

#include <contactglove/ContactGloveSDKv2.hpp>

コントローラーの入力状態を保持する構造体です。

公開属性

戻り値名前説明
std::stringidグローブID。
boolisLeft左手かどうか。
ButtonStatusaButtonAボタンの状態。
ButtonStatusbButtonBボタンの状態。
ButtonStatussysButtonシステムボタンの状態。
ButtonStatustriggerButtonトリガーボタンの状態。
ButtonStatusjoystickButtonジョイスティックボタンの状態。
ButtonStatustrackpadButtonトラックパッドのタッチ状態。
floattriggerトリガーの値（0.0〜1.0）。
floatgripValueグリップの値（0.0〜1.0）。
floatgripForceグリップの力（0.0〜1.0）。
floatjoystickXジョイスティックのX軸の値（-1.0〜1.0）。
floatjoystickYジョイスティックのY軸の値（-1.0〜1.0）。
floattrackpadXトラックパッドのX軸の値（-1.0〜1.0）。
floattrackpadYトラックパッドのY軸の値（-1.0〜1.0）。

id

std::string id

グローブIDです。

isLeft

bool isLeft = false

左手かどうかです。

aButton

ButtonStatus aButton = ButtonStatus::Unpressed

Aボタンの状態です。

bButton

ButtonStatus bButton = ButtonStatus::Unpressed

Bボタンの状態です。

sysButton

ButtonStatus sysButton = ButtonStatus::Unpressed

システムボタンの状態です。

triggerButton

ButtonStatus triggerButton = ButtonStatus::Unpressed

トリガーボタンの状態です。

joystickButton

ButtonStatus joystickButton = ButtonStatus::Unpressed

ジョイスティックボタンの状態です。

trackpadButton

ButtonStatus trackpadButton = ButtonStatus::Unpressed

トラックパッドのタッチ状態です。

trigger

float trigger = 0.0f

トリガーの値（0.0〜1.0）です。

gripValue

float gripValue = 0.0f

グリップの値（0.0〜1.0）です。

gripForce

float gripForce = 0.0f

グリップの力（0.0〜1.0）です。

joystickX

float joystickX = 0.0f

ジョイスティックのX軸の値（-1.0〜1.0）です。

joystickY

float joystickY = 0.0f

ジョイスティックのY軸の値（-1.0〜1.0）です。

trackpadX

float trackpadX = 0.0f

トラックパッドのX軸の値（-1.0〜1.0）です。

trackpadY

float trackpadY = 0.0f

トラックパッドのY軸の値（-1.0〜1.0）です。

ErgonomicsData

#include <contactglove/ContactGloveSDKv2.hpp>

指の開き角と曲げ角のデータを保持する構造体です。

data には片手分のERGONOMICS_DATA_COUNT個の要素が入ります。値の単位は度です。各インデックスの意味はErgonomicsDataTypeを参照してください。

公開属性

戻り値名前説明
std::stringidグローブID。
boolisLeft左手かどうか。
TimestampgeneratedAtフレームの生成時刻（Unix時間、ミリ秒）。
TrackingStatetrackingStateIKで求めたデータのトラッキング状態。
std::array< float, ERGONOMICS_DATA_COUNT >data関節ごとの開き角と曲げ角の値（片手分20要素、単位は度）。

id

std::string id

グローブIDです。

isLeft

bool isLeft = false

左手かどうかです。

generatedAt

Timestamp generatedAt = 0

フレームの生成時刻（Unix時間、ミリ秒）です。

trackingState

TrackingState trackingState = TrackingState::Tracked

IKで求めたデータのトラッキング状態です。

NotAttemptedは、必要なIK処理が実行されなかったことを表します。前段の処理失敗や入力不足のほか、更新間隔の制御で既存の姿勢を再利用するなど、姿勢計算が不要と判断された場合も含みます。この状態自体はIKの失敗を意味しません。

IkFailedとNotAttemptedの値は表示や診断には使えますが、制御・速度推定・補間には使わないでください。これらの用途で有効なのはTrackedの値だけです。

SkeletonDataはリターゲットIK、RawSkeletonDataとErgonomicsDataはソーススケルトンIKの状態を表し、同じ時刻でも状態が異なる場合があります。リターゲットIKのNotAttemptedにも、姿勢計算が不要と判断された場合が含まれます。

data

std::array< float, ERGONOMICS_DATA_COUNT > data {}

関節ごとの開き角と曲げ角の値（片手分20要素、単位は度）です。

SkeletonData

#include <contactglove/ContactGloveSDKv2.hpp>

手のスケルトンデータ（関節の位置と回転）を保持する構造体です。

transforms には片手分のSKELETON_DATA_COUNT個の要素が入ります。各インデックスの意味はSkeletonDataTypeを参照してください。 位置は手首を原点とする右手系の手モデル座標で、単位はメートルです。+Xは指先から手首、+Yは手のひらから手の甲に向かい、+Zは右手では小指から親指、左手では親指から小指に向かいます。回転は親関節に対するローカルクォータニオンです。手首と指先の回転は単位クォータニオンのプレースホルダーであり、計測値ではありません。この規約はスケルトンの変換に適用されます。生センサーの回転は手モデル座標系での向きを表します。

公開属性

戻り値名前説明
std::stringidグローブID。
std::stringprofileUuidリターゲットプロファイルの固定のUUID。
boolisLeft左手かどうか。
TimestampgeneratedAtフレームの生成時刻（Unix時間、ミリ秒）。
TrackingStatetrackingStateリターゲットIKのトラッキング状態。
std::array< Transform, SKELETON_DATA_COUNT >transformsノードごとの位置と回転（25要素）。

id

std::string id

グローブIDです。

profileUuid

std::string profileUuid

リターゲットプロファイルの固定のUUIDです。

isLeft

bool isLeft = false

左手かどうかです。

generatedAt

Timestamp generatedAt = 0

フレームの生成時刻（Unix時間、ミリ秒）です。

trackingState

TrackingState trackingState = TrackingState::Tracked

リターゲットIKのトラッキング状態です。

transforms

std::array< Transform, SKELETON_DATA_COUNT > transforms {}

ノードごとの位置と回転（25要素）です。

RawSkeletonData

#include <contactglove/ContactGloveSDKv2.hpp>

リターゲット前の手のスケルトンデータです。

公開属性

戻り値名前説明
std::stringid
boolisLeft
TimestampgeneratedAt
TrackingStatetrackingState
std::array< Transform, SKELETON_DATA_COUNT >transforms

id

std::string id

isLeft

bool isLeft = false

generatedAt

Timestamp generatedAt = 0

trackingState

TrackingState trackingState = TrackingState::Tracked

transforms

std::array< Transform, SKELETON_DATA_COUNT > transforms {}

RetargetProfileInfo

#include <contactglove/ContactGloveSDKv2.hpp>

リターゲットプロファイルの情報を含む応答です。

公開属性

戻り値名前説明
int32_trequestId
std::stringprofileUuid
int32_tstatus
std::stringname
std::stringdescription

requestId

int32_t requestId = 0

profileUuid

std::string profileUuid

status

int32_t status = 0

name

std::string name

description

std::string description

RawSensorTransformsData

#include <contactglove/ContactGloveSDKv2.hpp>

片手分のセンサーの生の変換データを保持する構造体です。

OSCアドレス /DS2/HC/RawSensorTransforms で受信したデータに対応します。各変換は、/DS2/HC/HandSkeleton と同じ、モデルを原点とする右手系の空間（model-rooted space）で表されます。位置は wrist を基準としたセンサーの中心で、回転はセンサーのローカル座標系からmodel-rooted spaceへの向きです。transforms には、親指・人差し指・中指・薬指・小指の順にRAW_SENSOR_TRANSFORM_COUNT個の要素が入ります。

公開属性

戻り値名前説明
std::stringidグローブID。
boolisLeft左手かどうか。
TimestampgeneratedAtフレームの生成時刻（Unix時間、ミリ秒）。
std::array< Transform, RAW_SENSOR_TRANSFORM_COUNT >transformsセンサーごとの位置と回転（片手分5要素）。

id

std::string id

グローブIDです。

isLeft

bool isLeft = false

左手かどうかです。

generatedAt

Timestamp generatedAt = 0

フレームの生成時刻（Unix時間、ミリ秒）です。

transforms

std::array< Transform, RAW_SENSOR_TRANSFORM_COUNT > transforms {}

センサーごとの位置と回転（片手分5要素）です。

Moxygenで生成しました。

ContactGlove C++/C/Rust SDK V2

前のページ

このページの内容

セットアップと組込み使用例DivingStationへの接続と切断データの取得更新を自動で受け取るC ABIとRust Binding定義されている型と関数クラス列挙型DeviceFamilyTypeDeviceColorDeviceConnectedStateTrackingStateSDKReturnCodeButtonStatusErgonomicsDataTypeSkeletonDataType型の別名TimestampGloveIdLedColorGloveDataStreamCallback_tControllerDataStreamCallback_tErgonomicsStreamCallback_tSkeletonStreamCallback_tRawSkeletonStreamCallback_tRawSensorTransformsStreamCallback_tRetargetProfileInfoCallback_t変数ERGONOMICS_DATA_COUNTSKELETON_NODE_COUNTSKELETON_DATA_COUNTRAW_SENSOR_TRANSFORM_COUNTSDK公開メソッドSDKSDKConnectToHost引数戻り値戻り値戻り値戻り値Disconnect引数戻り値戻り値DoesGloveSupportHaptics引数戻り値戻り値GetDataForGlove引数戻り値戻り値GetControllerDataForGlove引数戻り値戻り値GetErgonomicsDataForGlove引数戻り値戻り値GetSkeletonDataForGlove引数戻り値戻り値GetRawSkeletonDataForGloveGetRawSensorTransformsForGlove引数戻り値戻り値GetIdsOfAvailableGloves引数戻り値戻り値GetNumberofAvailableGloves引数戻り値戻り値VibrateGlove引数戻り値戻り値戻り値RequestRetargetProfileInfoRegisterCallbackForGloveDataStream引数戻り値RegisterCallbackForControllerDataStream引数戻り値RegisterCallbackForErgonomicsStream引数戻り値RegisterCallbackForSkeletonStream引数戻り値RegisterCallbackForRawSkeletonStreamRegisterCallbackForRawSensorTransformsStream引数戻り値RegisterCallbackForRetargetProfileInfoStreamGloveData公開属性idpairIdbatteryPercentageisHapticsisLeftfamilyTypecolorconnectedStatenameisExternalPowerPresentHost公開属性hostNameipAddressportreceivePortsendPortVec3公開属性xyzQuaternion公開属性wxyzTransform公開属性positionrotationControllerData公開属性idisLeftaButtonbButtonsysButtontriggerButtonjoystickButtontrackpadButtontriggergripValuegripForcejoystickXjoystickYtrackpadXtrackpadYErgonomicsData公開属性idisLeftgeneratedAttrackingStatedataSkeletonData公開属性idprofileUuidisLeftgeneratedAttrackingStatetransformsRawSkeletonData公開属性idisLeftgeneratedAttrackingStatetransformsRetargetProfileInfo公開属性requestIdprofileUuidstatusnamedescriptionRawSensorTransformsData公開属性idisLeftgeneratedAttransforms