miniworld-maze 1.1.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

miniworld_maze/__init__.py

@@ -15,17 +15,29 @@ Main modules:
 - tools: Observation generation and utilities
 """
 
+import os
+import warnings
+
+# Set PYGLET_HEADLESS=1 by default if not already set
+if "PYGLET_HEADLESS" not in os.environ:
+    os.environ["PYGLET_HEADLESS"] = "1"
+    warnings.warn(
+        "Automatically set PYGLET_HEADLESS=1 for headless rendering. "
+        "Set PYGLET_HEADLESS=0 before importing miniworld_maze to override this behavior.",
+        UserWarning,
+        stacklevel=2
+    )
+
 from .core import ObservationLevel
-from .environments.factory import (
-    NineRoomsEnvironmentWrapper,
-)
 from .environments.nine_rooms import NineRooms
 from .environments.spiral_nine_rooms import SpiralNineRooms
 from .environments.twenty_five_rooms import TwentyFiveRooms
 
-__version__ = "1.0.0"
+# Import factory to register environments
+from .environments import factory  # noqa: F401
+
+__version__ = "1.1.0"
 __all__ = [
-    "NineRoomsEnvironmentWrapper",
     "NineRooms",
     "SpiralNineRooms",
     "TwentyFiveRooms",

miniworld_maze/core/constants.py

@@ -57,23 +57,64 @@ DEFAULT_BENCHMARK_STEPS: Final[int] = 100
 DEFAULT_WARMUP_STEPS: Final[int] = 10
 
 # ========================
-# OBSERVATION TEST POSITIONS
+# TEXTURE THEMES
 # ========================
 
+class TextureThemes:
+    """Pre-defined texture themes for different environments."""
+
+    NINE_ROOMS = [
+        "beige",
+        "lightbeige",
+        "lightgray",
+        "copperred",
+        "skyblue",
+        "lightcobaltgreen",
+        "oakbrown",
+        "navyblue",
+        "cobaltgreen",
+    ]
+
+    SPIRAL_NINE_ROOMS = [
+        "beige",
+        "lightbeige",
+        "lightgray",
+        "copperred",
+        "skyblue",
+        "lightcobaltgreen",
+        "oakbrown",
+        "navyblue",
+        "cobaltgreen",
+    ]
+
+    TWENTY_FIVE_ROOMS = [
+        "crimson",
+        "beanpaste",
+        "cobaltgreen",
+        "lightnavyblue",
+        "skyblue",
+        "lightcobaltgreen",
+        "oakbrown",
+        "copperred",
+        "lightgray",
+        "lime",
+        "turquoise",
+        "violet",
+        "beige",
+        "morningglory",
+        "silver",
+        "magenta",
+        "sunnyyellow",
+        "blueberry",
+        "lightbeige",
+        "seablue",
+        "lemongrass",
+        "orchid",
+        "redbean",
+        "orange",
+        "realblueberry",
+    ]
 
-# Convenient position calculations for standard room layouts
-class RoomPositions:
-    """Pre-calculated positions for standard room layouts."""
-
-    # NineRooms (3x3) strategic positions
-    NINE_ROOMS_CENTER: Final[tuple[float, float, float]] = (22.5, 0.0, 22.5)
-    NINE_ROOMS_TOP_LEFT: Final[tuple[float, float, float]] = (7.5, 0.0, 7.5)
-    NINE_ROOMS_BOTTOM_RIGHT: Final[tuple[float, float, float]] = (37.5, 0.0, 37.5)
-
-    # TwentyFiveRooms (5x5) strategic positions
-    TWENTY_FIVE_CENTER: Final[tuple[float, float, float]] = (75.0, 0.0, 75.0)
-    TWENTY_FIVE_CORNER: Final[tuple[float, float, float]] = (37.5, 0.0, 37.5)
-    TWENTY_FIVE_FAR_CORNER: Final[tuple[float, float, float]] = (112.5, 0.0, 112.5)
 
 
 # ========================

miniworld_maze/core/miniworld_gymnasium/__init__.py

@@ -1,4 +1,4 @@
 # Core module cleaned up - imports removed since files were consolidated
 
 # Import the envs module so that envs register themselves
-from . import envs
+from . import envs as envs

miniworld_maze/core/miniworld_gymnasium/base_env.py

@@ -21,6 +21,7 @@ class MiniWorldEnv(UnifiedMiniWorldEnv):
         window_height=600,
         params=DEFAULT_PARAMS,
         domain_rand=False,
+        render_mode=None,
     ):
         """
         Initialize base MiniWorld environment.
@@ -33,6 +34,7 @@ class MiniWorldEnv(UnifiedMiniWorldEnv):
             window_height: Window height for human rendering
             params: Environment parameters for domain randomization
             domain_rand: Whether to enable domain randomization
+            render_mode: Render mode ("human", "rgb_array", or None)
         """
         # Mark this as a base environment (not custom) for background color handling
         self._is_custom_env = False
@@ -49,4 +51,5 @@ class MiniWorldEnv(UnifiedMiniWorldEnv):
             window_height=window_height,
             params=params,
             domain_rand=domain_rand,
+            render_mode=render_mode,
         )

miniworld_maze/core/miniworld_gymnasium/unified_env.py

@@ -63,7 +63,7 @@ class UnifiedMiniWorldEnv(gym.Env):
     both the enhanced features of CustomMiniWorldEnv and the legacy BaseEnv functionality.
     """
 
-    metadata = {"render.modes": ["human", "rgb_array"], "video.frames_per_second": 30}
+    metadata = {"render_modes": ["human", "rgb_array"], "video.frames_per_second": 30}
 
     # Enumeration of possible actions
     class Actions(IntEnum):
@@ -98,6 +98,7 @@ class UnifiedMiniWorldEnv(gym.Env):
         params=DEFAULT_PARAMS,
         domain_rand=False,
         info_obs: Optional[List[ObservationLevel]] = None,
+        render_mode=None,
     ):
         """
         Initialize unified MiniWorld environment.
@@ -114,6 +115,7 @@ class UnifiedMiniWorldEnv(gym.Env):
             params: Environment parameters for domain randomization
             domain_rand: Whether to enable domain randomization
             info_obs: List of observation levels to include in info dictionary
+            render_mode: Render mode ("human", "rgb_array", or None)
         """
         # Store configuration
         self.obs_level = obs_level
@@ -123,6 +125,13 @@ class UnifiedMiniWorldEnv(gym.Env):
         self.params = params
         self.domain_rand = domain_rand
         self.info_obs = info_obs
+        self.render_mode = render_mode
+
+        # Validate render_mode
+        if render_mode is not None and render_mode not in self.metadata["render_modes"]:
+            raise ValueError(
+                f"render_mode must be one of {self.metadata['render_modes']}, got {render_mode}"
+            )
 
         # Setup action space
         self._setup_action_space()
@@ -332,34 +341,32 @@ class UnifiedMiniWorldEnv(gym.Env):
         self._render_static()
 
         # Generate the first camera image
-        obs = self._generate_observation()
+        obs = self._generate_observation(self.obs_level)
 
         # Generate additional observations for info dictionary if specified
         info = {}
         if self.info_obs is not None:
             for obs_level in self.info_obs:
-                # Temporarily change obs_level to generate the desired observation
-                original_obs_level = self.obs_level
-                self.obs_level = obs_level
-                info_obs = self._generate_observation()
-                self.obs_level = original_obs_level
+                # Generate observation with the specified level
+                info_obs = self._generate_observation(observation_level=obs_level)
                 # Use the observation level name as key
                 info[str(obs_level)] = info_obs
 
         # Return first observation with info dict for Gymnasium compatibility
         return obs, info
 
-    def _generate_observation(self, render_agent: bool = None):
-        """Generate observation based on current observation level.
+    def _generate_observation(self, observation_level, render_agent: bool = None):
+        """Generate observation based on specified observation level.
 
         Args:
+            observation_level: Observation level to use.
             render_agent: Whether to render the agent in the observation.
                          If None, uses default behavior based on observation level.
         """
         # Import ObservationLevel here to avoid circular imports
         from ..observation_types import ObservationLevel
 
-        if self.obs_level == ObservationLevel.TOP_DOWN_PARTIAL:
+        if observation_level == ObservationLevel.TOP_DOWN_PARTIAL:
             if self.agent_mode == "empty":
                 # Agent mode 'empty' always renders without agent
                 render_ag = False
@@ -371,19 +378,19 @@ class UnifiedMiniWorldEnv(gym.Env):
                 render_ag = True
             return self.render_top_view(POMDP=True, render_ag=render_ag)
 
-        elif self.obs_level == ObservationLevel.TOP_DOWN_FULL:
+        elif observation_level == ObservationLevel.TOP_DOWN_FULL:
             # Use explicit render_agent parameter or default to True
             render_ag = render_agent if render_agent is not None else True
             return self.render_top_view(POMDP=False, render_ag=render_ag)
 
-        elif self.obs_level == ObservationLevel.FIRST_PERSON:
+        elif observation_level == ObservationLevel.FIRST_PERSON:
             # First person view doesn't include the agent anyway
             return self.render_obs()
 
         else:
             valid_levels = list(ObservationLevel)
             raise ValueError(
-                f"Invalid obs_level {self.obs_level}. Must be one of {valid_levels}"
+                f"Invalid obs_level {observation_level}. Must be one of {valid_levels}"
             )
 
     def _calculate_carried_object_position(self, agent_pos, ent):
@@ -507,7 +514,7 @@ class UnifiedMiniWorldEnv(gym.Env):
         self._process_action(action)
 
         # Generate observation
-        observation = self._generate_observation()
+        observation = self._generate_observation(self.obs_level)
 
         # Calculate step results
         reward, terminated, info = self._calculate_step_results(observation)
@@ -586,11 +593,8 @@ class UnifiedMiniWorldEnv(gym.Env):
         info = {}
         if self.info_obs is not None:
             for obs_level in self.info_obs:
-                # Temporarily change obs_level to generate the desired observation
-                original_obs_level = self.obs_level
-                self.obs_level = obs_level
-                info_obs = self._generate_observation()
-                self.obs_level = original_obs_level
+                # Generate observation with the specified level
+                info_obs = self._generate_observation(observation_level=obs_level)
                 # Use the observation level name as key
                 info[str(obs_level)] = info_obs
 

miniworld_maze/environments/__init__.py

@@ -1,14 +1,12 @@
 """Nine Rooms environment implementations."""
 
 from .base_grid_rooms import GridRoomsEnvironment
-from .factory import NineRoomsEnvironmentWrapper
 from .nine_rooms import NineRooms
 from .spiral_nine_rooms import SpiralNineRooms
 from .twenty_five_rooms import TwentyFiveRooms
 
 __all__ = [
     "GridRoomsEnvironment",
-    "NineRoomsEnvironmentWrapper",
     "NineRooms",
     "SpiralNineRooms",
     "TwentyFiveRooms",

miniworld_maze/environments/base_grid_rooms.py

@@ -46,6 +46,7 @@ class GridRoomsEnvironment(UnifiedMiniWorldEnv):
         agent_mode: Optional[str] = None,
         obs_width: int = DEFAULT_OBS_WIDTH,
         obs_height: int = DEFAULT_OBS_HEIGHT,
+        render_mode=None,
         **kwargs,
     ):
         """
@@ -64,6 +65,7 @@ class GridRoomsEnvironment(UnifiedMiniWorldEnv):
             agent_mode: Agent rendering mode ('triangle', 'circle', 'empty')
             obs_width: Observation width in pixels (defaults to DEFAULT_OBS_WIDTH)
             obs_height: Observation height in pixels (defaults to DEFAULT_OBS_HEIGHT)
+            render_mode: Render mode ("human", "rgb_array", or None)
             **kwargs: Additional arguments passed to parent class
         """
 
@@ -77,7 +79,8 @@ class GridRoomsEnvironment(UnifiedMiniWorldEnv):
 
         # Validate and set textures
         assert len(textures) == self.total_rooms, (
-            f"Textures for floor should be same as the number of the rooms ({self.total_rooms})"
+            f"Textures for floor should be same as the number of the rooms "
+            f"({self.total_rooms})"
         )
         self.textures = textures
 
@@ -119,6 +122,7 @@ class GridRoomsEnvironment(UnifiedMiniWorldEnv):
             agent_mode=self.agent_mode,
             obs_width=obs_width,
             obs_height=obs_height,
+            render_mode=render_mode,
             **kwargs,
         )
 
@@ -226,16 +230,20 @@ class GridRoomsEnvironment(UnifiedMiniWorldEnv):
         obs, reward, terminated, truncated, info = super().step(action)
 
         # Check if goal is achieved
-        if self.is_goal_achieved():
+        if self._is_goal_achieved():
             terminated = True
             reward = 1.0  # Positive reward for achieving goal
 
+        # Add agent and goal positions to info dictionary
+        agent_pos = self.agent.pos
+        info["agent_position"] = np.array([agent_pos[0], agent_pos[2]])  # x, z
+
+        if hasattr(self, "_current_goal_position"):
+            goal_pos = self._current_goal_position
+            info["goal_position"] = np.array([goal_pos[0], goal_pos[2]])  # x, z
+
         # Return observation as dict
-        obs_dict = {
-            "observation": obs,
-            "desired_goal": self.desired_goal,
-            "achieved_goal": obs,
-        }
+        obs_dict = self._build_observation_dict(obs)
         return obs_dict, reward, terminated, truncated, info
 
     def reset(self, seed=None, options=None, pos=None):
@@ -254,17 +262,21 @@ class GridRoomsEnvironment(UnifiedMiniWorldEnv):
         obs, info = super().reset(seed=seed, options=options, pos=pos)
 
         # Generate goal
-        self.desired_goal = self.get_goal()
+        self.desired_goal = self._get_goal()
+
+        # Add agent and goal positions to info dictionary
+        agent_pos = self.agent.pos
+        info["agent_position"] = np.array([agent_pos[0], agent_pos[2]])  # x, z
+
+        if hasattr(self, "_current_goal_position"):
+            goal_pos = self._current_goal_position
+            info["goal_position"] = np.array([goal_pos[0], goal_pos[2]])  # x, z
 
         # Return observation as dict with desired_goal and achieved_goal
-        obs_dict = {
-            "observation": obs,
-            "desired_goal": self.desired_goal,
-            "achieved_goal": obs,
-        }
+        obs_dict = self._build_observation_dict(obs)
         return obs_dict, info
 
-    def get_goal(self):
+    def _get_goal(self):
         """
         Generate a goal by randomly selecting a room and goal position.
 
@@ -318,7 +330,7 @@ class GridRoomsEnvironment(UnifiedMiniWorldEnv):
 
         return obs
 
-    def is_goal_achieved(self, pos=None, threshold=0.5):
+    def _is_goal_achieved(self, pos=None, threshold=0.5):
         """
         Check if the agent has achieved the current goal.
 
@@ -341,3 +353,66 @@ class GridRoomsEnvironment(UnifiedMiniWorldEnv):
         distance = np.linalg.norm(pos_array - goal_array)
 
         return bool(distance < threshold)
+
+    @staticmethod
+    def _generate_goal_positions(
+        grid_size: int, room_size: Union[int, float], goals_per_room: int = 2
+    ) -> List[List[List[float]]]:
+        """
+        Generate goal positions for grid layout.
+        Args:
+            grid_size: Size of the grid (e.g., 3 for 3x3, 5 for 5x5)
+            room_size: Size of each room
+            goals_per_room: Number of goals per room (1 or 2)
+        Returns:
+            List of goal positions for each room
+        """
+        goal_positions = []
+        for i in range(grid_size):  # rows
+            for j in range(grid_size):  # columns
+                center_x = room_size * j + room_size / 2
+                center_z = room_size * i + room_size / 2
+                if goals_per_room == 1:
+                    # One goal per room at the center
+                    goal_positions.append([[center_x, 0.0, center_z]])
+                else:
+                    # Two goals per room: center-left and center-right
+                    goal_positions.append([
+                        [center_x - 1.0, 0.0, center_z],  # left goal
+                        [center_x + 1.0, 0.0, center_z],  # right goal
+                    ])
+        return goal_positions
+
+    def get_extent(self, padding: float = 1.0) -> Tuple[float, float, float, float]:
+        """
+        Get the scene extent for use with matplotlib imshow.
+        
+        Returns the scene bounds with padding in the format expected by 
+        matplotlib's imshow(extent=...) parameter: (left, right, bottom, top).
+        
+        Args:
+            padding: Padding to add around environment bounds (default: 1.0)
+            
+        Returns:
+            Tuple[float, float, float, float]: (min_x, max_x, min_z, max_z) with padding
+        """
+        return (
+            self.min_x - padding,
+            self.max_x + padding,
+            self.min_z - padding,
+            self.max_z + padding
+        )
+
+    def _build_observation_dict(self, obs: np.ndarray) -> dict:
+        """
+        Build the standard observation dictionary format.
+        Args:
+            obs: The observation array
+        Returns:
+            Dictionary with observation, desired_goal, and achieved_goal
+        """
+        return {
+            "observation": obs,
+            "desired_goal": self.desired_goal,
+            "achieved_goal": obs,
+        }

miniworld_maze/environments/factory.py

@@ -1,105 +1,42 @@
-"""Factory for creating Nine Rooms environment variants."""
-
-from typing import List
-
-import gymnasium as gym
-import numpy as np
+"""Gymnasium environment registrations for Nine Rooms environment variants."""
 
+from gymnasium.envs.registration import register
 from ..core import ObservationLevel
 from ..core.constants import FACTORY_DOOR_SIZE, FACTORY_ROOM_SIZE
-from .nine_rooms import NineRooms
-from .spiral_nine_rooms import SpiralNineRooms
-from .twenty_five_rooms import TwentyFiveRooms
-
-
-class NineRoomsEnvironmentWrapper(gym.Wrapper):
-    """Unified wrapper for all Nine Rooms environment variants."""
-
-    def __init__(
-        self,
-        variant="NineRooms",
-        obs_level=ObservationLevel.TOP_DOWN_PARTIAL,
-        continuous=False,
-        size=64,
-        room_size=FACTORY_ROOM_SIZE,
-        door_size=FACTORY_DOOR_SIZE,
-        agent_mode=None,
-        info_obs: List[ObservationLevel] = None,
-    ):
-        """
-        Create a Nine Rooms environment variant.
-
-        Args:
-            variant: Environment variant ("NineRooms", "SpiralNineRooms", "TwentyFiveRooms")
-            obs_level: Observation level (ObservationLevel enum)
-            continuous: Whether to use continuous actions
-            size: Observation image size (rendered directly at this size to avoid resizing)
-            room_size: Size of each room in environment units
-            door_size: Size of doors between rooms
-            agent_mode: Agent rendering mode ('empty', 'circle', 'triangle', or None for default)
-            info_obs: List of observation levels to include in info dictionary
-        """
-        self.variant = variant
-
-        # Select the appropriate environment class
-        env_classes = {
-            "NineRooms": NineRooms,
-            "SpiralNineRooms": SpiralNineRooms,
-            "TwentyFiveRooms": TwentyFiveRooms,
-        }
-
-        if variant not in env_classes:
-            raise ValueError(
-                f"Unknown variant '{variant}'. Available: {list(env_classes.keys())}"
-            )
-
-        env_class = env_classes[variant]
-
-        # Create base environment with direct rendering size
-        base_env = env_class(
-            room_size=room_size,
-            door_size=door_size,
-            obs_level=obs_level,
-            continuous=continuous,
-            obs_width=size,
-            obs_height=size,
-            agent_mode=agent_mode,
-            info_obs=info_obs,
-        )
-
-        # Apply wrappers - no resize needed since we render at target size
-
-        # Initialize gym.Wrapper with the base environment
-        super().__init__(base_env)
-
-    def render_on_pos(self, pos):
-        """Render observation from a specific position."""
-        # Get access to the base environment
-        base_env = self.env
-        while hasattr(base_env, "env") or hasattr(base_env, "_env"):
-            if hasattr(base_env, "env"):
-                base_env = base_env.env
-            elif hasattr(base_env, "_env"):
-                base_env = base_env._env
-            else:
-                break
-
-        # Store original position
-        original_pos = base_env.agent.pos.copy()
-
-        # Move agent to target position
-        base_env.place_agent(pos=pos)
-
-        # Get first-person observation from the agent's perspective at this position
-        obs = base_env.render_obs()
-
-        # Restore original position
-        base_env.place_agent(pos=original_pos)
-
-        # Apply wrapper transformations manually for consistency
-        # Convert to PyTorch format (CHW) - no resize needed since we render at target size
-        obs = np.transpose(obs, (2, 0, 1))
-
-        return obs
-
 
+# Register environment variants with factory defaults matching the original wrapper
+register(
+    id="NineRooms-v0",
+    entry_point="miniworld_maze.environments.nine_rooms:NineRooms",
+    max_episode_steps=1000,
+    kwargs={
+        "room_size": FACTORY_ROOM_SIZE,
+        "door_size": FACTORY_DOOR_SIZE,
+        "obs_level": ObservationLevel.TOP_DOWN_PARTIAL,
+        "agent_mode": None,  # becomes "empty" by default
+    },
+)
+
+register(
+    id="SpiralNineRooms-v0", 
+    entry_point="miniworld_maze.environments.spiral_nine_rooms:SpiralNineRooms",
+    max_episode_steps=1000,
+    kwargs={
+        "room_size": FACTORY_ROOM_SIZE,
+        "door_size": FACTORY_DOOR_SIZE,
+        "obs_level": ObservationLevel.TOP_DOWN_PARTIAL,
+        "agent_mode": None,
+    },
+)
+
+register(
+    id="TwentyFiveRooms-v0",
+    entry_point="miniworld_maze.environments.twenty_five_rooms:TwentyFiveRooms", 
+    max_episode_steps=1000,
+    kwargs={
+        "room_size": FACTORY_ROOM_SIZE,
+        "door_size": FACTORY_DOOR_SIZE,
+        "obs_level": ObservationLevel.TOP_DOWN_PARTIAL,
+        "agent_mode": None,
+    },
+)

miniworld_maze/environments/nine_rooms.py

@@ -1,6 +1,7 @@
 """NineRooms environment implementation."""
 
 from ..core import ObservationLevel
+from ..core.constants import TextureThemes
 from .base_grid_rooms import GridRoomsEnvironment
 
 
@@ -46,31 +47,12 @@ class NineRooms(GridRoomsEnvironment):
             (6, 7),
             (7, 8),
         ]
-        default_textures = [
-            "beige",
-            "lightbeige",
-            "lightgray",
-            "copperred",
-            "skyblue",
-            "lightcobaltgreen",
-            "oakbrown",
-            "navyblue",
-            "cobaltgreen",
-        ]
+        default_textures = TextureThemes.NINE_ROOMS
 
         # Initialize goal positions for each room (2 goals per room)
-        goal_positions = []
-        for i in range(3):  # rows
-            for j in range(3):  # columns
-                center_x = room_size * j + room_size / 2
-                center_z = room_size * i + room_size / 2
-                # Two goals per room: center-left and center-right
-                goal_positions.append(
-                    [
-                        [center_x - 1.0, 0.0, center_z],  # left goal
-                        [center_x + 1.0, 0.0, center_z],  # right goal
-                    ]
-                )
+        goal_positions = GridRoomsEnvironment._generate_goal_positions(
+            3, room_size, goals_per_room=2
+        )
 
         super().__init__(
             grid_size=3,

miniworld_maze/environments/spiral_nine_rooms.py

@@ -1,6 +1,7 @@
 """SpiralNineRooms environment implementation."""
 
 from ..core import ObservationLevel
+from ..core.constants import TextureThemes
 from .base_grid_rooms import GridRoomsEnvironment
 
 
@@ -42,31 +43,12 @@ class SpiralNineRooms(GridRoomsEnvironment):
             (6, 7),
             (7, 8),
         ]
-        default_textures = [
-            "beige",
-            "lightbeige",
-            "lightgray",
-            "copperred",
-            "skyblue",
-            "lightcobaltgreen",
-            "oakbrown",
-            "navyblue",
-            "cobaltgreen",
-        ]
+        default_textures = TextureThemes.SPIRAL_NINE_ROOMS
 
         # Initialize goal positions for each room (2 goals per room)
-        goal_positions = []
-        for i in range(3):  # rows
-            for j in range(3):  # columns
-                center_x = room_size * j + room_size / 2
-                center_z = room_size * i + room_size / 2
-                # Two goals per room: center-left and center-right
-                goal_positions.append(
-                    [
-                        [center_x - 1.0, 0.0, center_z],  # left goal
-                        [center_x + 1.0, 0.0, center_z],  # right goal
-                    ]
-                )
+        goal_positions = GridRoomsEnvironment._generate_goal_positions(
+            3, room_size, goals_per_room=2
+        )
 
         super().__init__(
             grid_size=3,