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

miniworld_maze/__init__.py

@@ -18,8 +18,6 @@ Main modules:
 from .core import ObservationLevel
 from .environments.factory import (
     NineRoomsEnvironmentWrapper,
-    create_drstrategy_env,
-    create_nine_rooms_env,
 )
 from .environments.nine_rooms import NineRooms
 from .environments.spiral_nine_rooms import SpiralNineRooms
@@ -27,8 +25,6 @@ from .environments.twenty_five_rooms import TwentyFiveRooms
 
 __version__ = "1.0.0"
 __all__ = [
-    "create_drstrategy_env",
-    "create_nine_rooms_env",  # deprecated but kept for backward compatibility
     "NineRoomsEnvironmentWrapper",
     "NineRooms",
     "SpiralNineRooms",

miniworld_maze/core/miniworld_gymnasium/unified_env.py

@@ -3,6 +3,7 @@
 import math
 from ctypes import POINTER
 from enum import IntEnum
+from typing import List, Optional
 
 import gymnasium as gym
 import numpy as np
@@ -10,6 +11,7 @@ import pyglet
 from gymnasium import spaces
 from pyglet.gl import *
 
+from ..observation_types import ObservationLevel
 from .entities import *
 from .math import *
 from .objmesh import *
@@ -95,6 +97,7 @@ class UnifiedMiniWorldEnv(gym.Env):
         window_height=DEFAULT_WINDOW_HEIGHT,
         params=DEFAULT_PARAMS,
         domain_rand=False,
+        info_obs: Optional[List[ObservationLevel]] = None,
     ):
         """
         Initialize unified MiniWorld environment.
@@ -110,6 +113,7 @@ class UnifiedMiniWorldEnv(gym.Env):
             window_height: Window height for human rendering
             params: Environment parameters for domain randomization
             domain_rand: Whether to enable domain randomization
+            info_obs: List of observation levels to include in info dictionary
         """
         # Store configuration
         self.obs_level = obs_level
@@ -118,6 +122,7 @@ class UnifiedMiniWorldEnv(gym.Env):
         self.max_episode_steps = max_episode_steps
         self.params = params
         self.domain_rand = domain_rand
+        self.info_obs = info_obs
 
         # Setup action space
         self._setup_action_space()
@@ -329,8 +334,20 @@ class UnifiedMiniWorldEnv(gym.Env):
         # Generate the first camera image
         obs = self._generate_observation()
 
+        # 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
+                # Use the observation level name as key
+                info[str(obs_level)] = info_obs
+
         # Return first observation with info dict for Gymnasium compatibility
-        return obs, {}
+        return obs, info
 
     def _generate_observation(self, render_agent: bool = None):
         """Generate observation based on current observation level.
@@ -369,18 +386,6 @@ class UnifiedMiniWorldEnv(gym.Env):
                 f"Invalid obs_level {self.obs_level}. Must be one of {valid_levels}"
             )
 
-    def get_observation(self, render_agent: bool = None):
-        """Public method to generate observation with optional agent rendering control.
-
-        Args:
-            render_agent: Whether to render the agent in the observation.
-                         If None, uses default behavior based on observation level.
-
-        Returns:
-            np.ndarray: Generated observation image
-        """
-        return self._generate_observation(render_agent=render_agent)
-
     def _calculate_carried_object_position(self, agent_pos, ent):
         """Compute the position at which to place an object being carried."""
         dist = self.agent.radius + ent.radius + self.max_forward_step
@@ -577,21 +582,37 @@ class UnifiedMiniWorldEnv(gym.Env):
         if self.obs_level != 2:  # Not TOP_DOWN_FULL
             topdown = self.render_top_view(POMDP=False, frame_buffer=self.topdown_fb)
 
+        # 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
+                # Use the observation level name as key
+                info[str(obs_level)] = info_obs
+
         # Check termination
         if self.step_count >= self.max_episode_steps:
             terminated = True
             reward = 0
-            info = {
-                "pos": self.agent.pos,
-                "mdp_view": topdown if topdown is not None else observation,
-            }
+            info.update(
+                {
+                    "pos": self.agent.pos,
+                    "mdp_view": topdown if topdown is not None else observation,
+                }
+            )
         else:
             reward = 0
             terminated = False
-            info = {
-                "pos": self.agent.pos,
-                "mdp_view": topdown if topdown is not None else observation,
-            }
+            info.update(
+                {
+                    "pos": self.agent.pos,
+                    "mdp_view": topdown if topdown is not None else observation,
+                }
+            )
 
         return reward, terminated, info
 

miniworld_maze/environments/__init__.py

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

miniworld_maze/environments/base_grid_rooms.py

@@ -2,6 +2,8 @@
 
 from typing import List, Optional, Tuple, Union
 
+import cv2
+import numpy as np
 from gymnasium import spaces
 
 from ..core import COLORS, Box, ObservationLevel
@@ -35,6 +37,7 @@ class GridRoomsEnvironment(UnifiedMiniWorldEnv):
         grid_size: int,
         connections: List[Tuple[int, int]],
         textures: List[str],
+        goal_positions: List[List[List[float]]],
         placed_room: Optional[int] = None,
         obs_level: ObservationLevel = ObservationLevel.TOP_DOWN_PARTIAL,
         continuous: bool = False,
@@ -52,6 +55,7 @@ class GridRoomsEnvironment(UnifiedMiniWorldEnv):
             grid_size: Size of the grid (e.g., 3 for 3x3 grid)
             connections: List of (room1, room2) tuples for connections
             textures: List of texture names for each room
+            goal_positions: List of goal positions for each room
             placed_room: Initial room index (defaults to 0)
             obs_level: Observation level (defaults to 1)
             continuous: Whether to use continuous actions (defaults to False)
@@ -77,6 +81,9 @@ class GridRoomsEnvironment(UnifiedMiniWorldEnv):
         )
         self.textures = textures
 
+        # Set goal positions
+        self.goal_positions = goal_positions
+
         # Set placed room
         if placed_room is None:
             self.placed_room = 0  # Start in the first room
@@ -101,6 +108,10 @@ class GridRoomsEnvironment(UnifiedMiniWorldEnv):
         # Mark this as a custom environment for background color handling
         self._is_custom_env = True
 
+        # Store observation dimensions for rendering (needed before super().__init__)
+        self.obs_width = obs_width
+        self.obs_height = obs_height
+
         super().__init__(
             obs_level=obs_level,
             max_episode_steps=MAX_EPISODE_STEPS,
@@ -114,6 +125,18 @@ class GridRoomsEnvironment(UnifiedMiniWorldEnv):
         if not self.continuous:
             self.action_space = spaces.Discrete(self.actions.move_forward + 1)
 
+        # Store original observation space before updating
+        original_obs_space = self.observation_space
+
+        # Update observation space to include desired_goal and achieved_goal
+        self.observation_space = spaces.Dict(
+            {
+                "observation": original_obs_space,
+                "desired_goal": original_obs_space,
+                "achieved_goal": original_obs_space,
+            }
+        )
+
     def _generate_world_layout(self, pos=None):
         rooms = []
 
@@ -201,4 +224,120 @@ class GridRoomsEnvironment(UnifiedMiniWorldEnv):
 
     def step(self, action):
         obs, reward, terminated, truncated, info = super().step(action)
-        return obs, reward, terminated, truncated, info
+
+        # Check if goal is achieved
+        if self.is_goal_achieved():
+            terminated = True
+            reward = 1.0  # Positive reward for achieving goal
+
+        # Return observation as dict
+        obs_dict = {
+            "observation": obs,
+            "desired_goal": self.desired_goal,
+            "achieved_goal": obs,
+        }
+        return obs_dict, reward, terminated, truncated, info
+
+    def reset(self, seed=None, options=None, pos=None):
+        """
+        Reset the environment and generate a new goal.
+
+        Args:
+            seed: Random seed
+            options: Additional options
+            pos: Agent starting position
+
+        Returns:
+            tuple: (observation, info)
+        """
+        # Call parent reset
+        obs, info = super().reset(seed=seed, options=options, pos=pos)
+
+        # Generate goal
+        self.desired_goal = self.get_goal()
+
+        # Return observation as dict with desired_goal and achieved_goal
+        obs_dict = {
+            "observation": obs,
+            "desired_goal": self.desired_goal,
+            "achieved_goal": obs,
+        }
+        return obs_dict, info
+
+    def get_goal(self):
+        """
+        Generate a goal by randomly selecting a room and goal position.
+
+        Returns:
+            np.ndarray: Rendered goal image
+        """
+        # Select random room
+        room_idx = np.random.randint(len(self.goal_positions))
+
+        # Select random goal within room
+        goal_idx = np.random.randint(len(self.goal_positions[room_idx]))
+
+        # Get goal position
+        goal_position = self.goal_positions[room_idx][goal_idx]
+        self._current_goal_position = goal_position
+        self._current_goal_room = room_idx
+        self._current_goal_idx = goal_idx
+
+        # Render goal image
+        goal_image = self.render_on_pos(goal_position)
+
+        return goal_image
+
+    def render_on_pos(self, pos):
+        """
+        Render observation from a specific position.
+
+        Args:
+            pos: Position to render from [x, y, z]
+
+        Returns:
+            np.ndarray: Rendered observation
+        """
+        # Store current agent position
+        current_pos = self.agent.pos.copy()
+
+        # Move agent to target position
+        self.place_agent(pos=pos)
+
+        # Render observation from this position
+        obs = self.render_top_view(POMDP=True, render_ag=False)
+
+        # Resize to match observation dimensions if needed
+        if obs.shape[:2] != (self.obs_height, self.obs_width):
+            obs = cv2.resize(
+                obs, (self.obs_width, self.obs_height), interpolation=cv2.INTER_AREA
+            )
+
+        # Restore agent position
+        self.place_agent(pos=current_pos)
+
+        return obs
+
+    def is_goal_achieved(self, pos=None, threshold=0.5):
+        """
+        Check if the agent has achieved the current goal.
+
+        Args:
+            pos: Agent position to check (uses current agent pos if None)
+            threshold: Distance threshold for goal achievement
+
+        Returns:
+            bool: True if goal is achieved
+        """
+        if pos is None:
+            pos = self.agent.pos
+
+        if not hasattr(self, "_current_goal_position"):
+            return False
+
+        # Convert to numpy arrays and calculate distance
+        pos_array = np.array(pos)
+        goal_array = np.array(self._current_goal_position)
+        distance = np.linalg.norm(pos_array - goal_array)
+
+        return bool(distance < threshold)

miniworld_maze/environments/factory.py

@@ -1,11 +1,12 @@
 """Factory for creating Nine Rooms environment variants."""
 
+from typing import List
+
 import gymnasium as gym
 import numpy as np
 
 from ..core import ObservationLevel
 from ..core.constants import FACTORY_DOOR_SIZE, FACTORY_ROOM_SIZE
-from ..wrappers.image_transforms import ImageToPyTorch
 from .nine_rooms import NineRooms
 from .spiral_nine_rooms import SpiralNineRooms
 from .twenty_five_rooms import TwentyFiveRooms
@@ -23,6 +24,7 @@ class NineRoomsEnvironmentWrapper(gym.Wrapper):
         room_size=FACTORY_ROOM_SIZE,
         door_size=FACTORY_DOOR_SIZE,
         agent_mode=None,
+        info_obs: List[ObservationLevel] = None,
     ):
         """
         Create a Nine Rooms environment variant.
@@ -35,6 +37,7 @@ class NineRoomsEnvironmentWrapper(gym.Wrapper):
             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
 
@@ -61,13 +64,13 @@ class NineRoomsEnvironmentWrapper(gym.Wrapper):
             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
-        env = ImageToPyTorch(base_env)
 
-        # Initialize gym.Wrapper with the wrapped environment
-        super().__init__(env)
+        # Initialize gym.Wrapper with the base environment
+        super().__init__(base_env)
 
     def render_on_pos(self, pos):
         """Render observation from a specific position."""
@@ -100,56 +103,3 @@ class NineRoomsEnvironmentWrapper(gym.Wrapper):
         return obs
 
 
-def create_drstrategy_env(variant="NineRooms", **kwargs):
-    """
-    Factory function to create DrStrategy environment variants.
-
-    Args:
-        variant: Environment variant ("NineRooms", "SpiralNineRooms", "TwentyFiveRooms")
-        **kwargs: Additional arguments passed to NineRoomsEnvironmentWrapper
-
-    Returns:
-        NineRoomsEnvironmentWrapper instance
-    """
-    return NineRoomsEnvironmentWrapper(variant=variant, **kwargs)
-
-
-# Backward compatibility alias
-def create_nine_rooms_env(variant="NineRooms", **kwargs):
-    """
-    Legacy factory function for backward compatibility.
-
-    Deprecated: Use create_drstrategy_env() instead.
-    """
-    import warnings
-
-    warnings.warn(
-        "create_nine_rooms_env() is deprecated. Use create_drstrategy_env() instead.",
-        DeprecationWarning,
-        stacklevel=2,
-    )
-    return create_drstrategy_env(variant=variant, **kwargs)
-
-
-# Legacy function - deprecated
-def NineRoomsFullyPureGymnasium(
-    name="NineRooms",
-    obs_level=ObservationLevel.TOP_DOWN_PARTIAL,
-    continuous=False,
-    size=64,
-):
-    """
-    Legacy function for backward compatibility.
-
-    Deprecated: Use create_drstrategy_env() instead.
-    """
-    import warnings
-
-    warnings.warn(
-        "NineRoomsFullyPureGymnasium() is deprecated. Use create_drstrategy_env() instead.",
-        DeprecationWarning,
-        stacklevel=2,
-    )
-    return create_drstrategy_env(
-        variant="NineRooms", obs_level=obs_level, continuous=continuous, size=size
-    )

miniworld_maze/environments/nine_rooms.py

@@ -58,10 +58,25 @@ class NineRooms(GridRoomsEnvironment):
             "cobaltgreen",
         ]
 
+        # 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
+                    ]
+                )
+
         super().__init__(
             grid_size=3,
             connections=connections or default_connections,
             textures=textures or default_textures,
+            goal_positions=goal_positions,
             placed_room=placed_room,
             obs_level=obs_level,
             continuous=continuous,

miniworld_maze/environments/spiral_nine_rooms.py

@@ -54,10 +54,25 @@ class SpiralNineRooms(GridRoomsEnvironment):
             "cobaltgreen",
         ]
 
+        # 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
+                    ]
+                )
+
         super().__init__(
             grid_size=3,
             connections=connections or default_connections,
             textures=textures or default_textures,
+            goal_positions=goal_positions,
             placed_room=placed_room,
             obs_level=obs_level,
             continuous=continuous,

miniworld_maze/environments/twenty_five_rooms.py

@@ -106,10 +106,24 @@ class TwentyFiveRooms(GridRoomsEnvironment):
             "realblueberry",
         ]
 
+        # Initialize goal positions for each room (1 goal per room at center)
+        goal_positions = []
+        for i in range(5):  # rows
+            for j in range(5):  # columns
+                center_x = room_size * j + room_size / 2
+                center_z = room_size * i + room_size / 2
+                # One goal per room at the center
+                goal_positions.append(
+                    [
+                        [center_x, 0.0, center_z],
+                    ]
+                )
+
         super().__init__(
             grid_size=5,
             connections=connections or default_connections,
             textures=textures or default_textures,
+            goal_positions=goal_positions,
             placed_room=placed_room,
             obs_level=obs_level,
             continuous=continuous,

miniworld_maze/tools/generate_observations.py

@@ -11,7 +11,7 @@ import numpy as np
 from PIL import Image
 
 from ..core import FrameBuffer
-from ..environments.factory import create_nine_rooms_env
+from ..environments.factory import NineRoomsEnvironmentWrapper
 
 
 def generate_observations(variant, output_dir=None, high_res_full_views=False):
@@ -22,10 +22,10 @@ def generate_observations(variant, output_dir=None, high_res_full_views=False):
     os.makedirs(output_dir, exist_ok=True)
 
     # Create environment
-    env = create_nine_rooms_env(variant=variant, size=64)
+    env = NineRoomsEnvironmentWrapper(variant=variant, size=64)
 
     # Get base environment for direct render access
-    base_env = getattr(env, 'env', getattr(env, '_env', env))
+    base_env = getattr(env, "env", getattr(env, "_env", env))
     while hasattr(base_env, "env") or hasattr(base_env, "_env"):
         if hasattr(base_env, "env"):
             base_env = base_env.env

miniworld_maze-1.1.0.dist-info/METADATA

@@ -0,0 +1,250 @@
+Metadata-Version: 2.3
+Name: miniworld-maze
+Version: 1.1.0
+Summary: Multi-room maze environments from the DrStrategy paper for reinforcement learning research
+Keywords: reinforcement-learning,environment,gymnasium,multi-room-maze,drstrategy,maze-navigation,partial-observability,3d-environments
+Author: Tim Joseph
+Author-email: Tim Joseph <tim@mctigger.com>
+License: MIT License
+         
+         Copyright (c) 2025 Tim Joseph
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Environment :: Console
+Classifier: Typing :: Typed
+Requires-Dist: gymnasium>=1.0.0,<2.0.0
+Requires-Dist: numpy>=1.20.0,<3.0.0
+Requires-Dist: opencv-python>=4.5.0,<5.0.0
+Requires-Dist: pillow>=8.0.0,<11.0.0
+Requires-Dist: pyopengl>=3.1.0,<4.0.0
+Requires-Dist: pyglet>=1.5.0,<2.0.0
+Requires-Dist: black>=22.0,<25.0 ; extra == 'dev'
+Requires-Dist: isort>=5.10,<6.0 ; extra == 'dev'
+Requires-Dist: flake8>=4.0,<7.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.1.0,<1.0.0 ; extra == 'dev'
+Requires-Dist: build>=0.8.0,<2.0.0 ; extra == 'dev'
+Requires-Dist: twine>=4.0.0,<6.0.0 ; extra == 'dev'
+Requires-Dist: mujoco>=2.3.0,<4.0.0 ; extra == 'mujoco'
+Requires-Python: >=3.8
+Project-URL: Bug Tracker, https://github.com/mctigger/miniworld-maze/issues
+Project-URL: Documentation, https://github.com/mctigger/miniworld-maze#readme
+Project-URL: Homepage, https://github.com/mctigger/miniworld-maze
+Project-URL: Repository, https://github.com/mctigger/miniworld-maze
+Provides-Extra: dev
+Provides-Extra: mujoco
+Description-Content-Type: text/markdown
+
+# MiniWorld DrStrategy - Multi-Room Maze Environment
+
+A refactored implementation of Dr. Strategy's MiniWorld-based maze environments with updated dependencies and modern Python packaging. Based on the now-deprecated [MiniWorld](https://github.com/Farama-Foundation/Miniworld) project and the original [DrStrategy implementation](https://github.com/ahn-ml/drstrategy).
+
+## Environment Observations
+
+### Environment Views
+Full environment layout and render-on-position views:
+
+| Full Environment | Partial Top-Down Observations | Partial First-Person Observations |
+|---|---|---|
+| ![Full View Clean](assets/images/full_view_clean.png) | ![Top Middle TD](assets/images/render_on_pos_1_top_middle_room_topdown.png) ![Center TD](assets/images/render_on_pos_3_environment_center_topdown.png) | ![Top Middle FP](assets/images/render_on_pos_1_top_middle_room_firstperson.png) ![Center FP](assets/images/render_on_pos_3_environment_center_firstperson.png) |
+
+## Installation
+
+```bash
+pip install miniworld-maze
+```
+
+## Usage
+
+### Basic Usage
+
+See `examples/basic_usage.py` for a complete working example:
+
+```python
+#!/usr/bin/env python3
+"""
+Basic usage example for miniworld-maze environments.
+
+This is a minimal example showing how to create and interact with the environment.
+"""
+
+from miniworld_maze import NineRoomsEnvironmentWrapper
+
+
+def main():
+    # Create environment
+    env = NineRoomsEnvironmentWrapper(variant="NineRooms", size=64)
+    obs, info = env.reset()
+
+    # obs is a dictionary containing:
+    # - 'observation': (64, 64, 3) RGB image array
+    # - 'desired_goal': (64, 64, 3) RGB image of the goal state
+    # - 'achieved_goal': (64, 64, 3) RGB image of the current state
+
+    # Take a few random actions
+    for step in range(10):
+        action = env.action_space.sample()
+        obs, reward, terminated, truncated, info = env.step(action)
+
+        print(f"Step {step + 1}: reward={reward:.3f}, terminated={terminated}")
+
+        if terminated or truncated:
+            obs, info = env.reset()
+
+    env.close()
+    print("Environment closed successfully!")
+
+
+if __name__ == "__main__":
+    main()
+```
+
+### Headless Environments
+
+When running in headless environments (servers, CI/CD, Docker containers) or when encountering X11/OpenGL context issues, you need to enable headless rendering:
+
+```bash
+# Set environment variable before running Python
+export PYGLET_HEADLESS=1
+python your_script.py
+```
+
+Or in your Python code (must be set before importing the library):
+
+```python
+import os
+os.environ['PYGLET_HEADLESS'] = '1'
+
+import miniworld_maze
+# ... rest of your code
+```
+
+This configures the underlying pyglet library to use EGL rendering instead of X11, allowing the environments to run without a display server.
+
+## Environment Variants
+
+### Available Environments
+
+The package provides three main environment variants, each with different room layouts and connection patterns:
+
+#### 1. NineRooms (3×3 Grid)
+```
+-------------
+| 0 | 1 | 2 |
+-------------
+| 3 | 4 | 5 |
+-------------
+| 6 | 7 | 8 |
+-------------
+```
+A standard 3×3 grid where adjacent rooms are connected. The agent can navigate between rooms through doorways, with connections forming a fully connected grid pattern.
+
+#### 2. SpiralNineRooms (3×3 Spiral Pattern)
+```
+-------------
+| 0 | 1 | 2 |
+-------------
+| 3 | 4 | 5 |
+-------------
+| 6 | 7 | 8 |
+-------------
+```
+Same room layout as NineRooms but with a spiral connection pattern. Only specific room pairs are connected, creating a more challenging navigation task with fewer available paths.
+
+#### 3. TwentyFiveRooms (5×5 Grid)
+```
+---------------------
+| 0 | 1 | 2 | 3 | 4 |
+---------------------
+| 5 | 6 | 7 | 8 | 9 |
+---------------------
+|10 |11 |12 |13 |14 |
+---------------------
+|15 |16 |17 |18 |19 |
+---------------------
+|20 |21 |22 |23 |24 |
+---------------------
+```
+A larger 5×5 grid environment with 25 rooms, providing more complex navigation challenges and longer episode lengths.
+
+### Observation Types
+
+Each environment supports three different observation modes:
+
+- **`TOP_DOWN_PARTIAL`** (default): Agent-centered partial top-down view with limited visibility range (POMDP)
+- **`TOP_DOWN_FULL`**: Complete top-down view showing the entire environment
+- **`FIRST_PERSON`**: 3D first-person perspective view from the agent's current position
+
+### Action Space
+
+- **Discrete Actions** (default): 7 discrete actions (turn left/right, move forward/backward, strafe left/right, no-op)
+- **Continuous Actions**: Continuous control with `continuous=True` parameter
+
+### Environment Configuration
+
+All environments can be customized with the following parameters:
+
+```python
+from miniworld_maze import NineRoomsEnvironmentWrapper
+from miniworld_maze.core import ObservationLevel
+
+env = NineRoomsEnvironmentWrapper(
+    variant="NineRooms",                    # "NineRooms", "SpiralNineRooms", "TwentyFiveRooms"
+    obs_level=ObservationLevel.TOP_DOWN_PARTIAL,  # Observation type
+    continuous=False,                       # Use continuous actions
+    size=64,                               # Observation image size (64x64)
+    room_size=5,                           # Size of each room in environment units
+    door_size=2,                           # Size of doors between rooms  
+    agent_mode="empty",                    # Agent rendering: "empty", "circle", "triangle"
+)
+```
+
+### Observation Format
+
+The environment returns observations in dictionary format:
+
+```python
+obs = {
+    'observation': np.ndarray,    # (64, 64, 3) RGB image of current view
+    'desired_goal': np.ndarray,   # (64, 64, 3) RGB image of goal location
+    'achieved_goal': np.ndarray,  # (64, 64, 3) RGB image of current state
+}
+```
+
+### Reward Structure
+
+- **Goal reaching**: Positive reward when agent reaches the goal location
+- **Step penalty**: Small negative reward per step to encourage efficiency
+- **Episode termination**: When goal is reached or maximum steps exceeded
+
+
+## License
+
+MIT License - see LICENSE file for details.

{miniworld_maze-1.0.0.dist-info → miniworld_maze-1.1.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-miniworld_maze/__init__.py,sha256=P5cqGqyF1wSO-ERuRWW8jTHXFVOAelvlIvNUrZKoJio,1215
+miniworld_maze/__init__.py,sha256=kz5QqyvwIV_XkjXw_yHRkhqlPSl8X1Usra3DF0Zy4_E,1053
 miniworld_maze/core/__init__.py,sha256=5BA4WKXQjrG55TNaEid2JGrnf1KQniJZ1HhRqovM1Q0,293
 miniworld_maze/core/constants.py,sha256=GX1pSnaWGOkangYStxaBy7gIQhWxVKIbXnTSd-eA_vs,3962
 miniworld_maze/core/miniworld_gymnasium/README.md,sha256=kkZgkRKBdgixpot3uHuiBFlRIKRFIVBVfXwu68XTEv0,74
@@ -260,21 +260,19 @@ miniworld_maze/core/miniworld_gymnasium/textures/white_1.png,sha256=wRrgs92I_Ids
 miniworld_maze/core/miniworld_gymnasium/textures/wood_1.png,sha256=XRZyIN34HFo14olbxRcsHGrzCAFqUlowc6nLR22IFBE,184713
 miniworld_maze/core/miniworld_gymnasium/textures/wood_2.png,sha256=qSDHB-ZO11JJLQuiQse-0edpbuTg1YO-eIBhdTvNUhc,93121
 miniworld_maze/core/miniworld_gymnasium/textures/wood_planks_1.png,sha256=E4SNN1s4yOtkLfZFQy905eip6KvDWnnPUrpS82FxMAg,847259
-miniworld_maze/core/miniworld_gymnasium/unified_env.py,sha256=lKP9IdBJSl2sUHPLIP5OK3ncNuod_dKvm4CJ3Gc0egQ,45674
+miniworld_maze/core/miniworld_gymnasium/unified_env.py,sha256=oY2YXCZ-ro8kl6ie0h8TEBooWjB6bvmQu42-1tDsrw4,46689
 miniworld_maze/core/miniworld_gymnasium/utils.py,sha256=9cfpg4qYz-Esxvu8nTMPFJc-Tl0TRxTrX6cfg0YuK_o,1007
 miniworld_maze/core/miniworld_gymnasium/wrappers.py,sha256=cD0nGSJYNU96zoWv63aEiKd986POhtHfGGEpNpRL5ec,122
 miniworld_maze/core/observation_types.py,sha256=Co8mEIXzIgk0MLx6tqeBd1EE0PuZOL1gbZwobiEde08,1316
-miniworld_maze/environments/__init__.py,sha256=hIrk8MulC725dMfslsqHtQus3dHL8C-vasUQeDphEnU,467
-miniworld_maze/environments/base_grid_rooms.py,sha256=RqL8Te1vk3JaCC2aq5RxI2omXm1lkfiOfVNx2Pe-ZWU,7602
-miniworld_maze/environments/factory.py,sha256=U7SnhTzsPy6VhARDMpnexKZwtJj0kh4CSzgRQBeEVjc,4914
-miniworld_maze/environments/nine_rooms.py,sha256=hZwRb2jjsGxbwCBv0dhpMKvgkpCNGrNZvFJWLTaFjxo,1727
-miniworld_maze/environments/spiral_nine_rooms.py,sha256=gDI2mLvaNmaxeM4Ara7RD1hGCjvETo60V3ar-SZZ-Dk,1675
-miniworld_maze/environments/twenty_five_rooms.py,sha256=xpc_d91s5j_mWhH-r9YpCTVqCEzB4mVcyoQ7ywWHXPU,2905
+miniworld_maze/environments/__init__.py,sha256=6O1G4vlhUSn8OuR46u-t4Wz3de8da76Tz21TsVlzBZo,415
+miniworld_maze/environments/base_grid_rooms.py,sha256=kpF6psn0YCfvA-q1vtU2KaqwmfQaPpX0w9jBTxt2qs8,11833
+miniworld_maze/environments/factory.py,sha256=g8qYF6UF9DsKExZIHhMsP8PX3b11kvmkLMwE2IpgBxc,3501
+miniworld_maze/environments/nine_rooms.py,sha256=0CzUkRy2hJZ4JEEj9E-6xCopseZ1u8iGCfKLaxwATGo,2368
+miniworld_maze/environments/spiral_nine_rooms.py,sha256=LB9wKQXp9S8pVd8JhM9zfsc5z4ksxsQxQKoEXrDgPhE,2316
+miniworld_maze/environments/twenty_five_rooms.py,sha256=ExF4Mt0B3pkaVQtBF7oaVxdj_9uaAkTFYCe83Lw8Evk,3448
 miniworld_maze/tools/__init__.py,sha256=PgkKMO21xnwIfJtD437P_RtkguOHoOSFV1ohsO-n7tc,150
-miniworld_maze/tools/generate_observations.py,sha256=1etBz2ndTZwPFghnLhp15l1WVUaBN5DkMwjyGtzyepA,6769
-miniworld_maze/wrappers/__init__.py,sha256=cdTbUbwDBRC_d9kdFV0e392F3-718elthLoBJII5Npg,130
-miniworld_maze/wrappers/image_transforms.py,sha256=4xr4HfateUKeJjFRBBew8z6LO72ygue4yQjAZgOgo5g,1199
-miniworld_maze-1.0.0.dist-info/WHEEL,sha256=4n27za1eEkOnA7dNjN6C5-O2rUiw6iapszm14Uj-Qmk,79
-miniworld_maze-1.0.0.dist-info/entry_points.txt,sha256=Ue03NHCOQCiJ87tqfJSns29C3Dw02jsZXL_Auzw2pb4,91
-miniworld_maze-1.0.0.dist-info/METADATA,sha256=GhSg5-xatBRjjkKZuhnkjfFExyH_R77BUDrCjgoLCEE,4775
-miniworld_maze-1.0.0.dist-info/RECORD,,
+miniworld_maze/tools/generate_observations.py,sha256=-WWoex0KY6PSMs4BenMTepeE4tA2NYZ26jIQL2tYfZY,6781
+miniworld_maze-1.1.0.dist-info/WHEEL,sha256=NHRAbdxxzyL9K3IO2LjmlNqKSyPZnKv2BD16YYVKo18,79
+miniworld_maze-1.1.0.dist-info/entry_points.txt,sha256=Ue03NHCOQCiJ87tqfJSns29C3Dw02jsZXL_Auzw2pb4,91
+miniworld_maze-1.1.0.dist-info/METADATA,sha256=atsdko20fA_iqS8y2muB0dQkLDnmLpP4ppuTuNLfcxA,9270
+miniworld_maze-1.1.0.dist-info/RECORD,,

{miniworld_maze-1.0.0.dist-info → miniworld_maze-1.1.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.8.13
+Generator: uv 0.8.14
 Root-Is-Purelib: true
 Tag: py3-none-any

miniworld_maze/wrappers/__init__.py

@@ -1,5 +0,0 @@
-"""Gymnasium wrappers for Nine Rooms environments."""
-
-from .image_transforms import ImageToPyTorch
-
-__all__ = ["ImageToPyTorch"]

miniworld_maze/wrappers/image_transforms.py

@@ -1,40 +0,0 @@
-"""Image transformation wrappers for Nine Rooms environments."""
-
-import gymnasium as gym
-import numpy as np
-from gymnasium import spaces
-
-
-class ImageToPyTorch(gym.ObservationWrapper):
-    """Convert HWC to CHW format for PyTorch compatibility."""
-
-    def __init__(self, env):
-        """
-        Initialize PyTorch-compatible image transformation wrapper.
-
-        Transforms observation space from HWC (Height, Width, Channels) format
-        to CHW (Channels, Height, Width) format expected by PyTorch models.
-
-        Args:
-            env: The environment to wrap
-        """
-        super(ImageToPyTorch, self).__init__(env)
-        obs_shape = self.observation_space.shape
-        self.observation_space = spaces.Box(
-            low=0,
-            high=255,
-            shape=(obs_shape[2], obs_shape[0], obs_shape[1]),
-            dtype=np.uint8,
-        )
-
-    def observation(self, observation):
-        """
-        Transform observation from HWC to CHW format.
-
-        Args:
-            observation: Input observation in HWC format (H, W, C)
-
-        Returns:
-            np.ndarray: Observation in CHW format (C, H, W)
-        """
-        return np.transpose(observation, (2, 0, 1))

miniworld_maze-1.0.0.dist-info/METADATA

@@ -1,108 +0,0 @@
-Metadata-Version: 2.3
-Name: miniworld-maze
-Version: 1.0.0
-Summary: Multi-room maze environments from the DrStrategy paper for reinforcement learning research
-Keywords: reinforcement-learning,environment,gymnasium,multi-room-maze,drstrategy,maze-navigation,partial-observability,3d-environments
-Author: Tim Joseph
-Author-email: Tim Joseph <tim@mctigger.com>
-License: MIT License
-         
-         Copyright (c) 2025 DrStrategy Research Team
-         
-         Permission is hereby granted, free of charge, to any person obtaining a copy
-         of this software and associated documentation files (the "Software"), to deal
-         in the Software without restriction, including without limitation the rights
-         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-         copies of the Software, and to permit persons to whom the Software is
-         furnished to do so, subject to the following conditions:
-         
-         The above copyright notice and this permission notice shall be included in all
-         copies or substantial portions of the Software.
-         
-         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-         SOFTWARE.
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Science/Research
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Environment :: Console
-Classifier: Typing :: Typed
-Requires-Dist: gymnasium>=1.0.0,<2.0.0
-Requires-Dist: numpy>=1.20.0,<3.0.0
-Requires-Dist: opencv-python>=4.5.0,<5.0.0
-Requires-Dist: pillow>=8.0.0,<11.0.0
-Requires-Dist: pyopengl>=3.1.0,<4.0.0
-Requires-Dist: pyglet>=1.5.0,<2.0.0
-Requires-Dist: black>=22.0,<25.0 ; extra == 'dev'
-Requires-Dist: isort>=5.10,<6.0 ; extra == 'dev'
-Requires-Dist: flake8>=4.0,<7.0 ; extra == 'dev'
-Requires-Dist: build>=0.8.0,<2.0.0 ; extra == 'dev'
-Requires-Dist: twine>=4.0.0,<6.0.0 ; extra == 'dev'
-Requires-Dist: mujoco>=2.3.0,<4.0.0 ; extra == 'mujoco'
-Requires-Python: >=3.8
-Project-URL: Bug Tracker, https://github.com/mctigger/miniworld-maze/issues
-Project-URL: Documentation, https://github.com/mctigger/miniworld-maze#readme
-Project-URL: Homepage, https://github.com/mctigger/miniworld-maze
-Project-URL: Repository, https://github.com/mctigger/miniworld-maze
-Provides-Extra: dev
-Provides-Extra: mujoco
-Description-Content-Type: text/markdown
-
-# MiniWorld DrStrategy - Multi-Room Maze Environment
-
-A refactored implementation of Dr. Strategy's MiniWorld-based maze environments with updated dependencies and modern Python packaging. Based on the now-deprecated [MiniWorld](https://github.com/Farama-Foundation/Miniworld) project and the original [DrStrategy implementation](https://github.com/ahn-ml/drstrategy).
-
-## Environment Observations
-
-### Environment Views
-Full environment layout and render-on-position views:
-
-| Full Environment | Partial Top-Down Observations | Partial First-Person Observations |
-|---|---|---|
-| ![Full View Clean](assets/images/full_view_clean.png) | ![Top Middle TD](assets/images/render_on_pos_1_top_middle_room_topdown.png) ![Center TD](assets/images/render_on_pos_3_environment_center_topdown.png) | ![Top Middle FP](assets/images/render_on_pos_1_top_middle_room_firstperson.png) ![Center FP](assets/images/render_on_pos_3_environment_center_firstperson.png) |
-
-## Installation
-
-```bash
-pip install miniworld-maze
-```
-
-## Usage
-
-```python
-from miniworld_drstrategy import create_nine_rooms_env
-
-# Create environment
-env = create_nine_rooms_env(variant="NineRooms", size=64)
-obs, info = env.reset()
-
-# Take actions
-action = env.action_space.sample()
-obs, reward, terminated, truncated, info = env.step(action)
-
-env.close()
-```
-
-## Environment Variants
-
-- **NineRooms**: 3×3 grid layout
-- **SpiralNineRooms**: Spiral connection pattern  
-- **TwentyFiveRooms**: 5×5 grid layout
-
-
-## License
-
-MIT License - see LICENSE file for details.