[Python Viewer] Allow users to override rendering flags via user_scn.

Fixes #1190

PiperOrigin-RevId: 603672602
Change-Id: I3ff1bb0dca7e913b36f1b241aaea8b8bb95cadff

doc/changelog.rst

@@ -41,12 +41,14 @@ Python bindings
     - Uses :ref:`mjSTATE_FULLPHYSICS<geFullPhysics>` as state spec, enabling divergence detection by inspecting time.
     - Allows user-defined control spec for any combination of :ref:`user input<geInput>` fields as controls.
     - Outputs are no longer squeezed and always have dim=3.
+12. The ``sync`` function for the :ref:`passive viewer<PyViewerPassive>` can now pick up changes to rendering flags in
+    ``user_scn``, as requested in :github:issue:`1190`.
 
 Bug fixes
 ^^^^^^^^^
-12. Fixed a bug that prevented the use of pins with plugins if flexes are not in the worldbody. Fixes
+13. Fixed a bug that prevented the use of pins with plugins if flexes are not in the worldbody. Fixes
     :github:issue:`1270`.
-13. Fixed a bug in the :ref:`muscle model<CMuscle>` that led to non-zero values outside the lower
+14. Fixed a bug in the :ref:`muscle model<CMuscle>` that led to non-zero values outside the lower
     bound of the length range. Fixes :github:issue:`1342`.
 
 

doc/python.rst

@@ -124,15 +124,21 @@ attributes:
 - ``is_running()``: returns ``True`` if the viewer window is running and ``False`` if it is closed.
   This method can be safely called without locking.
 
-- ``user_scn``: an :ref:`mjvScene` object that allows users to add custom visualization geoms to the rendered scene.
+- ``user_scn``: an :ref:`mjvScene` object that allows users to add change rendering flags and add custom
-  This is separate from the ``mjvScene`` that the viewer uses internally to render the final scene, and is entirely
+  visualization geoms to the rendered scene. This is separate from the ``mjvScene`` that the viewer uses internally to
-  under the user's control. User scripts can call e.g. :ref:`mjv_initGeom` or :ref:`mjv_makeConnector` to add
+  render the final scene, and is entirely under the user's control. User scripts can call e.g. :ref:`mjv_initGeom` or
-  visualization geoms to ``user_scn``, and upon the next call to ``sync()``, the viewer will incorporate
+  :ref:`mjv_makeConnector` to add visualization geoms to ``user_scn``, and upon the next call to ``sync()``, the viewer
-  these geoms to future rendered images. For example:
+  will incorporate these geoms to future rendered images. Similarly, user scripts can make changes to ``user_scn.flags``
+  which would be picked up at the next call to ``sync()``. The ``sync()`` call also copies changes to rendering flags
+  made via the GUI back into ``user_scn`` to preserve consistency. For example:
 
   .. code-block:: python
 
     with mujoco.viewer.launch_passive(m, d, key_callback=key_callback) as viewer:
+
+      # Enable wireframe rendering of the entire scene.
+      v.user_scn.flags[mujoco.mjtRndFlag.mjRND_WIREFRAME] = 1
+
       while viewer.is_running():
         ...
         # Step the physics.

simulate/simulate.cc

@@ -2091,6 +2091,17 @@ void Simulate::Sync() {
       }
     }
 
+    // pick up rendering flags changed via user_scn
+    if (user_scn) {
+      for (int i = 0; i < mjNRNDFLAG; ++i) {
+        if (user_scn->flags[i] != user_scn_flags_prev_[i]) {
+          scn.flags[i] = user_scn->flags[i];
+        }
+      }
+      Copy(user_scn->flags, scn.flags);
+      Copy(user_scn_flags_prev_, user_scn->flags);
+    }
+
     mjopt_prev_ = scnstate_.model.opt;
     warn_vgeomfull_prev_ = scnstate_.data.warning[mjWARN_VGEOMFULL].number;
   }
@@ -2270,6 +2281,11 @@ void Simulate::LoadOnRenderThread() {
     this->scn.flags[mjRND_REFLECTION] = 0;
   }
 
+  if (this->user_scn) {
+    Copy(this->user_scn->flags, this->scn.flags);
+    Copy(this->user_scn_flags_prev_, this->scn.flags);
+  }
+
   // clear perturbation state
   this->pert.active = 0;
   this->pert.select = 0;

simulate/simulate.h

@@ -130,6 +130,7 @@ class Simulate {
   mjOption mjopt_prev_;
   mjvOption opt_prev_;
   mjvCamera cam_prev_;
+
   int warn_vgeomfull_prev_;
 
   // pending GUI-driven actions, to be applied at the next call to Sync
@@ -247,6 +248,7 @@ class Simulate {
 
   // additional user-defined visualization geoms (used in passive mode)
   mjvScene* user_scn = nullptr;
+  mjtByte user_scn_flags_prev_[mjNRNDFLAG];
 
   // OpenGL rendering and UI
   int refresh_rate = 60;