trianglengin 2.0.1__cp312-cp312-macosx_11_0_arm64.whl

trianglengin/ui/visualization/core/visualizer.py

@@ -0,0 +1,248 @@
+import logging
+
+import numpy as np
+import pygame  # Now a required dependency
+
+# Use absolute imports for core components
+from trianglengin.config import EnvConfig
+from trianglengin.game_interface import GameState, Shape
+
+# Use absolute imports within UI package where needed
+from trianglengin.ui.config import DisplayConfig
+
+# Import specific modules directly from the core package
+from trianglengin.ui.visualization.core import colors, coord_mapper
+from trianglengin.ui.visualization.core import (
+    layout as layout_module,
+)  # Import layout directly
+
+# Import drawing functions using absolute paths
+from trianglengin.ui.visualization.drawing import grid as grid_drawing
+from trianglengin.ui.visualization.drawing import highlight as highlight_drawing
+from trianglengin.ui.visualization.drawing import hud as hud_drawing
+from trianglengin.ui.visualization.drawing import previews as preview_drawing
+from trianglengin.ui.visualization.drawing.previews import (
+    draw_floating_preview,
+    draw_placement_preview,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class Visualizer:
+    """
+    Orchestrates rendering of a single game state for interactive modes.
+    Uses the GameState wrapper to access C++ state.
+    Receives interaction state (hover, selection) via render parameters.
+    """
+
+    def __init__(
+        self,
+        screen: pygame.Surface,
+        display_config: DisplayConfig,  # From UI config
+        env_config: EnvConfig,  # From core config
+        fonts: dict[str, pygame.font.Font | None],
+    ) -> None:
+        self.screen = screen
+        self.display_config = display_config
+        self.env_config = env_config
+        self.fonts = fonts
+        self.layout_rects: dict[str, pygame.Rect] | None = None
+        self.preview_rects: dict[int, pygame.Rect] = {}
+        self._layout_calculated_for_size: tuple[int, int] = (0, 0)
+        self.ensure_layout()
+
+    def ensure_layout(self) -> dict[str, pygame.Rect]:
+        """Returns cached layout or calculates it if needed."""
+        current_w, current_h = self.screen.get_size()
+        current_size = (current_w, current_h)
+
+        if (
+            self.layout_rects is None
+            or self._layout_calculated_for_size != current_size
+        ):
+            # Call the function via the imported module
+            self.layout_rects = layout_module.calculate_interactive_layout(
+                current_w,
+                current_h,
+                self.display_config,
+            )
+            self._layout_calculated_for_size = current_size
+            logger.info(
+                f"Recalculated interactive layout for size {current_size}: {self.layout_rects}"
+            )
+            self.preview_rects = {}  # Clear preview rect cache on layout change
+
+        return self.layout_rects if self.layout_rects is not None else {}
+
+    def render(
+        self,
+        game_state: GameState,  # Core GameState
+        mode: str,
+        selected_shape_idx: int = -1,
+        hover_shape: Shape | None = None,  # Core Shape
+        hover_grid_coord: tuple[int, int] | None = None,
+        hover_is_valid: bool = False,
+        hover_screen_pos: tuple[int, int] | None = None,
+        debug_highlight_coord: tuple[int, int] | None = None,
+    ) -> None:
+        """Renders the entire game visualization for interactive modes."""
+        self.screen.fill(colors.GRID_BG_DEFAULT)
+        layout_rects = self.ensure_layout()
+        grid_rect = layout_rects.get("grid")
+        preview_rect = layout_rects.get("preview")
+
+        grid_data_np = game_state.get_grid_data_np()
+
+        if grid_rect and grid_rect.width > 0 and grid_rect.height > 0:
+            try:
+                grid_surf = self.screen.subsurface(grid_rect)
+                cw, ch, ox, oy = coord_mapper._calculate_render_params(
+                    grid_rect.width, grid_rect.height, self.env_config
+                )
+                self._render_grid_area(
+                    grid_surf,
+                    game_state,
+                    grid_data_np,
+                    mode,
+                    grid_rect,
+                    hover_shape,
+                    hover_grid_coord,
+                    hover_is_valid,
+                    hover_screen_pos,
+                    debug_highlight_coord,
+                    cw,
+                    ch,
+                    ox,
+                    oy,
+                )
+            except ValueError as e:
+                logger.error(f"Error creating grid subsurface ({grid_rect}): {e}")
+                pygame.draw.rect(self.screen, colors.RED, grid_rect, 1)
+
+        if preview_rect and preview_rect.width > 0 and preview_rect.height > 0:
+            try:
+                preview_surf = self.screen.subsurface(preview_rect)
+                self._render_preview_area(
+                    preview_surf, game_state, mode, preview_rect, selected_shape_idx
+                )
+            except ValueError as e:
+                logger.error(f"Error creating preview subsurface ({preview_rect}): {e}")
+                pygame.draw.rect(self.screen, colors.RED, preview_rect, 1)
+
+        hud_drawing.render_hud(
+            surface=self.screen,
+            mode=mode,
+            fonts=self.fonts,
+        )
+
+    def _render_grid_area(
+        self,
+        grid_surf: pygame.Surface,
+        game_state: GameState,
+        grid_data_np: dict[str, np.ndarray],
+        mode: str,
+        grid_rect: pygame.Rect,
+        hover_shape: Shape | None,
+        hover_grid_coord: tuple[int, int] | None,
+        hover_is_valid: bool,
+        hover_screen_pos: tuple[int, int] | None,
+        debug_highlight_coord: tuple[int, int] | None,
+        cw: float,
+        ch: float,
+        ox: float,
+        oy: float,
+    ) -> None:
+        """Renders the main game grid and overlays onto the provided grid_surf."""
+        grid_drawing.draw_grid_background(
+            grid_surf,
+            self.env_config,
+            self.display_config,
+            cw,
+            ch,
+            ox,
+            oy,
+            game_state.is_over(),
+            mode == "debug",
+            death_mask_np=grid_data_np["death"],
+        )
+
+        grid_drawing.draw_grid_state(
+            grid_surf,
+            occupied_np=grid_data_np["occupied"],
+            color_id_np=grid_data_np["color_id"],
+            death_np=grid_data_np["death"],
+            rows=self.env_config.ROWS,
+            cols=self.env_config.COLS,
+            cw=cw,
+            ch=ch,
+            ox=ox,
+            oy=oy,
+        )
+
+        if mode == "play" and hover_shape:
+            if hover_grid_coord:
+                draw_placement_preview(
+                    grid_surf,
+                    hover_shape,
+                    hover_grid_coord[0],
+                    hover_grid_coord[1],
+                    is_valid=hover_is_valid,
+                    cw=cw,
+                    ch=ch,
+                    ox=ox,
+                    oy=oy,
+                )
+            elif hover_screen_pos:
+                local_hover_pos = (
+                    hover_screen_pos[0] - grid_rect.left,
+                    hover_screen_pos[1] - grid_rect.top,
+                )
+                if grid_surf.get_rect().collidepoint(local_hover_pos):
+                    draw_floating_preview(
+                        grid_surf,
+                        hover_shape,
+                        local_hover_pos,
+                    )
+
+        if mode == "debug" and debug_highlight_coord:
+            r, c = debug_highlight_coord
+            highlight_drawing.draw_debug_highlight(
+                grid_surf,
+                r,
+                c,
+                cw=cw,
+                ch=ch,
+                ox=ox,
+                oy=oy,
+            )
+
+        score_font = self.fonts.get("score")
+        if score_font:
+            score_text = f"Score: {game_state.game_score():.0f}"
+            score_surf = score_font.render(score_text, True, colors.YELLOW)
+            score_rect = score_surf.get_rect(topleft=(5, 5))
+            grid_surf.blit(score_surf, score_rect)
+
+    def _render_preview_area(
+        self,
+        preview_surf: pygame.Surface,
+        game_state: GameState,
+        mode: str,
+        preview_rect: pygame.Rect,
+        selected_shape_idx: int,
+    ) -> None:
+        """Renders the shape preview slots onto preview_surf and caches rects."""
+        current_shapes = game_state.get_shapes()
+        current_preview_rects = preview_drawing.render_previews(
+            preview_surf,
+            current_shapes,
+            preview_rect.topleft,
+            mode,
+            self.env_config,
+            self.display_config,
+            selected_shape_idx=selected_shape_idx,
+        )
+        # Cache the absolute screen coordinates of the preview slots
+        if not self.preview_rects or self.preview_rects != current_preview_rects:
+            self.preview_rects = current_preview_rects

trianglengin/ui/visualization/drawing/README.md

@@ -0,0 +1,49 @@
+
+# UI Visualization Drawing Submodule (`trianglengin.ui.visualization.drawing`)
+
+**Requires:** `pygame`
+
+## Purpose and Architecture
+
+This submodule contains specialized functions responsible for drawing specific visual elements of the game onto Pygame surfaces for the **interactive modes** within the `trianglengin.ui` package. These functions are typically called by the core renderer (`Visualizer`) in [`trianglengin.ui.visualization.core`](../core/README.md).
+
+-   **[`grid.py`](grid.py):** Functions for drawing the grid background (`draw_grid_background`), the individual triangles within it colored based on occupancy/emptiness (`draw_grid_state`), and optional debug overlays (`draw_debug_grid_overlay`).
+-   **[`shapes.py`](shapes.py):** Contains `draw_shape`, a function to render a given `Shape` object at a specific location on a surface (used primarily for previews).
+-   **[`previews.py`](previews.py):** Handles rendering related to shape previews:
+    -   `render_previews`: Draws the dedicated preview area, including borders and the shapes within their slots, handling selection highlights.
+    -   `draw_placement_preview`: Draws a semi-transparent version of a shape snapped to the grid, indicating a potential placement location (used in play mode hover).
+    -   `draw_floating_preview`: Draws a semi-transparent shape directly under the mouse cursor when hovering over the grid but not snapped (used in play mode hover).
+-   **[`hud.py`](hud.py):** `render_hud` draws Heads-Up Display elements like help text onto the main screen surface (simplified for interactive modes).
+-   **[`highlight.py`](highlight.py):** `draw_debug_highlight` draws a distinct border around a specific triangle, used for visual feedback in debug mode.
+-   **[`utils.py`](utils.py):** Helper functions, like `get_triangle_points`, used by other drawing functions.
+
+## Exposed Interfaces
+
+-   **Grid Drawing:**
+    -   `draw_grid_background(...)`
+    -   `draw_grid_state(...)`
+    -   `draw_debug_grid_overlay(...)`
+-   **Shape Drawing:**
+    -   `draw_shape(...)`
+-   **Preview Drawing:**
+    -   `render_previews(...) -> Dict[int, pygame.Rect]`
+    -   `draw_placement_preview(...)`
+    -   `draw_floating_preview(...)`
+-   **HUD Drawing:**
+    -   `render_hud(...)`
+-   **Highlight Drawing:**
+    -   `draw_debug_highlight(...)`
+-   **Utilities:**
+    -   `get_triangle_points(...) -> list[tuple[float, float]]`
+
+## Dependencies
+
+-   **`trianglengin` (core):** `EnvConfig`, `GameState`, `Shape`.
+-   **`trianglengin.ui.config`**: `DisplayConfig`.
+-   **`trianglengin.ui.visualization.core`**: `colors`, `coord_mapper`.
+-   **`pygame`**: The core library used for all drawing operations.
+-   **Standard Libraries:** `typing`, `logging`, `math`.
+
+---
+
+**Note:** Please keep this README updated when adding new drawing functions, modifying existing ones, or changing their dependencies.

trianglengin/ui/visualization/drawing/__init__.py

@@ -0,0 +1,43 @@
+"""Drawing functions for specific visual elements."""
+
+# Guard UI imports
+try:
+    # Import the new utility function
+    from .grid import (
+        draw_debug_grid_overlay,
+        draw_grid_background,
+        draw_grid_state,
+    )
+    from .highlight import draw_debug_highlight
+    from .hud import render_hud
+    from .previews import (
+        draw_floating_preview,
+        draw_placement_preview,
+        render_previews,
+    )
+    from .shapes import draw_shape
+    from .utils import get_triangle_points
+
+    __all__ = [
+        "draw_grid_background",
+        "draw_grid_state",
+        "draw_debug_grid_overlay",
+        "draw_shape",
+        "render_previews",
+        "draw_placement_preview",
+        "draw_floating_preview",
+        "render_hud",
+        "draw_debug_highlight",
+        "get_triangle_points",  # Export the helper
+    ]
+
+except ImportError as e:
+    import warnings
+
+    warnings.warn(
+        f"Could not import UI drawing components ({e}). "
+        "Ensure 'pygame' is installed (`pip install trianglengin[ui]`).",
+        ImportWarning,
+        stacklevel=2,
+    )
+    __all__ = []

trianglengin/ui/visualization/drawing/grid.py

@@ -0,0 +1,213 @@
+import logging
+
+import numpy as np
+
+# Guard UI imports
+try:
+    import pygame
+
+    from ..core import colors  # Relative import
+    from .utils import get_triangle_points  # Relative import
+except ImportError as e:
+    raise ImportError(
+        "UI components require 'pygame'. Install with 'pip install trianglengin[ui]'."
+    ) from e
+
+# Use absolute imports for core components
+from trianglengin.config import EnvConfig
+
+# Import DisplayConfig from the correct UI location
+from trianglengin.ui.config import DisplayConfig
+
+log = logging.getLogger(__name__)
+
+
+def draw_grid_background(
+    surface: pygame.Surface,
+    env_config: EnvConfig,  # Core config
+    display_config: DisplayConfig,  # UI config
+    cw: float,
+    ch: float,
+    ox: float,
+    oy: float,
+    game_over: bool = False,
+    debug_mode: bool = False,
+    death_mask_np: np.ndarray | None = None,
+) -> None:
+    """Draws the background grid structure using pre-calculated render parameters."""
+    bg_color = colors.GRID_BG_GAME_OVER if game_over else colors.GRID_BG_DEFAULT
+    surface.fill(bg_color)
+
+    if cw <= 0 or ch <= 0:
+        log.warning("Cannot draw grid background with zero cell dimensions.")
+        return
+
+    rows, cols = env_config.ROWS, env_config.COLS
+    if death_mask_np is None or death_mask_np.shape != (rows, cols):
+        log.warning(
+            "Death mask not provided or shape mismatch, cannot draw death zones accurately."
+        )
+        # Attempt to reconstruct death mask from config if not provided
+        death_mask_np = np.full((rows, cols), True, dtype=bool)
+        for r_idx in range(rows):
+            if r_idx < len(env_config.PLAYABLE_RANGE_PER_ROW):
+                start_c, end_c = env_config.PLAYABLE_RANGE_PER_ROW[r_idx]
+                if start_c < end_c:
+                    death_mask_np[r_idx, start_c:end_c] = False
+            else:
+                log.warning(f"Missing playable range definition for row {r_idx}")
+
+    for r in range(rows):
+        for c in range(cols):
+            is_up = (r + c) % 2 != 0
+            is_death = death_mask_np[r, c]
+
+            if is_death:
+                cell_color = colors.DEATH_ZONE_COLOR
+            else:
+                # Alternate background color based on checkerboard pattern
+                cell_color = (
+                    colors.GRID_BG_LIGHT if (r % 2 == c % 2) else colors.GRID_BG_DARK
+                )
+
+            points = get_triangle_points(r, c, is_up, ox, oy, cw, ch)
+            pygame.draw.polygon(surface, cell_color, points)
+            pygame.draw.polygon(surface, colors.GRID_LINE_COLOR, points, 1)
+
+            # Draw debug coordinates if in debug mode and font is available
+            if debug_mode:
+                debug_font = display_config.DEBUG_FONT
+                if debug_font:
+                    text = f"{r},{c}"
+                    text_surf = debug_font.render(text, True, colors.DEBUG_TOGGLE_COLOR)
+                    center_x = sum(p[0] for p in points) / 3
+                    center_y = sum(p[1] for p in points) / 3
+                    text_rect = text_surf.get_rect(center=(center_x, center_y))
+                    surface.blit(text_surf, text_rect)
+
+
+def draw_grid_state(
+    surface: pygame.Surface,
+    occupied_np: np.ndarray,
+    color_id_np: np.ndarray,
+    death_np: np.ndarray,
+    rows: int,
+    cols: int,
+    cw: float,
+    ch: float,
+    ox: float,
+    oy: float,
+) -> None:
+    """Draws the occupied triangles with their colors using pre-calculated parameters."""
+    if cw <= 0 or ch <= 0:
+        log.warning("Cannot draw grid state with zero cell dimensions.")
+        return
+
+    if (
+        occupied_np.shape != (rows, cols)
+        or color_id_np.shape != (rows, cols)
+        or death_np.shape != (rows, cols)
+    ):
+        log.error("Grid state array shape mismatch.")
+        return
+
+    for r in range(rows):
+        for c in range(cols):
+            if death_np[r, c]:
+                continue  # Skip death zones
+
+            if occupied_np[r, c]:
+                color_id = int(color_id_np[r, c])
+                color = colors.ID_TO_COLOR_MAP.get(color_id)
+                is_up = (r + c) % 2 != 0
+                points = get_triangle_points(r, c, is_up, ox, oy, cw, ch)
+
+                if color is not None:
+                    pygame.draw.polygon(surface, color, points)
+                elif color_id == colors.DEBUG_COLOR_ID:
+                    # Draw debug-toggled cells with a specific color
+                    pygame.draw.polygon(surface, colors.DEBUG_TOGGLE_COLOR, points)
+                else:
+                    # Fallback for unexpected color IDs
+                    log.warning(
+                        f"Occupied cell ({r},{c}) has invalid color ID: {color_id}"
+                    )
+                    pygame.draw.polygon(surface, colors.TRIANGLE_EMPTY_COLOR, points)
+
+
+def draw_debug_grid_overlay(
+    surface: pygame.Surface,
+    display_config: DisplayConfig,  # UI config
+    rows: int,
+    cols: int,
+    cw: float,
+    ch: float,
+    ox: float,
+    oy: float,
+) -> None:
+    """Draws debug information (coordinates) using pre-calculated render parameters."""
+    font = display_config.DEBUG_FONT
+    if not font:
+        log.warning("Debug font not available for overlay.")
+        return
+    if cw <= 0 or ch <= 0:
+        log.warning("Cannot draw debug overlay with zero cell dimensions.")
+        return
+
+    for r in range(rows):
+        for c in range(cols):
+            is_up = (r + c) % 2 != 0
+            points = get_triangle_points(r, c, is_up, ox, oy, cw, ch)
+            text = f"{r},{c}"
+            text_surf = font.render(text, True, colors.DEBUG_TOGGLE_COLOR)
+            center_x = sum(p[0] for p in points) / 3
+            center_y = sum(p[1] for p in points) / 3
+            text_rect = text_surf.get_rect(center=(center_x, center_y))
+            surface.blit(text_surf, text_rect)
+
+
+def draw_grid(
+    surface: pygame.Surface,
+    grid_data_np: dict[str, np.ndarray],
+    env_config: EnvConfig,  # Core config
+    display_config: DisplayConfig,  # UI config
+    cw: float,
+    ch: float,
+    ox: float,
+    oy: float,
+    game_over: bool = False,
+    debug_mode: bool = False,
+) -> None:
+    """Main function to draw the entire grid including background and state."""
+    draw_grid_background(
+        surface,
+        env_config,
+        display_config,
+        cw,
+        ch,
+        ox,
+        oy,
+        game_over,
+        debug_mode,
+        grid_data_np["death"],
+    )
+    draw_grid_state(
+        surface,
+        grid_data_np["occupied"],
+        grid_data_np["color_id"],
+        grid_data_np["death"],
+        env_config.ROWS,
+        env_config.COLS,
+        cw,
+        ch,
+        ox,
+        oy,
+    )
+    # Overlay debug coordinates only if in debug mode
+    # Note: draw_grid_background already handles drawing coords if debug_mode=True
+    # This function might be redundant if the background function does it.
+    # Keeping it separate allows potentially different debug info later.
+    # if debug_mode:
+    #     draw_debug_grid_overlay(
+    #         surface, display_config, env_config.ROWS, env_config.COLS, cw, ch, ox, oy
+    #     )

trianglengin/ui/visualization/drawing/highlight.py

@@ -0,0 +1,31 @@
+# Guard UI imports
+try:
+    import pygame
+
+    from ..core import colors  # Relative import
+    from .utils import get_triangle_points  # Relative import
+except ImportError as e:
+    raise ImportError(
+        "UI components require 'pygame'. Install with 'pip install trianglengin[ui]'."
+    ) from e
+
+
+def draw_debug_highlight(
+    surface: pygame.Surface,
+    r: int,
+    c: int,
+    cw: float,
+    ch: float,
+    ox: float,
+    oy: float,
+) -> None:
+    """Highlights a specific triangle border for debugging using pre-calculated parameters."""
+    if surface.get_width() <= 0 or surface.get_height() <= 0:
+        return
+    if cw <= 0 or ch <= 0:
+        return
+
+    is_up = (r + c) % 2 != 0
+    # Use helper
+    pts = get_triangle_points(r, c, is_up, ox, oy, cw, ch)
+    pygame.draw.polygon(surface, colors.DEBUG_TOGGLE_COLOR, pts, 3)  # Draw border

trianglengin/ui/visualization/drawing/hud.py

@@ -0,0 +1,43 @@
+from typing import Any
+
+# Guard UI imports
+try:
+    import pygame
+
+    from ..core import colors  # Relative import
+except ImportError as e:
+    raise ImportError(
+        "UI components require 'pygame'. Install with 'pip install trianglengin[ui]'."
+    ) from e
+
+
+def render_hud(
+    surface: pygame.Surface,
+    mode: str,
+    fonts: dict[str, pygame.font.Font | None],
+    _display_stats: dict[str, Any] | None = None,  # Prefix with underscore
+) -> None:
+    """
+    Renders HUD elements for interactive modes (play/debug).
+    Displays only help text relevant to the mode.
+    Ignores _display_stats.
+    """
+    screen_w, screen_h = surface.get_size()
+    help_font = fonts.get("help")
+
+    if not help_font:
+        return
+
+    bottom_y = screen_h - 10  # Position from bottom
+
+    # --- Render Help Text Only ---
+    help_text = "[ESC] Quit"
+    if mode == "play":
+        help_text += " | [Click] Select/Place Shape"
+    elif mode == "debug":
+        help_text += " | [Click] Toggle Cell"
+
+    help_surf = help_font.render(help_text, True, colors.LIGHT_GRAY)
+    # Position help text at the bottom right
+    help_rect = help_surf.get_rect(bottomright=(screen_w - 15, bottom_y))
+    surface.blit(help_surf, help_rect)