miniworld-maze 1.0.0__py3-none-any.whl

miniworld_maze/__init__.py

@@ -0,0 +1,37 @@
+"""
+MiniWorld DrStrategy - Multi-Room Maze Environment Package
+
+This package contains complete implementations of multi-room maze environment
+variants used in the DrStrategy paper, along with tools for generating observations.
+
+Available environment variants:
+- NineRooms: Classic 3x3 grid of rooms (9 rooms total)
+- SpiralNineRooms: 3x3 grid with spiral connections (9 rooms total)
+- TwentyFiveRooms: Large 5x5 grid with 40 connections (25 rooms total)
+
+Main modules:
+- environments: Environment implementations
+- wrappers: Gymnasium wrappers for PyTorch compatibility
+- tools: Observation generation and utilities
+"""
+
+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
+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",
+    "TwentyFiveRooms",
+    "ObservationLevel",
+]

miniworld_maze/core/__init__.py

@@ -0,0 +1,8 @@
+"""Core MiniWorld implementation."""
+
+from . import constants
+from .miniworld_gymnasium.entities import COLORS, Box
+from .miniworld_gymnasium.opengl import FrameBuffer
+from .observation_types import ObservationLevel
+
+__all__ = ["Box", "COLORS", "FrameBuffer", "ObservationLevel", "constants"]

miniworld_maze/core/constants.py

@@ -0,0 +1,130 @@
+"""Constants for Nine Rooms environments to improve code readability."""
+
+from typing import Final
+
+# ========================
+# ENVIRONMENT DIMENSIONS
+# ========================
+
+# Default room and door sizes
+DEFAULT_ROOM_SIZE: Final[int] = 5
+DEFAULT_DOOR_SIZE: Final[int] = 2
+FACTORY_ROOM_SIZE: Final[int] = 15  # Used in factory for larger environments
+FACTORY_DOOR_SIZE: Final[float] = 2.5
+
+# Agent dimensions
+AGENT_RADIUS: Final[float] = 0.5
+AGENT_START_POSITION: Final[tuple[float, float, float]] = (2.5, 0.0, 2.5)
+
+# ========================
+# OBSERVATION SETTINGS
+# ========================
+
+# Default observation dimensions
+DEFAULT_OBS_WIDTH: Final[int] = 80
+DEFAULT_OBS_HEIGHT: Final[int] = 80
+
+# POMDP view radius (units around agent)
+POMDP_VIEW_RADIUS: Final[float] = 2.5
+
+# Image color channels
+RGB_CHANNELS: Final[int] = 3
+PIXEL_VALUE_MAX: Final[int] = 255
+
+# ========================
+# ENVIRONMENT GENERATION
+# ========================
+
+# Box entity generation
+BOXES_PER_ROOM: Final[int] = 9
+BOX_GRID_SIZE: Final[int] = 3  # 3x3 grid of boxes per room
+BOX_SIZE_FRACTION: Final[float] = 2.0 / 15.0  # Box size relative to room size
+BOX_OFFSET_FRACTION: Final[float] = 0.16  # Offset from room edges
+
+# Room positioning
+ROOM_BOUNDARY_MARGIN: Final[float] = 0.05  # 95% of room size for boundaries
+ROOM_CENTER_FRACTION: Final[float] = 1.0 / 3.0  # Division for box positioning
+
+# ========================
+# PERFORMANCE SETTINGS
+# ========================
+
+# Episode limits
+MAX_EPISODE_STEPS: Final[int] = 1000
+
+# Warmup and benchmark defaults
+DEFAULT_BENCHMARK_STEPS: Final[int] = 100
+DEFAULT_WARMUP_STEPS: Final[int] = 10
+
+# ========================
+# OBSERVATION TEST POSITIONS
+# ========================
+
+
+# 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)
+
+
+# ========================
+# RENDERING CONSTANTS
+# ========================
+
+# Frame buffer settings
+DEFAULT_FRAME_BUFFER_SIZE: Final[int] = 512
+HIGH_RES_FRAME_BUFFER_SIZE: Final[int] = 512
+DEPTH_BUFFER_BITS: Final[int] = 8
+
+# Lighting
+DEFAULT_LIGHT_HEIGHT: Final[float] = 2.5
+AMBIENT_LIGHT_LEVEL: Final[float] = 0.45
+
+# Memory calculations (for benchmarking)
+FLOAT32_BYTES: Final[int] = 4
+MB_TO_BYTES: Final[int] = 1024 * 1024
+
+# ========================
+# OPENGL RENDERING CONSTANTS
+# ========================
+
+# Framebuffer scaling
+TOPDOWN_FRAMEBUFFER_SCALE: Final[int] = 20
+
+# Physics and interaction constants
+PICKUP_REACH_MULTIPLIER: Final[float] = 1.5
+PICKUP_RADIUS_MULTIPLIER: Final[float] = 1.2
+CARRY_POSITION_OFFSET: Final[float] = 1.05
+INTERACTION_DISTANCE_MULTIPLIER: Final[float] = 1.1
+
+# OpenGL clipping planes
+NEAR_CLIPPING_PLANE: Final[float] = 0.04
+FAR_CLIPPING_PLANE: Final[float] = 100.0
+ORTHOGRAPHIC_DEPTH_RANGE: Final[float] = 100.0
+
+# Occlusion query dimensions
+OCCLUSION_QUERY_BOX_SIZE: Final[float] = 0.1
+OCCLUSION_QUERY_BOX_HEIGHT: Final[float] = 0.2
+
+# Rendering display constants
+DEFAULT_DISPLAY_WIDTH: Final[int] = 256
+DEFAULT_WINDOW_WIDTH: Final[int] = 800
+DEFAULT_WINDOW_HEIGHT: Final[int] = 600
+FONT_SIZE: Final[int] = 14
+TEXT_LABEL_WIDTH: Final[int] = 400
+TEXT_MARGIN_X: Final[int] = 5
+TEXT_MARGIN_Y: Final[int] = 19
+
+# Rendering thresholds and tolerances
+EDGE_FACING_THRESHOLD: Final[float] = -0.9
+EDGE_TOUCHING_THRESHOLD: Final[float] = 0.05
+PORTAL_CONNECTION_TOLERANCE: Final[float] = 0.001

miniworld_maze/core/miniworld_gymnasium/README.md

@@ -0,0 +1 @@
+# Adapted from [MiniWorld](https://github.com/Farama-Foundation/Miniworld)

miniworld_maze/core/miniworld_gymnasium/__init__.py

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

miniworld_maze/core/miniworld_gymnasium/base_env.py

@@ -0,0 +1,52 @@
+"""Base MiniWorld environment class."""
+
+from .params import DEFAULT_PARAMS
+from .unified_env import UnifiedMiniWorldEnv
+
+
+class MiniWorldEnv(UnifiedMiniWorldEnv):
+    """
+    Legacy base class for MiniWorld environments.
+
+    This class provides backward compatibility with the original MiniWorld
+    environment interface while leveraging the unified implementation.
+    """
+
+    def __init__(
+        self,
+        max_episode_steps=1500,
+        obs_width=80,
+        obs_height=80,
+        window_width=800,
+        window_height=600,
+        params=DEFAULT_PARAMS,
+        domain_rand=False,
+    ):
+        """
+        Initialize base MiniWorld environment.
+
+        Args:
+            max_episode_steps: Maximum steps per episode
+            obs_width: Observation width in pixels
+            obs_height: Observation height in pixels
+            window_width: Window width for human rendering
+            window_height: Window height for human rendering
+            params: Environment parameters for domain randomization
+            domain_rand: Whether to enable domain randomization
+        """
+        # Mark this as a base environment (not custom) for background color handling
+        self._is_custom_env = False
+
+        # Initialize using unified base with base environment defaults
+        super().__init__(
+            obs_level=3,  # Default to FIRST_PERSON for base environments
+            continuous=False,  # Base environments use discrete actions
+            agent_mode="circle",  # Default agent mode
+            max_episode_steps=max_episode_steps,
+            obs_width=obs_width,
+            obs_height=obs_height,
+            window_width=window_width,
+            window_height=window_height,
+            params=params,
+            domain_rand=domain_rand,
+        )

miniworld_maze/core/miniworld_gymnasium/entities/__init__.py

@@ -0,0 +1,7 @@
+"""Entity classes for MiniWorld environments."""
+
+from .agent import Agent
+from .base_entity import COLOR_NAMES, COLORS, Entity, MeshEnt
+from .objects import Ball, Box, Key
+
+__all__ = ["Entity", "MeshEnt", "COLORS", "COLOR_NAMES", "Box", "Key", "Ball", "Agent"]

miniworld_maze/core/miniworld_gymnasium/entities/agent.py

@@ -0,0 +1,117 @@
+"""Agent entity for MiniWorld environments."""
+
+import math
+
+import numpy as np
+from pyglet.gl import *
+
+from ..math import *
+from .base_entity import Entity
+
+
+class Agent(Entity):
+    """The agent entity that represents the player/robot in the environment."""
+
+    def __init__(self, mode="triangle"):
+        super().__init__()
+        self.mode = mode
+        self.trable = False
+
+        # Distance between the camera and the floor
+        self.cam_height = 1.5
+
+        # Camera up/down angles in degrees
+        # Positive angles tilt the camera upwards
+        self.cam_pitch = 0
+
+        # Vertical field of view in degrees
+        self.cam_fov_y = 60
+
+        # Bounding cylinder size for the agent
+        if self.mode == "circle":
+            self.radius = 0.5
+        else:
+            self.radius = 0.6
+            self.height = 1.6
+
+        # Object currently being carried by the agent
+        self.carrying = None
+
+    @property
+    def cam_pos(self):
+        """Camera position in 3D space"""
+        rot_y = gen_rot_matrix(Y_VEC, self.dir)
+        cam_disp = np.array([self.cam_fwd_disp, self.cam_height, 0])
+        cam_disp = np.dot(cam_disp, rot_y)
+
+        return self.pos + cam_disp
+
+    @property
+    def cam_dir(self):
+        """Camera direction (lookat) vector
+
+        Note: this is useful even if just for slight domain
+        randomization of camera angle
+        """
+        rot_z = gen_rot_matrix(Z_VEC, self.cam_pitch * math.pi / 180)
+        rot_y = gen_rot_matrix(Y_VEC, self.dir)
+
+        dir = np.dot(X_VEC, rot_z)
+        dir = np.dot(dir, rot_y)
+
+        return dir
+
+    def randomize(self, params, rng):
+        params.sample_many(
+            rng,
+            self,
+            [
+                "cam_height",
+                "cam_fwd_disp",
+                "cam_pitch",
+                "cam_fov_y",
+            ],
+        )
+
+    def render(self):
+        """Draw the agent"""
+        # Note: this is currently only used in the top view
+        # Eventually, we will want a proper 3D model
+
+        if self.mode == "circle":
+
+            def draw_circle(pos, radius, num_segments):
+                glBegin(GL_LINE_STRIP)
+                glVertex3f(*pos)  # Center vertex
+                for i in range(num_segments + 1):
+                    angle = 2.0 * math.pi * i / num_segments
+                    x = radius * math.cos(angle) + pos[0]
+                    y = radius * math.sin(angle) + pos[2]
+                    glVertex3f(*self.pos)
+                    glVertex3f(x, 100.0, y)
+                glEnd()
+
+            glColor3f(1, 0, 0)
+            draw_circle(self.pos, self.radius, 1024)
+
+        elif self.mode == "triangle":
+            p = self.pos + Y_VEC * 100
+            dv = self.dir_vec * self.radius
+            rv = self.right_vec * self.radius
+
+            p0 = p + dv
+            p1 = p + 0.75 * (rv - dv)
+            p2 = p + 0.75 * (-rv - dv)
+
+            glColor3f(1, 0, 0)
+            glBegin(GL_TRIANGLES)
+            glVertex3f(*p0)
+            glVertex3f(*p2)
+            glVertex3f(*p1)
+            glEnd()
+
+        else:
+            pass
+
+    def step(self, delta_time):
+        pass

miniworld_maze/core/miniworld_gymnasium/entities/base_entity.py

@@ -0,0 +1,135 @@
+"""Base entity classes for MiniWorld environments."""
+
+import math
+
+import numpy as np
+from pyglet.gl import *
+
+from ..math import *
+from ..objmesh import ObjMesh
+
+# Map of color names to RGB values
+COLORS = {
+    "red": np.array([1.0, 0.0, 0.0]),
+    "green": np.array([0.0, 1.0, 0.0]),
+    "blue": np.array([0.0, 0.0, 1.0]),
+    "purple": np.array([0.44, 0.15, 0.76]),
+    "yellow": np.array([1.00, 1.00, 0.00]),
+    # 'grey'  : np.array([0.39, 0.39, 0.39]),
+    "light_yellow": np.array([0.5, 0.00, 0.39]),
+    "color1": np.array([0.7, 0.9, 0.39]),
+    "color2": np.array([0.15, 0.3, 0.39]),
+    "color3": np.array([1.0, 0.5, 0.0]),
+    "color4": np.array([1.0, 0.0, 0.5]),
+    "color5": np.array([0.3, 0.7, 0.1]),
+}
+
+# List of color names, sorted alphabetically
+COLOR_NAMES = sorted(list(COLORS.keys()))
+
+
+class Entity:
+    """Base class for all entities in the MiniWorld environment."""
+
+    def __init__(self):
+        # World position
+        # Note: for most entities, the position is at floor level
+        self.pos = None
+
+        # Direction/orientation angle in radians
+        self.dir = None
+
+        # Radius for bounding circle/cylinder
+        self.radius = 0
+
+        # Height of bounding cylinder
+        self.height = 0
+
+    def randomize(self, params, rng):
+        """Set the domain randomization parameters"""
+        pass
+
+    def render(self):
+        """Draw the object"""
+        raise NotImplementedError
+
+    def step(self, delta_time):
+        """Update the state of the object"""
+        pass
+
+    def draw_bound(self):
+        """Draw the bounding circle (used for debugging purposes)"""
+        x, _, z = self.pos
+
+        glColor3f(1, 0, 0)
+        glBegin(GL_LINES)
+
+        for i in range(60):
+            a = i * 2 * math.pi / 60
+            cx = x + self.radius * math.cos(a)
+            cz = z + self.radius * math.sin(a)
+            glVertex3f(cx, 0.01, cz)
+
+        glEnd()
+
+    @property
+    def dir_vec(self):
+        """Vector pointing in the direction of forward movement"""
+        x = math.cos(self.dir)
+        z = -math.sin(self.dir)
+        return np.array([x, 0, z])
+
+    @property
+    def right_vec(self):
+        """Vector pointing to the right of the agent"""
+        x = math.sin(self.dir)
+        z = math.cos(self.dir)
+        return np.array([x, 0, z])
+
+    @property
+    def is_static(self):
+        """True for objects that cannot move or animate (can be rendered statically)"""
+        return False
+
+
+class MeshEnt(Entity):
+    """Entity whose appearance is defined by a mesh file
+
+    Args:
+        mesh_name: Name of the mesh file
+        height: Scale the model to this height
+        static: Flag indicating this object cannot move
+        transparentable: Whether this entity can be made transparent
+    """
+
+    def __init__(self, mesh_name, height, static=True, transparentable=False):
+        super().__init__()
+        self.trable = transparentable
+        self.static = static
+
+        # Load the mesh
+        self.mesh = ObjMesh.get(mesh_name)
+
+        # Get the mesh extents
+        sx, sy, sz = self.mesh.max_coords
+
+        # Compute the mesh scaling factor
+        self.scale = height / sy
+
+        # Compute the radius and height
+        self.radius = math.sqrt(sx * sx + sz * sz) * self.scale
+        self.height = height
+
+    def render(self):
+        """Draw the object"""
+        glPushMatrix()
+        glTranslatef(*self.pos)
+        glScalef(self.scale, self.scale, self.scale)
+        glRotatef(self.dir * 180 / math.pi, 0, 1, 0)
+        glColor3f(1, 1, 1)
+        self.mesh.render()
+        glPopMatrix()
+
+    @property
+    def is_static(self):
+        return self.static

miniworld_maze/core/miniworld_gymnasium/entities/objects.py

@@ -0,0 +1,116 @@
+"""Object entities for MiniWorld environments."""
+
+import math
+
+import numpy as np
+from pyglet.gl import *
+
+from ..opengl import drawBox
+from .base_entity import COLOR_NAMES, COLORS, Entity, MeshEnt
+
+
+class Box(Entity):
+    """
+    Colored box object that can be placed in MiniWorld environments.
+
+    Boxes can be static (immovable) or dynamic (pickupable by the agent).
+    They support transparency effects and domain randomization of colors.
+    """
+
+    def __init__(self, color, size=0.8, transparentable=False, static=False):
+        """
+        Initialize a box entity.
+
+        Args:
+            color: Color name (must be in COLORS dictionary)
+            size: Box size - scalar for cube, or 3-element array for [width, height, depth]
+            transparentable: Whether box can become transparent during rendering
+            static: Whether box is immovable (True) or pickupable (False)
+        """
+        super().__init__()
+
+        # Store transparency and static properties with descriptive names
+        self.is_transparentable = transparentable
+        self.static_flag = static
+
+        # Convert size to 3D dimensions
+        if isinstance(size, (int, float)):
+            size = np.array([size, size, size])
+        size = np.array(size)
+
+        # Extract dimensions with clear names
+        size_x, size_y, size_z = size
+
+        self.color = color
+        self.size = size
+
+        # Calculate collision radius (distance from center to corner in XZ plane)
+        self.radius = math.sqrt(size_x * size_x + size_z * size_z) / 2
+        self.height = size_y
+
+    def randomize(self, params, rng):
+        """
+        Apply domain randomization to box appearance.
+
+        This method randomizes the box color by adding a bias sampled from
+        the environment parameters, then clips to valid color range.
+
+        Args:
+            params: Environment parameters containing randomization settings
+            rng: Random number generator for sampling
+        """
+        base_color = COLORS[self.color]
+        color_bias = params.sample(rng, "obj_color_bias")
+        self.color_vec = base_color + color_bias
+        self.color_vec = np.clip(self.color_vec, 0, 1)
+
+    def render(self):
+        """Render the box using OpenGL."""
+        size_x, size_y, size_z = self.size
+
+        # Set up OpenGL state for box rendering
+        glDisable(GL_TEXTURE_2D)
+        glColor3f(*self.color_vec)
+
+        # Apply transformations
+        glPushMatrix()
+        glTranslatef(*self.pos)
+        glRotatef(self.dir * (180 / math.pi), 0, 1, 0)
+
+        # Draw the box geometry
+        drawBox(
+            x_min=-size_x / 2,
+            x_max=+size_x / 2,
+            y_min=0,
+            y_max=size_y,
+            z_min=-size_z / 2,
+            z_max=+size_z / 2,
+        )
+
+        glPopMatrix()
+
+    @property
+    def is_static(self):
+        """Return whether this box is static (cannot move)."""
+        return self.static_flag
+
+    @property
+    def trable(self):
+        """Legacy property for transparency - kept for backward compatibility."""
+        return self.is_transparentable
+
+
+class Key(MeshEnt):
+    """Key the agent can pick up, carry, and use to open doors"""
+
+    def __init__(self, color):
+        assert color in COLOR_NAMES
+        super().__init__(mesh_name="key_{}".format(color), height=0.35, static=False)
+
+
+class Ball(MeshEnt):
+    """Ball (sphere) the agent can pick up and carry"""
+
+    def __init__(self, color, size=0.6):
+        assert color in COLOR_NAMES
+        super().__init__(mesh_name="ball_{}".format(color), height=size, static=False)