miniworld-maze 1.0.0__tar.gz

miniworld_maze-1.0.0/LICENSE

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

miniworld_maze-1.0.0/PKG-INFO

@@ -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.

miniworld_maze-1.0.0/README.md

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

miniworld_maze-1.0.0/examples/README.md

@@ -0,0 +1,125 @@
+# Examples
+
+This directory contains example scripts demonstrating the usage and performance of the Nine Rooms environments.
+
+## Scripts
+
+### live_control_opencv.py ⭐ **RECOMMENDED**
+
+Real-time dual-view OpenCV live control with ego view and top-down map side by side.
+
+**Usage:**
+```bash
+# Dual-view window with first-person ego view + top-down map
+python examples/live_control_opencv.py --variant NineRooms --size 128
+
+# Use top-down partial view as ego view + full map  
+python examples/live_control_opencv.py --variant NineRooms --size 128 --obs-level TOP_DOWN_PARTIAL
+
+# Different environment variants
+python examples/live_control_opencv.py --variant TwentyFiveRooms --size 128
+```
+
+**Controls:**
+- `W/A/S/D` - Move forward/turn left/move backward/turn right
+- `SPACE` - Pick up object, `X` - Drop object, `E` - Toggle/activate
+- `R` - Reset environment, `1/2/3` - Switch environment variants
+- `ESC/Q` - Quit
+
+**Requirements:**
+- Display environment (not headless)
+- Click OpenCV window to focus for keyboard input
+
+**Features:**
+- **Dual synchronized views**: Ego view (configurable) + top-down full map
+- **Real-time agent tracking**: See your position and orientation on the map
+- **Perfect synchronization**: Both environments step together automatically
+- **No OpenGL conflicts**: Reliable operation using OpenCV
+- **Multiple view combinations**: First-person + map, top-down + map, etc.
+
+### generate_observations.py
+
+Generate comprehensive observation datasets for all environment variants.
+
+**Usage:**
+```bash
+# Generate observations for NineRooms (default 64x64)
+python examples/generate_observations.py NineRooms
+
+# Generate observations for SpiralNineRooms with custom output directory
+python examples/generate_observations.py SpiralNineRooms --output-dir my_observations
+
+# Generate high-resolution full environment views (512x512)
+python examples/generate_observations.py TwentyFiveRooms --high-res-full
+```
+
+**Generated observations:**
+- Full environment views (with/without agent)
+- Partial observations from different positions
+- Standard Gymnasium observations after actions
+- render_on_pos examples from strategic locations
+
+### benchmark_rendering.py
+
+Benchmark rendering performance across different observation sizes and environment variants.
+
+**Usage:**
+```bash
+# Quick benchmark of NineRooms with common sizes
+python examples/benchmark_rendering.py --quick --variant NineRooms
+
+# Comprehensive benchmark of all variants and sizes
+python examples/benchmark_rendering.py --all-variants --sizes 32 64 128 256 --steps 100
+
+# Custom benchmark with specific parameters
+python examples/benchmark_rendering.py --variant SpiralNineRooms --sizes 64 128 256 --steps 50
+```
+
+**Features:**
+- FPS measurement across different observation sizes
+- Performance comparison between environment variants
+- Memory usage analysis
+- Detailed timing statistics (min/max/avg/std)
+- Scaling analysis (how performance scales with resolution)
+
+### observation_level_demo.py
+
+Demonstrates different observation levels and their visual differences.
+
+**Usage:**
+```bash
+python examples/observation_level_demo.py
+```
+
+**Features:**
+- Shows first-person, top-down partial, and top-down full views
+- Saves comparison images for each observation level
+- Demonstrates the impact of different observation settings
+
+## Key Benefits Demonstrated
+
+### Interactive Control
+- **Dual-View Navigation**: Ego view + top-down map displayed simultaneously
+- **Real-time Agent Tracking**: Always see your position and orientation on the map
+- **Synchronized Environments**: Both views update together for perfect consistency
+- **No OpenGL Conflicts**: Reliable operation using OpenCV for display
+- **Multiple View Combinations**: First-person + map, top-down + map, etc.
+
+### Direct Rendering Performance
+- **No Resize Overhead**: Environments render directly at requested size
+- **Excellent Scaling**: 256x256 images only ~1.2x slower than 32x32 despite 64x more pixels
+- **High Frame Rates**: 60-80 FPS for standard sizes (64x64, 128x128)
+- **Flexible Resolutions**: Any custom size supported without performance penalty
+
+### Environment Variants
+- **NineRooms**: ~73 FPS average (fastest, simplest 3x3 grid)
+- **SpiralNineRooms**: ~62 FPS average (moderate complexity)  
+- **TwentyFiveRooms**: ~26 FPS average (most complex, 5x5 grid with 25 rooms)
+
+## Usage Tips
+
+1. **For Interactive Exploration**: Use `live_control_opencv.py` for real-time navigation
+2. **For Research**: Use higher resolutions (256x256+) for detailed analysis
+3. **For Training**: Use standard sizes (64x64, 128x128) for optimal speed
+4. **For Visualization**: Use `generate_observations.py` to create comprehensive datasets
+5. **For Optimization**: Use `benchmark_rendering.py` to find optimal settings

miniworld_maze-1.0.0/examples/benchmark_rendering.py

@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+"""
+Benchmark rendering performance (FPS) for various observation sizes.
+
+This script tests the direct rendering performance of the Nine Rooms environments
+across different observation sizes to demonstrate the efficiency of the 
+direct rendering approach vs the old resize-based approach.
+"""
+
+import time
+import argparse
+import numpy as np
+from miniworld_drstrategy.environments.factory import create_nine_rooms_env
+from miniworld_drstrategy.core.constants import (
+    DEFAULT_BENCHMARK_STEPS, DEFAULT_WARMUP_STEPS, RGB_CHANNELS, FLOAT32_BYTES, MB_TO_BYTES
+)
+
+
+def benchmark_rendering_performance(variant="NineRooms", sizes=None, num_steps=DEFAULT_BENCHMARK_STEPS, num_warmup=DEFAULT_WARMUP_STEPS):
+    """
+    Benchmark rendering performance across different observation sizes.
+    
+    Args:
+        variant: Environment variant to test
+        sizes: List of observation sizes to test
+        num_steps: Number of steps to run for timing
+        num_warmup: Number of warmup steps (not timed)
+    
+    Returns:
+        Dictionary with benchmark results
+    """
+    if sizes is None:
+        sizes = [32, 48, 64, 96, 128, 192, 256]
+    
+    print(f"🚀 Benchmarking {variant} rendering performance...")
+    print(f"📊 Testing sizes: {sizes}")
+    print(f"⏱️  Steps per test: {num_steps} (+ {num_warmup} warmup)")
+    print("=" * 60)
+    
+    results = {}
+    
+    for size in sizes:
+        print(f"\n🔍 Testing {size}x{size} observations...")
+        
+        # Create environment with specific observation size
+        env = create_nine_rooms_env(variant, size=size)
+        
+        # Warmup phase
+        print(f"   🔥 Warming up ({num_warmup} steps)...")
+        obs, info = env.reset(seed=42)
+        for _ in range(num_warmup):
+            action = env.action_space.sample()
+            obs, reward, terminated, truncated, info = env.step(action)
+            if terminated or truncated:
+                obs, info = env.reset()
+        
+        # Benchmark phase
+        print(f"   ⏱️  Benchmarking ({num_steps} steps)...")
+        start_time = time.time()
+        
+        step_times = []
+        for i in range(num_steps):
+            step_start = time.time()
+            action = env.action_space.sample()
+            obs, reward, terminated, truncated, info = env.step(action)
+            if terminated or truncated:
+                obs, info = env.reset()
+            step_end = time.time()
+            step_times.append(step_end - step_start)
+        
+        end_time = time.time()
+        total_time = end_time - start_time
+        
+        env.close()
+        
+        # Calculate statistics
+        fps = num_steps / total_time
+        avg_step_time = np.mean(step_times)
+        min_step_time = np.min(step_times)
+        max_step_time = np.max(step_times)
+        std_step_time = np.std(step_times)
+        
+        # Memory per observation
+        pixels_per_obs = size * size * RGB_CHANNELS
+        memory_mb = (pixels_per_obs * FLOAT32_BYTES) / MB_TO_BYTES
+        
+        results[size] = {
+            'fps': fps,
+            'avg_step_time': avg_step_time,
+            'min_step_time': min_step_time,
+            'max_step_time': max_step_time,
+            'std_step_time': std_step_time,
+            'total_time': total_time,
+            'memory_mb': memory_mb,
+            'pixels': size * size
+        }
+        
+        print(f"   ✅ {fps:.2f} FPS (avg: {avg_step_time*1000:.2f}ms/step)")
+    
+    return results
+
+
+def print_benchmark_results(results, variant):
+    """Print detailed benchmark results in a formatted table."""
+    
+    print(f"\n{'='*80}")
+    print(f"📊 RENDERING PERFORMANCE BENCHMARK RESULTS - {variant}")
+    print(f"{'='*80}")
+    
+    # Table header
+    print(f"{'Size':>8} {'Pixels':>10} {'FPS':>8} {'Avg ms':>8} {'Min ms':>8} {'Max ms':>8} {'Std ms':>8} {'Memory':>8}")
+    print("-" * 80)
+    
+    # Table rows
+    for size, data in sorted(results.items()):
+        print(f"{size:>8} {data['pixels']:>10,} {data['fps']:>8.1f} {data['avg_step_time']*1000:>8.1f} "
+              f"{data['min_step_time']*1000:>8.1f} {data['max_step_time']*1000:>8.1f} "
+              f"{data['std_step_time']*1000:>8.1f} {data['memory_mb']:>7.1f}MB")
+    
+    print("-" * 80)
+    
+    # Performance insights
+    print(f"\n🎯 PERFORMANCE INSIGHTS:")
+    
+    # Find best and worst performers
+    best_fps = max(results.values(), key=lambda x: x['fps'])
+    worst_fps = min(results.values(), key=lambda x: x['fps'])
+    best_size = next(size for size, data in results.items() if data['fps'] == best_fps['fps'])
+    worst_size = next(size for size, data in results.items() if data['fps'] == worst_fps['fps'])
+    
+    print(f"   🏆 Highest FPS: {best_size}x{best_size} at {best_fps['fps']:.1f} FPS")
+    print(f"   🐌 Lowest FPS:  {worst_size}x{worst_size} at {worst_fps['fps']:.1f} FPS")
+    
+    # Calculate performance scaling
+    size_32 = results.get(32)
+    size_256 = results.get(256)
+    if size_32 and size_256:
+        pixel_ratio = (256 * 256) / (32 * 32)
+        fps_ratio = size_32['fps'] / size_256['fps']
+        print(f"   📈 Scaling: 256x256 has {pixel_ratio:.1f}x more pixels but only {fps_ratio:.1f}x slower")
+    
+    # Memory usage
+    total_memory = sum(data['memory_mb'] for data in results.values())
+    print(f"   💾 Total memory tested: {total_memory:.1f}MB across all sizes")
+
+
+def benchmark_environment_variants(sizes=None, num_steps=50):
+    """Benchmark all environment variants."""
+    
+    if sizes is None:
+        sizes = [64, 128, 256]
+    
+    variants = ["NineRooms", "SpiralNineRooms", "TwentyFiveRooms"]
+    all_results = {}
+    
+    print(f"🌟 COMPREHENSIVE ENVIRONMENT BENCHMARK")
+    print(f"Testing variants: {variants}")
+    print(f"Testing sizes: {sizes}")
+    print("=" * 80)
+    
+    for variant in variants:
+        results = benchmark_rendering_performance(
+            variant=variant, 
+            sizes=sizes, 
+            num_steps=num_steps,
+            num_warmup=5
+        )
+        all_results[variant] = results
+        
+        # Quick summary
+        avg_fps = np.mean([data['fps'] for data in results.values()])
+        print(f"\n📈 {variant} average FPS across all sizes: {avg_fps:.1f}")
+    
+    # Comparative analysis
+    print(f"\n{'='*80}")
+    print("🔄 VARIANT COMPARISON")
+    print("=" * 80)
+    
+    for size in sizes:
+        print(f"\nSize {size}x{size}:")
+        for variant in variants:
+            if size in all_results[variant]:
+                fps = all_results[variant][size]['fps']
+                print(f"   {variant:20}: {fps:6.1f} FPS")
+    
+    return all_results
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Benchmark Nine Rooms rendering performance')
+    parser.add_argument('--variant', default='NineRooms', 
+                        choices=['NineRooms', 'SpiralNineRooms', 'TwentyFiveRooms'],
+                        help='Environment variant to benchmark')
+    parser.add_argument('--sizes', nargs='+', type=int, 
+                        default=[32, 48, 64, 96, 128, 192, 256],
+                        help='Observation sizes to test')
+    parser.add_argument('--steps', type=int, default=1000,
+                        help='Number of steps per benchmark')
+    parser.add_argument('--all-variants', action='store_true',
+                        help='Benchmark all environment variants')
+    parser.add_argument('--quick', action='store_true',
+                        help='Quick benchmark with fewer steps and sizes')
+    
+    args = parser.parse_args()
+    
+    if args.quick:
+        args.steps = 30
+        args.sizes = [64, 128, 256]
+    
+    print("🎮 Nine Rooms Rendering Performance Benchmark")
+    print("=" * 80)
+    
+    if args.all_variants:
+        all_results = benchmark_environment_variants(sizes=args.sizes, num_steps=args.steps)
+        
+        # Print detailed results for each variant
+        for variant, results in all_results.items():
+            print_benchmark_results(results, variant)
+    
+    else:
+        results = benchmark_rendering_performance(
+            variant=args.variant,
+            sizes=args.sizes, 
+            num_steps=args.steps
+        )
+        print_benchmark_results(results, args.variant)
+    
+    print(f"\n🎉 Benchmark complete!")
+    print(f"✨ Direct rendering approach shows excellent performance scaling!")
+
+
+if __name__ == "__main__":
+    main()