Getting Started¶
cloneしてからIsaac Simで最初のワールドを開くまで(目安15分。Isaac Simのインストールは除く)。
0. どこで動かすか¶
Isaac Sim・Claude Code・agentic-sim-world-genは、どちらの形でもGPU機(Ubuntu+RTX)に入れる。違うのは、GPU機の画面とキーボードで直接操作するか、別のPCからsshで使うか。
flowchart LR
q1{"Ubuntu+RTXの<br/>GPU機がある?"} -- "ない" --> nogpu["検索・プレビュー・USDまで<br/>(チェックは無し)"]
q1 -- "ある" --> q2{"どこから<br/>操作する?"}
q2 -- "GPU機の画面と<br/>キーボードで" --> local["1. 全部手元<br/>ライブ確認もできる"]
q2 -- "別のPCから<br/>sshで" --> ssh["2. ssh先<br/>手元はsshとブラウザ"]
| 形 | GPU機 | 手元で見るもの | ライブモード | 手順 |
|---|---|---|---|---|
| 1. 全部手元 | 手元のUbuntu+RTX(画面あり) | Isaac Simの画面・プレビュー・ターミナル | 使える | use-local.md |
| 2. ssh先 | LANのUbuntu+RTXなど(画面は無くてよい) | sshのターミナルと、ブラウザのプレビュー(ssh -L) |
使えない(headless) | use-ssh.md |
下の節は2つに共通の内容(インストール・環境変数・流れ・出力)。
1. 必要なもの¶
| 必要なもの | 何に使うか |
|---|---|
Ubuntu+RTX GPU、Isaac Sim 6.1(pip版で確認済み。スタンドアロンのpython.shは未確認) |
物理チェック・スクショ・写真比較・合成データ |
| Python 3.12以上、uv | agentic-sim-world-gen本体(検索・プレビュー・USD出力) |
| Claude Code | 日本語の指示からシーンを作る(MCPサーバー+スキル) |
ffmpeg(任意。Ubuntu apt install ffmpeg、Mac brew install ffmpeg) |
物理チェックの様子をGIFに録る(check --gif) |
GPUの無いMac / PCでも、検索・プレビュー・USD出力まではできる(Isaac Simを使う操作だけ「Isaac Sim not found」になる)。
2. インストール¶
git clone https://github.com/atinfinity/agentic-sim-world-gen.git
cd agentic-sim-world-gen
uv sync --extra usd --extra hf --extra mcp --extra dev # 間取り図も使うなら --extra dxf --extra ifc も
source .venv/bin/activate
uv syncはuv.lockの版で.venvを作り、このリポジトリを編集可能な形で入れる(Pythonはrequires-pythonの3.12以上からuvが選ぶ)。
あとでextraを足すときは、使う--extraを全部付けてuv syncし直す(付けなかったextraは.venvから外れる)。
usd-coreは.venvにだけ入れる。 Isaac SimのPython(python.shやpip版のvenv)には何もpip installしない
(Isaac Simは自前のpxrを持っていて、混ざると壊れる)。
3. 環境変数¶
| 変数 | 既定 | 内容 |
|---|---|---|
ISAACSIM_PATH |
~/isaacsim |
スタンドアロン版(未確認)Isaac Simのフォルダ(python.shがある所) |
ISAACSIM_PYTHON |
なし | pip版Isaac Simのvenvのpython(設定するとISAACSIM_PATHより優先) |
OMNI_KIT_ACCEPT_EULA |
なし | YESでNVIDIA Omniverse EULAに同意(非対話でIsaac Simを動かすのに必要) |
AGENTIC_SIM_WORLD_GEN_OUT |
~/agentic_sim_world_gen_scenes |
MCP(Claude Code)で作ったシーンの保存先 |
AGENTIC_SIM_WORLD_GEN_EXAMPLES |
リポジトリのexamples/ |
作例ギャラリー(show_gallery)に並べるSceneSpecのフォルダ |
AGENTIC_SIM_WORLD_GEN_SOURCES |
simready-central,isaac,polyhaven |
アセットの検索元。+local:/data/usdで既定に手持ちのフォルダを足す(+なしで並べると既定を置き換える。defaultは既定の3つ)。polyhaven(Poly HavenのCC0モデル)は使うときだけ取得する |
AGENTIC_SIM_WORLD_GEN_POLYHAVEN_INDEX |
同梱の索引 | Poly Havenのモデル索引(scripts/build_polyhaven_models_index.pyで作り直し)の差し替え |
AGENTIC_SIM_WORLD_GEN_MDL |
1 |
0で床・壁・天井の材質にIsaac Sim同梱のMDLを使わない(CC0のPBRか色だけ)。同梱アセットを写さない絵を作る時にAGENTIC_SIM_WORLD_GEN_SOURCESからisaacを外すのと一緒に使う |
ISAAC_ASSETS_ROOT |
公開S3 | Isaac Sim同梱アセットをローカル / Nucleusに置いているならそのルート(Isaac/の親) |
AGENTIC_SIM_WORLD_GEN_ISAAC_LIVE |
127.0.0.1:8226 |
ライブcheckの接続先(use-local.md「ライブモード」) |
AGENTIC_SIM_WORLD_GEN_PREVIEW |
127.0.0.1:8765 |
プレビューのHTTPサーバー。ポートが使用中なら、同じ保存先フォルダで前回使った番号、それも使用中なら次の空き番号を使う(sshのトンネルを張り直さずに済むよう、~/.cache/agentic-sim-world-gen/preview_ports.jsonに覚える) |
AGENTIC_SIM_WORLD_GEN_BROWSER |
xdg-open / open |
プレビューを開くコマンド(例chromium --app={url})。画面の無いシェルでは開かず、URLを返す |
例(pip版):
4. Claude Codeで最初のワールド¶
作業用のフォルダを作って、そこでClaude Codeを起動する:
workspaceは作業フォルダに次のものを作る:.mcp.json(agentic-sim-world-genのMCPサーバー)、スキルworld-gen(リポジトリへのリンク)、
短いCLAUDE.md、会話の圧縮(compaction)の後も返答の言語を保つフックと、途中の1行・最終報告が利用者の言語で書かれたかを確かめるフック。シーンは~/agentic-sim-world-gen-ws/scenesにできる。
.mcp.jsonにはAGENTIC_SIM_WORLD_GEN_ISAAC_WORKER=1が入り、Isaac Simを起動したままにして2回目からのcheck・compare_photoを速くする(compare_photoで約90 → 70秒)。待っている間もGPUメモリを数GB使う(MoGeの単眼の深度の前には自動で止める)。要らなければ--env AGENTIC_SIM_WORLD_GEN_ISAAC_WORKER=0(.mcp.jsonの値が優先されるので、シェルの環境変数では切れない)。
作業フォルダはリポジトリの外に作る(中に作るとエラー)。リポジトリの中でclaudeを起動しても動くが、
開発用のCLAUDE.mdを毎ターン読むので料金が高く、会話の圧縮も早く起きる。
workspaceのオプション:
| オプション | 内容 |
|---|---|
--out <dir> |
シーンの保存先(AGENTIC_SIM_WORLD_GEN_OUTでも可) |
--env 名前=値 |
MCPサーバーの環境変数(例--env AGENTIC_SIM_WORLD_GEN_SOURCES=simready-central,isaac,local:/path)。Claude Codeの環境変数も引き継ぐ |
--allow-tools |
agentic-sim-world-genのツールを使うたびの許可を省く |
--model sonnet |
このフォルダのClaude Codeのモデル(安いモデルで作る時。出来の比較はまだしていない) |
--copy-skill |
スキルをリンクでなく写しにする(リンクならgit pullで更新される) |
--force |
中身の違うファイルを置き換える |
初回に.mcp.jsonのagentic-sim-world-gen MCPサーバーを承認する(スキルworld-genは自動で読み込まれる)。あとは頼むだけ:
6畳の書斎を作って。机と椅子、壁際に本棚
Claudeは次の順に進める(質問が来たら答える。2–3分、API料金は1回 $1前後)。
大きく分けると、create_sceneが叩き台(下の1〜5)までを1回で作って見せ、あなたが「これでいい」と言ったらfinishが仕上げ(5〜7)を1回で進める:
flowchart TD
ask(["頼む"]) --> cs
subgraph cs["create_scene(1〜5)"]
direction LR
a1["既定を決める"] --> a2["アセット検索"] --> a3["配置・検査"] --> a4["叩き台を描画"]
end
cs --> look{"直したい所は?"}
look -- "ある:言葉で頼む・プレビューで動かす" --> cs
look -- "これでいい" --> fin
subgraph fin["finish(5〜7)"]
direction LR
f1["USDを出力"] --> f2["Isaac Simで物理チェック<br/>(倒れた物は直して再チェック)"] --> f3["指示との突き合わせ<br/>ライセンス"]
end
fin --> done(["scene.usda・LICENSES.md"])
- 指示に無いこと(広さ・床・照明など)は既定で決め、先には聞かない(
plan_questions) - 部屋と家具をSceneSpecにし、英語のクエリ+類義語でアセットを検索(
create_scene)。プレビューもここでブラウザに開く - 候補のサムネイルを見て選ぶ(
view_candidates)。合うものが無ければ近いもので代用し、そう報告する - 関係で配置(壁際・机の前など)。重なり・はみ出しを検査
- USDを出力(
compose_scene)し、物理なしで描画した叩き台を見せて、違う所を聞く(check_in_isaacのdraft)。 「最後まで進めて」と頼めば止まらない - Isaac Simで物理チェック+スクショ(
check_in_isaac)。倒れた・沈んだ物があれば直して再チェック - 指示の項目ごとに満たしたかを確かめ(
check_request)、使ったアセットのライセンスをまとめる(license_report→ LICENSES.md)
続けて「本棚を窓の反対側に」「椅子を黒いものに替えて」のように直していける。
シーンは$AGENTIC_SIM_WORLD_GEN_OUT/<名前>/(作業フォルダから起動したならscenes/<名前>/)にできる。
この例の流れ(②〜④は実際の画面。それぞれ下の「プレビューで見るもの」で詳しく):

プレビューで見るもの¶
作業中はブラウザのプレビュー(preview.html。MCPはopen_preview、CLIはagentic-sim-world-gen preview <scene> --open)を開いておく。
変更のたびにその場で書き換わる(再読み込みしないので、ちらつかない)。

(Claude Codeに「6畳の書斎を作って。机と椅子、壁際に本棚を置いて」と頼み、Isaac Simのチェックまで終えたところ。ページ上部の「指示との突き合わせ」「雰囲気」「仮定」は省いている)
| ページの部分 | 中身 |
|---|---|
| アセット候補 | 1物体1行:選択中のサムネイル・アセット名・ライセンスのバッジ・代用や配置の問題のバッジ。今作業中の物だけ開く。「要確認のみ」で代用・ライセンス不明・非商用・配置の問題のある物だけに絞れる |
| 変更履歴 | このシーンで行った操作の一覧(新しい順、最大200件)。ヘッダーの「取り消す」で1つ前の版に、行の「ここに戻す」でその版に戻せる(直近30版まで)。操作ごとに、何がどう変わったか(アセット、位置・向き、部屋の寸法、床・壁・照明、配置の問題の数)を日本語で書く。関係で決まる物(机の前の椅子など)が連動して動いた分も載る。直前の操作の変更内容はページ上部にも出る |
| 上面図・3Dの叩き台 | 物をドラッグで動かす・候補を選ぶ。ダブルクリックすると、その場所へのメモ(「ここにゴミ箱を置いて」など)をClaudeに書き込める |
| checkの結果 | 「OK」(緑)/「要修正」(赤)のバッジ |
同じフォルダには、候補一覧と上面図が単独のファイルとしてもできる:
| candidates.html(候補一覧、緑枠が選択中) | layout.svg(上から見た配置。矢印が正面) |
|---|---|
![]() |
![]() |
Isaac Simのcheckは、物理が落ち着いたあとの部屋をcheck.pngに撮る:

さらに部屋を周りから24方向で撮る(check_orbit/。約6秒増える。orbit=0 / --orbit 0で撮らない)。
プレビューのページでは、この画像をドラッグ(← → キー)で回せる:

できたワールドをIsaac Simで開く方法と、開いているIsaac Simの画面でcheckする「ライブモード」はuse-local.md。
ssh先でのプレビューの開き方(ssh -L)はuse-ssh.md。
5. CLIで同じことをする¶
Claude Codeを使わず、SceneSpec(JSON)を自分で書いても同じ処理を呼べる。コマンドと、できるファイル:
flowchart LR
spec["SceneSpec<br/>examples/*.json"] -- "resolve" --> r["scene.resolved.json<br/>candidates.html<br/>layout.svg"]
r -- "compose" --> u["scene.usda"]
u -- "check" --> c["check.json・check.png<br/>check_orbit/"]
r -- "licenses" --> l["LICENSES.md"]
r -. "編集してpreview" .-> r
agentic-sim-world-gen search "office chair" --limit 5 # 検索だけ
agentic-sim-world-gen resolve examples/p0_study_room.json -o out/study
# out/study/scene.resolved.json 候補付きのシーン(selected・position を編集できる)
# out/study/candidates.html 候補一覧
# out/study/layout.svg 配置図
agentic-sim-world-gen preview out/study/scene.resolved.json # 編集後にプレビューを作り直す
agentic-sim-world-gen preview out/study --open # preview.htmlをブラウザで開き、変更のたびに自動更新(--serveはブラウザを開かずURLだけ)
agentic-sim-world-gen compose out/study/scene.resolved.json # -> out/study/scene.usda
agentic-sim-world-gen check out/study # Isaac Sim headless で物理+スクショ(約 35 秒)
agentic-sim-world-gen licenses out/study # -> out/study/LICENSES.md
agentic-sim-world-gen finish out/study # compose(古ければ)・check・指示との突き合わせ・licensesをまとめて(MCPのfinishと同じ)
シーンのファイルの例はexamples/。その形式と、Isaac Simのチェックのスクリプトを直接呼ぶ方法は
開発に参加する。
6. 他の入力¶
文章のほかに、間取り図・写真からも作れる。
| 入力 | 例 | 詳しく |
|---|---|---|
| 間取り図(JSON / DXF / IFC) | agentic-sim-world-gen plan examples/plans/1ldk.json -o out/1ldk_planでplan.jsonにし、room.plan_fileに指定する。Claudeには「examples/plans/1ldk.jsonの間取りで、LDKにソファ、和室に座卓」(和室は畳、洗面はタイルの床になる) |
データの形、src/agentic_sim_world_gen/scene/plan.py |
| 間取り図(画像 / PDF) | Claudeに画像を渡すと、なぞってJSONにする(単位px+下敷き画像) | スキルのplans.md |
| 写真 | 「examples/photos/living_room.jpgの部屋を作って」。出典は隣の<stem>.source.json。agentic-sim-world-gen photo <scene>で同じ視点の描画と並べる |
スキルのphotos.md |
| 写真の深度 | 下の「単眼の深度」のvenvを作り、agentic-sim-world-gen fit-photos req.json --depth(写真にimage)。部屋の寸法が決まりやすくなる |
下の「単眼の深度」 |
単眼の深度(任意)¶
fit_photos(depth=true)は写真ごとの深度をMoGe-2(MIT、141 MB)で求める。MoGeは依存が重いのでagentic-sim-world-genとは別のvenvに入れる:
python -m venv ~/.venvs/moge && ~/.venvs/moge/bin/pip install torch torchvision pillow numpy scipy \
opencv-python-headless huggingface-hub click
~/.venvs/moge/bin/pip install --no-deps "git+https://github.com/microsoft/MoGe.git@74fbce054ebed49800de42d0ad0e83495065719a" \
"git+https://github.com/EasternJournalist/utils3d-moge.git@62f09d58509485564e24d5d9f6aac9ee9ebc0c37" \
"git+https://github.com/EasternJournalist/pipeline.git@1c511390d90226c00c101f34b84df26a0f8789b4"
export AGENTIC_SIM_WORLD_GEN_DEPTH_PYTHON=~/.venvs/moge/bin/python
AGENTIC_SIM_WORLD_GEN_DEPTH_DOWNLOAD=1 agentic-sim-world-gen fit-photos req.json --depth # 初回だけモデルを取得
同じ手順がscripts/depth/moge_depth.pyの先頭にある。深度は各写真の隣の<stem>.depth.npzに残り、2回目からはモデルを回さない。
AGENTIC_SIM_WORLD_GEN_DEPTH_MODELで別のMoGe-2のモデルにできる。
ほかの機能¶
| 機能 | 例 | 詳しく |
|---|---|---|
| 繰り返し配置 | agentic-sim-world-gen resolve examples/warehouse_racks.json -o out/racks(ラック列+通路) |
READMEのset_array |
| 屋外 | agentic-sim-world-gen resolve examples/outdoor_yard.json -o out/yard(道路・歩道・建物・空) |
データの形 |
| 手持ちのUSDフォルダ | AGENTIC_SIM_WORLD_GEN_SOURCES=+local:/data/usd、中身の確認はagentic-sim-world-gen index /data/usd --list |
README「手持ちのUSDフォルダ」 |
| 床・壁・照明 | room.floor: "wood_light"、room.lighting: "office"など(「床はフローリング、照明は夜」のように言葉でも可) |
USDの合成 |
| 合成データ | agentic-sim-world-gen sdg out/study --frames 24 --coco → RGB・bbox・セグメンテーション・深度 |
Isaac Sim側 |
| 足りなかったアセットを多い順に見る | agentic-sim-world-gen missing(この機械で作った全シーンの、代用した物・候補が無かった物・見送った小物・無いので外した物・報告だけの物) |
アセット検索 |
| アセットを足した後に、足りなかった物を探し直す | agentic-sim-world-gen missing --recheck(今のアセット源で全部の検索語を探し直し、見つかった物を別の欄に移す) |
アセット検索 |
7. 出力¶
<scene>/
scene.resolved.json シーンの本体(SceneSpec+候補+選択+計算した位置)。これを編集・再利用する
candidates.html 候補アセット一覧
layout.svg 上面の配置図
scene.usda Isaac Sim 用ワールド(アセットは URL 参照。--localize でローカルにコピー)
check.json / .png 物理チェックの報告とスクショ(.gif は gif=true のとき)
check_orbit/NN.jpg 周りから撮った画像(プレビューでドラッグして回す)
LICENSES.md 使ったアセット・入力写真・空(HDRI)、アセットのテクスチャに使った写真・書体のライセンスと帰属表示
plan.json / plan.svg 間取り図を読み込んだとき
sdg/ 合成データ
check.jsonの主な項目:unstable(動いた・倒れた)、sunk(床に沈んだ)、no_collider(当たり判定が無い)、
static(動かない固定物。家具なら問題ない)、物ごとのmax_displacement_m・moved_body。
no_colliderの物はset_collider(box)でアセットと同じ大きさの見えない箱の当たり判定を付けられる(動かない固定物になる)。
物理が無いと分かっているSimReadyのアセット(Vertivのラックなど)には最初から付く。
Claude(MCP)やagentic-sim-world-gen checkに返すのは要約で、物体IDごとの数と最大移動、問題のある物体の詳細だけ(物が多くても数千字)。
それぞれの項目が表す状態(explodedは物ごとの項目、blew_upは「physics did not run」の時だけ出る):
8. ライセンス¶
USDの各アセットのcustomData agentic_sim_world_gen:licenseとLICENSES.mdに、出典・作者・ライセンスが記録される。
SimReady Central / SimReady(Isaac Sim同梱)は主にCC BY 4.0(帰属表示が必要)。Isaac Sim同梱のProps・Environments・空は
NVIDIA-Isaac-Sim(Isaac Simのライセンスに従う。再配布に注意)。
アセットのフォルダのasset.jsonにimage_credits(テクスチャに使った写真や書体)があれば、LICENSES.mdの
「Material used in the assets」に1件ずつ、使っている物の名前と並べて出る(例: Noto Sans JP、SIL Open Font License 1.1)。
どこから入手したどの版かも、アセットごとに後から同じものを特定できる形で残る(LICENSES.mdの「Sources」、プレビューの「ライセンスと入手先」、
USDのcustomData agentic_sim_world_gen:origin)。記録する内容は出どころで違う:
- SimReady Central:Hugging Faceのコミット(URLに入っている)とデータセット内のパス
- Isaac Sim同梱:リリース(例6.1)とパス。リリース内で差し替わる可能性があるので「リリース単位」と表示
- 手持ちのフォルダ(
local:):アセット自身の版(asset.jsonのversion、無ければUSDのassetInfo.version。 例v1.3.0)、gitのリモート、そのアセットのフォルダを最後に変えたコミット、ファイルのSHA-256。 フォルダに未コミットの変更があると「未コミットの変更」と警告する(同じものを取り直せない)。gitの外なら版とSHA-256だけ
共有する前にLICENSES.mdの「Warnings」(非商用、継承条件、不明)を確認し、帰属表示を添える。 不明なものは元のフォルダのライセンスを確認するか、別のアセットに替える。
9. トラブルシューティング¶
| 症状 | 対処 |
|---|---|
Isaac Sim not found |
ISAACSIM_PATH(python.shのあるフォルダ)かISAACSIM_PYTHON(pip版のpython)を設定 |
Isaac Sim EULA not accepted/止まったまま |
export OMNI_KIT_ACCEPT_EULA=YES |
| 初回のcheckがとても遅い | アセットのダウンロードとシェーダーのコンパイル。初回は数分、2回目以降は約35秒 |
| 検索が失敗する・遅い(SimReady Central) | Hugging Face側の制限や一時的な不調。少し待って再実行。オフラインでもAGENTIC_SIM_WORLD_GEN_SOURCES=isaacなら同梱の索引で検索できる |
| スクショが真っ黒・暗い | 照明プリセット(room.lighting)を変えるかlighting_scaleを上げる。屋外の空はHDRI。GPU / ドライバーがRTX描画に対応しているか確認 |
| マテリアルが赤い | MDLの読み込み失敗(HFからの読み込みが時々失敗する)。compose --localizeで回避 |
| 物が後ろを向いている | アセットの正面の規約違い。view_fronts(CLI agentic-sim-world-gen fronts <scene>)で確認し、front_offset_degで直す。手持ちのフォルダならagentic-sim-world-gen.jsonのfront |
| 物が飛ぶ・倒れる(unstable) | 重なり(issuesを確認)、細長い・頭が重い形、小さい物の上に置いた等。位置をずらすかgapを足すか別のアセットに |
| ライブcheckがheadlessで動いた | 報告のlive_fallbackに理由。Isaac Simを--enable isaacsim.code_editor.python_serverで起動しているか、物が重なっていないか |
| checkで「physics did not run」 | 物どうしが接したりめり込んだりして吹き飛び、GPU物理が止まった(CUDA error)。同じシーンは何度やっても同じ。blew_upの物を数cm離す(キャスター付きの椅子を隙間なしで並べた等)。ライブならIsaac Simも再起動する |
次に読むもの¶
使う:
- use-local.md・use-ssh.md:全部手元/ssh先での手順
- tools.md:全MCPツールと引数
- .claude/skills/world-gen/SKILL.md:Claudeの対話手順・家具の標準サイズ・和英クエリ例
コードを変える:
- architecture.md:仕組みを図で
- contributing.md:セットアップ・テスト・どこに何があるか・プルリクエスト
- CLAUDE.md:規約(座標系、USDの構造)

