miniworld-maze 1.1.0__tar.gz → 1.3.0__tar.gz

{miniworld_maze-1.1.0 → miniworld_maze-1.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.3
 Name: miniworld-maze
-Version: 1.1.0
-Summary: Multi-room maze environments from the DrStrategy paper for reinforcement learning research
+Version: 1.3.0
+Summary: Multi-room maze environments from the DrStrategy paper. Provides NineRooms-v0, SpiralNineRooms-v0, and TwentyFiveRooms-v0 gymnasium environments.
 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>
@@ -46,9 +46,6 @@ 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'
@@ -83,6 +80,18 @@ pip install miniworld-maze
 
 ## Usage
 
+### Registered Environments
+
+This package registers the following gymnasium environments:
+
+| Environment ID | Description | Rooms | Max Steps |
+|---|---|---|---|
+| `NineRooms-v0` | Standard 3×3 grid with adjacent room connections | 9 | 1000 |
+| `SpiralNineRooms-v0` | 3×3 grid with spiral connection pattern | 9 | 1000 |
+| `TwentyFiveRooms-v0` | Large 5×5 grid with complex navigation | 25 | 1000 |
+
+All environments use `TOP_DOWN_PARTIAL` observation level and factory default room/door sizes by default.
+
 ### Basic Usage
 
 See `examples/basic_usage.py` for a complete working example:
@@ -95,12 +104,13 @@ 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
+import gymnasium as gym
+import miniworld_maze  # noqa: F401
 
 
 def main():
-    # Create environment
-    env = NineRoomsEnvironmentWrapper(variant="NineRooms", size=64)
+    # Create environment using gymnasium registry
+    env = gym.make("NineRooms-v0", obs_width=64, obs_height=64)
     obs, info = env.reset()
 
     # obs is a dictionary containing:
@@ -212,14 +222,15 @@ Each environment supports three different observation modes:
 All environments can be customized with the following parameters:
 
 ```python
-from miniworld_maze import NineRoomsEnvironmentWrapper
-from miniworld_maze.core import ObservationLevel
+import gymnasium as gym
+from miniworld_maze import ObservationLevel
+import miniworld_maze  # noqa: F401
 
-env = NineRoomsEnvironmentWrapper(
-    variant="NineRooms",                    # "NineRooms", "SpiralNineRooms", "TwentyFiveRooms"
+env = gym.make(
+    "NineRooms-v0",                        # Environment variant
     obs_level=ObservationLevel.TOP_DOWN_PARTIAL,  # Observation type
-    continuous=False,                       # Use continuous actions
-    size=64,                               # Observation image size (64x64)
+    obs_width=64,                          # Observation image width
+    obs_height=64,                         # Observation image height
     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"

{miniworld_maze-1.1.0 → miniworld_maze-1.3.0}/README.md

@@ -19,6 +19,18 @@ pip install miniworld-maze
 
 ## Usage
 
+### Registered Environments
+
+This package registers the following gymnasium environments:
+
+| Environment ID | Description | Rooms | Max Steps |
+|---|---|---|---|
+| `NineRooms-v0` | Standard 3×3 grid with adjacent room connections | 9 | 1000 |
+| `SpiralNineRooms-v0` | 3×3 grid with spiral connection pattern | 9 | 1000 |
+| `TwentyFiveRooms-v0` | Large 5×5 grid with complex navigation | 25 | 1000 |
+
+All environments use `TOP_DOWN_PARTIAL` observation level and factory default room/door sizes by default.
+
 ### Basic Usage
 
 See `examples/basic_usage.py` for a complete working example:
@@ -31,12 +43,13 @@ 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
+import gymnasium as gym
+import miniworld_maze  # noqa: F401
 
 
 def main():
-    # Create environment
-    env = NineRoomsEnvironmentWrapper(variant="NineRooms", size=64)
+    # Create environment using gymnasium registry
+    env = gym.make("NineRooms-v0", obs_width=64, obs_height=64)
     obs, info = env.reset()
 
     # obs is a dictionary containing:
@@ -148,14 +161,15 @@ Each environment supports three different observation modes:
 All environments can be customized with the following parameters:
 
 ```python
-from miniworld_maze import NineRoomsEnvironmentWrapper
-from miniworld_maze.core import ObservationLevel
+import gymnasium as gym
+from miniworld_maze import ObservationLevel
+import miniworld_maze  # noqa: F401
 
-env = NineRoomsEnvironmentWrapper(
-    variant="NineRooms",                    # "NineRooms", "SpiralNineRooms", "TwentyFiveRooms"
+env = gym.make(
+    "NineRooms-v0",                        # Environment variant
     obs_level=ObservationLevel.TOP_DOWN_PARTIAL,  # Observation type
-    continuous=False,                       # Use continuous actions
-    size=64,                               # Observation image size (64x64)
+    obs_width=64,                          # Observation image width
+    obs_height=64,                         # Observation image height
     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"

{miniworld_maze-1.1.0 → miniworld_maze-1.3.0}/examples/basic_usage.py

@@ -5,12 +5,13 @@ 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
+import gymnasium as gym
+import miniworld_maze  # noqa: F401
 
 
 def main():
-    # Create environment
-    env = NineRoomsEnvironmentWrapper(variant="NineRooms", size=64)
+    # Create environment using gymnasium registry
+    env = gym.make("NineRooms-v0", obs_width=64, obs_height=64)
     obs, info = env.reset()
 
     # obs is a dictionary containing:

{miniworld_maze-1.1.0 → miniworld_maze-1.3.0}/examples/benchmark_rendering.py

@@ -23,7 +23,8 @@ from miniworld_maze.core.constants import (
     MB_TO_BYTES,
     RGB_CHANNELS,
 )
-from miniworld_maze.environments.factory import NineRoomsEnvironmentWrapper
+import gymnasium as gym
+import miniworld_maze  # noqa: F401
 
 
 def benchmark_rendering_performance(
@@ -58,7 +59,12 @@ def benchmark_rendering_performance(
         print(f"\n🔍 Testing {size}x{size} observations...")
 
         # Create environment with specific observation size
-        env = NineRoomsEnvironmentWrapper(variant, size=size)
+        variant_mapping = {
+            "NineRooms": "NineRooms-v0",
+            "SpiralNineRooms": "SpiralNineRooms-v0", 
+            "TwentyFiveRooms": "TwentyFiveRooms-v0"
+        }
+        env = gym.make(variant_mapping[variant], obs_width=size, obs_height=size)
 
         # Warmup phase
         print(f"   🔥 Warming up ({num_warmup} steps)...")

{miniworld_maze-1.1.0 → miniworld_maze-1.3.0}/examples/generate_observations.py

@@ -10,10 +10,12 @@ import os
 import numpy as np
 from PIL import Image
 
+import gymnasium as gym
+
 from miniworld_maze.core.miniworld_gymnasium.rendering.framebuffer import (
     FrameBuffer,
 )
-from miniworld_maze.environments.factory import NineRoomsEnvironmentWrapper
+import miniworld_maze  # noqa: F401
 
 
 def generate_observations(variant, output_dir=None, high_res_full_views=False):
@@ -24,7 +26,12 @@ def generate_observations(variant, output_dir=None, high_res_full_views=False):
     os.makedirs(output_dir, exist_ok=True)
 
     # Create environment
-    env = NineRoomsEnvironmentWrapper(variant=variant, size=64)
+    variant_mapping = {
+        "NineRooms": "NineRooms-v0",
+        "SpiralNineRooms": "SpiralNineRooms-v0",
+        "TwentyFiveRooms": "TwentyFiveRooms-v0"
+    }
+    env = gym.make(variant_mapping[variant], obs_width=64, obs_height=64)
 
     # Get base environment for direct render access
     base_env = env.env if hasattr(env, "env") else env
@@ -157,7 +164,7 @@ def generate_observations(variant, output_dir=None, high_res_full_views=False):
 
     for i, (pos, pos_name) in enumerate(test_positions):
         # First-person view from agent's perspective
-        render_obs = env.render_on_pos(pos)
+        render_obs = base_env.render_on_pos(pos)
 
         # Convert CHW to HWC for PIL
         if len(render_obs.shape) == 3 and render_obs.shape[0] == 3:

{miniworld_maze-1.1.0 → miniworld_maze-1.3.0}/examples/live_control_opencv.py

@@ -28,7 +28,15 @@ from typing import Optional
 import cv2
 import numpy as np
 
-from miniworld_maze import NineRoomsEnvironmentWrapper, ObservationLevel
+import gymnasium as gym
+
+from miniworld_maze import ObservationLevel
+import miniworld_maze  # noqa: F401
+from miniworld_maze.utils import (
+    clamp_pixel_coords,
+    environment_to_pixel_coords,
+    get_environment_bounds,
+)
 
 OPENCV_AVAILABLE = True
 
@@ -110,18 +118,25 @@ class OpenCVLiveController:
         print(f"🔄 Creating {variant} environments...")
 
         # Create main environment (ego view)
-        self.env = NineRoomsEnvironmentWrapper(
-            variant=variant,
-            size=self.size,
+        variant_mapping = {
+            "NineRooms": "NineRooms-v0",
+            "SpiralNineRooms": "SpiralNineRooms-v0",
+            "TwentyFiveRooms": "TwentyFiveRooms-v0"
+        }
+        self.env = gym.make(
+            variant_mapping[variant],
+            obs_width=self.size,
+            obs_height=self.size,
             obs_level=self.obs_level,
             agent_mode="triangle",  # Make agent visible for better demo
             info_obs=[ObservationLevel.FIRST_PERSON],
         )
 
         # Create separate environment for top-down map
-        self.map_env = NineRoomsEnvironmentWrapper(
-            variant=variant,
-            size=self.size,
+        self.map_env = gym.make(
+            variant_mapping[variant],
+            obs_width=self.size,
+            obs_height=self.size,
             obs_level=ObservationLevel.TOP_DOWN_FULL,
             # Always use full top-down for map
             agent_mode="triangle",  # Make agent visible in map view
@@ -130,7 +145,7 @@ class OpenCVLiveController:
 
         # Synchronize both environments to same initial state
         obs, info = self.env.reset(seed=42)
-        map_obs, map_info = self.map_env.reset(seed=42)
+        map_obs, _ = self.map_env.reset(seed=42)
 
         # Store info for accessing additional observations
         self.current_info = info
@@ -216,138 +231,100 @@ class OpenCVLiveController:
 
     def get_map_view_display(self) -> Optional[np.ndarray]:
         """
-        Get current map observation with agent rendered by the engine.
+        Get current map observation with agent and goal markers.
 
         Returns:
             BGR image array for OpenCV or None if failed
         """
-        if self.map_env is not None:
-            # Get base environment to access the new get_observation method
-            base_env = self.map_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
-
-            # Use the new get_observation method with agent rendering enabled
-            if hasattr(base_env, "get_observation"):
-                map_obs_with_agent = base_env.get_observation(render_agent=True)
-
-                if map_obs_with_agent is not None:
-                    # get_observation returns HWC format, so use directly
-                    obs_hwc = map_obs_with_agent
-
-                    # Convert RGB to BGR for OpenCV
-                    obs_bgr = cv2.cvtColor(obs_hwc, cv2.COLOR_RGB2BGR)
-
-                    # Resize for display
-                    obs_resized = cv2.resize(obs_bgr, (self.view_size, self.view_size))
-
-                    return obs_resized
-                else:
-                    return self._create_placeholder("No Map View")
-            else:
-                # Fallback to current observation with manual overlay (HWC format)
-                if self.current_map_obs is not None:
-                    obs_hwc = self.current_map_obs  # Already in HWC format
-                    obs_bgr = cv2.cvtColor(obs_hwc, cv2.COLOR_RGB2BGR)
-                    obs_resized = cv2.resize(obs_bgr, (self.view_size, self.view_size))
-                    return self._add_agent_marker(obs_resized)
-                else:
-                    return self._create_placeholder("No Map View")
-        else:
-            return self._create_placeholder("No Map View")
+        # Use current map observation with manual overlay
+        obs_hwc = self.current_map_obs  # Already in HWC format
+        obs_bgr = cv2.cvtColor(obs_hwc, cv2.COLOR_RGB2BGR)
+        obs_resized = cv2.resize(obs_bgr, (self.view_size, self.view_size))
+        return self._add_agent_marker(obs_resized)
 
     def _add_agent_marker(self, map_image: np.ndarray) -> np.ndarray:
         """
-        Add agent position and orientation marker to the map view.
+        Add agent and goal position markers to the map view.
 
         Args:
             map_image: The top-down map image
 
         Returns:
-            Map image with agent marker
+            Map image with agent and goal markers
         """
-        # Get access to the base environment to read agent position
-        base_env = self.map_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
-
-        # Get agent position and orientation
-        if hasattr(base_env, "agent") and base_env.agent is not None:
-            agent_pos = base_env.agent.pos
-            agent_dir = base_env.agent.dir
-
-            # Convert world coordinates to pixel coordinates
-            # Environment bounds
-            env_min_x = base_env.min_x
-            env_max_x = base_env.max_x
-            env_min_z = base_env.min_z
-            env_max_z = base_env.max_z
-
-            # Convert agent position to pixel coordinates
-            pixel_x = int(
-                (agent_pos[0] - env_min_x) / (env_max_x - env_min_x) * self.view_size
-            )
-            pixel_z = int(
-                (agent_pos[2] - env_min_z) / (env_max_z - env_min_z) * self.view_size
-            )
+        # Get positions from info dictionary - these are guaranteed to be available
+        agent_pos_2d = self.current_info["agent_position"]  # [x, z] coordinates as ndarray
+        goal_pos_2d = self.current_info["goal_position"]  # [x, z] coordinates as ndarray
 
-            # Clamp to image bounds
-            pixel_x = max(0, min(self.view_size - 1, pixel_x))
-            pixel_z = max(0, min(self.view_size - 1, pixel_z))
-
-            # Create a copy to avoid modifying the original
-            marked_image = map_image.copy()
-
-            # Draw agent position as a circle
-            agent_radius = max(5, self.view_size // 80)  # Scale with image size
-            cv2.circle(
-                marked_image, (pixel_x, pixel_z), agent_radius, (0, 255, 255), -1
-            )  # Yellow filled circle
-            cv2.circle(
-                marked_image, (pixel_x, pixel_z), agent_radius + 2, (0, 0, 0), 2
-            )  # Black outline
-
-            # Draw direction indicator (small arrow/line)
-            if agent_dir is not None:
-                # Calculate direction vector
-                dir_length = agent_radius + 8
-                end_x = int(pixel_x + dir_length * math.cos(agent_dir))
-                end_z = int(pixel_z + dir_length * math.sin(agent_dir))
-
-                # Draw direction line
-                cv2.line(
-                    marked_image, (pixel_x, pixel_z), (end_x, end_z), (0, 255, 0), 3
-                )  # Green direction line
-
-                # Draw small arrowhead
-                arrow_size = 5
-                arrow_angle = 0.5  # radians
-
-                # Calculate arrowhead points
-                left_x = int(end_x - arrow_size * math.cos(agent_dir - arrow_angle))
-                left_z = int(end_z - arrow_size * math.sin(agent_dir - arrow_angle))
-                right_x = int(end_x - arrow_size * math.cos(agent_dir + arrow_angle))
-                right_z = int(end_z - arrow_size * math.sin(agent_dir + arrow_angle))
-
-                # Draw arrowhead
-                cv2.line(marked_image, (end_x, end_z), (left_x, left_z), (0, 255, 0), 2)
-                cv2.line(
-                    marked_image, (end_x, end_z), (right_x, right_z), (0, 255, 0), 2
-                )
+        # Get environment bounds using utility function
+        env_min_bounds, env_max_bounds = get_environment_bounds(self.map_env)
+        env_min_bounds = np.array(env_min_bounds)
+        env_max_bounds = np.array(env_max_bounds)
 
-            return marked_image
-        else:
-            return map_image
+        # Create a copy to avoid modifying the original
+        marked_image = map_image.copy()
+
+        # Convert goal position to pixel coordinates and clamp
+        goal_pixel_x, goal_pixel_z = environment_to_pixel_coords(
+            goal_pos_2d, env_min_bounds, env_max_bounds, self.view_size
+        )
+        goal_pixel_x, goal_pixel_z = clamp_pixel_coords(
+            goal_pixel_x, goal_pixel_z, self.view_size
+        )
+
+        # Draw goal as a red circle
+        goal_radius = max(7, self.view_size // 70)
+        cv2.circle(
+            marked_image, (goal_pixel_x, goal_pixel_z), goal_radius, (0, 0, 255), -1
+        )  # Red filled circle
+        cv2.circle(
+            marked_image,
+            (goal_pixel_x, goal_pixel_z),
+            goal_radius + 2,
+            (255, 255, 255),
+            2,
+        )  # White outline
+
+        # Convert agent position to pixel coordinates and clamp
+        pixel_x, pixel_z = environment_to_pixel_coords(
+            agent_pos_2d, env_min_bounds, env_max_bounds, self.view_size
+        )
+        pixel_x, pixel_z = clamp_pixel_coords(pixel_x, pixel_z, self.view_size)
+
+        # Draw agent position as a circle
+        agent_radius = max(5, self.view_size // 80)
+        cv2.circle(
+            marked_image, (pixel_x, pixel_z), agent_radius, (0, 255, 255), -1
+        )  # Yellow filled circle
+        cv2.circle(
+            marked_image, (pixel_x, pixel_z), agent_radius + 2, (0, 0, 0), 2
+        )  # Black outline
+
+        # Draw direction indicator
+        # Get base environment for agent direction
+        base_env = self.map_env.unwrapped
+        agent_dir = base_env.agent.dir
+        dir_length = agent_radius + 8
+        end_x = int(pixel_x + dir_length * math.cos(agent_dir))
+        end_z = int(pixel_z + dir_length * math.sin(agent_dir))
+
+        # Draw direction line
+        cv2.line(
+            marked_image, (pixel_x, pixel_z), (end_x, end_z), (0, 255, 0), 3
+        )  # Green direction line
+
+        # Draw arrowhead
+        arrow_size = 5
+        arrow_angle = 0.5  # radians
+        left_x = int(end_x - arrow_size * math.cos(agent_dir - arrow_angle))
+        left_z = int(end_z - arrow_size * math.sin(agent_dir - arrow_angle))
+        right_x = int(end_x - arrow_size * math.cos(agent_dir + arrow_angle))
+        right_z = int(end_z - arrow_size * math.sin(agent_dir + arrow_angle))
+
+        cv2.line(marked_image, (end_x, end_z), (left_x, left_z), (0, 255, 0), 2)
+        cv2.line(marked_image, (end_x, end_z), (right_x, right_z), (0, 255, 0), 2)
+
+        return marked_image
 
     def _create_placeholder(self, text: str) -> np.ndarray:
         """Create a placeholder image with text."""
@@ -484,16 +461,18 @@ class OpenCVLiveController:
         legend_y = goal_y + 20
         legend_font_scale = 0.4
 
-        # Legend text - agent is now rendered by the engine
-        cv2.putText(
-            combined_img,
-            "Agent Rendered by Engine",
-            (legend_x, legend_y),
-            font,
-            legend_font_scale,
-            (200, 200, 200),
-            1,
-        )
+        # Legend text - positions from info dict
+        legend_lines = ["Yellow: Agent (from info)", "Red: Goal (from info)"]
+        for i, line in enumerate(legend_lines):
+            cv2.putText(
+                combined_img,
+                line,
+                (legend_x, legend_y + i * 15),
+                font,
+                legend_font_scale,
+                (200, 200, 200),
+                1,
+            )
 
         # Create info panel at bottom
         info_y = self.view_size + 70
@@ -560,7 +539,7 @@ class OpenCVLiveController:
                 # Use same seed to keep environments synchronized
                 seed = np.random.randint(0, 1000000)
                 obs, info = self.env.reset(seed=seed)
-                map_obs, map_info = self.map_env.reset(seed=seed)
+                map_obs, _ = self.map_env.reset(seed=seed)
 
                 # Store info for accessing additional observations
                 self.current_info = info
@@ -588,9 +567,7 @@ class OpenCVLiveController:
             action = self.action_map[key]
             # Step both environments with the same action
             obs, reward, terminated, truncated, info = self.env.step(action)
-            map_obs, map_reward, map_terminated, map_truncated, map_info = (
-                self.map_env.step(action)
-            )
+            map_obs, _, _, _, _ = self.map_env.step(action)
 
             # Store info for accessing additional observations
             self.current_info = info
@@ -622,7 +599,7 @@ class OpenCVLiveController:
                 # Reset both environments with same seed
                 seed = np.random.randint(0, 1000000)
                 obs, info = self.env.reset(seed=seed)
-                map_obs, map_info = self.map_env.reset(seed=seed)
+                map_obs, _ = self.map_env.reset(seed=seed)
                 # Store info for accessing additional observations
                 self.current_info = info
                 # Extract observation array from dict
@@ -740,7 +717,7 @@ def main():
 
     # Convert string to enum
     obs_level_map = {
-        "FIRST_PERSON": ObservationLevel.TOP_DOWN_PARTIAL,
+        "FIRST_PERSON": ObservationLevel.FIRST_PERSON,
         "TOP_DOWN_PARTIAL": ObservationLevel.TOP_DOWN_PARTIAL,
         "TOP_DOWN_FULL": ObservationLevel.TOP_DOWN_FULL,
     }

{miniworld_maze-1.1.0 → miniworld_maze-1.3.0}/examples/observation_level_demo.py

@@ -6,8 +6,10 @@ This example shows how to use the descriptive enum values instead of magic numbe
 """
 
 from PIL import Image
+import gymnasium as gym
 
-from miniworld_maze import NineRoomsEnvironmentWrapper, ObservationLevel
+from miniworld_maze import ObservationLevel
+import miniworld_maze  # noqa: F401
 
 
 def main():
@@ -27,10 +29,11 @@ def main():
         print(f"\n🔍 Testing {obs_level.name}...")
 
         # Create environment with specific observation level
-        env = NineRoomsEnvironmentWrapper(
-            variant="NineRooms",
+        env = gym.make(
+            "NineRooms-v0",
             obs_level=obs_level,  # Using descriptive enum!
-            size=64,
+            obs_width=64,
+            obs_height=64,
         )
 
         # Reset and get observation