Introduction of Space Renderer

docs/apis/visualization.md

@@ -59,11 +59,72 @@ For detailed tutorials, please refer to:
    :show-inheritance:
 ```
 
+
 ## Command Console
 
 ```{eval-rst}
 .. automodule:: mesa.visualization.command_console
    :members:
    :undoc-members:
    :show-inheritance:
-```
+```
+
+
+## Portrayal Components
+```{eval-rst}
+.. automodule:: mesa.visualization.components.portrayal_components
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+
+## Backends
+
+```{eval-rst}
+.. automodule:: mesa.visualization.backends.__init__
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+```{eval-rst}
+.. automodule:: mesa.visualization.backends.abstract_renderer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+```{eval-rst}
+.. automodule:: mesa.visualization.backends.altair_backend
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+```{eval-rst}
+.. automodule:: mesa.visualization.backends.matplotlib_backend
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+
+## Space Renderer
+
+```{eval-rst}
+.. automodule:: mesa.visualization.space_renderer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+
+## Space Drawers
+
+```{eval-rst}
+.. automodule:: mesa.visualization.space_drawers
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```

mesa/visualization/__init__.py

@@ -13,13 +13,15 @@
 from .components import make_plot_component, make_space_component
 from .components.altair_components import make_space_altair
 from .solara_viz import JupyterViz, SolaraViz
+from .space_renderer import SpaceRenderer
 from .user_param import Slider
 
 __all__ = [
     "CommandConsole",
     "JupyterViz",
     "Slider",
     "SolaraViz",
+    "SpaceRenderer",
     "draw_space",
     "make_plot_component",
     "make_space_altair",

mesa/visualization/backends/__init__.py

@@ -0,0 +1,23 @@
+"""Visualization backends for Mesa space rendering.
+
+This module provides different backend implementations for visualizing
+Mesa agent-based model spaces and components.
+
+Note:
+    These backends are used internally by the space renderer and are not intended for
+    direct use by end users. See `SpaceRenderer` for actual usage and setting up
+    visualizations.
+
+Available Backends:
+    1. AltairBackend
+    2. MatplotlibBackend
+
+"""
+
+from .altair_backend import AltairBackend
+from .matplotlib_backend import MatplotlibBackend
+
+__all__ = [
+    "AltairBackend",
+    "MatplotlibBackend",
+]

mesa/visualization/backends/abstract_renderer.py

@@ -0,0 +1,97 @@
+"""Abstract base class for visualization backends in Mesa.
+
+This module provides the foundational interface for implementing various
+visualization backends for Mesa agent-based models.
+"""
+
+from abc import ABC, abstractmethod
+
+import mesa
+from mesa.discrete_space import (
+    OrthogonalMooreGrid,
+    OrthogonalVonNeumannGrid,
+)
+from mesa.space import (
+    HexMultiGrid,
+    HexSingleGrid,
+    MultiGrid,
+    NetworkGrid,
+    SingleGrid,
+)
+
+OrthogonalGrid = SingleGrid | MultiGrid | OrthogonalMooreGrid | OrthogonalVonNeumannGrid
+HexGrid = HexSingleGrid | HexMultiGrid | mesa.discrete_space.HexGrid
+Network = NetworkGrid | mesa.discrete_space.Network
+
+
+class AbstractRenderer(ABC):
+    """Abstract base class for visualization backends.
+
+    This class defines the interface for rendering Mesa spaces and agents.
+    For details on the methods checkout specific backend implementations.
+    """
+
+    def __init__(self, space_drawer):
+        """Initialize the renderer.
+
+        Args:
+            space_drawer: Object responsible for drawing space elements. Checkout `SpaceDrawer`
+            for more details on the detailed implementations of the drawing functions.
+        """
+        self.space_drawer = space_drawer
+        self._canvas = None
+
+    def _get_agent_pos(self, agent, space):
+        """Get agent position based on space type."""
+        if isinstance(space, NetworkGrid):
+            return agent.pos, agent.pos
+        elif isinstance(space, Network):
+            return agent.cell.coordinate, agent.cell.coordinate
+        else:
+            x = agent.pos[0] if agent.pos is not None else agent.cell.coordinate[0]
+            y = agent.pos[1] if agent.pos is not None else agent.cell.coordinate[1]
+            return x, y
+
+    @abstractmethod
+    def initialize_canvas(self):
+        """Set up the drawing canvas."""
+
+    @abstractmethod
+    def draw_structure(self, **kwargs):
+        """Draw the space structure.
+
+        Args:
+            **kwargs: Structure drawing configuration options.
+        """
+
+    @abstractmethod
+    def collect_agent_data(self, space, agent_portrayal, default_size=None):
+        """Collect plotting data for all agents in the space.
+
+        Args:
+            space: The Mesa space containing agents.
+            agent_portrayal (Callable): Function that returns AgentPortrayalStyle for each agent.
+            default_size (float, optional): Default marker size if not specified in portrayal.
+
+        Returns:
+            dict: Dictionary containing agent plotting data arrays with keys:
+        """
+
+    @abstractmethod
+    def draw_agents(self, arguments, **kwargs):
+        """Drawing agents on space.
+
+        Args:
+            arguments (dict): Dictionary containing agent data.
+            **kwargs: Additional drawing configuration options.
+        """
+
+    @abstractmethod
+    def draw_propertylayer(self, space, property_layers, propertylayer_portrayal):
+        """Draw property layers on the visualization.
+
+        Args:
+            space: The model's space object.
+            property_layers (dict): Dictionary of property layers to visualize.
+            propertylayer_portrayal (Callable): Function that returns PropertyLayerStyle.
+        """