wuji-cli-viz

ビューアーを起動する

viz は Wuji Hand 2 と Wuji Glove に対応しています。--sn を指定しない場合は、両方のデバイスタイプをスキャンします。

wuji viz

対応する両方のデバイスタイプをまとめて数え、対応デバイスがちょうど 1 台見つかった場合にのみ直接接続します。対話型ターミナルでは、対応デバイスが複数見つかると、SN と Device Type が表示される検索可能なセレクターが開きます。ハイライトされた項目には、Transport と Address が別々の詳細行に表示され、USB Port または IP は該当するフィールドがある場合にのみ表示されます。選択したデバイスだけに接続します。セレクターで Esc または Ctrl+C を押すと、Cancelled. を stderr に出力してコード 9 で終了し、接続も別のデバイスへのフォールバックも行いません。接続に失敗した場合も、フォールバックは行いません。

特定の対応デバイスを選択するには、wuji viz --sn <SN> を使用します。構造化出力を使う場合、および対話なしで実行する場合は、対応デバイスが複数あると --sn が必要です。この場合、セレクターは開きません。

このコマンドはビューアーの URL を出力し、デフォルトのブラウザーで開きます。停止するまで、デバイスのセッションとビューアーを実行し続けます。エージェントがチャットから起動した場合は、エージェントに viz の停止を依頼してください。チャットでユーザーに Ctrl+C を押すよう案内しないでください。Ctrl+C が適切なのは、ユーザーが viz を自分のターミナルで直接実行している場合のみです。

ホストが実際にヘッドレスの場合、またはユーザーがブラウザーを開かずに出力された URL を手動で開くよう明示的に求めた場合は、--no-open を使用します。エージェントがコマンドを実行しているという理由だけで、このオプションを使うと判断しないでください。

wuji viz --no-open

機械可読な起動レポートを出力するには、整形済み JSON には --json、コンパクトな JSON 1 行には --jsonl を使用します。ゼロ調整の動作は、エージェント実行契約に記載されたデバイス固有のルールに従って選択します。この例では、ヘッドレスホストで、触覚ハードウェアを搭載しているか触覚機能が不明な Hand 2 を使用し、指先が無荷重であることの確認は行いません。

wuji viz --sn <HAND2_SN> --no-zero --no-open --jsonl

ビューアーの準備が完了すると、stdout に起動レポートが正確に 1 件出力され、コマンドが実行を続ける前にフラッシュされます。

{
  "status": "running",
  "device": {
    "sn": "WH2-...",
    "handedness": "left"
  },
  "viewer": {
    "url": "http://127.0.0.1:...",
    "lan": false
  }
}

ライブセンサーフレームはビューアーに表示され、stdout には書き込まれません。進行状況、警告、エラーは stderr に出力されます。ビューアーの準備完了前に失敗した場合、stdout は空のままで、通常の構造化エラーエンベロープが stderr に出力されます。実行開始後に失敗した場合、起動レポートは stdout に残り、エラーエンベロープは stderr に出力されます。Ctrl+C を押しても、2 件目の構造化レコードは追加されません。

このコマンドは RRD ファイルを記録せず、デバイスの選択に --address または --handedness を使用できません。

選択したデバイスによって、表示されるビューアーページが決まります。

• Wuji Hand 2 では、ライブの手のポーズと、利用可能な場合は指先の触覚データが表示されます。
• Wuji Glove では、ライブの手とセンサーの可視化が表示されます。

viz はライブ表示専用です。RRD の記録や、MCAP／RRD ファイルの読み込み・再生は行いません。

要求されたデバイスを解釈する

デバイスの選択を絞り込む際は、ユーザーのデバイスの呼び方に従います。

• 「hand」、「Hand 2」、「二代手」、または「手」は wuji_hand_2 を意味します。
• 「glove」、「Wuji Glove」、または「手套」は wuji_glove を意味します。

ユーザーがカテゴリを 1 つ指定した場合は、そのカテゴリに絞って検出し、もう一方のカテゴリには決してフォールバックしません。要求されたカテゴリのデバイスが利用できない場合は、別のデバイスタイプを起動せず、その旨を伝えてください。

エージェント実行契約

このスキルが wuji viz の起動、確認、またはテストのリクエストに対して選択された場合、ユーザーのマシンで実際にコマンドを実行してください。ユーザーが実行するコマンドを貼り付けるだけにしないでください。インストール済みの wuji バイナリまたは対応デバイスを利用できない場合は、Viewer を起動したと偽らず、具体的な阻害要因を報告してください。

ユーザーが実行ファイルのパスを指定した場合は、デバイスの検出とすべての viz コマンドで、必ずその正確なパスを使用してください。wuji コマンドだけに置き換えたり、別のインストール済みバージョンを黙って選択したりしないでください。

長時間実行プロセスを開始する前に、ユーザーの意図に基づいて実行方法を選択してください。

1. デバイスを選択します。 ユーザーが SN を指定した場合は、--sn <SN> を指定します。そうでない場合は、まず wuji devices --json を実行し、wuji_hand_2 と wuji_glove に絞り込んで、明示的に特定された候補を 1 台使用します。Agent やその他の非対話型プロセスでは、--sn を指定せずにセレクターを起動しないでください。対応デバイスが複数残る場合は、推測で選ばず、ユーザーに使用する SN を尋ねて停止してください。セレクターとして --address や --handedness を使用しないでください。
2. デバイスに応じてゼロ調整の動作を選択します。 Wuji Glove、または触覚ハードウェアがないことを確認済みの Hand 2 では、--no-zero を省略し、指先に荷重がかかっていないことの確認を求めないでください。触覚ハードウェアを搭載した Hand 2、または触覚機能が不明な Hand 2 では、ユーザーが読み取り専用での起動を希望する場合、ゼロ調整のスキップを求める場合、または 5 本すべての指先に荷重がかかっていないことを明示的に確認していない場合は、--no-zero を追加してください。この確認があり、読み取り専用やゼロ調整のスキップが求められていない場合に限り、省略してください。このルールは、グラフィカル起動、対話型起動、Agent 管理下の起動に適用します。機能情報には既存のデバイス情報を使用し、ゼロの力の値や欠落データを根拠にしないでください。このフラグを選ぶためだけの追加プローブを行わないでください。通常の進捗メッセージで、ゼロ調整、指先に荷重がかかっていないことの確認、または --no-zero について告知しないでください。実際の CLI のゼロ調整エラーや安全上の制限が発生した場合は、それを伝えて停止してください。Wuji Glove では、Hand 2 のゼロ調整を決して実行したり、言及したりしないでください。
3. ブラウザーと出力処理を選択します。 グラフィカルデスクトップでは、デフォルトのコマンドでブラウザーが開きます。wuji viz または wuji viz --sn <SN> を使用し、--no-open は付けないでください。ヘッドレスホストでは --no-open を追加してください。Agent が実行しているという理由だけで追加してはいけません。呼び出し元が機械可読な起動レコードを明示的に必要としている場合に限り、--jsonl（または --json）を使用してください。URL は status: "running" のレコードが出力された後に限り解析してください。進捗、警告、エラーは stderr に出力されます。
4. ネットワークへの公開は慎重に選択します。 ローカルでの使用では、デフォルトのループバックバインドを維持してください。ユーザーがリモートブラウザーを明示的に必要としており、ネットワークが信頼できる場合に限り、--lan または --bind <local-IP> を追加してください。これらのモードには認証も TLS もありません。
5. セッションを維持します。 起動に成功してもプロセスが完了したわけではありません。viz はストリーミングを続けます。Agent がチャットから起動した場合は、Agent が管理するターミナル／セッション内で実行を継続し、URL を返してください。ユーザーに Ctrl+C を押すよう伝えてはいけません。このキー操作は Agent の会話全体を中断する可能性があります。ユーザーが停止を希望する場合は、Agent を通じて該当する viz セッション／プロセスを停止してください。Ctrl+C に言及するのは、ユーザーが viz を専用のターミナルで直接操作している場合に限ります。最初の Viewer ページが閉じられるまでは、2 つ目の Viewer ページを起動しないでください。切断されると Viewer は最後の状態を保持し、コマンドは自動再接続しません。ゼロ調整で一部完了または失敗が報告された場合は、停止して報告してください。自動的に再試行しないでください。

一般的な呼び出し方法：

# Local interactive desktop, Hand 2 with tactile capability unknown and no unload confirmation
wuji viz --no-zero

# Graphical desktop, Hand 2 with unloaded fingertips confirmed and zeroing allowed
wuji viz --sn <HAND2_SN>

# Graphical desktop, Hand 2 with tactile hardware or unknown capability, no unload confirmation
wuji viz --sn <HAND2_SN> --no-zero

# Graphical desktop, Hand 2 already confirmed to have no tactile hardware
wuji viz --sn <HAND2_SN>

# Graphical desktop, explicit Wuji Glove (opens the browser)
wuji viz --sn <GLOVE_SN>

# Explicitly requested manual URL / machine-readable Glove startup
wuji viz --sn <GLOVE_SN> --no-open --jsonl

# User will open the Glove URL manually on this trusted machine
wuji viz --sn <GLOVE_SN> --no-open

# Remote browser on a trusted LAN, Hand 2 with tactile hardware or unknown capability
wuji viz --sn <HAND2_SN> --no-zero --lan --no-open

Hand 2 の触覚動作

Hand 2 は、接続されたハードウェアに応じて触覚表示を自動的に調整します。

• 触覚ハードウェアがある場合は、触覚ビューと力の履歴を表示します。
• 触覚ハードウェアがない場合は、関節ポーズのみを表示し、完全なハンドモデルは表示したまま、触覚パネルと力の履歴を非表示にします。
• 触覚機能を一部しか利用できない場合は、共通のレイアウトを維持し、利用できない指のビューは空のままにします。

力の値から触覚機能の有無を推測しないでください。起動時に触覚機能の有無を判定できない場合は、安全な表示を維持し、デバイスを変更するゼロ化処理をスキップしてください。

Control Runtime の触覚ゼロ化

コマンドのデフォルトの実行では、選択された Hand 2 で利用可能なハードウェアに応じて触覚ゼロ化を処理します。触覚ハードウェアのない Hand 2 と Wuji Glove では、この処理が自動的にスキップされます。--no-zero が意味を持つのは、触覚ハードウェアを搭載した Hand 2 の場合のみです。

選択されたデバイスが Wuji Glove の場合、ユーザー向けの進行状況メッセージは、Glove の表示を開始していることだけを伝えてください。「読み取り専用」、「ゼロ化をスキップ」、「--no-zero」など、Hand 2 専用のゼロ化の詳細は表示しないでください。

触覚ハードウェアを搭載している、または触覚機能の有無が不明な Hand 2 では、--no-zero を指定してゼロ化を防止してください。

wuji viz --sn <HAND2_SN> --no-zero

CLI が実際にゼロ化を行う場合に限り、5 つすべての触覚センサーについて、想定されたモデルと準備状態であることを確認し、読み取り値を実行時のゼロ基準値として取得したうえで、サブスクリプションと Viewer の開始前に、5 つすべてが Ready に戻るまで待機します。この処理中は、ターミナルに Tactile zero: ready. と表示されるまで、すべての指先に荷重をかけないでください。

--no-zero を指定した場合は、ゼロ化固有の確認、基準値の取得、完了待ちをスキップします。この分岐では、ゼロ化のために指先を無荷重にする確認を求めたり、Tactile zero: ready. が表示されるまで待機したりしないでください。通常の触覚機能の検出と表示の初期化は引き続き実行します。

エージェント実行契約に記載されたデバイスごとの実行ルールに従ってください。Glove と、触覚ハードウェアがないことが確認された Hand 2 の起動では、指先を無荷重にする確認や --no-zero は必要ありません。触覚機能の有無が不明であることは、Hand 2 に触覚ハードウェアがない証拠にはなりません。実際のゼロ化条件の確認は CLI が引き続き担当します。ゼロ化が許可されている場合は、ターミナルに Tactile zero: ready. と表示されるまで、5 つすべての指先の表面に荷重をかけないでください。ゼロ化中に荷重がかかっていると、その荷重も基準値の一部になります。この処理では、永続的な触覚モデルへの書き込みは行いません。ゼロ化が部分的に行われた可能性があるとコマンドが報告した場合は、処理を停止してエラーを報告してください。ユーザーの指示なしに再試行しないでください。

ページを読む

触覚ハードウェアを搭載した Hand 2 の場合、Viewer には次のものが表示されます。

• ライブの関節状態に基づいて動く、3D の Wuji Hand 2 モデル。
• ハンド上に表示される、タクセルごとの実線の力矢印。
• 各指につき 1 つの合力矢印。
• 5 つの指先 3D パネル。
• 60 秒間のローリングウィンドウで表示される、5 つの合力の大きさの系列。

触覚ハードウェアのない Hand 2 では、関節ポーズのみのレイアウトが使われます。触覚マトリックス、指先パネル、合力の履歴は非表示にし、指先シェルのメッシュを含む完全な URDF は維持してください。触覚データを非表示にするために URDF から指先シェルのジオメトリを削除しないでください。これらのメッシュはハンドモデルの一部です。触覚機能を一部しか利用できない Hand 2 では、5 つのパネル枠を維持し、利用できない指のパネルは空のままにします。

デフォルトでは、Viewer は Rerun のダークテーマで開き、3D 背景は黒一色です。

力の方向と大きさには、Viewer に表示される座標規約を使用します。触覚データが利用可能な場合、Viewer は指ごとの合力とその履歴を表示します。

障害への対処

警告 Using a standard model for visualization. は、Viewer が標準モデルを使用していることを意味します。 デバイスのライブデータを使った可視化は続行できます。

詳細な警告やエラーはターミナルに表示されます。Viewer ページ内にヘルス状態を示すマーカーは追加されません。

• 指先から有効なフレームが一度でも生成された後に障害が発生すると、そのフレームが保持されます。影響を受けている指と理由はターミナルで確認できます。他のストリームの更新は続行されます。
• 関節ストリームで障害が発生すると、指先パネルの更新は続行されますが、有効な手のポーズがあれば、その最後の状態が保持されます。
• 触覚データが欠落しても、手のポーズは引き続き表示されます。
• Glove の更新は、利用可能な最新の状態を使って最大 60 Hz で描画されます。いずれかのストリームで無効なフレームが発生した場合、そのストリームの最後の有効な表示が保持され、影響を受けていないストリームの更新は続行されます。
• デバイスがレート制御に対応している場合、Glove の起動時に、上流データの emf_poses、tactile、tactile_zones、および手のひらの IMU が 60 Hz で要求され、実際のレートが報告されます。レート制御がサポートされていない場合は警告が表示されますが、Viewer の上限は 60 Hz のままです。
• デバイスが切断されると、Viewer は最後の状態を保持し、コマンドは失敗を報告します。Agent が管理するセッションは Agent を通じて停止するか、スタンドアロンのターミナルでのみ Ctrl+C を使用してください。

このコマンドは自動的に再接続しません。

信頼できる LAN で共有する

デフォルトでは、Viewer はループバックを使用します。マシンのプライベートネットワークアドレスで公開するには、次のようにします。

wuji viz --lan --no-open

--lan はデフォルトルート上のプライベートアドレスを選択します。そのルートが誤ったインターフェースを指している場合は、代わりに特定のローカルアドレスを選択してください。

wuji viz --bind 10.42.0.7 --no-open

--lan と --bind は同時に指定できません。ループバック以外からのアクセスには、認証も TLS もありません。信頼できるネットワークでのみ使用し、表示された URL は閲覧を許可する相手とのみ共有してください。サポートされる使い方は、wuji viz のセッションごとにアクティブな Viewer ページを 1 つだけ開くことに限られます。別のページを開く前に、既存のページを閉じてください。