Add keyboard event callback for Python passive viewer.

Fixes #766
Fixes #846

PiperOrigin-RevId: 549449372
Change-Id: I37d17f1162c66d0e8482d402aae22d9a16b59deb

doc/changelog.rst

@@ -30,6 +30,8 @@ Python bindings
   ``update_texture`` methods to allow users to update renderable assets.
   (`#812 <https://github.com/deepmind/mujoco/issues/812>`_, `#958 <https://github.com/deepmind/mujoco/issues/958>`_,
   `#965 <https://github.com/deepmind/mujoco/issues/965>`_)
+- Allow a custom keyboard event callback to be specified in the :ref:`passive viewer<PyViewerPassive>`.
+  (`#766 <https://github.com/deepmind/mujoco/issues/766>`_)
 - Fix GLFW crash when Python exits while the passive viewer is running.
   (`#790 <https://github.com/deepmind/mujoco/issues/790>`_)
 

doc/python.rst

@@ -160,6 +160,29 @@ illustrative example that does **not** necessarily keep the physics ticking at t
       if time_until_next_step > 0:
         time.sleep(time_until_next_step)
 
+Optionally, ``viewer.launch_passive`` also accepts a callable as a keyword argument ``key_callback``, which gets called
+each time a keyboard event occurs in the viewer window. This allows user scripts to react to various key presses, e.g.
+pause or resume the run loop when the spacebar is pressed.
+
+.. code-block:: python
+
+  paused = False
+
+  def key_callback(keycode):
+    if chr(keycode) == ' ':
+      global paused
+      paused = not paused
+
+  ...
+
+  with mujoco.viewer.launch_passive(m, d, key_callback=key_callback) as viewer:
+    while viewer.is_running():
+      ...
+      if not paused:
+        mujoco.mj_step(m, d)
+        viewer.sync()
+      ...
+
 
 .. _PyUsage: