render

Render

このスキルを使用すると、生成または変更した CAD ファイルやロボット記述ファイルを CAD Explorer で開けます。入力には、すでに存在するか、別のスキルによって生成された明示的なファイルパスを 1 つ以上指定します。

対応ファイル：.step、.stp、.glb、.stl、.3mf、.dxf、.urdf、.srdf、.sdf。

引き継ぎ契約

• CAD、URDF、SRDF、SDF、SendCutSend、または標準部品のワークフローから明示的なファイルパスを受け取ります。
• dev:ensure を使って CAD Explorer を起動または再利用します。固定ポートを前提にしないでください。返すリンクが有効かどうかの確認には、dev:ensure をビューアーの稼働確認として扱います。
• ポートの再利用は必須です。dev:ensure が EPERM や EACCES などのローカルバインド／プローブの拒否を報告した場合は、自分で新しいポートを選ばず、必要なローカルバインド権限／権限昇格を付与して同じ dev:ensure コマンドを再実行します。
• 通常のエージェントからの引き継ぎでは、npm run dev -- --port ...、生の vite dev、生の vite preview を使用しないでください。これらは再利用ポリシーを回避し、localhost 上で Explorer サーバーが重複して実行される原因になります。
• リクエストされた各ファイルについて、表示された Explorer URL を返します。
• 生成物のレビューや視覚的なフィードバックには、ビューアーを手動で開いたり Playwright を使用したりするより、スナップショット CLI を優先します。引き継ぎやライブレビュー用にはビューアーのリンクも返します。
• GIF を生成するのは、CAD の STEP モジュールのパラメーターアニメーションをレビューする場合に限ります。それ以外では GIF ではなく静止スナップショットを使用します。
• 起動に失敗した場合は、その失敗を報告し、担当スキルが GUI を使わない検証を続行できるようにします。

コマンド

このスキルのディレクトリから実行します。

npm --prefix scripts/viewer run dev:ensure -- --file path/to/model.step

保存するヘッドレススナップショットには、スキルレベルのスナップショットラッパーを使用します。このラッパーは、ビューアーパッケージの scripts/viewer/snapshot 実装に処理を委譲します。

python3 scripts/snapshot --job path/to/render-job.json
python3 scripts/snapshot --job -

一般的なテーマのスナップショットには、ショートカットフラグのみを使用できます。

python3 scripts/snapshot \
  --input path/to/model.step \
  --output /tmp/model.png \
  --mode view \
  --theme technical \
  --camera iso \
  --view-labels

静止画やアニメーション GIF の STEP モジュールのサイドカーパラメーターは、--params で指定できます。

python3 scripts/snapshot \
  --input path/to/model.step \
  --output /tmp/model.png \
  --params '{"drive":180,"ringVisible":false}'

python3 scripts/snapshot \
  --input path/to/model.step \
  --output /tmp/model.gif \
  --params '{"values":{"ringVisible":true},"animate":{"drive":{"from":0,"to":1260}},"durationSeconds":6,"fps":18,"loop":true}'

スナップショット CLI のデフォルトテーマは --theme technical です。これは、プレゼンテーションではなく視覚的な診断を目的とした、フラットでコントラストの高いテーマです。--theme には、組み込みテーマ名、インライン JSON テーマオブジェクト、または JSON テーマファイルのパスを指定できます。表面またはワイヤー出力にするには、theme.display.mode を solid または wireframe に設定します。--params の対象は Explorer の .step.js STEP モジュールのサイドカーパラメーターであり、Python／build123d の再生成パラメーターではありません。幅／高さが省略された場合、スナップショット CLI はリクエストのコンテキストに応じてデフォルトの寸法を選択します。診断用静止画は 1600x1200、ラベルのない単純な部品は 1200x900、断面／ラベル付き／寸法入りビューは 1600x1200 以上、複雑なアセンブリは render.sizeProfile を介して 1800x1200 または 1920x1440、プレゼンテーション用レンダリングは render.sizeProfile を介して 2400x1600 または 2800x1800、STEP モジュールのパラメーター GIF は 960x640、コンタクトシートは幅 2400 px 以上です。透明なスナップショットは、透明度によって重なり、衝突、または内部の関係性について具体的な疑問に答えられる場合を除き、プレゼンテーション用途にとどめます。カスタムテーマ設定、選択、断面、オービット設定、ロボットの関節値、STEP モジュールのパラメーター、DXF の厚さ／曲げオプション、複数出力のスナップショットには JSON ジョブを使用します。対応するレンダリングモードは view、orbit、section、list です。対応する入力は .step、.stp、.glb、.stl、.3mf、.dxf、.urdf、.srdf、.sdf です。

ワークスペースのルートがわかっている場合は、明示的に指定します。

npm --prefix scripts/viewer run dev:ensure -- \
  --workspace-root /path/to/workspace \
  --file path/to/model.step

手動での Explorer 開発に限り、フォアグラウンド Vite を使用します。

npm --prefix scripts/viewer run dev

dev:ensure は、まず登録済みのローカル CAD Explorer サーバーをポート範囲全体にわたってプローブして確認し、可能な場合は一致するスキャンルートを持つサーバーを再利用します。その後、利用可能な最初のポートで Vite サーバーをデタッチして起動します。表示された URL を使用してください。

MoveIt2 コントロール

SRDF Explorer のレビューでは、ユーザーがインタラクティブな IK または経路計画のコントロールを必要とする場合にのみ、MoveIt2 サーバーを起動してください。SRDF の生成と通常の Explorer リンクには必要ありません。

このスキルディレクトリから実行します：

scripts/moveit2_server/setup.sh
scripts/moveit2_server/check-moveit2-server.sh
scripts/moveit2_server/run-moveit2-server.sh

サーバーのデフォルトは ws://127.0.0.1:8765/ws です。ローカル開発環境では、EXPLORER_MOVEIT2_WS_URL またはブラウザーの ?moveit2Ws= クエリで上書きしない限り、CAD Explorer はこの URL に接続します。

プロトコルとレポートの詳細については、references/moveit2-server.md をお読みください。

Explorer で使用する環境変数：

EXPLORER_PORT
EXPLORER_PORT_END
EXPLORER_ROOT_DIR
EXPLORER_DEFAULT_FILE
EXPLORER_WORKSPACE_ROOT
EXPLORER_GITHUB_URL
EXPLORER_MOVEIT2_WS_URL
EXPLORER_ALLOWED_HOSTS
EXPLORER_SERVER_REGISTRY

CAD Explorer を remotehost/Tailscale Serve 経由で公開する場合は、dev:ensure を開始または再起動する前に、EXPLORER_ALLOWED_HOSTS に Serve のホスト名を設定してください：

EXPLORER_ALLOWED_HOSTS=macbook-pro-108.tail3c8ded.ts.net \
  npm --prefix scripts/viewer run dev:ensure -- \
    --workspace-root /path/to/workspace \
    --root-dir models \
    --file path/to/model.urdf

リモートリンクを返す前に、ホストヘッダーのパスをローカルで確認してください：

curl -I -H 'Host: macbook-pro-108.tail3c8ded.ts.net' \
  'http://127.0.0.1:PORT/?file=path/to/model.urdf'

想定される応答は 200 OK です。

リモートのスマートフォンでページのシェルは読み込まれるものの、Vite 開発サーバー経由では画面が空白または黒く表示される場合は、レンダリングをさらに変更する前に、プロダクションプレビューを試してください。同じスキャンルートとデフォルトファイルを使ってビルドし、同じ EXPLORER_ALLOWED_HOSTS のホスト名で vite preview を起動して、Host ヘッダーのパスを確認してから、remotehost/Tailscale Serve の転送先をプレビューポートに変更してください：

EXPLORER_WORKSPACE_ROOT=/path/to/workspace \
EXPLORER_ROOT_DIR=models \
EXPLORER_DEFAULT_FILE=robots/elrobot/elrobot-follower.urdf \
  npm --prefix scripts/viewer run build

cd scripts/viewer
EXPLORER_WORKSPACE_ROOT=/path/to/workspace \
EXPLORER_ROOT_DIR=models \
EXPLORER_DEFAULT_FILE=robots/elrobot/elrobot-follower.urdf \
EXPLORER_ALLOWED_HOSTS=macbook-pro-108.tail3c8ded.ts.net \
EXPLORER_PORT=4202 \
  npm exec vite preview -- --host 127.0.0.1 --port 4202 --strictPort

これにより、同じ ?file= URL を維持したまま、スマートフォンへのアクセス経路から Vite の開発用クライアントと HMR WebSocket が除かれます。

GUI の作業は軽量に保ってください。リンクやレビューが必要な場合にのみサーバーを起動し、エージェントのワークフローでは dev:ensure を優先して使い、ユーザーから依頼されない限り、既存の Explorer サーバーを停止しないでください。