01. 印刷Inverse3

シミュレーション用WebSocketに接続し、サービスから報告される最初のInverse3 のカーソル位置、速度、および力のデータを継続的に受信します。

学習内容：

• WebSocket 接続を確立し、初期の完全な状態メッセージを受信する
• ゼロフォースを送信する set_cursor_force 保育所探しに関する指示により、セッションが継続して実行される
• Haply Hub がシミュレーションを識別できるように、セッションプロファイルを登録してください
• 最初のメッセージでのみハンドシェイクを行うモード――初回送信後は session/configure を削除する
• ワークスペースを、部分更新のセマンティクスに従って読み込む transform（位置、回転、拡大・縮小）
• コンソールの出力を、読み取り可能な頻度にとどめる

ワークフロー

1. 開く ws://localhost:10001 の WebSocket。サービスは直ちに完全なステートフレーム，そこには接続済みのデバイスが一覧表示されています。
2. 最初のフレームを受信した際、最初のInverse3 の device_id，そして2つの部分からなるリクエストメッセージを構築します：
   • session.configure.profile.name —— 向Haplyこのシミュレーションを登録してください。
   • 各デバイスごとに set_cursor_force コマンド、力ベクトルはゼロ。サービスはこれを接続維持信号として使用します。コマンドの受信が続く限り、サービスはステータスフレームを送信し続けます。
3. メッセージを返信する。次のサイクルが始まる前に取り除く session フィールド——セッション設定ファイルは、初回の手順のみであり、その後のサイクルではコマンドのみが送信される。
4. その後の各ステートフレームについて：約 10 Hz の周波数でカーソルの表示速度を制限する vec3 フィールド（位置、速度、力）を取得し、ゼロ力キープコマンドを再送信する。

パラメータ

名称	デフォルト値	用途
URI	ws://localhost:10001	WebSocket チャネルの URL
PRINT_EVERY_MS	100	コンソールの出力速度制限
セッションプロファイル名	co.haply.inverse.tutorials:print-inverse3	Haply Hub でこのシミュレーションを識別する

読み込まれたステータスフィールド

出典： data.inverse3[0].state：

• cursor_position、cursor_velocity、current_cursor_force —— いずれも vec3
• transform —— ワークスペースの変換；子オブジェクトとして、以下を含む position（vec3）、rotation（quaternion）と scale（vec3）

部分更新の意味

その単位のデフォルト値に等しいサブフィールド（position: {0,0,0}、rotation: {w:1,x:0,y:0,z:0}、scale: {1,1,1}）帯域幅を節約するため、負荷から省略。読み込み時には必ずデフォルト値を指定してください（たとえば、C++ では .value("position", default_pos)，Python での使用方法 .get("position", default_pos)）。すべてのフィールドを常に受信するには、 serialization/explicit_fields。

送信 / 受信

WebSocket ループ：ステータスフレームを受信し、それを基にフレームを構築して返信するコマンドフレーム。最初のコマンドフレームには、セッションのハンドシェイク情報とゼロフォースの set_cursor_force 保育所探し指令；その後、1フレームごとにのみ「保活」コマンドを保持（セッション情報は削除済み）。

Python

単一の非同期ループ――recv() → 構築コマンド → send() → 重複しています。

async with websockets.connect(URI) as websocket:
    while True:
        msg  = await websocket.recv()
        data = json.loads(msg)

        if first_message:
            first_message = False
            device_id = data["inverse3"][0]["device_id"]
            request_msg = {
                "session": {"configure": {"profile": {
                    "name": "co.haply.inverse.tutorials:print-inverse3"}}},
                "inverse3": [{
                    "device_id": device_id,
                    "commands": {"set_cursor_force":
                        {"vector": {"x": 0.0, "y": 0.0, "z": 0.0}}},
                }]
            }

        await websocket.send(json.dumps(request_msg))
        request_msg.pop("session", None)  # one-shot handshake

C++ (nlohmann)

libhv は、独自の I/O スレッド上で WebSocket を処理します。各フレームの処理は ws.onmessage 中。メインスレッドは、ユーザーが ENTER キーを押すのをブロックして待つだけでよい。

ws.onmessage = [&](const std::string &msg) {
    const json data = json::parse(msg);

    if (first_message) {
        first_message = false;
        device_id = data["inverse3"][0].at("device_id").get<std::string>();
        request_msg = {
            {"session", {{"configure", {{"profile",
                {{"name", "co.haply.inverse.tutorials:print-inverse3"}}}}}}},
            {"inverse3", json::array({
                {{"device_id", device_id},
                 {"commands", {{"set_cursor_force",
                   {{"vector", {{"x", 0.0}, {"y", 0.0}, {"z", 0.0}}}}}}}},
            })},
        };
    }

    ws.send(request_msg.dump());
    request_msg.erase("session");  // one-shot handshake
};
ws.open("ws://localhost:10001");
while (std::cin.get() != '\n') {}  // block main thread

C++ (Glaze)

nlohmann バリアントと同じ libhv コールバックモデル――関数本体のみが異なります。Glaze はコンパイル時のリフレクションを使用します。JSON 構造と一致する構造体を宣言し、 glz::read / glz::write_json。std::optional<session_cmd> 使い捨てのハンドシェイク情報を格納するために使用されます。設定されていない場合、Glaze はこのフィールドをシリアライズされた JSON から省略します。

// Struct models
struct vec3 { float x{}, y{}, z{}; };
struct inverse_state {
    vec3 cursor_position{}, cursor_velocity{}, current_cursor_force{};
    /* + body_orientation, angular_position, angular_velocity */
};
struct inverse_device { std::string device_id; inverse_state state; };
struct devices_message { std::vector<inverse_device> inverse3; };

struct set_cursor_force_cmd { vec3 vector; };
struct commands_message {
    std::optional<session_cmd> session;  // omitted from JSON when unset
    std::vector<device_commands> inverse3;
};

// Send / receive
ws.onmessage = [&](const std::string &msg) {
    devices_message data{};
    if (glz::read<glz_settings>(data, msg)) return;

    commands_message out_cmds{};
    if (first_message) {
        first_message = false;
        out_cmds.session = session_cmd{ /* profile = print-inverse3 */ };
    }
    // ... populate out_cmds.inverse3 with zero-force keepalive ...

    std::string out_json;
    (void)glz::write_json(out_cmds, out_json);
    ws.send(out_json);
};
ws.open("ws://localhost:10001");
while (std::cin.get() != '\n') {}  // block main thread

コマンドライン引数（Python）

このPythonのバリエーションは、チュートリアルの出力内容を変更するために2つの引数を受け取ります：

パラメータ	作用
--full	各ステータスフレームに含まれる生のJSONペイロードデータを、1行の要約ではなく、フォーマットされた形式で出力します。これにより、サービスがどのフィールドを出力しているかを把握しやすくなります。
--query-config	各サイクルごとに再注入を行う session.force_render_full_state: {}，これにより、サービスは各フレームごとに完全なスナップショットを再出力するようになります（以下を含む config ブロック――デバイスタイプ、ファームウェア、プリセット、インストール方法、フィルターなど）。このパラメータを使用しない場合は、config 最初のフレームにのみ出現し、それ以降のフレームはすべてストリーミング形式の増分データである。

2つのパラメータを組み合わせて使用することができます――python 01-haply-inverse-print-inverse3.py --full --query-config 各サイクルごとに、可視情報を含む出力が生成されます config 完全な JSON ペイロードデータは、Haply Hub または HTTP API を通じて設定の変更をリアルタイムで監視する際に非常に役立ちます。基盤となる WebSocket コマンドについては、以下を参照してください。 session.force_render_full_state。

C++のバリアントはこれらの引数をサポートしていません。バリアントは常に1行の要約のみを出力し、かつ config 最初のフレームでのみ受信します。

SDK インストーラーに同梱されています

チュートリアル 01 も SDK とともにローカルにインストールされます。サービスがインストールされているディレクトリ内の tutorials/01-haply-inverse-print-inverse3/ 中で探す。

出典： Python ・C++ ・C++ Glaze

関連情報： WebSocket プロトコル ・ 制御コマンド（set_cursor_force） ・ 会話 ・ 型（vec3）