Metadata-Version: 2.4
Name: minobot
Version: 0.0.7
Summary: A package for visualizing maze solving intended for students learning programming with Python. Developed at the VU Amsterdam.
Keywords: maze,education
Author: Banno Postma, Ahmad Ramadan, Mauricio Verano Merino
Author-email: Banno Postma <b.postma@vu.nl>, Mauricio Verano Merino <m.verano.merino@vu.nl>
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Education
Requires-Dist: pygame>=2.6.1
Requires-Dist: opencv-python>=4.8.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: ipykernel>=6.29.5
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Minobot

An educational Python package for learning programming through maze solving.

## For Students

Learn programming concepts by writing code to solve mazes. Watch your robot navigate through mazes in real-time or as videos in Jupyter notebooks.

## Quick Start

```python
from minobot import *

# Create a maze
maze = [
    [1, 1, 1, 1, 1], # 1 represents a wall
    [1, 0, 0, 2, 1], # 0 is empty and 2 is the starting position
    [1, 0, 1, 0, 1],
    [1, 0, 0, 3, 1], # 3 is the goal
    [1, 1, 1, 1, 1]
]

# Write your solution
def solve():
    while not has_reached_end():
        if can_move():
            move()
        else:
            turn_left()

# Watch it work
solve_maze(maze, solve)
```

## Installation

```bash
pip install --upgrade pip
pip install --prefer-binary minobot
```

In a Jupyter notebook, run the same commands in a cell with `%pip` instead of `pip`, then restart the kernel.

### Installation hangs on "Building wheel for opencv-python" (macOS)

The newest OpenCV versions only have ready-made packages (wheels) for recent macOS versions:
macOS 13 or newer on Apple Silicon (M1 and later), and macOS 14 or newer on Intel Macs.
On older macOS versions pip downloads the OpenCV source code instead and tries to compile it,
which takes very long and usually fails.

`--prefer-binary` in the command above fixes this: pip then installs the newest OpenCV version
that has a ready-made package for your Mac. If you already started an installation, stop it
(Ctrl+C) and run:

```bash
pip install --upgrade pip
pip install --prefer-binary --force-reinstall opencv-python
```

Updating macOS also works. You can check which OpenCV versions support your macOS version under
*Download files* on the [opencv-python PyPI page](https://pypi.org/project/opencv-python/#files).

### Videos don't play in the notebook

Minobot tries to create an MP4 video first. If that doesn't work on your computer, it automatically
falls back to WebM, then to an animated WebP image and finally to an animated GIF, and prints which
format it used. If a video still doesn't play in your browser, pick a format yourself at the top of
your notebook:

```python
from minobot import *
config.video_format = "gif"  # or "mp4", "webm", "webp"; "auto" is the default
```

If none of the formats work, installing OpenCV from conda-forge usually helps:

```bash
pip uninstall opencv-python
conda install -c conda-forge opencv
```


## Running Modes

Minobot can run your solution in a few different ways:

- `solve_maze(maze, solve)`: Watch the robot solve the maze. In a Jupyter notebook this shows a video, and in a normal Python script it opens a Pygame window. In the window, press Space to pause, use the left and right arrow keys to step through the moves while paused, and press Esc to close it. Minobot detects your environment automatically. To choose yourself, pass `notebook=True` or `notebook=False`.
- `debug_maze(maze, solve)`: Like `solve_maze`, but shows every command and its return value in a history panel next to the maze. Useful when your robot does something unexpected.
- `test_maze(maze, solve)`: Runs your solution without any visuals and returns a dictionary with the results, such as `solvable`, `steps` and `instruction_count`.
- `show_maze(maze)`: Shows the maze as an image without running any code, so you can look at it before writing your solution.

### What are `maze` and `solve`?

- `maze` is a list of rows, where each row is a list of numbers: `0` is an empty tile, `1` is a wall, `2` is where the robot starts and `3` is the goal. The robot always starts facing south (down). Instead of a list you can also pass the name of a built-in maze, such as `"simple"`, `"branching"`, `"looping"`, `"spiral"` or `"complex"`.
- `solve` is a function you write yourself that takes no arguments and uses the robot instructions below. Pass the function itself, without parentheses: `solve_maze(maze, solve)`, not `solve_maze(maze, solve())`.


## Robot Instructions

The MinoBot provides simple, intuitive instructions for maze navigation:

### Movement Instructions
- `move()` - Move forward one step (returns `True` if successful, `False` if blocked)
- `turn_left()` - Turn 90 degrees to the left
- `turn_right()` - Turn 90 degrees to the right  
- `turn_around()` - Turn 180 degrees

### Sensing Instructions
- `can_move()` - Check if the robot can move forward without hitting a wall
- `has_reached_end()` - Check if the robot has reached the goal
- `get_position()` - Get current (x, y) position
- `get_direction()` - Get current direction (NORTH, EAST, SOUTH, WEST)
- `get_steps()` - Get number of steps taken

### Painting Instructions
- `paint_current(color)` - Paint the tile the robot is standing on
- `paint_forward(color)` - Paint the tile in front of the robot
- `get_current_color()` - Get color of current tile
- `get_forward_color()` - Get color of tile in front

#### Colors

The MinoBot can paint tiles with the following colors:
- `red` - Light red
- `blue` - Light blue  
- `green` - Light green
- `yellow` - Light yellow
- `purple` - Light purple
- `orange` - Light orange
- `pink` - Light pink
- `cyan` - Light cyan



## Educational Features

- **Visual Learning**: See your code execute step-by-step
- **Multiple Environments**: Works in Jupyter notebooks and standalone Python
- **Algorithm Practice**: Perfect for learning loops, conditionals, and problem-solving
