Skip to content

[Assets] Resolve spawner USD assets from SimReady semantic search queries#6522

Draft
hujc7 wants to merge 3 commits into
isaac-sim:developfrom
hujc7:jichuanh/simready-usd-search
Draft

[Assets] Resolve spawner USD assets from SimReady semantic search queries#6522
hujc7 wants to merge 3 commits into
isaac-sim:developfrom
hujc7:jichuanh/simready-usd-search

Conversation

@hujc7

@hujc7 hujc7 commented Jul 14, 2026

Copy link
Copy Markdown
Collaborator

1. Summary

  • Spawn configurations can now resolve their USD assets from a SimReady USD-Search semantic query instead of a hardcoded path: SimReadyUsdFileCfg(query="food box") picks the top-ranked asset, SimReadyMultiUsdFileCfg(query="food box", top_k=15) resolves a top-k list for heterogeneous cloning / clutter randomization.
  • The search itself is a spawner-agnostic resolver, isaaclab.utils.assets.search_simready_usd_paths, placed next to the existing asset-retrieval helpers (retrieve_file_path, retrieve_git_asset_path) so non-spawner consumers (collections, tooling, user scripts) can call it directly. The new isaaclab.sim.spawners.simready sub-module contains only the two cfg subclasses (~150 LOC total). Zero changes to existing spawners — the query resolves once at cfg construction, and downstream code sees a plain usd_path.
  • Optional dependency simready-search (public PyPI) ships behind a new simready extra: ./isaaclab.sh -i simready or pip install isaaclab[simready]. The import is lazy, so the core install stays dependency-free.
  • 13 unit tests, split to mirror the layout: resolver tests run against a mocked simready.search (no network, no optional dep needed); spawner-cfg tests stub the resolver directly. The resolver is additionally validated against the real package.

2. Design notes

  • The service is queried exactly once per configuration: __post_init__ freezes the resolved paths into usd_path, so no network calls happen during simulation. copy()/replace() re-run __post_init__, but an already-resolved guard prevents re-querying (configclass default factories deepcopy MISSING, so the guard matches by type rather than identity).
  • Results are sorted by (-relevance_score, asset_path) so relevance ties resolve identically across processes — relevant for multi-GPU runs where each rank queries independently.
  • The library is constructed with raise_on_network_error=True: auth/network failures raise typed errors instead of the library default of silently returning zero results. A genuinely empty result raises ValueError with the query in the message.
  • min_relevance, filter_profiles, and filter_features map to the library's relevance/profile/feature filters — e.g. filter_features=["FET004_BASE_PHYSX"] restricts results to physics-ready SimReady assets.
  • The simready extra is excluded from ./isaaclab.sh -i all: the search service requires credentials (USD_SEARCH_USERNAME / USD_SEARCH_PASSWORD environment variables, documented in the resolver docstring).
  • Since the resolved list depends on the state of the asset index, re-running a script may resolve different assets. The frozen list lands in the run's env-cfg dump; pinning it back via usd_path reproduces a run exactly (documented on the cfg class).

3. Test plan

  • pytest source/isaaclab/test/utils/test_assets.py -k simready — 6 resolver tests against a fake simready.search module (runs in CI without the optional dependency or network).
  • pytest source/isaaclab/test/sim/test_spawn_simready.py — 7 spawner-cfg tests with the resolver stubbed (resolve-once contract, copy/replace no-requery, parameter forwarding, explicit usd_path pinning).
  • Real-package check: the resolver drives simready-search 2026.4.2 end-to-end; the un-authenticated 403 from the dev endpoint surfaces as a typed AssetLibraryRemoteResponseError instead of an empty result.
  • Lazy-export smoke: SimReadyUsdFileCfg and SimReadyMultiUsdFileCfg import from both isaaclab.sim and isaaclab.sim.spawners; search_simready_usd_paths imports from isaaclab.utils.assets.
  • Pre-commit clean on all files.
  • Live search + spawn validation against the service (needs service credentials).

4. Out of scope / follow-ups

  • Cross-run result caching (pinning via the env-cfg dump covers reproducibility).
  • Production service endpoint and credential distribution — coordination with the SimReady team; the dev endpoint is the package-documented default for now.

Spawn configurations previously required hardcoded USD file paths. This
adds the isaaclab.sim.spawners.simready sub-module, which resolves the
usd_path of a spawner configuration from a SimReady USD-Search semantic
query at configuration construction time: SimReadyUsdFileCfg uses the
top-ranked result and SimReadyMultiUsdFileCfg freezes the top-k results
for heterogeneous cloning. No spawner changes are needed since the
resolved paths feed the existing UsdFileCfg/MultiUsdFileCfg machinery.

The required simready-search package is optional and lazy-imported,
available through the new 'simready' extra (./isaaclab.sh -i simready).
Search failures raise typed errors, results are tie-broken
deterministically for multi-process runs, and already-resolved
configurations skip the query on copy()/replace().
@github-actions github-actions Bot added documentation Improvements or additions to documentation isaac-lab Related to Isaac Lab team infrastructure labels Jul 14, 2026
hujc7 added 2 commits July 14, 2026 12:20
The constant tests assert the literal contents of VALID_EXTRA_FEATURES
and MANUAL_EXTRA_FEATURES, so the new 'simready' extra must be added to
their expected sets. Also mirror the manual-extra dispatch test used by
'ov' for the new selector-less 'simready' token.
The search function is spawner-agnostic: it takes a query and returns
USD asset paths. Move it and the endpoint constant to
isaaclab.utils.assets, next to the other asset retrieval helpers, so
non-spawner consumers can use it without importing spawner modules.
The simready spawner sub-module keeps only the two cfg subclasses.

Split the tests to mirror the layout: resolver tests move to the
utils asset tests together with the fake simready.search module; the
spawner cfg tests stub the resolver directly and gain a
parameter-forwarding test.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation infrastructure isaac-lab Related to Isaac Lab team

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant