Merge remote-tracking branch 'upstream/main' into feature/contact-force-filter-link-idx

Author: jsw7460

.github/workflows/examples.yml

@@ -50,7 +50,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip setuptools wheel
           pip install torch --index-url https://download.pytorch.org/whl/cpu
-          pip install '.[dev,usd]'
+          pip install '.[dev,render,usd]'
 
       - name: Get Quadrants version
         id: quadrants_version

.github/workflows/generic.yml

@@ -135,7 +135,7 @@ jobs:
       - name: Install Genesis
         shell: bash
         run: |
-          PYTHON_DEPS="dev"
+          PYTHON_DEPS="dev,render"
           # Install USD for all platforms except ARM (usd-core doesn't support ARM)
           # This is required for test_mesh.py which tests USD parsing functionality
           if [[ "${{ matrix.OS }}" != 'ubuntu-24.04-arm' ]] ; then

.github/workflows/scripts/production_build.sh

@@ -14,3 +14,7 @@ uv pip install torch --index-url https://download.pytorch.org/whl/cu129
 uv pip install --upgrade pip setuptools wheel
 uv pip install omniverse-kit --index-url https://pypi.nvidia.com/
 uv pip install ".[dev,render,usd]" "pyuipc==0.0.7"
+# imgui-bundle has no pre-built wheel for Python 3.10 (which this runner uses) so it is excluded from the
+# ``[render]`` extras marker. Install it manually. Disable MicroTeX since we don't use it and its submodule
+# is missing from the 1.92.x source distribution.
+SKBUILD_CMAKE_DEFINE="IMGUI_BUNDLE_WITH_MICROTEX=OFF" uv pip install imgui-bundle

examples/gui/imgui_joint_control.py

@@ -0,0 +1,71 @@
+"""Interactive joint control example using ImGui overlay.
+
+Demonstrates:
+- Simulation controls (play/pause/step/reset)
+- Entity browser with joint sliders
+- Visualization toggles
+- Camera controls
+- Custom user panels via register_panel()
+- Scene rebuild (add entities, change scale)
+"""
+
+import os
+import time
+
+import genesis as gs
+from genesis.engine.interactive_scene import InteractiveScene
+from genesis.ext.pyrender.overlay import ImGuiOverlayPlugin
+
+gs.init()
+
+interactive = InteractiveScene()
+interactive.rebuild(
+    scene_kwargs=dict(
+        viewer_options=gs.options.ViewerOptions(
+            camera_pos=(2.0, 2.0, 1.5),
+            camera_lookat=(0.0, 0.0, 0.5),
+        ),
+        show_viewer=True,
+    ),
+    entities_kwargs={
+        "Plane": dict(
+            morph=gs.morphs.Plane(),
+        ),
+        "Panda": dict(
+            morph=gs.morphs.MJCF(
+                file="xml/franka_emika_panda/panda.xml",
+            ),
+        ),
+        "Box": dict(
+            morph=gs.morphs.Box(
+                pos=(0, 0, 1.0),
+                size=(0.2, 0.2, 0.2),
+            ),
+        ),
+    },
+)
+
+plugin = ImGuiOverlayPlugin()
+interactive.viewer.add_plugin(plugin)
+
+
+def custom_panel(imgui):
+    imgui.text("Custom Demo Panel")
+    imgui.text("This panel was registered via register_panel()")
+
+
+plugin.register_panel(custom_panel)
+
+is_test = "PYTEST_VERSION" in os.environ
+horizon = 5 if is_test else None
+
+frame = 0
+while interactive.viewer.is_alive():
+    if plugin.rebuild_requested:
+        interactive.rebuild(entities_kwargs=plugin.pending_entities_kwargs)
+    if plugin.should_step():
+        interactive.scene.step()
+    frame += 1
+    if horizon is not None and frame >= horizon:
+        break
+    time.sleep(0.01)

examples/viewer_plugin/mouse_interaction.py

@@ -10,9 +10,10 @@
     parser.add_argument(
         "--use_force", "-f", action="store_true", help="Apply spring forces instead of setting position"
     )
+    parser.add_argument("--num_envs", "-b", type=int, default=1, help="Number of environments to create")
     args = parser.parse_args()
 
-    gs.init(backend=gs.gpu)
+    gs.init(backend=gs.cpu)
 
     scene = gs.Scene(
         viewer_options=gs.options.ViewerOptions(
@@ -51,7 +52,7 @@
         )
     )
 
-    scene.build()
+    scene.build(n_envs=args.num_envs)
 
     is_running = True
 

genesis/__init__.py

@@ -255,6 +255,21 @@ def init(
             random_seed=seed,
         )
 
+    # On Metal, share PyTorch MPS's command queue with Quadrants so that GPU-side ordering is automatic and the
+    # per-interop-point sync overhead (qd.sync / torch.mps.synchronize) is eliminated.
+    if backend == _gs_backend.metal and device.type == "mps":
+        mps_queue = qd.interop.get_mps_command_queue()
+        if not mps_queue:
+            raise_exception(
+                "Failed to extract PyTorch MPS's Metal command queue. This is required on Apple Metal for correct "
+                "GPU synchronisation between Genesis and PyTorch. Please ensure you are using a supported PyTorch "
+                "version (>= 2.0)."
+            )
+        qd_init_kwargs.update(
+            external_metal_command_queue=mps_queue,
+            external_metal_command_queue_is_torch_queue=True,
+        )
+
     # init quadrants
     qd_debug = debug and (os.environ.get("QD_DEBUG") != "0")
     with redirect_stdout(_qd_outputs):

genesis/_main.py

@@ -338,6 +338,57 @@ def view(filename, collision, rotate, scale=1.0, show_link_frame=False):
         gui_process.join()
 
 
+def play(filename=None, collision=False, scale=1.0):
+    import time
+
+    gs.init()
+
+    scene = gs.Scene(
+        viewer_options=gs.options.ViewerOptions(
+            camera_pos=(2.0, 2.0, 1.5),
+            camera_lookat=(0.0, 0.0, 0.5),
+        ),
+        show_viewer=True,
+    )
+
+    if filename is None:
+        scene.add_entity(gs.morphs.Plane())
+        scene.add_entity(gs.morphs.MJCF(file="xml/franka_emika_panda/panda.xml"))
+    else:
+        filename_lower = filename.lower()
+        morphs = gs.options.morphs
+        surface = gs.surfaces.Default(vis_mode="visual" if not collision else "collision")
+
+        if filename_lower.endswith(morphs.USD_FORMATS):
+            scene.add_stage(
+                morph=gs.morphs.USD(file=filename, collision=collision, scale=scale),
+                vis_mode=surface.vis_mode,
+            )
+        elif filename_lower.endswith(morphs.URDF_FORMAT):
+            scene.add_entity(gs.morphs.URDF(file=filename, collision=collision, scale=scale), surface=surface)
+        elif filename_lower.endswith(morphs.MJCF_FORMAT):
+            scene.add_entity(gs.morphs.MJCF(file=filename, collision=collision, scale=scale), surface=surface)
+        elif filename_lower.endswith(morphs.MESH_FORMATS):
+            scene.add_entity(gs.morphs.Mesh(file=filename, collision=collision, scale=scale), surface=surface)
+        else:
+            gs.raise_exception(
+                f"Unsupported file format for 'gs play'. Expected {morphs.URDF_FORMAT}, "
+                f"{morphs.MJCF_FORMAT}, {morphs.MESH_FORMATS}, or {morphs.USD_FORMATS}."
+            )
+
+    scene.build()
+
+    from genesis.ext.pyrender.overlay import ImGuiOverlayPlugin
+
+    plugin = ImGuiOverlayPlugin()
+    scene.viewer.add_plugin(plugin)
+
+    while scene.viewer.is_alive():
+        if plugin.should_step():
+            scene.step()
+        time.sleep(0.01)
+
+
 def animate(filename_pattern, fps):
     import glob
 
@@ -365,6 +416,19 @@ def main():
     parser_view.add_argument("-s", "--scale", type=float, default=1.0, help="Scale of the entity")
     parser_view.add_argument("-l", "--link_frame", action="store_true", default=False, help="Show link frame")
 
+    parser_play = subparsers.add_parser("play", help="Interactive viewer with ImGui joint controls and simulation")
+    parser_play.add_argument(
+        "filename",
+        type=str,
+        nargs="?",
+        default=None,
+        help="Optional asset file (URDF/MJCF/Mesh/USD). Defaults to a demo scene.",
+    )
+    parser_play.add_argument(
+        "-c", "--collision", action="store_true", default=False, help="Visualize collision geometry"
+    )
+    parser_play.add_argument("-s", "--scale", type=float, default=1.0, help="Scale of the entity")
+
     parser_animate = subparsers.add_parser("animate", help="Compile a list of image files into a video")
     parser_animate.add_argument("filename_pattern", type=str, help="Image files, via glob pattern")
     parser_animate.add_argument("--fps", type=int, default=30, help="FPS of the output video")
@@ -373,6 +437,8 @@ def main():
 
     if args.command == "view":
         view(args.filename, args.collision, args.rotate, args.scale, args.link_frame)
+    elif args.command == "play":
+        play(args.filename, args.collision, args.scale)
     elif args.command == "animate":
         animate(args.filename_pattern, args.fps)
     elif args.command is None: