miniworld-maze 1.0.0__py3-none-any.whl

miniworld_maze/environments/twenty_five_rooms.py

@@ -0,0 +1,122 @@
+"""TwentyFiveRooms environment implementation."""
+
+from ..core import ObservationLevel
+from .base_grid_rooms import GridRoomsEnvironment
+
+
+class TwentyFiveRooms(GridRoomsEnvironment):
+    """
+    Traverse the 25 rooms
+
+    ---------------------
+    | 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 |
+    ---------------------
+    """
+
+    def __init__(
+        self,
+        connections=None,
+        textures=None,
+        placed_room=None,
+        obs_level=ObservationLevel.TOP_DOWN_PARTIAL,
+        continuous=False,
+        room_size=5,
+        door_size=2,
+        agent_mode=None,
+        obs_width=80,
+        obs_height=80,
+        **kwargs,
+    ):
+        # Default configuration for TwentyFiveRooms
+        default_connections = [
+            (0, 1),
+            (0, 5),
+            (1, 2),
+            (1, 6),
+            (2, 3),
+            (2, 7),
+            (3, 4),
+            (3, 8),
+            (4, 9),
+            (5, 6),
+            (5, 10),
+            (6, 7),
+            (6, 11),
+            (7, 8),
+            (7, 12),
+            (8, 9),
+            (8, 13),
+            (9, 14),
+            (10, 11),
+            (10, 15),
+            (11, 12),
+            (11, 16),
+            (12, 13),
+            (12, 17),
+            (13, 14),
+            (13, 18),
+            (14, 19),
+            (15, 16),
+            (15, 20),
+            (16, 17),
+            (16, 21),
+            (17, 18),
+            (17, 22),
+            (18, 19),
+            (18, 23),
+            (19, 24),
+            (20, 21),
+            (21, 22),
+            (22, 23),
+            (23, 24),
+        ]
+        default_textures = [
+            "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",
+        ]
+
+        super().__init__(
+            grid_size=5,
+            connections=connections or default_connections,
+            textures=textures or default_textures,
+            placed_room=placed_room,
+            obs_level=obs_level,
+            continuous=continuous,
+            room_size=room_size,
+            door_size=door_size,
+            agent_mode=agent_mode,
+            obs_width=obs_width,
+            obs_height=obs_height,
+            **kwargs,
+        )

miniworld_maze/tools/__init__.py

@@ -0,0 +1,5 @@
+"""Tools for Nine Rooms environments."""
+
+from .generate_observations import generate_observations, main
+
+__all__ = ["generate_observations", "main"]

miniworld_maze/tools/generate_observations.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""
+Generate comprehensive observations for Nine Rooms environment variants.
+Supports: NineRooms, SpiralNineRooms, TwentyFiveRooms
+"""
+
+import argparse
+import os
+
+import numpy as np
+from PIL import Image
+
+from ..core import FrameBuffer
+from ..environments.factory import create_nine_rooms_env
+
+
+def generate_observations(variant, output_dir=None, high_res_full_views=False):
+    """Generate comprehensive observations for the specified environment variant."""
+    if output_dir is None:
+        output_dir = f"{variant.lower()}_observations"
+
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Create environment
+    env = create_nine_rooms_env(variant=variant, size=64)
+
+    # Get base environment for direct render access
+    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
+        elif hasattr(base_env, "_env"):
+            base_env = base_env._env
+        else:
+            break
+
+    # Reset environment
+    obs, _ = env.reset(seed=42)
+
+    # Create high-resolution frame buffer if requested
+    high_res_fb = None
+    if high_res_full_views:
+        high_res_fb = FrameBuffer(512, 512, 8)
+
+    # === FULL ENVIRONMENT OBSERVATIONS ===
+
+    # 1. Full view with agent at starting position
+    if high_res_full_views:
+        full_view_start = base_env.render_top_view(
+            frame_buffer=high_res_fb, POMDP=False
+        )
+    else:
+        full_view_start = base_env.render_top_view(POMDP=False)
+    Image.fromarray(full_view_start).save(f"{output_dir}/full_view_start.png")
+
+    # 2. Full view without agent (clean maze view)
+    if high_res_full_views:
+        full_view_clean = base_env.render_top_view(
+            frame_buffer=high_res_fb, POMDP=False, render_ag=False
+        )
+    else:
+        full_view_clean = base_env.render_top_view(POMDP=False, render_ag=False)
+    Image.fromarray(full_view_clean).save(f"{output_dir}/full_view_clean.png")
+
+    # 3. Full view with agent in center
+    center_x = (base_env.min_x + base_env.max_x) / 2
+    center_z = (base_env.min_z + base_env.max_z) / 2
+    base_env.place_agent(pos=[center_x, 0.0, center_z])
+    if high_res_full_views:
+        full_view_center = base_env.render_top_view(
+            frame_buffer=high_res_fb, POMDP=False
+        )
+    else:
+        full_view_center = base_env.render_top_view(POMDP=False)
+    Image.fromarray(full_view_center).save(f"{output_dir}/full_view_center.png")
+
+    # === PARTIAL OBSERVATIONS ===
+
+    # Reset agent to start position
+    base_env.place_agent(pos=[2.5, 0.0, 2.5])
+
+    # 1. Partial view from starting position
+    partial_start = base_env.render_top_view(POMDP=True)
+    Image.fromarray(partial_start).save(f"{output_dir}/partial_start.png")
+
+    # 2. Partial view from center
+    base_env.place_agent(pos=[center_x, 0.0, center_z])
+    partial_center = base_env.render_top_view(POMDP=True)
+    Image.fromarray(partial_center).save(f"{output_dir}/partial_center.png")
+
+    # 3. Partial view from corner/edge
+    corner_x = base_env.max_x - 2.5
+    corner_z = base_env.max_z - 2.5
+    base_env.place_agent(pos=[corner_x, 0.0, corner_z])
+    partial_corner = base_env.render_top_view(POMDP=True)
+    Image.fromarray(partial_corner).save(f"{output_dir}/partial_corner.png")
+
+    # 4. Partial view at strategic location
+    if variant == "NineRooms":
+        strategic_x, strategic_z = 15.0, 7.5  # Room boundary
+    elif variant == "SpiralNineRooms":
+        strategic_x, strategic_z = 22.5, 15.0  # Center of spiral
+    else:  # TwentyFiveRooms
+        strategic_x, strategic_z = 37.5, 37.5  # Mid-outer area
+
+    base_env.place_agent(pos=[strategic_x, 0.0, strategic_z])
+    partial_strategic = base_env.render_top_view(POMDP=True)
+    Image.fromarray(partial_strategic).save(f"{output_dir}/partial_strategic.png")
+
+    # === WRAPPED OBSERVATIONS ===
+
+    # Reset environment
+    obs, _ = env.reset(seed=42)
+
+    # 1. Standard gymnasium observation
+    obs_hwc = np.transpose(obs, (1, 2, 0))
+    Image.fromarray(obs_hwc).save(f"{output_dir}/gymnasium_standard.png")
+
+    # 2. Observations after movement
+    actions = [2, 2, 1]  # move_forward, move_forward, turn_right
+    action_names = ["move_forward", "move_forward", "turn_right"]
+
+    for i, action in enumerate(actions):
+        obs, _, _, _, _ = env.step(action)
+        obs_hwc = np.transpose(obs, (1, 2, 0))
+        Image.fromarray(obs_hwc).save(
+            f"{output_dir}/gymnasium_step_{i + 1}_{action_names[i]}.png"
+        )
+
+    # === RENDER_ON_POS EXAMPLES ===
+
+    # Define test positions based on variant
+    if variant == "NineRooms":
+        test_positions = [
+            [7.5, 0.0, 7.5],  # top-middle room center
+            [37.5, 0.0, 37.5],  # bottom-right room center
+            [22.5, 0.0, 22.5],  # environment center
+            [7.5, 0.0, 22.5],  # middle-left room center
+        ]
+    elif variant == "SpiralNineRooms":
+        test_positions = [
+            [7.5, 0.0, 7.5],  # top-left room (spiral start)
+            [37.5, 0.0, 37.5],  # bottom-right room (spiral end)
+            [22.5, 0.0, 7.5],  # top-right room
+            [7.5, 0.0, 37.5],  # bottom-left room
+        ]
+    else:  # TwentyFiveRooms
+        test_positions = [
+            [37.5, 0.0, 37.5],  # room (1,1) - near corner
+            [112.5, 0.0, 112.5],  # room (4,4) - far corner
+            [75.0, 0.0, 75.0],  # center room (2,2)
+            [37.5, 0.0, 112.5],  # room (1,4) - opposite corner
+        ]
+
+    for i, pos in enumerate(test_positions):
+        render_obs = env.render_on_pos(pos)
+
+        # Convert CHW to HWC for PIL
+        if len(render_obs.shape) == 3 and render_obs.shape[0] == 3:
+            render_obs = np.transpose(render_obs, (1, 2, 0))
+
+        Image.fromarray(render_obs).save(f"{output_dir}/render_on_pos_{i + 1}.png")
+
+    env.close()
+    return output_dir
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Generate observations for Nine Rooms environment variants"
+    )
+    parser.add_argument(
+        "variant",
+        choices=["NineRooms", "SpiralNineRooms", "TwentyFiveRooms"],
+        help="Environment variant to use",
+    )
+    parser.add_argument(
+        "--output-dir",
+        type=str,
+        default=None,
+        help="Output directory for images (default: {variant}_observations)",
+    )
+    parser.add_argument(
+        "--high-res-full",
+        action="store_true",
+        help="Generate 512x512 high-resolution full environment views",
+    )
+
+    args = parser.parse_args()
+
+    output_dir = generate_observations(
+        args.variant, args.output_dir, args.high_res_full
+    )
+
+    return output_dir
+
+
+if __name__ == "__main__":
+    main()

miniworld_maze/wrappers/__init__.py

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

miniworld_maze/wrappers/image_transforms.py

@@ -0,0 +1,40 @@
+"""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

@@ -0,0 +1,108 @@
+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.