[FEATURE] Add ImGui overlay for interactive joint control and visualization

examples/gui/imgui_joint_control.py

@@ -0,0 +1,89 @@
+"""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 numpy as np
+
+import genesis as gs
+from genesis.ext.pyrender.imgui_overlay import ImGuiOverlayPlugin
+
+gs.init()
+
+# Store scene options for 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,
+)
+
+scene = gs.Scene(**scene_kwargs)
+scene.add_entity(gs.morphs.Plane())
+scene.add_entity(gs.morphs.MJCF(file="xml/franka_emika_panda/panda.xml"))
+scene.add_entity(gs.morphs.Box(pos=(0, 0, 1.0), size=(0.2, 0.2, 0.2)))
+scene.build()
+
+
+def rebuild_scene(plugin):
+    """Rebuild scene from plugin's entity_specs."""
+    global scene
+    specs = plugin.entity_specs
+
+    # Save camera state
+    cam_pos = scene.viewer.camera_pos.copy()
+    cam_lookat = np.array(scene.viewer._pyrender_viewer._trackball._n_target).copy()
+
+    scene.destroy()
+
+    scene = gs.Scene(**scene_kwargs)
+    for spec in specs:
+        scene.add_entity(
+            spec["morph"],
+            material=spec["material"],
+            surface=spec["surface"],
+            visualize_contact=spec["visualize_contact"],
+        )
+    scene.build()
+
+    # Re-register plugin on new viewer
+    scene.viewer._pyrender_viewer.register_plugin(plugin)
+
+    # Restore camera
+    scene.viewer.set_camera_pose(pos=cam_pos, lookat=cam_lookat)
+
+
+plugin = ImGuiOverlayPlugin(rebuild_fn=rebuild_scene)
+scene.viewer._pyrender_viewer.register_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 scene.viewer.is_alive():
+    if plugin.rebuild_requested:
+        rebuild_scene(plugin)
+    if plugin.should_step():
+        scene.step()
+    frame += 1
+    if horizon is not None and frame >= horizon:
+        break
+    time.sleep(0.01)

genesis/_main.py

@@ -337,6 +337,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.imgui_overlay import ImGuiOverlayPlugin
+
+    plugin = ImGuiOverlayPlugin()
+    scene.viewer._pyrender_viewer.register_plugin(plugin)
+
+    while scene.viewer.is_alive():
+        if plugin.should_step():
+            scene.step()
+        time.sleep(0.01)
+
+
 def animate(filename_pattern, fps):
     import glob
 
@@ -364,6 +415,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")
@@ -372,6 +436,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: