Adds methods to define physics-based schemas on prims (#120)

# Description

This is a follow-up to PR #110. It adds additional methods that allow
defining i.e. creating the schemas at the specified prim path. This is
useful when creating your own meshes or prims procedurally. The methods
also check if there are any conflicting schemas on the prim to which we
want to apply a new schema. This makes sure that schemas are defined on
a prim gracefully.

## Type of change

- New feature (non-breaking change which adds functionality)
- This change requires a documentation update

## Checklist

- [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with
`./orbit.sh --format`
- [x] 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
- [x] I have updated the changelog and the corresponding version in the
extension's `config/extension.toml` file

source/extensions/omni.isaac.orbit/config/extension.toml

 [package]
 
 # Note: Semantic Versioning is used: https://semver.org/
-version = "0.8.9"
+version = "0.8.10"
 
 # Description
 title = "ORBIT framework for Robot Learning"

source/extensions/omni.isaac.orbit/docs/CHANGELOG.rst

 Changelog
 ---------
 
+0.8.10 (2023-08-17)
+~~~~~~~~~~~~~~~~~~
+
+Added
+^^^^^
+
+* Added methods for defining different physics-based schemas in the :mod:`omni.isaac.orbit.sim.schemas` module.
+  These methods allow creating the schema if it doesn't exist at the specified prim path and modify
+  its properties based on the configuration object.
+
+
 0.8.9 (2023-08-09)
 ~~~~~~~~~~~~~~~~~~
 

source/extensions/omni.isaac.orbit/omni/isaac/orbit/sim/schemas/__init__.py

@@ -34,10 +34,14 @@ Locally, the schemas are defined in the following files:
 """
 
 from .schemas import (
-    set_articulation_root_properties,
-    set_collision_properties,
-    set_mass_properties,
-    set_rigid_body_properties,
+    define_articulation_root_properties,
+    define_collision_properties,
+    define_mass_properties,
+    define_rigid_body_properties,
+    modify_articulation_root_properties,
+    modify_collision_properties,
+    modify_mass_properties,
+    modify_rigid_body_properties,
 )
 from .schemas_cfg import (
     ArticulationRootPropertiesCfg,
@@ -49,14 +53,18 @@ from .schemas_cfg import (
 __all__ = [
     # articulation root
     "ArticulationRootPropertiesCfg",
-    "set_articulation_root_properties",
+    "define_articulation_root_properties",
+    "modify_articulation_root_properties",
     # rigid bodies
     "RigidBodyPropertiesCfg",
-    "set_rigid_body_properties",
+    "define_rigid_body_properties",
+    "modify_rigid_body_properties",
     # colliders
     "CollisionPropertiesCfg",
-    "set_collision_properties",
+    "define_collision_properties",
+    "modify_collision_properties",
     # mass
     "MassPropertiesCfg",
-    "set_mass_properties",
+    "define_mass_properties",
+    "modify_mass_properties",
 ]

source/extensions/omni.isaac.orbit/omni/isaac/orbit/sim/utils.py

@@ -3,11 +3,13 @@
 #
 # SPDX-License-Identifier: BSD-3-Clause
 
+from __future__ import annotations
+
 import functools
 from typing import Any, Callable
 
 import carb
-import omni.isaac.core.utils.prims as prim_utils
+import omni.isaac.core.utils.stage as stage_utils
 import omni.kit.commands
 from pxr import Sdf, Usd
 
@@ -110,16 +112,20 @@ def apply_nested(func: Callable) -> Callable:
 
     Args:
         func (Callable): The function to apply to all prims under a specified prim-path. The function
-            must take the prim-path as the first argument and the configuration as the second argument.
+            must take the prim-path, the configuration object and the stage as inputs. It should return
+            a boolean indicating whether the function succeeded or not.
 
     Returns:
         Callable: The wrapped function that applies the function to all prims under a specified prim-path.
     """
 
     @functools.wraps(func)
-    def wrapper(prim_path: str, cfg: object):
+    def wrapper(prim_path: str, cfg: object, stage: Usd.Stage | None = None):
+        # get current stage
+        if stage is None:
+            stage = stage_utils.get_current_stage()
         # get USD prim
-        prim = prim_utils.get_prim_at_path(prim_path)
+        prim: Usd.Prim = stage.GetPrimAtPath(prim_path)
         # check if prim is valid
         if not prim.IsValid():
             raise ValueError(f"Prim at path '{prim_path}' is not valid.")
@@ -128,7 +134,7 @@ def apply_nested(func: Callable) -> Callable:
         while len(all_prims) > 0:
             # get current prim
             child_prim = all_prims.pop(0)
-            child_prim_path = prim_utils.get_prim_path(child_prim)
+            child_prim_path = child_prim.GetPath().pathString
             # check if prim is a prototype
             # note: we prefer throwing a warning instead of ignoring the prim since the user may
             #   have intended to set properties on the prototype prim.
@@ -136,7 +142,7 @@ def apply_nested(func: Callable) -> Callable:
                 carb.log_warn(f"Cannot perform '{func.__name__}' on instanced prim: '{child_prim_path}'")
                 continue
             # set properties
-            success = func(child_prim_path, cfg)
+            success = func(child_prim_path, cfg, stage=stage)
             # if successful, do not look at children
             # this is based on the physics behavior that nested schemas are not allowed
             if not success: