agentic-sim-world-genの仕組み¶
この文書は、コードを開く前にagentic-sim-world-gen全体の流れをつかむためのものです。 使い方はgetting-started.mdにあります。
各節は「図 → 短い説明 → 関係するファイル」の順に書いています。図に出てくる名前(関数・ファイル・MCPツール・primのパス)はコードにある名前です。
目次
1. 全体の流れ¶
flowchart TD
subgraph inputs["入力"]
nl["言葉の指示"]
photo["写真"]
plan["間取り図JSON / DXF / IFC"]
ref["参考画像"]
end
nl -->|"plan_questionsの既定+Claudeが英訳して書く"| spec["SceneSpec"]
photo -->|"fit_photos"| spec
plan -->|"import_floor_plan → room.plan_file"| spec
ref -->|"InputRef kind=referenceのtaste"| spec
spec -->|"create_scene"| search["候補検索 _find_candidates"]
search --> resolved["ResolvedScene<br/>scene.resolved.json"]
resolved -->|"density"| decor["小物・店の陳列<br/>_apply_density"]
decor --> resolved
resolved -->|"保存のたびに"| solve["レイアウトsolve"]
solve --> autofix["直し方が決まっている問題を直す<br/>_auto_fix"]
autofix --> checks["静的チェック・使い勝手"]
checks --> preview["プレビュー<br/>candidates.html / layout.svg / preview.html"]
preview -->|"合意したらfinish(compose_scene)"| usd["scene.usda"]
usd -->|"finish(check_in_isaac)"| isaac["Isaac Simで物理settle+撮影<br/>check.json / check.png"]
isaac --> fix{"問題あり?"}
fix -->|"はい:set_layout / select_asset / set_colliderなど"| resolved
fix -->|"いいえ"| report["finishの結果(指示との突き合わせ・ライセンス)→ 報告"]
入力からSceneSpecへ¶
どの入力も、いったんSceneSpec(部屋と物の指定を書いたJSON)に集まります。 言葉の指示からSceneSpecを書くのは呼び出し側のClaudeで、サーバー側にLLMはありません。検索クエリは英語で書きます(英訳が検索の精度に最も効く)。
指示に無い項目(広さ・入口・レジの位置など)は、plan_questionsが場所ごとに返す既定で埋めて叩き台を作り、推測として記録します(8. 対話の流れ)。
既定で埋める代わりに、次の3つの進め方もあります。
| こんなとき | 進め方 | 名前 | 記録のされ方 |
|---|---|---|---|
| 広さが指示に無い | 叩き台を1つ作る代わりに、広さだけを変えた3案の上面図を並べて選んでもらう | create_scene(drafts="size")・propose_drafts |
推測ではなく「選んだ」 |
| 家・オフィス・学校・研究室 | 広さや人数ではなく「誰が・何人で・何をする場所か」を聞き、広さ・主な家具・数を表から逆算する | scene/activity.pyのderive_activity |
根拠「活動から」の推測 |
| 叩き台に理由の無い「違う」が返った | 今の案と1つの軸(広さ・物の量・雰囲気・配置の型)だけを変えた案を並べて「どちらが近いか」を聞き、2〜3回で違っていた軸を絞る | propose_contrast・choose_contrast |
ResolvedSceneと保存のたびの処理¶
create_sceneが物ごとにアセットを検索して候補を付けたものがResolvedSceneで、シーンのディレクトリのscene.resolved.jsonに保存されます。
以後のツール(set_layout、select_asset、set_room …)はどれも、このファイルを読んで変えて保存します。保存(service._save)のたびに次を行います。
- 天井のある事務所・教室・店などで、場所の器具(
Room.fixtures_from="place"、新しいシーンで誰も器具を決めていない時に付く)を見直す(_default_fixtures)。 器具はプリセットの裸の光と同じ格子に立つ。場所・照明が変われば付け替え、天井を外した時・天井付けの照明器具の物がある時は外す。決めた器具とfixtures: falseには触らない。 - レイアウトを解き直す(
solve)。 - 直し方が1つに決まる問題をサーバーが直す(
_auto_fix)。対象は、狭い通路(narrow_aisle)、近すぎる関節付きの椅子どうし(too_close)、足の無いTV(tips_over)です。 検査がIssue.fixesに付けた直し方をシーンの写しに当てて解き直し、その問題が消えて新しい問題が1つも増えない時だけ採用します。ユーザーが置いた物と、その呼び出しが動かした物は動かしません。 直した内容は、結果のauto_fixed、仮定の「自動で直した」、プレビューの変更履歴に出ます。 - 静的チェックと使い勝手の検査をする(5. 検証)。
- プレビューを書き直す。
create_sceneとfinish¶
よく続けて呼ぶ処理は、1回の呼び出しにまとめてあります(個別のツールも残っています)。
create_scene(MCPツール。中身はservice.start_scene):シーンを作った後、用途の記録(purpose)・窓の作り込み(windows)・プレビューを開く(preview)・叩き台の3Dの撮影(draft)まで進めます。skipで一部を飛ばせます。finish:ユーザーが合意した後の仕上げです。USDを書き(compose_scene)、Isaac Simの物理を回して確かめ(check_in_isaac)、指示との突き合わせとライセンスの一覧まで返します。 問題があればstoppedで止まるので、直してもう一度finishを呼びます。これが修正ループです。
flowchart TD
f["finish"] --> iss{"配置のissuesや<br/>未選択の配置案がある?"}
iss -->|"ある"| s1["stopped=issues / layout_options"]
iss -->|"無い"| gate{"窓の外が灰色(siteもwindow_viewの仮定も無い)?<br/>写真と比べていない(比較の回数が残りIsaac Simがある)?"}
gate -->|"はい"| s0["stopped=window_view / compare"]
gate -->|"いいえ"| comp["compose_scene<br/>(scene.usdaが古いときだけ)"]
comp -->|"失敗"| s2["stopped=compose"]
comp --> isaac{"Isaac Simがある?"}
isaac -->|"無い"| lic
isaac -->|"ある"| chk["check_in_isaac<br/>(前回passedから変わっていなければ使い回す)"]
chk -->|"verdictがfailed / needs_fix"| s3["stopped=check"]
chk -->|"draft=true"| dr["叩き台の撮影だけで終わる"]
chk -->|"passed"| req["check_request<br/>指示の項目を測り直す"]
req --> lic["license_report<br/>ライセンスの一覧"]
lic --> done["done(unmetの項目が無ければtrue)<br/>Isaac Simが無ければunverifiedに物理を挙げる<br/>report_must_includeに報告で触れること"]
編集ツールの結果(service.reply)は、前回の結果から変わったところだけを返します。
ステータスのヒント(*_hint・*_next・substitute)も同じで、前回と同じ文面なら本文を送らず、上の方のopen_hintsにキーと最初の一文を並べます。
ツール自身のhint / nextは毎回送ります。前回の結果を別のサーバープロセスが返していたら(新しいセッション)、全部を全文で送ります。
並びは言語→issues→open_hints→新しいヒント→残り(usabilityは先頭5件とusability_more)。
読み流されたヒントのうち、窓の外と写真の比較はfinishで止め(stopped)、報告に要るもの(usabilityの件数・種類、代用、見送った小物、
アセットの無い窓・カーテン、写真で位置の分からない家具)はfinishのreport_must_includeに挙げます。
関係するファイル
- src/agentic_sim_world_gen/service.py:CLIとMCP共通の操作(create_scene・start_scene・_save・compose_scene・check_in_isaac・finishなど)
- src/agentic_sim_world_gen/mcp_server.py:MCPサーバー(ツールはserviceの関数を呼ぶだけ)
- src/agentic_sim_world_gen/cli.py:CLI(agentic-sim-world-gen ...)
- .claude/skills/world-gen/SKILL.md:Claudeが従う手順
2. データの形¶
図には主な項目だけを載せています(全項目はscene/spec.pyとassets/record.py)。
classDiagram
class SceneSpec {
name
room
objects
inputs
sdg
purpose
mood
photo_aisle
assumptions
requirements
layout_options
notes
}
class Room {
place
width / depth / height
floor / walls / ceiling
lighting / fixtures
openings
columns / levels / stairs
plan
density
goods / goods_words
outdoor / site
}
class ObjectSpec {
id
query / alt_queries
min_size / max_size
layout
array
fill
position / facing_deg
variants / tint / screen
collider
decor
}
class Layout {
against_wall / along
in_front_of
next_to / side
on
facing
center / ceiling
gap
}
class InputRef {
kind
camera
taste
}
class ResolvedScene {
spec
placements
}
class Placement {
object_id
selected
candidates
size_misses
}
class AssetRecord {
source / uri
bbox_min / bbox_max
up_axis / meters_per_unit
license
thumbnail_url
variant_selections
shelves / hooks / screens
}
SceneSpec *-- Room
SceneSpec *-- "0..*" ObjectSpec
SceneSpec *-- "0..*" InputRef
ObjectSpec o-- Layout
ResolvedScene *-- SceneSpec
ResolvedScene *-- "0..*" Placement
Placement --> "0..*" AssetRecord : candidates
| クラス | 中身 |
|---|---|
| SceneSpec | ユーザーの指示そのもの。部屋・物・入力・用途purpose・雰囲気mood・仮定・指示の項目・プレビューのメモnotes。アセットの選択は含まない |
| Room | 矩形の部屋(width・depth)、間取り(plan)、屋外(outdoor)のどれか。場所の種類place(home・office・店の種類STORE_PLACESなど)、床・壁・照明・開口・柱・段差・密度もここに持つ。表に無い業種の店の商品はgoods、屋内の部屋の外まわり(歩道・駐車場・隣の建物)はsite |
| ObjectSpec | 置きたい物1つ。英語のqueryと、置き方を関係で書くlayout(座標はsolveが決める)。同じ物の並びはarray、棚への陳列はfill。密度に応じて自動で足した物はdecor=true(idはdecor_*) |
| ResolvedScene | SceneSpecに、物ごとのPlacement(候補アセットの一覧と、選んだ候補の番号selected)を足したもの |
| AssetRecord | 検索で見つかったアセット1つ。bbox・軸・単位・ライセンス・サムネイルなど、配置と合成に要る情報を持つ |
シーンとは「scene.resolved.jsonのあるディレクトリ」のことです。そこにできる主なファイル:
<scene>/
scene.resolved.json シーンの本体(SceneSpec+候補+選択+計算した位置)
candidates.html 候補アセットの一覧
layout.svg 上面の配置図
preview.html / preview.json ライブプレビューのページと更新の印
.history/NNNNNN.json.gz 保存ごとの scene.resolved.json(直近 30 件。取り消し・「ここに戻す」・restore が読む)
scene.usda Isaac Sim 用のワールド
check.json / check.png / check.gif Isaac Sim の物理チェックの報告とスクショ
check_orbit/NN.jpg 周りから撮った画像(プレビューで回して見る)
LICENSES.md アセット・材質・入力写真のライセンスと帰属表示
surfaces.json 床・壁・天井の材質の検索結果
layout_options/ 配置案・叩き台 3 案の上面図と summary.json
taste_pool.json テイスト検査の比較用の候補
plan.json / plan.svg 間取り図を読み込んだとき
inputs/ 入力の写真(出典は <stem>.source.json)
photo_fit.json / compare.png 写真から推定したときの結果と見比べ
nav/ ロボット用のナビ地図(map.pgm・map.yaml、nav_map)
variants/ シーンのバリエーション(make_variants)
sdg/ 合成データ
関係するファイル - src/agentic_sim_world_gen/scene/spec.py:SceneSpec・Room・ObjectSpec・Layout・ResolvedScene・Placement - src/agentic_sim_world_gen/scene/plan.py:開口(Opening)・間取り(FloorPlan) - src/agentic_sim_world_gen/assets/record.py:AssetRecord - 出力の説明:getting-started.md「7. 出力」
3. アセット検索¶
flowchart TD
obj["ObjectSpecのquery+alt_queries"] --> prov["get_provider<br/>CompositeProvider"]
prov --> src1["SimReadyCentralProvider<br/>HFの検索API"]
prov --> src2["IsaacIndexProvider<br/>isaac_6.1.jsonl.gz"]
prov --> src3["LocalFolderProvider<br/>local:dirの索引"]
prov --> src4["PolyHavenProvider<br/>polyhaven_models.jsonl.gz"]
src1 --> merge["ソースの結果をまとめる<br/>同名ファイルは先のソースが勝つ"]
src2 --> merge
src3 --> merge
src4 --> merge
merge --> size["サイズの絞り込みfits<br/>min_size / max_size"]
size --> qmerge["クエリごとの結果をまとめる<br/>同じアセットは順位の良い方"]
qmerge --> rr["rerank:名詞の一致でスコア<br/>weak=たぶん別物"]
rr --> drop{"強い一致がある?"}
drop -->|"ある"| keep["weakを外す"]
drop -->|"無い"| sub["全部weakのまま残す<br/>substitute=代用"]
keep --> order["合わない物を後ろへ<br/>(下の表)"]
sub --> order
order --> cands["Placement.candidates"]
cands -->|"view_candidates"| img["Claudeがサムネイルで判断"]
img -->|"select_asset / research_object"| cands
- 検索:物ごとに
queryとalt_queries(英語の類義語)で、設定されたすべてのソースを検索します。 ソースは環境変数AGENTIC_SIM_WORLD_GEN_SOURCESで選びます(既定はSimReady Central・Isaac同梱・Poly Haven。+local:<dir>で既定に足す)。 1回の呼び出し(create_scene・add_objects)で要る検索は先にまとめて並列に投げます(service._searching)。SimReady Centralの答えはAGENTIC_SIM_WORLD_GEN_CACHE/searchに1日残します。 - サイズ:
min_size/max_size(footprintの長辺・短辺・高さ)から外れる物を落とします(fits)。アセットの向きには依りません。
3. 再ランク(
rerank):クエリの最後の名詞(物そのもの)が、アセットのclass・tags・caption・nameに名詞として出るかで点を付けます。
たとえば「desk lamp」は机ではなく、「coffee table」はdining tableの代わりにならない(どちらもweak)。アセットのカード(assets/cards.py)に見て確かめた種類kindがあれば、ラベルよりそちらを使います。
強い一致が1つでもあればweakは一覧から外し、全部weakなら「該当なし=代用」として残します。
形・つくりの語(round・oval・rectangular・upholstered・glass)はグループで照らし合わせ、合えば加点、逆の形(楕円を頼んで四角)なら減点します。
4. 後ろへ回す:合わない物も消さずに、次の表の上の行ほど後ろへ回します。
| 印 | どんな物か | 例 |
|---|---|---|
too_tall |
天井より上に出る | |
off_size |
サイズの指定が無いとき、種類の標準サイズ(assets/sizes.pyのTYPICAL)から大きく外れる |
「cardboard box」にパスタの箱 |
off_place |
場所(Room.place)に合わない分野のアセット(assets/domain.py) |
家に病院のベッド |
カードのphysics_issue |
自分の落下テストに失敗したアセット | |
heavy |
大きさの割に面が多すぎる | |
_wrong_picture |
絵柄が別の店のもの。並びの段ではなく、スコアを少し下げるだけ(PICTURE_PENALTY) |
ドラッグストアに書店のレジ看板 |
- 見つからない時:全部が代用のときは、種類の表(
assets/kinds.py、MCPkind_availability)を引いて、その種類がどのソースにも無いか(not_in_catalog)を返し、探し直しを止めます。 全部weakでサイズの指定があるときは、サイズで落とした強い一致をPlacement.size_missesに挙げます(指定を広げる手がかり)。 足りなかった物は保存のたびにシーンごとにAGENTIC_SIM_WORLD_GEN_CACHE/missing/へ記録され(missing.py)、agentic-sim-world-gen missingで多い順に見られます。 無いので外した物(remove_object(no_asset=true))と、報告だけの物(note_missing)も残ります。アセットを足したらagentic-sim-world-gen missing --recheckで探し直し、見つかった物は別の欄に移ります(missing-found.json)。 - 最後の判断:Claudeが
view_candidates(サムネイル画像を返す)で決めます。メタデータだけでは色・素材・形が分からないためです。
関係するファイル
- src/agentic_sim_world_gen/assets/providers/base.py:AssetProviderプロトコル・fits
- src/agentic_sim_world_gen/assets/providers/composite.py・simready_central.py・isaac_index.py・local_folder.py・polyhaven.py
- src/agentic_sim_world_gen/assets/sizes.py:TYPICAL(種類ごとの標準サイズ)・kinds.py:種類の表
- src/agentic_sim_world_gen/assets/rerank.py:rerank・score・noun_last
- src/agentic_sim_world_gen/assets/cards.py:アセットごとのカード(of・physics_issue・brief)。データはsrc/agentic_sim_world_gen/data/asset_cards.jsonl.gz、作り直しはscripts/build_asset_cards.py
- src/agentic_sim_world_gen/assets/domain.py:off_place
- src/agentic_sim_world_gen/service.py:get_provider・_find_candidates・_wrong_picture・research_object
4. レイアウト¶
flowchart TD
room["Room"] --> geom["RoomGeometry<br/>walls・faces・obstacles・zones"]
objs["ObjectSpec.layout"] --> order["_order<br/>相手を先に解く"]
order --> rel{"関係の種類"}
geom --> rel
rel -->|"against_wall"| wall["壁面faces_forに背を付ける<br/>alongで位置"]
rel -->|"in_front_of"| front["相手の正面に立ち、相手を向く"]
rel -->|"next_to+side"| side["相手の横に同じ向きで"]
rel -->|"on"| on["相手の上面に載せる<br/>zが決まる"]
rel -->|"facing・center"| face["向き・部屋の中心"]
frame["frame.py<br/>正面は +X、例外はKNOWN_FRONTS"] --> front
frame --> face
wall --> pose["position / yaw_deg / z"]
front --> pose
side --> pose
on --> pose
face --> pose
pose --> arr["array.instances<br/>ラック列・机の島"]
pose --> fill["fill.slots<br/>棚板に商品を並べる"]
pose --> dec["decor.plan<br/>密度に応じた小物・店の棚の陳列"]
win["fill_windows<br/>窓の開口に窓・カーテン"] --> pose
RoomGeometryは、矩形の部屋も間取りも屋外も同じ形で表します。
| 要素 | 中身 |
|---|---|
壁walls |
中心線と厚さ |
壁面faces |
物が背を付けられる内側の面。ドアの前は障害物(空き)で避ける |
障害物obstacles |
壁本体・ドアの前・柱columns・段差levels・階段・天井の梁や照明器具 |
ゾーンzones |
間取りの部屋 |
外まわり(siteがあるとき) |
部屋の外壁・エリアの辺・建物の面と、エリア・建物の障害物。外の物のzoneはoutsideかエリアのID |
段差の上に中心がある物は、ソルバがその段差の高さに載せます。
- solve:
layoutの関係(against_wall・in_front_of・next_to・on・facing・center・gap)から位置・向き・高さを決めます。「机を先に、椅子を後に」という解く順は_orderが決めます。 保存のたびに解き直すので、アセットを差し替えてサイズが変わっても配置が追従します。move_objectで手で動かした物はlayoutが消え、座標のままになります。 - 正面の規約:アセットの正面は+Xです(Isaac Sim 6.1で、約40点を4方向から描いて確認)。
ForgeCADのアセット(作者または入手先がForgeCAD)は-Y向きです(
FORGECAD_FRONT_DEG=270。椅子の背もたれやトイレのタンクが+Y側にある)。 例外はKNOWN_FRONTS・KNOWN_FRONT_PATTERNSに、手持ちのフォルダならagentic-sim-world-gen.jsonのfrontに、物ごとならfront_offset_degに書きます。手で向きを決めるときはfacing_deg(0=東=+X、90=北=+Y)。 - 繰り返し:
arrayはブロック全体を1つの物として置き、検証・プレビュー・USDではユニット(<id>.r<row>c<col>)に展開します。 - 陳列:
fillは、什器のジオメトリから見つけた棚板(assets/shelves.py)に商品を並べます。 - 小物:
Room.density(sparse / normal / lived_in)に応じて、机に本、ソファの前にラグ、のような小物decor_*をcreate_sceneが足します。問題が増える置き方は捨てます(service._apply_density)。 - 店の陳列:店(
shopとSTORE_PLACESの25種:コンビニ・スーパー・ドラッグストア・書店・パン屋・自転車店・家具店など)では、同じ仕組みで空いている什器に商品をfillで並べます。 商品は店の種類ごとの表(decor.PRODUCTS。冷蔵ケースはCOLD_PRODUCTS、フックはHANG)から選び、隣の什器とは違う商品から始めます。 表に無い業種では、Room.goods(商品の英語の検索語)・goods_words(業種の語)を名乗る商品だけを並べます(decor.fits_goods)。店の広さ・入口・レジなどの既定はplan_questionsの表(questions.STORE_SIZES)にあります。 - 窓:窓の開口は壁の穴でしかないので、
fill_windowsが窓のアセットwin_<id>を足します。窓は開口に合わせて伸ばし(fit_scale)、店の幅1.8 m以上の窓はショーウィンドウにします。家ではカーテンcurtain_<id>、オフィス・学校・研究室・病院ではブラインドblind_<id>も足します(covers="auto"。coversで選び直せる)。
layout.svg(上面図、矢印が正面):

関係するファイル
- src/agentic_sim_world_gen/layout/room.py:RoomGeometry・Wall・Face・Obstacle
- src/agentic_sim_world_gen/layout/solver.py:solve
- src/agentic_sim_world_gen/layout/knee.py:机の下に椅子を差し込む深さ(部品の高さの格子)
- src/agentic_sim_world_gen/layout/frame.py:正面方向(asset_front_deg・yaw_for_facing。壁に掛ける薄い物で記録が無ければ薄い方向)
- src/agentic_sim_world_gen/layout/array.py・fill.py・assets/shelves.py
- src/agentic_sim_world_gen/scene/decor.py:plan・PRODUCTS・fits_goods
- src/agentic_sim_world_gen/scene/columns.py・levels.py・fixtures.py:柱・床の一部の仕上げ、段差・階段、天井の照明器具・梁
- src/agentic_sim_world_gen/preview/layout2d.py:layout.svg
5. 検証¶
flowchart LR
scene["ResolvedScene"] --> v1["validate.check<br/>issues"]
scene --> v2["usability.usability<br/>使い勝手の注意"]
scene --> v3["request.evaluate<br/>指示との突き合わせ"]
scene --> v4["taste.report<br/>テイストの外れ"]
v1 --> i1["out_of_room・overlap 3D・hits_wall<br/>blocks_door・too_tall・tips_overなど"]
v2 --> i2["歩ける範囲の格子から<br/>narrow_aisle・unreachable・no_front_space<br/>chair_facing・tv_distance<br/>empty_shelves・register_hiddenなど"]
v3 --> i3["met / unmet / unknown"]
v4 --> i4["outliersとalternatives"]
i1 --> st["statusとpreview.html"]
i2 --> st
i3 --> st
i4 --> st
検査は4種類あり、扱いの強さが違います。
| 検査 | 何を見るか | 扱い |
|---|---|---|
静的チェックvalidate.check |
部屋からのはみ出し、物どうしの重なり(足元の多角形のSAT+高さの範囲=3D)、壁の中・ドアの前、天井より高い | issues。0件になるまで直す |
使い勝手usability |
歩ける範囲・通路幅・物の前に立てるか・向きと距離(下の箇条書き) | 警告。理由があれば残してよい |
指示との突き合わせrequest.evaluate |
指示を項目に分け、壁際・隣・個数・向き・ゾーン・上に載る、を配置から測る | check_request。報告の前に必ず回す |
テイストtaste.report |
選んだアセットのサムネイルをSigLIP2で埋め込み、1つだけ見た目が浮いている物を探す | 警告。勝手に差し替えない |
使い勝手の検査の中身:
- 床を格子にし、ドアから歩ける範囲を求めます。そこから、棚・レジなどの前に立てるかを見ます。
- 通路幅が場所に足りるかを見ます(用途purposeがamrならロボットの幅)。通路の幅は距離変換の地図1枚(AisleMap)から求め、最も狭い所の幅と場所をnarrow_aisleに書きます。layout.svgには通路の中心線を幅に応じた色で描きます(赤=通れない、橙=狭い、緑=通路、青=広い)。
- 椅子と机・テレビの向きと距離、窓をふさぐ背の高い物、店の空の棚、入口から見えないレジも見ます。
椅子が机の下に入る重なりは、椅子の足元の短辺の60%まで許します(tuck_pair・MAX_TUCK)。ただしソルバは自分では差し込みません(差し込むのはgapを負にしたときだけ)。机の下に脚を入れる空間があるかはbboxから分からず、重なったまま物理を回すとPhysXが爆発するためです。
関係するファイル
- src/agentic_sim_world_gen/layout/validate.py:check・Issue・overlap_depth
- src/agentic_sim_world_gen/layout/usability.py:usability・AisleMap・aisle_map
- src/agentic_sim_world_gen/layout/widths.py:edt(距離変換)・widest(入口からの最も広い道)・narrowest・ridge(中心線)。usability・nav(routes)・layout2dが共有
- src/agentic_sim_world_gen/layout/request.py:evaluate・summary
- src/agentic_sim_world_gen/taste.py:report・analyze
6. USDの合成¶
flowchart TD
world["/World<br/>defaultPrim、Z-up、metersPerUnit=1"] --> phys["PhysicsScene"]
world --> lights["Lights"]
world --> room["Room"]
world --> objects["Objects"]
world --> cams["Cameras/id<br/>写真と同じ視点"]
room --> floor["Floor・ZoneFloors/id"]
room --> walls["Wall_S / Wall_N / Wall_W / Wall_E<br/>開口があればPart_NN"]
room --> ceil["Ceiling"]
room --> doors["Doors/id<br/>自動ドア"]
room --> parts["Columns・Levels・Stairs・Railings<br/>FloorAreas・CeilingFeatures"]
room --> looks["Looks<br/>Floor・Wall・Ceiling・SDG"]
objects --> obj["Objects/id<br/>Xform:配置のxformOps+customData"]
obj --> asset["Asset<br/>アセットの参照+バリアントPhysX=Enabled"]
obj --> col["Collider<br/>物理の無いアセットだけ"]
objects --> grp["Objects/id<br/>array・fillのグループ"]
grp --> unit["id_r0c0など<br/>それぞれにAsset"]
座標の規約¶
ステージはZ-up、メートル(metersPerUnit=1)で、defaultPrimは/Worldです。矩形の部屋の内側はx∈[0, width]、y∈[0, depth]で、床の上面がz=0です。
y (北)
↑
depth ┌──────────── Wall_N ────────────┐
│ │ │
│ Wall_W 部屋の内側 Wall_E
│ │ 床の上面z=0 │
│ │ │
0 └──────────── Wall_S ────────────┘
0 ─────────────────────────── width → x (東)
facing_deg:0=東(+X)、90=北(+Y)。zは上向き
物のprimとxformOps¶
物は/World/Objects/<id>(Xform)の子Assetからアセットを参照します。参照を子に置くのは、アセット自身のルートの変換(cmのアセットのscale 0.01など)を消さないためです。外側のXformにxformOpOrderを書くと、同じprimに付いた参照のルートの変換は上書きされてしまいます。
外側のXformのxformOpsは、xformOpOrderでは下の図の「primの形」の順に並びます。点に効くのは逆の順(右から)で、アセットの点はまずpivotを原点へ動かされ、最後に部屋の中の位置へ移ります(図の1→6)。
式で書くとp' = translate · rotateZ(yaw) · scale(mpu) · rotateX(90°, Y-upのとき) · (p − pivot)です。
このほか、開口に合わせて伸ばす窓・カーテンにはrotateZの直後にscale:fitが、寝かせて陳列する商品(fill.lay_flat)にはlayFlatの一連のopsが入ります。
array・fillの物は/World/Objects/<id>がグループになり、その下のユニット(arrayは<id>_r<row>c<col>、fillは<id>_<unit>_l<level>_<col>_<row>)がそれぞれ上と同じ形でAssetを持ちます。
出典・物理・見た目¶
- 出典:物のprimのcustomDataに、
agentic_sim_world_gen:source・agentic_sim_world_gen:uri・agentic_sim_world_gen:license・agentic_sim_world_gen:label・agentic_sim_world_gen:origin(入手先と版)・agentic_sim_world_gen:facing_degを書きます。ライセンスの一覧はlicense_reportがLICENSES.mdにまとめます。 - 物理:アセットの
PhysXバリアントをEnabledにすると、SimReadyのアセットに剛体とコライダーが付きます。 物理の無いアセットには、bboxと同じ大きさの見えない固定の箱Colliderを付けます(colliderがboxのとき、またはautoで物理の無いことが分かっているとき)。床・壁は静的なコライダーと摩擦のマテリアルを持ちます。 - 床・壁・天井の見た目:
Looksの下のマテリアル(UsdPreviewSurface、テクスチャ、MDL)です。 材質は、名前のプリセット(scene/looks.py)か、索引(Isaac Sim同梱のMDLのmaterials.py、CC0のPBR=ambientCG・Poly Havenのpbr.py)からselect_surfaceで選びます。見本の画像から床・壁・照明をまとめて選ぶのがmoods/apply_mood(scene/moods.py)です。 - 物の色:
tint(usd/tint.py)で、アセットのファイルを変えずにシーンの側からマテリアルの色を上書きします(UsdPreviewSurface・OmniPBR・OpenPBR・MaterialX standard_surfaceの基本色。テクスチャには色を掛けます)。
関係するファイル
- src/agentic_sim_world_gen/usd/compose.py:compose・build_room・build_site・_add_asset・add_box_collider・build_inputs
- src/agentic_sim_world_gen/usd/look.py:マテリアルと照明(build_lights)
- src/agentic_sim_world_gen/materials.py・pbr.py・scene/moods.py:床・壁の材質の検索、雰囲気の見本
- src/agentic_sim_world_gen/usd/door.py・screen.py:自動ドア、画面に画像(宣言の無いテレビは光るテクスチャのマテリアルを画面とみなす。テクスチャの無いlcdなどの画面は正面に重ねた板に描く。オフィス・教室・ラボのモニター・テレビは黒い画像で消す)
- src/agentic_sim_world_gen/license.py・origin.py:ライセンスと入手先
7. Isaac Sim側¶
Isaac SimはUbuntu(RTX)機にだけあり、agentic-sim-world-gen本体(usd-coreを使うPython)とは別のプロセスで動きます。 agentic-sim-world-genからIsaac Simを使う方法は、「スクリプトをIsaac SimのPythonで実行する」か「起動中のIsaac Simにコードを送る」かの2つです。
flowchart TD
call["check_in_isaac"] --> live{"live=true?"}
live -->|"はい"| risk{"物が重なっている?<br/>_live_risk"}
risk -->|"重なりが無く、python_serverが応答"| lx["live_exec<br/>開いているIsaac Simの :8226へコードを送る"]
risk -->|"重なりがある・応答が無い"| hl
live -->|"いいえ"| hl["_run_isaac<br/>scripts/isaac/check_scene.pyをheadlessで<br/>(Isaac workerがあればそちらへ。下の図)"]
lx --> core["check_core.run"]
hl --> core
core --> s1["open_stage:USDを開き参照の読み込みを待つ"]
s1 --> s2["survey:剛体・コライダーを数える"]
s2 --> s3["物理をstepsフレーム回す"]
s3 --> s4["judge:unstable・sunk・no_collider・static"]
s4 --> s5["check.png・check.gif<br/>draft=trueは物理なしで撮影だけ"]
s5 --> s6["orbit:check_orbit/NN.jpg"]
s6 --> rep["check.json → summarize_report"]
- headless:
check_scene.pyが自分でSimulationAppを立ち上げ、check_core.runを呼びます。Isaac SimのPythonはISAACSIM_PYTHON(pip版)か、ISAACSIM_PATHのpython.shです。 - ライブモード:
--enable isaacsim.code_editor.python_serverで起動したIsaac Simに、同じcheck_coreのコードを送ります。ユーザーの画面でシーンを開いて物理を回し、問題の物を選択状態にします。 物が重なっているシーンはheadlessに回します。重なった物がPhysXで爆発すると、GUIのIsaac SimのGPU物理がそのセッションの間止まってしまうためです。 - checkの中身:物理を回す前後で剛体の位置を比べ、動いた・倒れた(
unstable)、床に沈んだ(sunk)、当たり判定が無い(no_collider)、動かない固定物(static)を報告します。そのあと部屋を24方向から撮り、プレビューで回して見られるようにします。 - 結果:
summarize_reportが物体IDごとの要約にし、check_in_isaacがverdict(passed/needs_fix/draft/failed)を付けます。draft=trueは物理を回さず、叩き台の3Dを撮るだけです。
Isaac worker¶
Kitの起動はdraftのcheckの約40 sのほとんどを占めます。AGENTIC_SIM_WORLD_GEN_ISAAC_WORKER=1にすると、最初の呼び出しで起動したheadlessのIsaac Sim(scripts/isaac/worker.py)を起動したままにし、以後のcheck_scene.py・front_views.py・render_view.pyをそこで続けて実行します。
サーバーの既定は切ですが、agentic-sim-world-gen workspaceで作った作業フォルダでは入です。待っている間もKit 1つがGPUメモリを数GB(3.8〜7.9 GB)持つので、MoGe(単眼の深度)の前にisaac_worker.free_gpu()で止めます(実行中の仕事は終わるまで待つ。次のIsaac Simの呼び出しで起動し直す、約11 s)。
flowchart TD
req["_run_isaac → isaac_worker.run"] --> on{"AGENTIC_SIM_WORLD_GEN_ISAAC_WORKER=1で<br/>workerが実行できるスクリプト?"}
on -->|"いいえ"| one["1回ずつ起動して実行(one-shot)"]
on -->|"はい"| up{"workerが動いている?"}
up -->|"いいえ"| start["worker.pyを起動<br/>spoolフォルダ(AGENTIC_SIM_WORLD_GEN_CACHE)で待つ"]
start --> job
up -->|"はい"| job["job_NNNNNN.jsonを置き<br/>reply_N.jsonを待つ"]
job --> ok{"成功した?"}
ok -->|"失敗・時間切れ・落ちた"| fail["workerを止める<br/>(PhysXの爆発後はGPU物理が壊れたまま)"]
fail --> one
ok -->|"成功"| cnt{"AGENTIC_SIM_WORLD_GEN_ISAAC_WORKER_JOBS<br/>(既定40)回に達した?"}
cnt -->|"はい"| stop["workerを止める<br/>次の呼び出しで起動し直す"]
cnt -->|"いいえ"| idle["次の仕事を待つ<br/>AGENTIC_SIM_WORLD_GEN_ISAAC_WORKER_IDLE(既定600 s)の間<br/>仕事が無いか、サーバーが終わると自分で止まる"]
workerは仕事ごとにステージを閉じ、その仕事のフォルダのレイヤーを読み直すので、前の仕事のものは残りません。どちらの方法で動いたかは結果のisaac(modeがworkerかone-shot)に出ます。
ほかのIsaac Simの処理¶
view_fronts(front_views.py):各物を想定した正面から撮ります。撮らない物を非アクティブにしたレイヤーfront_views_stage.usdaを開くので、撮る物のアセットだけを読みます。compare_photo(render_view.py):写真と同じ視点で描きます。nav_map(isaac=true)(nav_map.py):Isaac SimのOccupancy Mapでナビ地図を作ります。front_views.py・render_view.pyは、決まったコマ数だけ待ってから撮るのではありません。20コマおきに撮り直し、2枚続けて同じ画になったら止めます(view.capture_settled、上限900コマ)。シェーダーのコンパイル中に撮って、モデルが抜けることを防ぎます。
どれもcheckと同じく、Isaac SimのPythonで動かします。
合成データ(SDG)¶
flowchart LR
gen["generate_data"] --> sp["sdg.plan<br/>カメラ・照明・材質をシードから決める"]
sp --> pj["sdg/plan.json"]
pj --> rs["scripts/isaac/sdg.py<br/>Replicatorのwriter"]
rs --> out["sdg/basic・coco・kitti<br/>summary.json・sheet.jpg"]
カメラ位置・照明・材質の割り当てはPython側(sdg.plan)がシードから決めてsdg/plan.jsonに書きます。Isaac側のscripts/isaac/sdg.pyは、それを当ててReplicatorのwriterを回すだけです。ラベルはcomposeがprimに付けたUsdSemanticsを使います。
check_orbitの回り込み画像:

関係するファイル
- scripts/isaac/check_scene.py・check_core.py・view.py・front_views.py・nav_map.py・worker.py
- src/agentic_sim_world_gen/service.py:check_in_isaac・live_exec・summarize_report・generate_data
- src/agentic_sim_world_gen/isaac_worker.py:run(起動したままのIsaac Simに仕事を渡す)
- src/agentic_sim_world_gen/sdg.py・scripts/isaac/sdg.py
8. 対話の流れ¶
sequenceDiagram
actor U as ユーザー
participant C as Claude(スキル)
participant W as agentic-sim-world-gen MCP
participant P as プレビュー
participant I as Isaac Sim
U->>C: 6畳の書斎を作って
C->>W: plan_questions
W-->>C: 結果を大きく変える項目と既定(場所が分からないときだけ先に聞くask_now)
C->>W: get_preferences
C->>W: create_scene(用途・窓・プレビュー・叩き台の3Dまで)
W->>P: preview.htmlを書いて開く(以後、保存のたびに更新)
W->>I: 物理なしで撮影(叩き台の3D)
C->>W: view_candidates(怪しい物の候補を1枚の一覧で) / select_asset
C->>W: propose_layouts(並べ方に選択肢があるとき)
C->>W: set_assumptions(配置から分からない推測だけ。残りはサーバーが記録)
C->>W: 直したらfinish(draft=true)(叩き台を撮り直す)
C->>U: 叩き台と推測を見せて「違う所を教えてください」
U->>P: ドラッグで移動・候補の差し替え・仮定に「違う」・メモ・雰囲気
P->>W: POST api/edit(move / select / feedback / note / mood / choose_layout)
U->>C: これでいい
C->>W: get_scene(preview_edits・assumption_feedback・notesを読む)
C->>W: finish
W->>I: USDを書いて物理settle+撮影
I-->>W: check.json・check.png・check_orbit
W-->>C: check・指示との突き合わせ・ライセンス(問題があればstopped)
C->>W: 問題があれば直して再finish
C->>U: 指示との突き合わせ表・USD・ライセンスを報告
スキル(SKILL.md)がClaudeに指示している手順です。
- 既定で叩き台:
plan_questionsが場所ごとの質問表から、指示にまだ書かれていない項目と既定を返します。先には聞かず、既定で作って推測として記録します。 先に聞くのは次の場合だけです。 - 場所が分からないとき(
ask_now) - 「先に質問して」と言われたとき(
ask_first) - 後からの手直しが大きい2項目:用途がロボット(amr / manipulation)で機体の大きさが書かれていないとき、実在の場所(「うちの店」)の依頼で図面・写真が付いていないとき
質問表が無い場所(病院・学校・駅など。plan_questionsがgalleryを返す)では、show_galleryが作例(examples/)と過去のシーンの上面図を並べたページ(gallery.html)を出し、選ばれた物のSceneSpecをstart_from_exampleが叩き台にします。引き継いだ寸法・場所・仕上げ・什器は「作例「…」から」の推測として記録します(gallery.py)。
2. 作成:get_preferencesで前回までの好みを読み、create_sceneを呼びます。create_sceneは続けて用途の既定(set_purpose。密度・通路幅などを用途から決める、scene/purpose.py)と窓(fill_windows)まで進めます。
仮定どうしが食い違えば(6畳に8人掛けの机、ロボットより狭い通路など。scene/conflicts.py)、叩き台を撮らずにconflictsを返します。Claudeはどちらを優先するかを1問だけ聞きます(おまかせなら広い方に合わせて報告)。
3. 候補の確認:プレビューはcreate_sceneが開きます。怪しい候補(代用・弱い一致・寸法や置き場所が合わない物)はview_candidatesが1枚の一覧画像で返すので、見て差し替えます。
4. 配置:issuesが0になるまで直し、使い勝手の注意を見ます。並べ方そのものが選択肢ならpropose_layoutsで2〜3案を出します。
5. 叩き台を見せる:部屋の5項目と物ごとの仮定はサーバーが配置から記録します(_auto_assumptions)。そのためset_assumptionsには、配置から分からない推測だけを書きます。
3Dはcreate_sceneが撮っています(直した後はfinish(draft=true)で撮り直す)。推測したところを先に見せて止まります(「おまかせ」なら止まらない)。
6. check:合意したらfinish(USD → check → 指示との突き合わせ → ライセンス)。
7. 突き合わせ:check_requestで指示の各項目を測ります。
8. 報告:突き合わせ表・USDのパス・選んだアセット(代用を明記)・ライセンス。
プレビューのページ¶

ユーザーはチャットだけでなく、プレビューのページでも操作できます。ページでの操作は、プレビューサーバーのapi/editからserviceの関数を呼んでシーンに反映されます。
| ページでの操作 | api/editのop |
|---|---|
| layout.svgの物のドラッグ・回転 | try(動かしている途中の検査)・move |
| 候補カードのクリックでの差し替え | select |
| 「仮定」表の「違う」 | feedback |
| 配置案の「この案にする」 | choose_layout |
| 雰囲気の見本の選択・取り消し | mood・mood_undo |
| メモの書き込み・削除 | note・note_delete |
| 取り消し・削除・複製・密度・部屋・照明 | restore・remove・duplicate・density・room・light |
上面図やcheckの3Dをダブルクリックして書くメモ(「ここにライトを」)は、シーンを変えずに残ります(notes.py)。Claudeがresolve_notesで返事をすると消えます。
次のターンのClaudeは、ツールの結果のstatusにあるpreview_edits・assumption_feedback・notesでページでの操作を知ります。
プレビューサーバーは、MCPサーバーのプロセスの中のスレッドです。
- 待ち受け:127.0.0.1:8765(AGENTIC_SIM_WORLD_GEN_PREVIEW)。使用中なら、そのフォルダで前に使った番号か、次の空き番号を使います。
- 配るもの:シーンの親フォルダ(ふつうAGENTIC_SIM_WORLD_GEN_OUT)の下。
- 更新:ページが1秒ごとにpreview.jsonを見て、変わった部分だけを書き換えます。
- 書き込みの条件:ページに埋めたトークンと、loopbackからの接続。
ユーザーが直した値(correction=trueのset_room・set_layout・set_array・select_asset、プレビューでの差し替え)は好みとして記録されます。2つ以上のシーンで同じ値(数値なら同じ向きの変化)になった項目は、次からの既定になります。
関係するファイル
- .claude/skills/world-gen/SKILL.md:手順の全文
- src/agentic_sim_world_gen/scene/questions.py:plan_questions
- src/agentic_sim_world_gen/scene/purpose.py:用途(demo / amr / manipulation / sdg)からの既定
- src/agentic_sim_world_gen/scene/conflicts.py:食い違う仮定の検出(床の占有・天井高・ロボットの通路幅・人数と席数)。statusのconflicts。あればcreate_sceneは叩き台を撮らない
- src/agentic_sim_world_gen/gallery.py:作例と過去のシーンの一覧(entries・rank)、ページ(write_page)、引き継いだ値(inherited)。作例の上面図はscripts/make_gallery.pyでdata/gallery/に作る
- src/agentic_sim_world_gen/preferences.py:observe・apply
- src/agentic_sim_world_gen/preview/server.py:serve・edit(上の表のop)・api/gallery/pick(ギャラリーで選んだ作例)
- src/agentic_sim_world_gen/notes.py:プレビューのメモの場所を言葉にする
- src/agentic_sim_world_gen/preview/page.py・changes.py:ページと変更履歴
9. 写真から部屋を推定¶
流れは2段です。まず写真から部屋の寸法とカメラを推定し(fit_photos)、次にその結果をシーンに入れて、家具の位置を決めたり写真と見比べたりします。
部屋とカメラの推定¶
flowchart TD
photos["写真"] --> lm["Claudeが目印を拾う<br/>部屋の角・壁の継ぎ目・開口の角"]
photos -->|"depth.run"| dep["MoGe-2の深度<br/>stem.depth.npz"]
lm --> fit["fit_photos<br/>photo_fit.fitの最小二乗"]
dep -->|"depth=true"| fit
fit --> res["部屋の寸法・開口・各カメラ"]
部屋を箱とみなし、写真ごとに見えている目印(部屋の角、壁と床の線、ドア・窓の角、複数の写真に写る共有点)の画素をClaudeが拾います。
fit_photosは、部屋の幅・奥行き・開口の位置・各カメラの位置と向き・視野角を未知数にして、目印の再投影の誤差を最小にします(純PythonのLevenberg–Marquardt)。
尺度は壁の高さで決まります。天井の目印が無ければ、カメラの高さ(eye_height)で決めます。
天井が見えないと写真ごとに尺度が別になるので、ドアの上端などの高さの分かる物は、それが写る写真の尺度しか決めません。幅・奥行きを測る写真(向かい合う2つの壁を写す写真)が高さの分かる物を写していなければ、その寸法はカメラの高さで決まったと結果のscaleと警告に出します(_scale_reach)。
壁の高さも当てはめて、それが部屋の種類の範囲(place)から外れたり怪しい(height_suspect)ときは、同じ呼び出しの中で高さを固定して当て直し、目印が同じくらい合い、深度などメートルで測ったものも悪くならなければ固定した方を採ります(height_refit。placeが無い・載っていない部屋は当て直さない)。
単眼の深度(MoGe-2)を足すと、壁を1〜2面しか写さない写真でも寸法が決まりやすくなります。
シーンに入れて確かめる¶
flowchart TD
res["fit_photosの結果<br/>部屋の寸法・開口・各カメラ"] -->|"set_room / set_input"| scene["シーン"]
res -->|"place_from_photos"| pp["photo_place.py<br/>足元の点から家具の位置・向き"]
pp -->|"outlinesがあれば"| ref["photo_refine.py<br/>箱の投影を足元・矩形に合わせる"]
pp --> scene
ref --> scene
scene -->|"compare_photo"| cmp["同じ視点で描いて写真と並べる"]
scene -->|"measure_photo"| ms["photo_measure.py<br/>写真のカメラから見た部屋・通路の幅<br/>深度マップの床面と空き幅(depth_floor)"]
- 結果は
set_roomとset_input(カメラ)でシーンに入れます。 - 写真で家具の足元を拾っていれば、
place_from_photosが、選んだアセットのfootprintをその点に当てはめて位置と向きを決めます。 写真上で物を囲んだ矩形(outlines)も渡すと、アセットの箱を推定したカメラで写真に投影し、足元の画素と矩形に合うように位置を詰めます(photo_refine.py)。 compare_photoで同じ視点から描いて写真と見比べ、measure_photoで部屋と通路の幅を写真と数値で比べます。- 通路をまたぐ画素の組を
aisle_pairで指すと、その幅が配置の目標(SceneSpec.photo_aisle)になります。使われるのは、配列の通路、usability.photo_aisleを通した歩行幅・広すぎの判定、statusのphoto_aisleの比です。 - 寸法の分かる物(棚1台・ドア・床タイルなど)が写っていれば、その画素を
knownで渡します。その物を物差しにした幅とカメラの高さも出します。
関係するファイル
- src/agentic_sim_world_gen/photo_fit.py:fit(結果のscale= 縮尺の根拠の一覧は_scale_evidence。高さの当て直しは_height_refit)・FitRequest・PointObs・LineObs・SurfaceObs
- src/agentic_sim_world_gen/photo_refine.py:refine(箱の投影と足元・輪郭の画素の差を最小化)
- src/agentic_sim_world_gen/photo_place.py・photo_measure.py:写真から家具の位置、写真との幅の比較(幅には誤差の幅を付ける)。photo_vanish.py:写真の縦の線の消失点からカメラのピッチ・ロール
- src/agentic_sim_world_gen/depth.py・scripts/depth/moge_depth.py:単眼の深度
- src/agentic_sim_world_gen/inputs.py:入力の出典(<stem>.source.json)
- scripts/isaac/render_view.py:写真と同じ視点で描く