Add initial documentation for experimental OpenUSD support in MuJoCo.

PiperOrigin-RevId: 789365870 Change-Id: I19cce03ec2ffc28cdf4252bfd02c8b5163bb5ba2
2025-07-31 09:29:38 -07:00
parent 32c7d3f085
commit 700da7c5bd
7 changed files with 349 additions and 0 deletions
@@ -0,0 +1,87 @@
+File Format Plugin
+=========================
+
+What is an SdfFileFormat plugin?
+--------------------------------
+
+In the OpenUSD framework, ``Sdf`` stands for Scene Description Foundations. It's the underlying layer that handles the
+serialization and composition of scene data. A ``SdfFileFormat`` plugin is a component that teaches USD how to read and
+write a specific file format.
+
+By default, USD comes with plugins for its own formats (``.usda``, ``.usdc``, ``.usdz``) and the community has created
+several plugin extension such as the `Adobe File Format Plugins
+<https://github.com/adobe/USD-Fileformat-plugins/tree/main>`__.
+
+The MJCF ``SdfFileFormat`` plugin allows USD-aware applications to directly understand and interact with MuJoCo's native
+``.xml`` (MJCF) files as if they were native USD files.
+
+What does it enable?
+------------------------
+
+This plugin enables:
+
+1.  **Referencing MJCF files in USD:** Using standard USD composition arcs (like references, payloads) to include an
+    MJCF file directly within a larger USD scene. For example, you can place a MuJoCo robot defined in an ``.xml`` file
+    into a room scene modeled in USD.
+2.  **Load MJCF files in USD tools:** Tools like ``usdview`` or other USD-based
+    applications can open, inspect, and render MJCF files, translating the MJCF elements into USD prims and attributes
+    on the fly.
+3.  **Convert MJCF to USD:** The plugin can be used as a basis for converting MJCF files to persistent
+    USD files (e.g., ``.usda`` or ``.usdc``).
+
+Essentially, it makes MJCF a first-class citizen in the USD ecosystem.
+
+Usage
+------------------
+
+1.  **Installation:** refer to :doc:`building`.
+
+2.  **Referencing in a USD file (e.g., ``.usda``):**
+
+    .. code-block:: usd
+        :caption: example.usda
+
+        #usda 1.0
+        (
+            upAxis = "Z"
+        )
+
+        def Xform "world"
+        {
+            def "robot" (
+                prepend references = @./my_robot.xml@
+            )
+            {
+            }
+        }
+
+    In this example, ``my_robot.xml`` is an MJCF file in the same directory. USD will use the plugin to load and
+    interpret its contents.
+
+3.  **Opening in usdview:**
+
+    .. code-block:: bash
+
+       usdview my_robot.xml
+
+    If the plugin is correctly set up, ``usdview`` will render the robot defined in the MJCF file.
+
+4.  **Using in Python (with USD API):**
+
+    .. code-block:: python
+
+        from pxr import Usd
+
+        # Load an MJCF file as a USD stage
+        stage = Usd.Stage.Open('my_robot.xml')
+
+        if stage:
+            print(f"Successfully opened {stage.GetRootLayer().identifier}")
+            # You can now inspect the stage as any other USD stage
+            for prim in stage.TraverseAll():
+                print(prim.GetPath())
+        else:
+            print("Failed to open MJCF file")
+
+    This plugin significantly enhances the interoperability between MuJoCo and USD-based workflows, allowing
+    seamless integration of physics assets defined in MJCF into broader 3D environments.