メインコンテンツまでスキップ

08. リモートセッション・コンフィギュレーター

別のアプリ、Unity のシーン、Haply Hub のデモなど、別の場所で既に実行中のセッションを再構成します。デバイスに対して HTTP の REST 呼び出しを送ることで行います。このチュートリアルでは WebSocket を開きません。GET、POST、DELETE だけを使い、他のアプリがハプティクスを描画し続けている間に、基底、ワークスペースのプリセット、マウントトランスフォームを変更します。

ユースケース​

  • 実行中のデモをライブで調整する。 Haply Hub の Orb デモを起動してから、2 つ目のターミナルでこのチュートリアルを実行します。基底の並べ替えの切り替え、ワークスペースのプリセットの変更、マウントトランスフォームの微調整を行うと、デモを停止せずに Orb の座標フレームが即座に変わります。
  • ユーザーごとのワークスペース調整。 ハプティクスのシーンをメインマシンで実行し続けたまま、同じネットワーク上のオペレーターが mount のオフセット／回転／スケールを送信できるようにします。これにより、仮想ワークスペースをユーザーの机に合わせられます。
  • デバイス選択付きのオプションメニュー。 同じ HTTP のヘルパーで GET /devices（チュートリアル 00 を参照）を呼び出してデバイスを列挙し、インタラクティブなメニューを構築できます。メニューからデバイスを選び、そのデバイスを再設定します。セッションの WebSocket には触れません。このチュートリアルは /sessions をクエリして *inverse/0 をハードコードしていますが、/devices ベースのピッカーに置き換えるのはローカルでの変更で済みます。
  • スクリプトによる再構成。 セッションの記録を開始する前に、事前準備の手順（基底 + プリセット + マウントの設定）を自動化します。各クライアントにセットアップを組み込む必要はありません。

前提条件​

チュートリアル 08 は、既に実行中のセッションを再構成します。アクティブなハプティクスのセッションが必要です。別のチュートリアル、Unity のシーン、Haply Hub のデモのいずれでも構いません。

セッションを最も早く起動する方法

Haply Hub を開き、Orb デモを起動してから、それを直接指定します:

./08-haply-inverse-http-remote-config --session co.haply.hub::demo-orb
python 08-haply-inverse-http-remote-config.py --session "co.haply.hub::demo-orb"

Orb シーンは、デバイスのワークスペース内に球体を描画します。チュートリアル 08 で基底やプリセットを切り替えたり、マウントトランスフォームを微調整したりすると、Orb の座標フレームがリアルタイムで視覚的に変化します。

使い方​

# Pick a session interactively (lists every session the service knows)
./08-haply-inverse-http-remote-config
python 08-haply-inverse-http-remote-config.py

# Target the Haply Hub Orb demo directly
./08-haply-inverse-http-remote-config --session co.haply.hub::demo-orb
python 08-haply-inverse-http-remote-config.py --session "co.haply.hub::demo-orb"

# Target one directly by selector
./08-haply-inverse-http-remote-config --session :my_profile:0
python 08-haply-inverse-http-remote-config.py --session "#42"

# Or by a wildcard profile pattern (first match) — handy when the exact profile is unknown
./08-haply-inverse-http-remote-config --session "co.haply.hub::*:0"

# Pick a specific device on the session (default is *inverse/0)
./08-haply-inverse-http-remote-config --device 'inverse3/#A12'        # by exact id
./08-haply-inverse-http-remote-config --device '*inverse:left/0'      # first left-handed inverse
./08-haply-inverse-http-remote-config --device '*inverse:right/0'     # first right-handed inverse
./08-haply-inverse-http-remote-config --device '*verse_grip/0'        # first grip-family device

このチュートリアルは、起動時にセッションの現在の basis / preset / mount を表示し、その後キー入力を待ちます。キーを押すたびに、ちょうど1回 の REST 呼び出しが送信されます。

シミュレーションでプロファイル名を設定する

プロファイル名のないセッションは、数値の ID でしか指定できません。この ID は実行のたびに変わります。メインアプリの最初のメッセージで session.configure.profile.name を呼び出すようにすると、--session :my_profile:0 のような安定したセレクターを、すべての実行で再利用できます。詳細は セッション — プロファイル名 を参照してください。

キーバインド​

キー操作
Bbasis の順列 を順に切り替え
Pワークスペースプリセット を順に切り替え
W / E / Rマウント編集モードを選択 — 位置 (mm) / 回転 (°) / スケール (%)
← / →現在のモードで −X / +X 方向に移動
↑ / ↓現在のモードで +Y / −Y 方向に移動
Page Up / Page Down現在のモードで +Z / −Z 方向に移動
= / -3軸すべてを一括で均一に拡大／縮小 (±)（常に利用可能）
DeleteDELETE で basis・preset・mount をリセットし、デバイスのデフォルトに戻す
Hヘルプを表示
Esc終了（Ctrl+C でも可）

HTTP メソッド — GET、POST、DELETE​

このチュートリアルでは、HTTP メソッドのうち3種類のみを使用します。すべての呼び出しは、標準の JSON エンベロープ を返します（成功時は {"ok": true, "data": {...}}、失敗時は {"ok": false, "error": "..."}）。また、ステータスコードは次の3種類のいずれかです: 200 成功、400 リクエストの形式不正、404 セレクターに一致するものがない。

メソッド役割使用するパス
GET現在の状態を読み取る — セッション一覧、対象セッションの検索、現在の設定値/sessions、/sessions/<selector>、/<device_selector>/config/{basis,preset,mount}?session=...
POST設定値を置き換える — ボディは JSON/<device_selector>/config/{basis,preset,mount}?session=...
DELETE設定値をデバイスのデフォルトに戻す/<device_selector>/config/{basis,preset,mount}?session=...

HTTP ヘルパー​

上記3つのメソッドを薄くラップし、チュートリアルの残りの部分を本体のロジックとして読めるようにしたものです:

Python では、HTTP キープアライブのために requests.Session() を使用しています（リクエストごとのレイテンシを約 50 ms から約 5 ms に短縮）:

http = requests.Session()

def api_get(path):
    r = http.get(f"{BASE_URL}{path}", timeout=3)
    return r.json() if r.status_code == 200 else None

def api_post(path, body):
    r = http.post(f"{BASE_URL}{path}", json=body, timeout=3)
    return r.json() if r.status_code == 200 else None

def api_delete(path):
    r = http.delete(f"{BASE_URL}{path}", timeout=3)
    return r.json() if r.status_code == 200 else None

def session_url(endpoint):
    return f"{endpoint}?session={session_selector}"

セッションの検出 — GET /sessions​

--session の指定有無によって処理が分岐します:

  • --session SELECTOR を指定した場合 → GET /sessions/<SELECTOR> を1回実行します。200 の場合はその結果を使用し、404 の場合はエラーで終了します。
  • フラグなし → GET /sessions（一覧）を実行 → プロファイル名付きでセッションを表示 → インデックスの入力を求める → 最終的なセレクターを組み立てます（利用可能な場合は :profile:0 を優先し、それ以外は #id にフォールバック）。

SELECTOR は セレクター — セッションセレクター で定義されているすべての形式を受け付けます: :profile:instance、#id、:-1、:0、プロファイル名のみ、または co.haply.hub::*:0 のような プロファイル名のワイルドカード パターンです。このチュートリアルでは文字列をそのまま渡し、解析はサービス側で行われます。

def discover_session(session_arg):
    global session_selector

    if session_arg:
        # Direct lookup (e.g. ":my_profile:0", "#42", ":-1")
        if api_get(f"/sessions/{session_arg}") is None:
            return False
        session_selector = session_arg
        return True

    # Otherwise: list and pick
    data     = api_get("/sessions")
    sessions = data.get("data", {}).get("sessions", [])
    for i, s in enumerate(sessions):
        name = s.get("config", {}).get("profile", {}).get("name", "default")
        print(f"  [{i}] session #{s['session_id']}  profile={name}")

    picked = sessions[int(input("Pick session index: "))]
    name   = picked.get("config", {}).get("profile", {}).get("name", "")
    # Prefer the profile selector — it survives restarts; id doesn't
    session_selector = (f":{name}:0" if name and name != "default"
                        else f"#{picked['session_id']}")
    return True

デバイスセレクター — *inverse/0​

設定に関するすべての呼び出しは、デバイス単位で範囲が指定されます。このチュートリアルでは、ファミリーのワイルドカード + インデックス のセレクターを使用します:

/*inverse/0/config/<key>
  • *inverse は Inverse ファミリーに属する任意のデバイス（inverse3、inverse3x、minverse）に一致します。このチュートリアルは、具体的なモデルに関係なくそのまま動作します。
  • 0 は、そのファミリー内の 0 始まりのインデックスです。このチュートリアルが操作するのは、常に最初の Inverse だけです。

ターゲットの変更は、文字列を1つ変えるだけで済みます。--device を渡してください（パスはそこから組み立てられます）:

/verse_grip/0/config/basis?session=...        # --device verse_grip/0
/*verse_grip/0/config/basis?session=...       # --device '*verse_grip/0'        — first grip, any kind
/inverse3/A14/config/mount?session=...        # --device 'inverse3/#A14'
/*inverse:left/0/config/basis?session=...     # --device '*inverse:left/0'      — first left-handed inverse
/*inverse:right/0/config/basis?session=...    # --device '*inverse:right/0'     — first right-handed inverse

:left / :right クラスは、インデックス作成の前に適用されます — *inverse:left/0 は「0 番目の左手系の逆」を意味し、「0 番目の逆で、たぶん左のもの」ではありません。詳しくは セレクター — インデックス作成の前にクラスフィルターが解決される を参照してください。

対象デバイスが見つからない場合、チュートリアル 08 は終了します

チュートリアルは起動時に GET …/config/basis を発行します。セッションに --device に一致するデバイスがない場合（例：右手系のみのセットアップで --device '*inverse:left/0' を指定した場合）、サービスは 404 no device matches selector '<sel>' を返し、チュートリアルは Device '<sel>' not found in session '<sel>'. を出力して ステータス 1 で終了します。古いデフォルト値のままキーボードループに入ることはありません。

完全な文法については、セレクター — デバイスセレクター を参照してください。値をハードコーディングする代わりにデバイス選択メニューを作成するには、GET /devices?session=<selector>（チュートリアル 00）で一覧を取得し、選択された device_id を設定パスに組み込みます。

POST config — basis、preset、mount​

3 つのキーは、リクエストの形式が同じで、ボディのスキーマが異なります。すべての POST は、結果の値を data に含む 200 を返します。セッション／デバイスのセレクターに一致するものがない場合は 404 を返します。

Basis​

POST /*inverse/0/config/basis?session=:my_profile:0
Content-Type: application/json

{"permutation": "XZY"}

レスポンス: {"ok": true, "data": {"permutation": "XZY"}}

def post_basis():
    perm, _ = BASIS_OPTIONS[basis_index]
    api_post(session_url("/inverse3/0/config/basis"), {"permutation": perm})

Preset​

POST /*inverse/0/config/preset?session=:my_profile:0
Content-Type: application/json

{"preset": "arm_front_centered"}

レスポンス: {"ok": true, "data": {"preset": "arm_front_centered"}}

def post_preset():
    preset = PRESET_OPTIONS[preset_index]
    api_post(session_url("/inverse3/0/config/preset"), {"preset": preset})

Mount​

POST /*inverse/0/config/mount?session=:my_profile:0
Content-Type: application/json

{
  "transform": {
    "position": {"x": 0.02, "y": 0.0, "z": 0.0},
    "rotation": {"w": 0.966, "x": 0.0, "y": 0.259, "z": 0.0},
    "scale":    {"x": 1.0,  "y": 1.0, "z": 1.0}
  }
}

レスポンス: {"ok": true, "data": {"transform": { ... }}} — 正規化後の有効な transform をそのまま返します。

def post_mount():
    body = {
        "transform": {
            "position": {"x": mount_pos[0], "y": mount_pos[1], "z": mount_pos[2]},
            "rotation": quat_from_euler_deg(*mount_rot),
            "scale":    {"x": mount_scale[0], "y": mount_scale[1], "z": mount_scale[2]},
        }
    }
    api_post(session_url("/inverse3/0/config/mount"), body)
mount と preset は相互に排他的です

一方を POST すると、デバイス上でもう一方がクリアされます。このチュートリアルではこれを明示的に追跡していません。各 POST は独立しており、競合はサーバーが解決します。同じルールを WebSocket 側から見た説明は、チュートリアル 07 を参照してください。

DELETE によるリセット — 3回の呼び出し​

reset は設定キーごとに1回ずつ DELETE を発行します。各呼び出しは、デフォルト値になった値を data に含む 200 を返します。

def reset_all():
    api_delete(session_url("/inverse3/0/config/basis"))
    api_delete(session_url("/inverse3/0/config/preset"))
    api_delete(session_url("/inverse3/0/config/mount"))

マウントの回転の合成​

transform.rotation は、通信時には単位クォータニオンです。このチュートリアルでは、回転を Z-Y-X 固有オイラー角の3つ組（X 軸周りのピッチ、Z 軸周りのヨー、Y 軸周りのロール — すべて度単位）として保持し、POST のたびにクォータニオンを再合成します。

def quat_from_euler_deg(pitch_x, yaw_z, roll_y):
    """Hamilton quaternion for q = q_z * q_y * q_x (apply X, then Y, then Z)."""
    hx, hy, hz = (math.radians(a) * 0.5 for a in (pitch_x, roll_y, yaw_z))
    cx, sx = math.cos(hx), math.sin(hx)
    cy, sy = math.cos(hy), math.sin(hy)
    cz, sz = math.cos(hz), math.sin(hz)
    return {
        "w": cz*cy*cx + sz*sy*sx,
        "x": cz*cy*sx - sz*sy*cx,
        "y": cz*sy*cx + sz*cy*sx,
        "z": sz*cy*cx - cz*sy*sx,
    }
クォータニオンの規約

単位ハミルトン四元数、右手系、スカラーファースト（w）です。これはサービス内の他の部分と同じ規約です。詳しくは quaternion を参照してください。合成順序はZ-Y-X intrinsic（q = q_z * q_y * q_x）です：まずXまわりのピッチを適用し、次にYまわりのロール、最後にZまわりのヨーを適用します。

チュートリアルでは、ステータス行ごとに導出されたクォータニオンをオイラー角の3つ組とともに表示するため、デバイスが回転する前に合成を確認できます。ローカルのオイラー状態は、セッションに既に保持されている値にかかわらず (0, 0, 0) から始まります。最初の mount POST によって、それまでの値は上書きされます。

入力モデル（概要）​

HTTP の配線が肝心で、キーボードのUXは二次的なものです。意図的に簡略化した点が2つあります：

  • Python は keyboard パッケージを使用しています。クロスプラットフォームに対応し、キーの長押しによる繰り返し入力をネイティブに処理します。矢印キー、Page Up / Page Down、= / - は、押している間マウント軸を移動させます。B と P は立ち上がりエッジで、基底とプリセットを順に切り替えます。
  • C++ は std::getline(std::cin, ...) と簡潔なトークン文法（x+20、sx-5、u+10）を使用しています。連続的な微調整には使いにくいものの、プラットフォームごとのコンソールAPIを #ifdef で分岐させずに済むため、移植性があります。

ソース​

SDKインストーラーに同梱

チュートリアル08も、SDKと一緒にローカルへインストールされています。サービスのインストールディレクトリ配下にある tutorials/08-haply-inverse-http-remote-config/ を確認してください。

関連: セッション — リモートコントロール · セレクター · デバイス構成 · 基底の置換 · マウントとワークスペース · JSON の規約 · チュートリアル00 — デバイス一覧 · チュートリアル07 — 基底とマウント（WebSocket 版）