Creates a minimal function to change prim properties (isaac-sim#4337)

# Description

This MR introduces a simplified version of the `ChangePrimProperty`
command.

The original command is designed to handle complex USD layer
compositions, but most of our applications do not require this level of
functionality. In practice, we either do not support multiple
composition layers at all, or only support limited mechanisms such as
references or variants.

Using the Kit-provided command also introduces unnecessary side effects,
such as early stage attachment, due to its reliance on layer-resolving
APIs. To avoid this extra coupling and complexity, this MR replaces the
command with a lightweight implementation tailored to our actual use
cases.

## Type of change

- Breaking change (existing functionality will not work without user
modification)

## Checklist

- [x] I have read and understood the [contribution
guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html)
- [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with
`./isaaclab.sh --format`
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have updated the changelog and the corresponding version in the
extension's `config/extension.toml` file
- [ ] I have added my name to the `CONTRIBUTORS.md` or my name already
exists there

Author: Mayankm96

source/isaaclab/config/extension.toml

@@ -1,7 +1,7 @@
 [package]
 
 # Note: Semantic Versioning is used: https://semver.org/
-version = "0.53.0"
+version = "0.53.1"
 
 # Description
 title = "Isaac Lab framework for Robot Learning"

source/isaaclab/docs/CHANGELOG.rst

@@ -1,6 +1,21 @@
 Changelog
 ---------
 
+0.53.1 (2026-01-08)
+~~~~~~~~~~~~~~~~~~~
+
+Added
+^^^^^
+
+* Added function :func:`~isaaclab.sim.utils.prims.change_prim_property` to change attributes on a USD prim.
+  This replaces the previously used USD command ``ChangeProperty`` that depends on Omniverse Kit API.
+
+Changed
+^^^^^^^
+
+* Replaced occurrences of ``ChangeProperty`` USD command to :func:`~isaaclab.sim.utils.prims.change_prim_property`.
+
+
 0.53.0 (2026-01-07)
 ~~~~~~~~~~~~~~~~~~~
 

source/isaaclab/isaaclab/markers/visualization_markers.py

@@ -24,7 +24,6 @@
 import torch
 from dataclasses import MISSING
 
-import omni.kit.commands
 import omni.physx.scripts.utils as physx_utils
 from pxr import Gf, PhysxSchema, Sdf, Usd, UsdGeom, UsdPhysics, Vt
 
@@ -396,18 +395,12 @@ def _process_prototype_prim(self, prim: Usd.Prim):
                 child_prim.SetInstanceable(False)
             # check if prim is a mesh -> if so, make it invisible to secondary rays
             if child_prim.IsA(UsdGeom.Gprim):
-                # early attach stage to usd context if stage is in memory
-                # since stage in memory is not supported by the "ChangePropertyCommand" kit command
-                sim_utils.attach_stage_to_usd_context(attaching_early=True)
-
                 # invisible to secondary rays such as depth images
-                omni.kit.commands.execute(
-                    "ChangePropertyCommand",
-                    prop_path=Sdf.Path(f"{child_prim.GetPrimPath().pathString}.primvars:invisibleToSecondaryRays"),
+                sim_utils.change_prim_property(
+                    prop_path=f"{child_prim.GetPrimPath().pathString}.primvars:invisibleToSecondaryRays",
                     value=True,
-                    prev=None,
+                    stage=prim.GetStage(),
                     type_to_create_if_not_exist=Sdf.ValueTypeNames.Bool,
-                    usd_context_name=prim.GetStage(),
                 )
             # add children to list
             all_prims += child_prim.GetChildren()

source/isaaclab/isaaclab/sim/converters/mesh_converter.py

@@ -15,7 +15,7 @@
 from isaaclab.sim.converters.asset_converter_base import AssetConverterBase
 from isaaclab.sim.converters.mesh_converter_cfg import MeshConverterCfg
 from isaaclab.sim.schemas import schemas
-from isaaclab.sim.utils import export_prim_to_file
+from isaaclab.sim.utils import delete_prim, export_prim_to_file
 
 # import logger
 logger = logging.getLogger(__name__)
@@ -173,7 +173,7 @@ def _convert_asset(self, cfg: MeshConverterCfg):
             )
             # Delete the original prim that will now be a reference
             geom_prim_path = geom_prim.GetPath().pathString
-            omni.kit.commands.execute("DeletePrims", paths=[geom_prim_path], stage=stage)
+            delete_prim(geom_prim_path, stage=stage)
             # Update references to exported Xform and make it instanceable
             geom_undef_prim = stage.DefinePrim(geom_prim_path)
             geom_undef_prim.GetReferences().AddReference(self.usd_instanceable_meshes_path, primPath=geom_prim_path)
@@ -220,7 +220,6 @@ async def _convert_mesh_to_usd(in_file: str, out_file: str, load_materials: bool
         enable_extension("omni.kit.asset_converter")
 
         import omni.kit.asset_converter
-        import omni.usd
 
         # Create converter context
         converter_context = omni.kit.asset_converter.AssetConverterContext()

source/isaaclab/isaaclab/sim/converters/urdf_converter.py

@@ -10,7 +10,6 @@
 from packaging.version import Version
 from typing import TYPE_CHECKING
 
-import isaacsim
 import omni.kit.app
 import omni.kit.commands
 

source/isaaclab/isaaclab/sim/spawners/from_files/from_files.py

@@ -17,11 +17,11 @@
     add_labels,
     bind_physics_material,
     bind_visual_material,
+    change_prim_property,
     clone,
     create_prim,
     get_current_stage,
     get_first_matching_child_prim,
-    is_current_stage_in_memory,
     select_usd_variants,
     set_prim_visibility,
 )
@@ -231,25 +231,13 @@ def spawn_ground_plane(
     # Change the color of the plane
     # Warning: This is specific to the default grid plane asset.
     if cfg.color is not None:
-        # avoiding this step if stage is in memory since the "ChangePropertyCommand" kit command
-        # is not supported in stage in memory
-        if is_current_stage_in_memory():
-            logger.warning(
-                "Ground plane color modification is not supported while the stage is in memory. Skipping operation."
-            )
-
-        else:
-            prop_path = f"{prim_path}/Looks/theGrid/Shader.inputs:diffuse_tint"
-
-            # change the color
-            omni.kit.commands.execute(
-                "ChangePropertyCommand",
-                prop_path=Sdf.Path(prop_path),
-                value=Gf.Vec3f(*cfg.color),
-                prev=None,
-                type_to_create_if_not_exist=Sdf.ValueTypeNames.Color3f,
-                usd_context_name=stage,
-            )
+        # change the color
+        change_prim_property(
+            prop_path=f"{prim_path}/Looks/theGrid/Shader.inputs:diffuse_tint",
+            value=Gf.Vec3f(*cfg.color),
+            stage=stage,
+            type_to_create_if_not_exist=Sdf.ValueTypeNames.Color3f,
+        )
     # Remove the light from the ground plane
     # It isn't bright enough and messes up with the user's lighting settings
     omni.kit.commands.execute("ToggleVisibilitySelectedPrims", selected_paths=[f"{prim_path}/SphereLight"], stage=stage)

source/isaaclab/isaaclab/sim/spawners/materials/visual_materials.py

@@ -8,10 +8,10 @@
 import logging
 from typing import TYPE_CHECKING
 
-import omni.kit.commands
-from pxr import Usd
+from omni.usd.commands import CreateMdlMaterialPrimCommand, CreateShaderPrimFromSdrCommand
+from pxr import Usd, UsdShade
 
-from isaaclab.sim.utils import attach_stage_to_usd_context, clone, safe_set_attribute_on_usd_prim
+from isaaclab.sim.utils import clone, safe_set_attribute_on_usd_prim
 from isaaclab.sim.utils.stage import get_current_stage
 from isaaclab.utils.assets import NVIDIA_NUCLEUS_DIR
 
@@ -30,9 +30,9 @@ def spawn_preview_surface(prim_path: str, cfg: visual_materials_cfg.PreviewSurfa
     both *specular* and *metallic* workflows. All color inputs are in linear color space (RGB).
     For more information, see the `documentation <https://openusd.org/release/spec_usdpreviewsurface.html>`__.
 
-    The function calls the USD command `CreatePreviewSurfaceMaterialPrim`_ to create the prim.
+    The function calls the USD command `CreateShaderPrimFromSdrCommand`_ to create the prim.
 
-    .. _CreatePreviewSurfaceMaterialPrim: https://docs.omniverse.nvidia.com/kit/docs/omni.usd/latest/omni.usd.commands/omni.usd.commands.CreatePreviewSurfaceMaterialPrimCommand.html
+    .. _CreateShaderPrimFromSdrCommand: https://docs.omniverse.nvidia.com/kit/docs/omni.usd/latest/omni.usd.commands/omni.usd.commands.CreateShaderPrimFromSdrCommand.html
 
     .. note::
         This function is decorated with :func:`clone` that resolves prim path into list of paths
@@ -55,18 +55,39 @@ def spawn_preview_surface(prim_path: str, cfg: visual_materials_cfg.PreviewSurfa
 
     # spawn material if it doesn't exist.
     if not stage.GetPrimAtPath(prim_path).IsValid():
-        # early attach stage to usd context if stage is in memory
-        # since stage in memory is not supported by the "CreatePreviewSurfaceMaterialPrim" kit command
-        attach_stage_to_usd_context(attaching_early=True)
-
-        omni.kit.commands.execute("CreatePreviewSurfaceMaterialPrim", mtl_path=prim_path, select_new_prim=False)
+        # note: we don't use Omniverse's CreatePreviewSurfaceMaterialPrimCommand
+        # since it does not support USD stage as an argument. The created material
+        # in that case is always the one from USD Context which makes it difficult to
+        # handle scene creation on a custom stage.
+        material_prim = UsdShade.Material.Define(stage, prim_path)
+        if material_prim:
+            shader_prim = CreateShaderPrimFromSdrCommand(
+                parent_path=prim_path,
+                identifier="UsdPreviewSurface",
+                stage_or_context=stage,
+                name="Shader",
+            ).do()
+            # bind the shader graph to the material
+            if shader_prim:
+                surface_out = shader_prim.GetOutput("surface")
+                if surface_out:
+                    material_prim.CreateSurfaceOutput().ConnectToSource(surface_out)
+
+                displacement_out = shader_prim.GetOutput("displacement")
+                if displacement_out:
+                    material_prim.CreateDisplacementOutput().ConnectToSource(displacement_out)
+        else:
+            raise ValueError(f"Failed to create preview surface shader at path: '{prim_path}'.")
     else:
         raise ValueError(f"A prim already exists at path: '{prim_path}'.")
 
     # obtain prim
     prim = stage.GetPrimAtPath(f"{prim_path}/Shader")
+    # check prim is valid
+    if not prim.IsValid():
+        raise ValueError(f"Failed to create preview surface material at path: '{prim_path}'.")
     # apply properties
-    cfg = cfg.to_dict()
+    cfg = cfg.to_dict()  # type: ignore
     del cfg["func"]
     for attr_name, attr_value in cfg.items():
         safe_set_attribute_on_usd_prim(prim, f"inputs:{attr_name}", attr_value, camel_case=True)
@@ -75,7 +96,9 @@ def spawn_preview_surface(prim_path: str, cfg: visual_materials_cfg.PreviewSurfa
 
 
 @clone
-def spawn_from_mdl_file(prim_path: str, cfg: visual_materials_cfg.MdlMaterialCfg) -> Usd.Prim:
+def spawn_from_mdl_file(
+    prim_path: str, cfg: visual_materials_cfg.MdlFileCfg | visual_materials_cfg.GlassMdlCfg
+) -> Usd.Prim:
     """Load a material from its MDL file and override the settings with the given config.
 
     NVIDIA's `Material Definition Language (MDL) <https://www.nvidia.com/en-us/design-visualization/technologies/material-definition-language/>`__
@@ -108,25 +131,24 @@ def spawn_from_mdl_file(prim_path: str, cfg: visual_materials_cfg.MdlMaterialCfg
 
     # spawn material if it doesn't exist.
     if not stage.GetPrimAtPath(prim_path).IsValid():
-        # early attach stage to usd context if stage is in memory
-        # since stage in memory is not supported by the "CreateMdlMaterialPrim" kit command
-        attach_stage_to_usd_context(attaching_early=True)
-
         # extract material name from path
         material_name = cfg.mdl_path.split("/")[-1].split(".")[0]
-        omni.kit.commands.execute(
-            "CreateMdlMaterialPrim",
+        CreateMdlMaterialPrimCommand(
             mtl_url=cfg.mdl_path.format(NVIDIA_NUCLEUS_DIR=NVIDIA_NUCLEUS_DIR),
             mtl_name=material_name,
             mtl_path=prim_path,
+            stage=stage,
             select_new_prim=False,
-        )
+        ).do()
     else:
         raise ValueError(f"A prim already exists at path: '{prim_path}'.")
     # obtain prim
     prim = stage.GetPrimAtPath(f"{prim_path}/Shader")
+    # check prim is valid
+    if not prim.IsValid():
+        raise ValueError(f"Failed to create MDL material at path: '{prim_path}'.")
     # apply properties
-    cfg = cfg.to_dict()
+    cfg = cfg.to_dict()  # type: ignore
     del cfg["func"]
     del cfg["mdl_path"]
     for attr_name, attr_value in cfg.items():

source/isaaclab/isaaclab/sim/spawners/sensors/sensors.py

@@ -8,10 +8,9 @@
 import logging
 from typing import TYPE_CHECKING
 
-import omni.kit.commands
 from pxr import Sdf, Usd
 
-from isaaclab.sim.utils import attach_stage_to_usd_context, clone, create_prim, get_current_stage
+from isaaclab.sim.utils import change_prim_property, clone, create_prim, get_current_stage
 from isaaclab.utils import to_camel_case
 
 if TYPE_CHECKING:
@@ -94,17 +93,11 @@ def spawn_camera(
 
     # lock camera from viewport (this disables viewport movement for camera)
     if cfg.lock_camera:
-        # early attach stage to usd context if stage is in memory
-        # since stage in memory is not supported by the "ChangePropertyCommand" kit command
-        attach_stage_to_usd_context(attaching_early=True)
-
-        omni.kit.commands.execute(
-            "ChangePropertyCommand",
-            prop_path=Sdf.Path(f"{prim_path}.omni:kit:cameraLock"),
+        change_prim_property(
+            prop_path=f"{prim_path}.omni:kit:cameraLock",
             value=True,
-            prev=None,
+            stage=stage,
             type_to_create_if_not_exist=Sdf.ValueTypeNames.Bool,
-            usd_context_name=stage,
         )
     # decide the custom attributes to add
     if cfg.projection_type == "pinhole":