Restore remote asset URLs in stage dumps

Author: pbarejko

source/isaaclab/changelog.d/pbarejko-unmirror-cached-asset-paths.minor.rst

@@ -0,0 +1,7 @@
+Added
+^^^^^
+
+* Added :func:`~isaaclab.utils.assets.unmirror_file_path`, which maps a locally cached asset copy
+  written by :func:`~isaaclab.utils.assets.retrieve_file_path` back to the URL it was downloaded
+  from. Exports of a stage that references cached copies can use it to name the source assets
+  instead of machine-specific cache paths.

source/isaaclab/isaaclab/utils/assets.py

@@ -118,6 +118,11 @@ def _resolve_asset_root() -> str:
 
 _GIT_SSH_RE = re.compile(r"^[^@/:]+@[^:]+:.+")
 
+_MIRROR_URL_SCHEMES = frozenset({"http", "https", "omniverse"})
+"""URL schemes whose assets are cached locally, and which therefore start a cache layout."""
+
+_MIRROR_NETLOC_PORT_RE = re.compile(r"^(.+)_(\d+)$")
+
 
 def retrieve_git_asset_path(
     git_path: str, local_path: str, cache_dir: str | None = None, force_update: bool = False
@@ -305,6 +310,33 @@ def _mirror_path(url: str, download_dir: str) -> str:
     return os.path.join(download_dir, parsed.scheme, netloc, *parsed.path.lstrip("/").split("/"))
 
 
+def unmirror_file_path(path: str) -> str:
+    """Reverses :func:`retrieve_file_path` caching, mapping a cached copy back to its source URL.
+
+    A remote asset is cached under ``<download_dir>/<scheme>/<host>/<path>``, and stages reference
+    that cached copy rather than the URL it came from. Exports of such a stage therefore carry
+    absolute paths that only resolve on the machine holding the cache. This recovers the URL so an
+    export can name the source asset instead.
+
+    Args:
+        path: Local filesystem path, typically an asset path read from a USD layer.
+
+    Returns:
+        The URL the path was cached from, or ``""`` when it does not lie inside a cache layout.
+    """
+    parts = path.replace(os.sep, "/").split("/")
+    # the last two components are the host and at least one path component, so a scheme found
+    # there cannot be the start of a cache layout
+    for index, part in enumerate(parts[:-2]):
+        if part.lower() not in _MIRROR_URL_SCHEMES:
+            continue
+        netloc, *remainder = parts[index + 1 :]
+        # ``_mirror_path`` writes a port separator as '_', which is not valid in a host name
+        netloc = _MIRROR_NETLOC_PORT_RE.sub(r"\1:\2", netloc)
+        return f"{part.lower()}://{netloc}/{'/'.join(remainder)}"
+    return ""
+
+
 def _remote_fingerprint(url: str) -> dict | None:
     """Provider metadata identifying the revision of ``url`` the server currently holds.
 

source/isaaclab/test/utils/test_assets.py

@@ -419,6 +419,28 @@ def test_using_local_copies_is_announced_once_per_cache_directory(asset_cache, m
     assert {_REMOTE_URL, other_url} == {record.args[0] for record in per_asset}
 
 
+@pytest.mark.parametrize(
+    "url",
+    [
+        "https://example.com/Assets/Isaac/6.0/Isaac/Props/Blocks/DexCube/Materials/dex_cube_mod.png",
+        "http://example.com/Assets/example.usd",
+        "omniverse://nucleus.example-lab.com:3009/Assets/example.usd",
+    ],
+)
+def test_unmirror_file_path_recovers_the_url_a_copy_was_cached_from(tmp_path, url):
+    """Test a cached copy names the asset it came from, so exports do not carry local paths."""
+    assert assets_utils.unmirror_file_path(assets_utils._mirror_path(url, str(tmp_path))) == url
+
+
+@pytest.mark.parametrize(
+    "path",
+    ["/home/user/assets/example.usd", "Materials/dex_cube_mod.png", "OmniPBR.mdl", ""],
+)
+def test_unmirror_file_path_leaves_paths_outside_the_cache_unclaimed(path):
+    """Test a locally authored asset path is not mistaken for a cached remote copy."""
+    assert assets_utils.unmirror_file_path(path) == ""
+
+
 def test_newton_asset_dir_uses_environment_override(tmp_path, monkeypatch):
     """Test that the Newton asset directory is defined from the environment."""
     repo_dir = tmp_path / "newton-assets"

source/isaaclab_tasks/changelog.d/pbarejko-unmirror-cached-asset-paths.skip

@@ -0,0 +1,3 @@
+Rendering test stage dumps rewrite cached asset paths back to their source URLs, so a stage saved
+through ``ISAAC_LAB_SAVE_STAGES`` no longer carries texture paths that only resolve on the machine
+that ran the test.

source/isaaclab_tasks/test/rendering_test_utils.py

@@ -510,6 +510,20 @@ def _sanitize_golden_stage_text(text: str) -> str:
     return text.rstrip("\n") + "\n"
 
 
+def _restore_remote_asset_paths(layer) -> None:
+    """Point cached asset paths in ``layer`` back at the URLs they were downloaded from.
+
+    Remote USD assets are referenced through a local cache copy, so flattening resolves the
+    textures and materials they carry into absolute cache paths that exist only on the machine
+    that ran the test. Locally authored paths are left untouched.
+    """
+    from pxr import UsdUtils  # noqa: PLC0415
+
+    from isaaclab.utils.assets import unmirror_file_path  # noqa: PLC0415
+
+    UsdUtils.ModifyAssetPaths(layer, lambda asset_path: unmirror_file_path(asset_path) or asset_path)
+
+
 def maybe_save_stage(
     test_name: str,
     physics_backend: str,
@@ -551,6 +565,7 @@ def maybe_save_stage(
         flat_layer = opened_stage.Flatten()
         if flat_layer is None:
             pytest.fail(f"Could not flatten the saved stage at {stage_path}.")
+        _restore_remote_asset_paths(flat_layer)
 
         if out_dir:
             os.makedirs(out_dir, exist_ok=True)