Merge pull request #161 from gbionics/copilot/update-usd-section-clarity

docs: Improve usd documentation

Author: Giulero

README.md

@@ -304,41 +304,46 @@ J = kinDyn.jacobian('frame_name', w_H_b, joints)
 
 ### OpenUSD
 
-adam supports both exporting a model to OpenUSD and loading it back for computations.
+adam supports loading robot models directly from OpenUSD files and exporting models to OpenUSD.
+
+**Loading directly from a USD file:**
 
 ```python
 import numpy as np
 from adam import Representations
-from adam.model import Model, build_model_factory
 from adam.numpy import KinDynComputations
-from adam.numpy.numpy_like import SpatialMath
-
-# You can convert a URDF to a USD
-model_path = "robot.urdf"
-joints_name_list = ["joint_1", "joint_2"]
 
-factory = build_model_factory(description=model_path, math=SpatialMath())
-model = Model.build(factory=factory, joints_name_list=joints_name_list)
-
-# Export robot articulation to USD (use .usda for text, .usdc for binary)
-usd_path = "robot.usda"
-model.to_usd(usd_path, robot_prim_path="/Robot")
-
-# If you have an existing USD file, start from this to create a KinDynComputations instance
+# Load directly from any existing USD file
 kinDyn = KinDynComputations.from_usd(
-    usd_path,
+    "robot.usd",
     robot_prim_path="/Robot",
-    joints_name_list=joints_name_list,
+    joints_name_list=["joint_1", "joint_2"],
 )
 kinDyn.set_frame_velocity_representation(Representations.MIXED_REPRESENTATION)
 
 # Compute quantities as usual
 w_H_b = np.eye(4)
-q = np.zeros(len(joints_name_list))
+q = np.zeros(kinDyn.NDoF)
 M = kinDyn.mass_matrix(w_H_b, q)
 com = kinDyn.CoM_position(w_H_b, q)
 ```
 
+**Exporting a model to USD** (e.g. to convert a URDF to USD):
+
+```python
+from adam.model import Model, build_model_factory
+from adam.numpy.numpy_like import SpatialMath
+
+model_path = "robot.urdf"
+joints_name_list = ["joint_1", "joint_2"]
+
+factory = build_model_factory(description=model_path, math=SpatialMath())
+model = Model.build(factory=factory, joints_name_list=joints_name_list)
+
+# Export to USD
+model.to_usd("robot.usd", robot_prim_path="/Robot")
+```
+
 ### Visualization
 
 adam also provides a lightweight visualization layer based on [viser](https://viser.studio/).
@@ -349,7 +354,7 @@ For quick inspection from the terminal, use the bundled viewer command:
 ```bash
 adam-model-view --urdf path/to/robot.urdf
 adam-model-view --mujoco path/to/model.xml
-adam-model-view --usd path/to/robot.usda --robot-prim-path /Robot
+adam-model-view --usd path/to/robot.usd --robot-prim-path /Robot
 ```
 
 ```python
@@ -385,7 +390,7 @@ With other model sources, only the loader changes:
 kindyn = KinDynComputations.from_mujoco_model(mj_model)
 
 # USD
-kindyn = KinDynComputations.from_usd("robot.usda", robot_prim_path="/Robot")
+kindyn = KinDynComputations.from_usd("robot.usd", robot_prim_path="/Robot")
 ```
 
 Batched visualization is available through the same `ModelHandle` API by passing

docs/guides/usd.rst

@@ -29,7 +29,7 @@ Use ``from_usd()`` with a USD path:
     from adam import Representations
     from adam.numpy import KinDynComputations
 
-    usd_path = "robot.usda"
+    usd_path = "robot.usd"
     joints_name_list = ["joint_1", "joint_2"]
 
     kinDyn = KinDynComputations.from_usd(
@@ -50,7 +50,7 @@ Use ``from_usd_stage()`` with an in-memory ``pxr.Usd.Stage``:
     from pxr import Usd
     from adam.numpy import KinDynComputations
 
-    stage = Usd.Stage.Open("robot.usda")
+    stage = Usd.Stage.Open("robot.usd")
     kinDyn = KinDynComputations.from_usd_stage(
         stage,
         robot_prim_path="/Robot",
@@ -73,7 +73,7 @@ Build an adam model and export with ``model.to_usd()``:
     factory = build_model_factory(description=urdf_path, math=SpatialMath())
     model = Model.build(factory=factory, joints_name_list=joints_name_list)
 
-    model.to_usd("robot.usda", robot_prim_path="/Robot")
+    model.to_usd("robot.usd", robot_prim_path="/Robot")
 
 Conversion API
 --------------
@@ -84,7 +84,7 @@ You can also use the functional converter API:
 
     from adam.model.conversions import model_to_usd
 
-    model_to_usd(model, "robot.usda", robot_prim_path="/Robot")
+    model_to_usd(model, "robot.usd", robot_prim_path="/Robot")
 
 
 
@@ -100,7 +100,7 @@ USD loading is available through all backend frontends:
     from adam.casadi import KinDynComputations as CasadiKinDynComputations
     from adam.pytorch import KinDynComputations as TorchKinDynComputations
 
-    kinDyn = NumpyKinDynComputations.from_usd("robot.usda", robot_prim_path="/Robot", joints_name_list=["joint_1", "joint_2"])
+    kinDyn = NumpyKinDynComputations.from_usd("robot.usd", robot_prim_path="/Robot", joints_name_list=["joint_1", "joint_2"])
 
 See Also
 --------

docs/guides/visualization.rst

@@ -62,7 +62,7 @@ If you just want to inspect a model quickly, use the bundled ``adam-model-view``
 
     adam-model-view --urdf path/to/robot.urdf
     adam-model-view --mujoco path/to/model.xml
-    adam-model-view --usd path/to/robot.usda --robot-prim-path /Robot
+    adam-model-view --usd path/to/robot.usd --robot-prim-path /Robot
 
 The viewer loads the requested model, starts a viser server, adds a default ground plane,
 and exposes one joint-slider panel per robot when the model has actuated joints.

docs/quickstart/casadi.rst

@@ -222,7 +222,7 @@ Load models from OpenUSD for symbolic workflows:
     from adam.casadi import KinDynComputations
 
     kinDyn = KinDynComputations.from_usd(
-        "robot.usda",
+        "robot.usd",
         robot_prim_path="/Robot",
         joints_name_list=["joint_1", "joint_2"],
     )

docs/quickstart/jax.rst

@@ -241,7 +241,7 @@ Load models from OpenUSD and use them with JAX transformations:
     from adam.jax import KinDynComputations
 
     kinDyn = KinDynComputations.from_usd(
-        "robot.usda",
+        "robot.usd",
         robot_prim_path="/Robot",
         joints_name_list=["joint_1", "joint_2"],
     )

docs/quickstart/numpy.rst

@@ -111,7 +111,7 @@ You can also load models from OpenUSD:
     from adam.numpy import KinDynComputations
 
     kinDyn = KinDynComputations.from_usd(
-        "robot.usda",
+        "robot.usd",
         robot_prim_path="/Robot",
         joints_name_list=["joint_1", "joint_2"],
     )

docs/quickstart/pytorch.rst

@@ -323,7 +323,7 @@ Load models from OpenUSD and use them with autograd:
     from adam.pytorch import KinDynComputations
 
     kinDyn = KinDynComputations.from_usd(
-        "robot.usda",
+        "robot.usd",
         robot_prim_path="/Robot",
         joints_name_list=["joint_1", "joint_2"],
     )

examples/visualization/visualize_usd.py

@@ -4,7 +4,7 @@
 Usage
 -----
     PYTHONPATH=src python3 examples/visualization/visualize_usd.py
-    PYTHONPATH=src python3 examples/visualization/visualize_usd.py --usd-path /path/to/robot.usda
+    PYTHONPATH=src python3 examples/visualization/visualize_usd.py --usd-path /path/to/robot.usd
 
 Dependencies
 ------------