[PyrenderViewer] Add v option to switch visual mesh and collision mesh (#579)

Author: iory

docs/source/_static/visual-collision-comparison.jpg

@@ -62,22 +62,156 @@ PyrenderViewer
 --------------
 
 **Description:**
-  The ``PyrenderViewer`` utilizes the Pyrender library for advanced 3D rendering, ideal for creating realistic visual simulations. This viewer is particularly suited for complex rendering tasks in robotics, including detailed lighting and shading effects.
+  The ``PyrenderViewer`` utilizes the Pyrender library for advanced 3D rendering, ideal for creating realistic visual simulations. This viewer is implemented as a Singleton to ensure only one instance exists throughout the program. It's particularly suited for complex rendering tasks in robotics, including detailed lighting, shading effects, and collision visualization.
 
 **Key Functionalities:**
 
 - **Initialization and Configuration:**
-  The viewer is initialized with specified resolution and rendering flags, creating a scene managed by Pyrender. It supports high-quality rendering features like raymond lighting.
+  The viewer is initialized with specified resolution, update interval, and rendering flags. Key parameters include:
+
+  - ``resolution``: Window size (default: ``(640, 480)``)
+  - ``update_interval``: Update frequency in seconds (default: ``1.0``)
+  - ``enable_collision_toggle``: Enable collision/visual mesh switching (default: ``True``)
+  - ``title``: Window title (default: ``'scikit-robot PyrenderViewer'``)
 
 - **Rendering Control:**
-  Handles real-time scene updates triggered by user interactions such as mouse events and keyboard inputs, ensuring the scene remains interactive and up-to-date.
+  Handles real-time scene updates triggered by user interactions. The viewer automatically manages OpenGL compatibility with fallback support from OpenGL 4.1 → 4.0 → 3.3, ensuring robust operation across different systems including WSL2.
 
 - **Scene Management:**
-  Similar to ``TrimeshSceneViewer``, it allows for the addition and removal of visual meshes linked to robotic models, supporting dynamic updates to the scene as robotic configurations change.
+  Supports dynamic addition and removal of visual and collision meshes linked to robotic models. The viewer maintains real-time synchronization with robot configurations through the ``redraw()`` method.
 
 - **Camera Management:**
-  Offers detailed camera setup options, including angle adjustments, distance settings, center positioning, and field of view configuration, providing flexibility in viewing angles for complex scenes.
+  Offers detailed camera setup options through the ``set_camera()`` method:
+
+  - Angle-based positioning with Euler angles
+  - Distance and center point configuration
+  - Field of view (FOV) adjustment
+  - Direct Coordinates object support for precise camera placement
+
+- **Collision/Visual Mesh Toggle:**
+  When ``enable_collision_toggle=True``, press the ``v`` key to switch between:
+
+  - **Visual meshes**: Default appearance meshes for rendering (left in figure below)
+  - **Collision meshes**: Simplified meshes used for collision detection (displayed in orange/transparent, right in figure below)
+
+  .. figure:: ../_static/visual-collision-comparison.jpg
+     :width: 100%
+     :align: center
+     :alt: Visual mesh (left) vs Collision mesh (right) comparison
+
+     **Visual mesh (left) vs Collision mesh (right).** The visual mesh shows the detailed appearance of the robot with textured wheels. The collision mesh on the right uses simplified cylinder representations for the wheels, which are computationally more efficient for collision detection algorithms.
+
+- **360-Degree Image Capture:**
+  The ``capture_360_images()`` method enables automated scene capture from multiple angles:
+
+  - Configurable number of frames and camera elevation
+  - Automatic GIF animation generation
+  - Transparent background support
+  - Custom lighting configuration options
+
+
+**Keyboard Controls:**
+
+The PyrenderViewer provides extensive keyboard controls for interactive manipulation:
+
+.. list-table:: Keyboard Controls
+   :header-rows: 1
+   :widths: 10 90
+
+   * - Key
+     - Function
+   * - ``a``
+     - Toggle rotational animation mode
+   * - ``c``
+     - Toggle backface culling
+   * - ``f``
+     - Toggle fullscreen mode
+   * - ``h``
+     - Toggle shadow rendering (may impact performance)
+   * - ``i``
+     - Cycle through axis display modes (none → world → mesh → all)
+   * - ``l``
+     - Cycle lighting modes (scene → Raymond → direct)
+   * - ``m``
+     - Toggle face normal visualization
+   * - ``n``
+     - Toggle vertex normal visualization
+   * - ``o``
+     - Toggle orthographic camera mode
+   * - ``q``
+     - Quit the viewer
+   * - ``r``
+     - Start/stop GIF recording (opens file dialog on stop)
+   * - ``s``
+     - Save current view as image (opens file dialog)
+   * - ``v``
+     - **Toggle between visual and collision meshes** (if enabled)
+   * - ``w``
+     - Cycle wireframe modes
+   * - ``z``
+     - Reset camera to default view
+
+**Mouse Controls:**
+
+- **Left-click + drag**: Rotate camera around scene center
+- **Ctrl + Left-click + drag**: Rotate camera around viewing axis
+- **Shift + Left-click + drag** or **Middle-click + drag**: Pan camera
+- **Right-click + drag** or **Scroll wheel**: Zoom in/out
+
+**Example Usage:**
+
+Basic viewer initialization and robot display:
+
+.. code-block:: python
+
+    from skrobot.viewers import PyrenderViewer
+    from skrobot.models import PR2
+
+    # Create viewer instance (Singleton pattern ensures only one instance)
+    viewer = PyrenderViewer(resolution=(800, 600), update_interval=1.0/30)
+    
+    # Load and add robot model
+    robot = PR2()
+    viewer.add(robot)
+    
+    # Show the viewer window
+    viewer.show()
+    
+    # Update robot pose and redraw
+    robot.reset_manip_pose()
+    viewer.redraw()
+
+Collision/Visual mesh toggle example:
+
+.. code-block:: python
+
+    # Enable collision toggle functionality
+    viewer = PyrenderViewer(enable_collision_toggle=True)
+    
+    # Add robot to viewer
+    viewer.add(robot)
+    viewer.show()
+    
+    # Press 'v' key in the viewer to toggle between visual and collision meshes
+    # Collision meshes will appear in orange/transparent color
+    
+    # The visual mesh displays the full detailed geometry with textures
+    # while collision mesh shows simplified shapes (e.g., cylinders for wheels)
+    # optimized for physics calculations
+
+360-degree image capture example:
+
+.. code-block:: python
 
+    # Capture 360-degree rotation images
+    viewer.capture_360_images(
+        output_dir="./robot_360",
+        num_frames=36,  # One image every 10 degrees
+        camera_elevation=45,  # Camera elevation angle
+        create_gif=True,  # Generate animated GIF
+        gif_duration=100,  # 100ms between frames
+        transparent_background=True  # Render with transparent background
+    )
 
 .. caution::
 
@@ -88,6 +222,7 @@ PyrenderViewer
   .. code-block:: python
 
     viewer = skrobot.viewers.TrimeshSceneViewer(resolution=(640, 480), update_interval=1.0/30)   # Set update interval for 30 Hz
+    viewer = skrobot.viewers.PyrenderViewer(resolution=(640, 480), update_interval=1.0/30)      # Same for PyrenderViewer
 
 
 Color Management

docs/source/reference/viewers.rst

@@ -76,18 +76,26 @@ class PyrenderViewer(pyrender.Viewer):
         1.0 seconds.
     title : str, optional
         The title of the viewer window. Default is 'scikit-robot PyrenderViewer'.
+    enable_collision_toggle : bool, optional
+        Enable collision/visual mesh toggle functionality with 'v' key.
+        Default is True.
 
     Notes
     -----
     Since this is a singleton, the __init__ method might be called
     multiple times, but only one instance is actually used.
+
+    Keyboard Controls
+    -----------------
+    v : Toggle between visual and collision meshes (if enable_collision_toggle=True)
+        Collision meshes are displayed in orange/transparent color
     """
 
     # Class variable to hold the single instance of the class.
     _instance = None
 
     def __init__(self, resolution=None, update_interval=1.0,
-                 render_flags=None, title=None):
+                 render_flags=None, title=None, enable_collision_toggle=True):
         if getattr(self, '_initialized', False):
             return
         if resolution is None:
@@ -96,6 +104,12 @@ def __init__(self, resolution=None, update_interval=1.0,
         self.thread = None
         self._visual_mesh_map = collections.OrderedDict()
 
+        # Collision toggle functionality
+        self.enable_collision_toggle = enable_collision_toggle
+        if self.enable_collision_toggle:
+            self._stored_links = []
+            self.show_collision = False
+
         self._redraw = True
 
         refresh_rate = 1.0 / update_interval
@@ -228,9 +242,26 @@ def on_mouse_scroll(self, *args, **kwargs):
         self._redraw = True
         return super(PyrenderViewer, self).on_mouse_scroll(*args, **kwargs)
 
-    def on_key_press(self, *args, **kwargs):
+    def on_key_press(self, symbol, modifiers, *args, **kwargs):
+        """Handle key press events with collision toggle support."""
+        # Handle 'v' key for collision toggle if enabled
+        if self.enable_collision_toggle:
+            from pyglet.window import key
+            if symbol == key.V:
+                # Toggle display mode
+                self.show_collision = not self.show_collision
+
+                # Rebuild scene with current mesh type
+                self._rebuild_scene_for_toggle()
+
+                mode_text = "Collision" if self.show_collision else "Visual"
+                print(f"Switched to {mode_text.lower()} mesh display")
+
+                self._redraw = True
+                return True
+
         self._redraw = True
-        return super(PyrenderViewer, self).on_key_press(*args, **kwargs)
+        return super(PyrenderViewer, self).on_key_press(symbol, modifiers, *args, **kwargs)
 
     def on_resize(self, *args, **kwargs):
         self._redraw = True
@@ -283,6 +314,12 @@ def add(self, geometry):
         else:
             raise TypeError('geometry must be Link or CascadedLink')
 
+        # Store links for collision toggle if enabled
+        if self.enable_collision_toggle:
+            for link in links:
+                if link not in self._stored_links:
+                    self._stored_links.append(link)
+
         for link in links:
             self._add_link(link)
 
@@ -568,3 +605,78 @@ def _calculate_camera_distance(self, distance_margin=1.2):
         bounds = self.scene.bounds
         bbox_diagonal = np.linalg.norm(bounds[1] - bounds[0])
         return bbox_diagonal * distance_margin
+
+    def _rebuild_scene_for_toggle(self):
+        """Completely rebuild the scene with current mesh type for toggle functionality."""
+        if not self.enable_collision_toggle:
+            return
+
+        with self._render_lock:
+            # Clear all mesh nodes but preserve camera and lights
+            mesh_nodes_to_remove = []
+
+            for node in list(self.scene.nodes):
+                if node.camera is None and node.light is None and node.mesh is not None:
+                    mesh_nodes_to_remove.append(node)
+
+            # Remove mesh nodes
+            for node in mesh_nodes_to_remove:
+                self.scene.remove_node(node)
+
+            # Clear visual mesh map
+            self._visual_mesh_map.clear()
+
+            # Add meshes for current mode
+            for link in self._stored_links:
+                self._add_single_link_mesh_for_toggle(link)
+
+    def _add_single_link_mesh_for_toggle(self, link):
+        """Add a single mesh (visual or collision) for a link during toggle."""
+        if not isinstance(link, model_module.Link):
+            return
+
+        link_id = str(id(link))
+        transform = link.worldcoords().T()
+
+        # Choose mesh based on current mode
+        if self.show_collision:
+            mesh = link.collision_mesh
+            # Process collision mesh with orange coloring
+            if mesh is not None:
+                if isinstance(mesh, list):
+                    colored_meshes = []
+                    for m in mesh:
+                        colored_mesh = m.copy()
+                        colored_mesh.visual.face_colors = [255, 150, 100, 200]
+                        colored_meshes.append(colored_mesh)
+                    if colored_meshes:
+                        mesh = trimesh.util.concatenate(colored_meshes)
+                    else:
+                        mesh = None
+                else:
+                    mesh = mesh.copy()
+                    mesh.visual.face_colors = [255, 150, 100, 200]
+        else:
+            mesh = link.concatenated_visual_mesh
+
+        if mesh is not None and len(mesh.vertices) > 0:
+            # Create pyrender mesh
+            pyrender_mesh = pyrender.Mesh.from_trimesh(mesh, smooth=False)
+
+            # Create node with transformation matrix
+            node = pyrender.Node(
+                name=f"{'collision' if self.show_collision else 'visual'}_{link.name}_{link_id}",
+                mesh=pyrender_mesh,
+                matrix=transform
+            )
+
+            # Add to scene
+            self.scene.add_node(node)
+
+            # Update visual mesh map for compatibility (only for visual meshes)
+            if not self.show_collision:
+                self._visual_mesh_map[link_id] = (node, link)
+
+        # Process child links
+        for child_link in link.child_links:
+            self._add_single_link_mesh_for_toggle(child_link)