cege-gopher 0.1.0__tar.gz

cege_gopher-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seongjin Choi
+
+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.

cege_gopher-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: cege-gopher
+Version: 0.1.0
+Summary: A Karel-style grid robot for teaching Python, themed as Goldy Gopher. Records and replays, so it works in Colab.
+Author-email: Seongjin Choi <chois@umn.edu>
+License: MIT License
+        
+        Copyright (c) 2026 Seongjin Choi
+        
+        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.
+        
+Keywords: education,karel,robot,colab,cege3101
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Education
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.5
+Dynamic: license-file
+
+# cege_gopher
+
+A Karel-style grid robot for teaching introductory Python, themed as Goldy
+Gopher. Written for **CEGE 3101 — Computer Applications I** at the University of
+Minnesota.
+
+Ported from the MATLAB robot used in earlier offerings of the course, which was
+itself a port of the KAIST CS101 HUBO exercise
+([otfried/cs101](https://github.com/otfried/cs101)) — Karel the Robot, at the
+root of it.
+
+## Why this exists
+
+The original libraries open a live window and animate each command as it runs.
+**Google Colab cannot host one.**
+
+So this version **records, then replays**. Every command appends a frame to a
+buffer; nothing is drawn until `show()`, which renders the whole run as an
+inline animation:
+
+> write the whole program → run the cell → watch it play back
+
+Students never drive the robot interactively; every program is pre-coded, which
+is also how the homework is graded.
+
+## Install
+
+```bash
+pip install cege-gopher
+```
+
+Or, from the course repository:
+
+```bash
+pip install "git+https://github.com/benchoi93/CEGE3101_Computer_Applications.git#subdirectory=packages/cege-gopher"
+```
+
+The 13 world files ship **inside the package**, so nothing needs uploading —
+`load_world("harvest1.wld")` just works.
+
+## Use
+
+```python
+from cege_gopher import *
+
+load_world("harvest1.wld")       # or: create_world(10, 10)
+goldy = Gopher()
+goldy.set_trace("maroon")
+
+while goldy.front_is_clear():
+    if goldy.on_carrot():
+        goldy.pick_carrot()
+    goldy.move()
+
+show()                           # the animation renders here
+```
+
+`list_worlds()` returns the bundled world names.
+
+## API
+
+| | |
+|---|---|
+| Module | `create_world(avenues, streets)`, `load_world(name)`, `list_worlds()`, `show(fps=)`, `show_final()`, `get_world()` |
+| Move | `move()`, `turn_left()`, `turn_right()` |
+| Carrots | `pick_carrot()`, `drop_carrot()` |
+| Sense | `front_is_clear()`, `left_is_clear()`, `right_is_clear()`, `facing_north()`, `on_carrot()`, `carries_carrots()` |
+| Display | `set_trace(color)`, `get_pos()` |
+
+`Robot` is an alias for `Gopher`, and `pick_beeper`/`pick_coin` for
+`pick_carrot`, so code written against `cs1robots` or the MATLAB version still
+runs.
+
+## A bug fixed in this port
+
+The MATLAB version had `leftIsClear` and `rightIsClear` **swapped** — facing
+east it checked south for "left", when `turnLeft` rotates counter-clockwise
+(E→N) so left of east is north. This port uses `left = (-dy, dx)`,
+`right = (dy, -dx)`.
+
+## License
+
+MIT.

cege_gopher-0.1.0/README.md

@@ -0,0 +1,83 @@
+# cege_gopher
+
+A Karel-style grid robot for teaching introductory Python, themed as Goldy
+Gopher. Written for **CEGE 3101 — Computer Applications I** at the University of
+Minnesota.
+
+Ported from the MATLAB robot used in earlier offerings of the course, which was
+itself a port of the KAIST CS101 HUBO exercise
+([otfried/cs101](https://github.com/otfried/cs101)) — Karel the Robot, at the
+root of it.
+
+## Why this exists
+
+The original libraries open a live window and animate each command as it runs.
+**Google Colab cannot host one.**
+
+So this version **records, then replays**. Every command appends a frame to a
+buffer; nothing is drawn until `show()`, which renders the whole run as an
+inline animation:
+
+> write the whole program → run the cell → watch it play back
+
+Students never drive the robot interactively; every program is pre-coded, which
+is also how the homework is graded.
+
+## Install
+
+```bash
+pip install cege-gopher
+```
+
+Or, from the course repository:
+
+```bash
+pip install "git+https://github.com/benchoi93/CEGE3101_Computer_Applications.git#subdirectory=packages/cege-gopher"
+```
+
+The 13 world files ship **inside the package**, so nothing needs uploading —
+`load_world("harvest1.wld")` just works.
+
+## Use
+
+```python
+from cege_gopher import *
+
+load_world("harvest1.wld")       # or: create_world(10, 10)
+goldy = Gopher()
+goldy.set_trace("maroon")
+
+while goldy.front_is_clear():
+    if goldy.on_carrot():
+        goldy.pick_carrot()
+    goldy.move()
+
+show()                           # the animation renders here
+```
+
+`list_worlds()` returns the bundled world names.
+
+## API
+
+| | |
+|---|---|
+| Module | `create_world(avenues, streets)`, `load_world(name)`, `list_worlds()`, `show(fps=)`, `show_final()`, `get_world()` |
+| Move | `move()`, `turn_left()`, `turn_right()` |
+| Carrots | `pick_carrot()`, `drop_carrot()` |
+| Sense | `front_is_clear()`, `left_is_clear()`, `right_is_clear()`, `facing_north()`, `on_carrot()`, `carries_carrots()` |
+| Display | `set_trace(color)`, `get_pos()` |
+
+`Robot` is an alias for `Gopher`, and `pick_beeper`/`pick_coin` for
+`pick_carrot`, so code written against `cs1robots` or the MATLAB version still
+runs.
+
+## A bug fixed in this port
+
+The MATLAB version had `leftIsClear` and `rightIsClear` **swapped** — facing
+east it checked south for "left", when `turnLeft` rotates counter-clockwise
+(E→N) so left of east is north. This port uses `left = (-dy, dx)`,
+`right = (dy, -dx)`.
+
+## License
+
+MIT.

cege_gopher-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cege-gopher"
+version = "0.1.0"
+description = "A Karel-style grid robot for teaching Python, themed as Goldy Gopher. Records and replays, so it works in Colab."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [{ name = "Seongjin Choi", email = "chois@umn.edu" }]
+keywords = ["education", "karel", "robot", "colab", "cege3101"]
+classifiers = [
+    "Intended Audience :: Education",
+    "Programming Language :: Python :: 3",
+    "Topic :: Education",
+]
+dependencies = ["matplotlib>=3.5"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+cege_gopher = ["worlds/*.wld", "sprites/*.png"]

cege_gopher-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cege_gopher-0.1.0/src/cege_gopher/__init__.py

@@ -0,0 +1,611 @@
+"""cege_gopher --- a Karel-style grid robot for CEGE 3101, themed as Goldy Gopher.
+
+Ported from the MATLAB `robot_matlab` version in
+`lectures/week-02/python_tutorial_with_gopher/`, which was itself a port of the
+KAIST CS101 `cs1robots` library (https://github.com/otfried/cs101).
+
+WHY THIS EXISTS / WHAT IS DIFFERENT
+-----------------------------------
+The original opens a live window and animates each command as it happens. That
+does not work in Google Colab, which cannot host an interactive window.
+
+So this version **records, then replays**. Every command appends a frame to a
+buffer; nothing is drawn until you call `show()`, which renders the whole run as
+an inline animation. The practical consequence for students:
+
+    write the whole program  ->  run the cell  ->  watch it play back
+
+You never "drive" the gopher interactively. Everything is pre-coded, which is
+also how the homework is graded.
+
+QUICK START
+-----------
+    from cege_gopher import *
+
+    load_world("harvest1.wld")            # or: create_world(10, 10)
+    goldy = Gopher(carrots=0)
+    goldy.set_trace("maroon")
+
+    for i in range(5):
+        goldy.move()
+        if goldy.on_carrot():
+            goldy.pick_carrot()
+
+    show()          # <- the animation appears here
+
+API
+---
+Module:   create_world(avenues, streets), load_world(path), show(), show_final()
+Gopher:   move, turn_left, turn_right, pick_carrot, drop_carrot,
+          front_is_clear, left_is_clear, right_is_clear,
+          facing_north, carries_carrots, on_carrot, set_trace, get_pos
+
+Aliases are provided so code written against the original libraries still runs:
+`Robot` for `Gopher`; `pick_beeper`/`pick_coin` for `pick_carrot`, and so on.
+
+FIXED IN THIS PORT
+------------------
+The MATLAB version had `leftIsClear` and `rightIsClear` swapped -- facing East it
+checked South for "left", when left of East is North. Verified against the
+turn_left direction cycle, which is counter-clockwise (E -> N -> W -> S). This
+port uses left = (-dy, dx), right = (dy, -dx).
+"""
+from __future__ import annotations
+
+import os
+import re
+
+import matplotlib
+import matplotlib.pyplot as plt
+from matplotlib import animation
+from matplotlib.patches import Circle, Ellipse, Polygon, Rectangle
+
+__all__ = [
+    "Gopher", "Robot", "World",
+    "create_world", "load_world", "show", "show_final", "get_world",
+    "list_worlds", "GopherError",
+]
+
+UMN_MAROON = "#7A0019"
+UMN_GOLD = "#FFCC33"
+_TRACE_COLORS = {"maroon": UMN_MAROON, "gold": UMN_GOLD}
+
+# Orientation is stored as a unit vector (dx, dy). East is the start, matching
+# the `robot = (1, 1, 'E', 0)` line in the .wld files.
+_DIRS = {"E": (1, 0), "N": (0, 1), "W": (-1, 0), "S": (0, -1)}
+_DIR_NAMES = {v: k for k, v in _DIRS.items()}
+
+
+class GopherError(Exception):
+    """Raised when the gopher is asked to do something impossible."""
+
+
+# ==========================================================================
+# World
+# ==========================================================================
+class World:
+    """A grid of avenues (columns) x streets (rows).
+
+    Two coordinate systems are in play, and mixing them up is the classic bug:
+
+    * **cell** coordinates ``(avenue, street)``, 1-based, are what the gopher
+      uses. Avenue is the column, street is the row.
+    * **doubled** coordinates ``(col, row)`` are what *walls* use, where a cell
+      ``(a, s)`` sits at ``(2a-1, 2s-1)``. A wall lives between two cells, so it
+      always has one even coordinate. This is the same convention as the
+      original `.wld` files, so world files are compatible unchanged.
+    """
+
+    def __init__(self, avenues=10, streets=10, walls=None, carrots=None):
+        self.avenues = int(avenues)
+        self.streets = int(streets)
+        self.walls = set(walls or ())
+        # {(avenue, street): count}
+        self.carrots = dict(carrots or {})
+        self._borders = self._make_borders()
+
+    # ---- geometry ----------------------------------------------------
+    def _make_borders(self) -> set:
+        b = set()
+        for a in range(1, self.avenues + 1):
+            b.add((2 * a - 1, 0))                    # south wall of the world
+            b.add((2 * a - 1, 2 * self.streets))     # north wall
+        for s in range(1, self.streets + 1):
+            b.add((0, 2 * s - 1))                    # west wall
+            b.add((2 * self.avenues, 2 * s - 1))     # east wall
+        return b
+
+    def is_clear(self, col, row) -> bool:
+        """True if no wall and no world border sits at this doubled coordinate."""
+        return (col, row) not in self.walls and (col, row) not in self._borders
+
+    def toggle_wall(self, col, row):
+        if (col + row) % 2 == 0:
+            raise GopherError(
+                f"A wall cannot sit at ({col}, {row}) -- walls go *between* "
+                "cells, so exactly one coordinate must be even.")
+        self.walls.symmetric_difference_update({(col, row)})
+
+    # ---- carrots -----------------------------------------------------
+    def count_carrots(self, avenue, street) -> int:
+        return self.carrots.get((avenue, street), 0)
+
+    def add_carrot(self, avenue, street):
+        self.carrots[(avenue, street)] = self.count_carrots(avenue, street) + 1
+
+    def remove_carrot(self, avenue, street):
+        n = self.count_carrots(avenue, street)
+        if n <= 1:
+            self.carrots.pop((avenue, street), None)
+        else:
+            self.carrots[(avenue, street)] = n - 1
+
+
+# ==========================================================================
+# World files
+# ==========================================================================
+def _parse_world(text: str):
+    """Parse a `.wld` file.
+
+    Accepts ``carrots``, ``coins`` and ``beepers`` as the item key, so both the
+    MATLAB-era worlds in this repo and the original CS101 worlds load unchanged.
+    """
+    def _int(key, default=10):
+        m = re.search(rf"{key}\s*=\s*(\d+)", text)
+        return int(m.group(1)) if m else default
+
+    avenues, streets = _int("avenues"), _int("streets")
+
+    walls = set()
+    m = re.search(r"walls\s*=\s*\[(.*?)\]", text, re.S)
+    if m:
+        for a, b in re.findall(r"\(\s*(\d+)\s*,\s*(\d+)\s*\)", m.group(1)):
+            walls.add((int(a), int(b)))
+
+    carrots = {}
+    m = re.search(r"(?:carrots|coins|beepers)\s*=\s*\{(.*?)\}", text, re.S)
+    if m:
+        for a, b, n in re.findall(
+                r"\(\s*(\d+)\s*,\s*(\d+)\s*\)\s*:\s*(\d+)", m.group(1)):
+            carrots[(int(a), int(b))] = int(n)
+
+    start = (1, 1, "E", 0)
+    m = re.search(r"robot\s*=\s*\(\s*(\d+)\s*,\s*(\d+)\s*,\s*'(\w)'\s*,\s*(\d+)",
+                  text)
+    if m:
+        start = (int(m.group(1)), int(m.group(2)), m.group(3).upper(),
+                 int(m.group(4)))
+
+    return World(avenues, streets, walls, carrots), start
+
+
+_world: World | None = None
+_start = (1, 1, "E", 0)
+_frames: list = []
+_gophers: list = []
+_last_anim = None   # holds the most recent animation so it is not garbage-collected
+
+
+def create_world(avenues=10, streets=10):
+    """Make an empty world and reset the recording."""
+    global _world, _start, _frames, _gophers
+    _world = World(avenues, streets)
+    _start = (1, 1, "E", 0)
+    _frames, _gophers = [], []
+    return _world
+
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_BUNDLED = os.path.join(_HERE, "worlds")
+_SPRITES = os.path.join(_HERE, "sprites")
+_sprite_cache: dict = {}
+
+
+def _sprite(direction):
+    """The gopher artwork for a facing direction, or None if unavailable.
+
+    One PNG per direction, so the sprite never has to be rotated. These are the
+    same images the MATLAB `visualizeWorld.m` used.
+    """
+    name = _DIR_NAMES[direction]
+    if name not in _sprite_cache:
+        path = os.path.join(_SPRITES, f"{name}.png")
+        try:
+            _sprite_cache[name] = plt.imread(path)
+        except Exception:
+            _sprite_cache[name] = None
+    return _sprite_cache[name]
+
+
+def list_worlds():
+    """Names of the world files that ship with the package."""
+    try:
+        return sorted(f for f in os.listdir(_BUNDLED) if f.endswith(".wld"))
+    except OSError:
+        return []
+
+
+def _resolve_world(filename):
+    """Find a world file.
+
+    Looks in this order, so that no upload is ever required:
+
+    1. the path exactly as given (your own world files still work)
+    2. the worlds bundled inside the installed package, by bare name --
+       ``load_world("harvest1.wld")`` and ``load_world("worlds/harvest1.wld")``
+       both resolve to the bundled copy
+    """
+    if os.path.exists(filename):
+        return filename
+    bundled = os.path.join(_BUNDLED, os.path.basename(filename))
+    if os.path.exists(bundled):
+        return bundled
+    raise GopherError(
+        f"No world file called {os.path.basename(filename)!r}.\n"
+        f"Worlds bundled with cege_gopher: {', '.join(list_worlds()) or '(none)'}")
+
+
+def load_world(filename):
+    """Load a `.wld` file and reset the recording.
+
+    The name alone is enough for the worlds that ship with the package:
+    ``load_world("harvest1.wld")``.
+    """
+    global _world, _start, _frames, _gophers
+    with open(_resolve_world(filename)) as fh:
+        _world, _start = _parse_world(fh.read())
+    _frames, _gophers = [], []
+    return _world
+
+
+def get_world() -> World:
+    if _world is None:
+        raise GopherError("No world yet -- call create_world() or load_world() first.")
+    return _world
+
+
+# ==========================================================================
+# Gopher
+# ==========================================================================
+class Gopher:
+    """Goldy, on a grid. Every command records a frame; nothing draws until show()."""
+
+    def __init__(self, orientation=None, avenue=None, street=None, carrots=None,
+                 color=UMN_MAROON, **kw):
+        if _world is None:
+            create_world()
+        sa, ss, so, sc = _start
+        self.avenue = sa if avenue is None else int(avenue)
+        self.street = ss if street is None else int(street)
+        self.orientation = _DIRS[(orientation or so).upper()]
+        # accept beepers=/coins= as aliases for carrots=
+        if carrots is None:
+            carrots = kw.pop("beepers", kw.pop("coins", sc))
+        self.carrots = int(carrots)
+        self.color = color
+        self.trace_color = None
+        self.trace = []
+        self.steps = 0
+        _gophers.append(self)
+        self._record()
+
+    # ---- internals ---------------------------------------------------
+    def _record(self):
+        if self.trace_color:
+            self.trace.append((self.avenue, self.street))
+        _frames.append({
+            "avenue": self.avenue,
+            "street": self.street,
+            "dir": self.orientation,
+            "carried": self.carrots,
+            "world": dict(get_world().carrots),
+            "trace": list(self.trace),
+            "steps": self.steps,
+        })
+
+    def _doubled(self):
+        return 2 * self.avenue - 1, 2 * self.street - 1
+
+    # ---- movement ----------------------------------------------------
+    def move(self):
+        """Move one cell in the direction the gopher is facing."""
+        if not self.front_is_clear():
+            raise GopherError(
+                f"Ouch! There is a wall in front of me at avenue {self.avenue}, "
+                f"street {self.street}, facing {_DIR_NAMES[self.orientation]}.")
+        dx, dy = self.orientation
+        self.avenue += dx
+        self.street += dy
+        self.steps += 1
+        self._record()
+
+    def turn_left(self):
+        """Turn 90 degrees counter-clockwise (E -> N -> W -> S -> E)."""
+        dx, dy = self.orientation
+        self.orientation = (-dy, dx)
+        self._record()
+
+    def turn_right(self):
+        """Not in the original API -- three lefts, provided for convenience."""
+        for _ in range(3):
+            self.turn_left()
+
+    # ---- sensing -----------------------------------------------------
+    def front_is_clear(self) -> bool:
+        col, row = self._doubled()
+        dx, dy = self.orientation
+        return get_world().is_clear(col + dx, row + dy)
+
+    def left_is_clear(self) -> bool:
+        col, row = self._doubled()
+        dx, dy = self.orientation
+        return get_world().is_clear(col - dy, row + dx)
+
+    def right_is_clear(self) -> bool:
+        col, row = self._doubled()
+        dx, dy = self.orientation
+        return get_world().is_clear(col + dy, row - dx)
+
+    def facing_north(self) -> bool:
+        return self.orientation == _DIRS["N"]
+
+    def carries_carrots(self) -> bool:
+        return self.carrots > 0
+
+    def on_carrot(self) -> bool:
+        return get_world().count_carrots(self.avenue, self.street) > 0
+
+    def get_pos(self):
+        return self.avenue, self.street
+
+    # ---- carrots -----------------------------------------------------
+    def pick_carrot(self):
+        if not self.on_carrot():
+            raise GopherError(
+                f"There is no carrot at avenue {self.avenue}, street {self.street}.")
+        get_world().remove_carrot(self.avenue, self.street)
+        self.carrots += 1
+        self._record()
+
+    def drop_carrot(self):
+        if not self.carries_carrots():
+            raise GopherError("I am not carrying any carrots to drop.")
+        get_world().add_carrot(self.avenue, self.street)
+        self.carrots -= 1
+        self._record()
+
+    # ---- display -----------------------------------------------------
+    def set_trace(self, color="maroon"):
+        """Draw a line behind the gopher as it moves."""
+        self.trace_color = _TRACE_COLORS.get(color, color)
+        self.trace = [(self.avenue, self.street)]
+
+    def set_pause(self, delay=0):
+        """No-op. Kept so code from the original library still runs; pacing is
+        set by show(fps=...) instead, because playback is a recording."""
+        return None
+
+    # ---- compatibility aliases --------------------------------------
+    pick_beeper = pick_coin = pick_carrot
+    drop_beeper = drop_coin = drop_carrot
+    on_beeper = on_coin = on_carrot
+    carries_beepers = carries_coins = carries_carrots
+
+
+Robot = Gopher  # so `Robot(...)` from the original examples still works
+
+
+# ==========================================================================
+# Rendering
+# ==========================================================================
+def _draw_gopher(ax, x, y, direction, color):
+    """Draw the gopher facing `direction`, using the artwork if it is available."""
+    img = _sprite(direction)
+    if img is not None:
+        h = 0.86                                   # cell heights
+        w = h * img.shape[1] / img.shape[0]        # keep the sprite's aspect
+        ax.imshow(img, extent=[x - w / 2, x + w / 2, y - h / 2, y + h / 2],
+                  zorder=10, interpolation="antialiased")
+        return
+
+    # Fallback: a simple drawn gopher, so the library still works if the
+    # sprite files are missing.
+    dx, dy = direction
+    px, py = -dy, dx
+    for sgn in (-1, 1):
+        ax.add_patch(Circle((x - 0.20 * dx + 0.17 * px * sgn,
+                             y - 0.20 * dy + 0.17 * py * sgn),
+                            0.11, facecolor=color, edgecolor="white",
+                            linewidth=1.0, zorder=5))
+    ax.add_patch(Circle((x, y), 0.30, facecolor=color, edgecolor="white",
+                        linewidth=1.4, zorder=6))
+    ax.add_patch(Ellipse((x + 0.13 * dx, y + 0.13 * dy), 0.24, 0.24,
+                         facecolor=UMN_GOLD, edgecolor="white",
+                         linewidth=1.0, zorder=7))
+    ax.add_patch(Polygon(
+        [(x + 0.36 * dx, y + 0.36 * dy),
+         (x + 0.16 * dx + 0.11 * px, y + 0.16 * dy + 0.11 * py),
+         (x + 0.16 * dx - 0.11 * px, y + 0.16 * dy - 0.11 * py)],
+        closed=True, facecolor="#2b2b2b", edgecolor="white",
+        linewidth=0.8, zorder=8))
+
+
+def _present(html: str, controls: bool = False) -> str:
+    """Prepare a matplotlib jshtml animation for the classroom.
+
+    Two changes, both cosmetic but both worth having:
+
+    * **Autoplay.** `to_jshtml` always renders paused and has no autoplay option
+      (only `to_html5_video` autoplays). It does build a global `animNNN` object
+      inside a `setTimeout(..., 0)`, so we find that name and poll until it
+      exists, then press play.
+    * **Hide the controls** -- the slider, the button row and the
+      once/loop/reflect radios. Students are watching a replay, not scrubbing a
+      video, and the controls are more clutter than help.
+
+    The controls are *hidden with CSS, not removed*: the animation's JavaScript
+    looks the slider and the loop-select up by id at construction time, so
+    deleting them from the DOM breaks playback. The rule is scoped to this one
+    animation so it cannot affect anything else on the page.
+
+    The id is a hex uuid, not a number -- e.g. animef73a836c4794088b855e878cfca32da.
+    """
+    m = re.search(r"\banim(\w+)\s*=\s*new\s+Animation", html)
+    if not m:                     # matplotlib changed its template; leave it be
+        return html
+    ident = m.group(1)
+
+    hide = "" if controls else f"""
+<style>
+  #gopher-anim-{ident} .anim-controls {{ display: none !important; }}
+</style>"""
+
+    return f"""<div id="gopher-anim-{ident}">
+{html}
+</div>{hide}
+<script language="javascript">
+  (function() {{
+    var tries = 0;
+    var timer = setInterval(function() {{
+      if (typeof anim{ident} !== "undefined" && anim{ident}) {{
+        anim{ident}.play_animation();
+        clearInterval(timer);
+      }} else if (++tries > 100) {{
+        clearInterval(timer);      /* give up rather than poll forever */
+      }}
+    }}, 50);
+  }})()
+</script>
+"""
+
+
+def _auto_figsize(world):
+    """Size the figure from the world, the way visualizeWorld.m did.
+
+    MATLAB used 50 pixels per cell; at matplotlib's 100 dpi that is 0.5 inch.
+    Clamped so a 3x3 world is still readable and a 20x20 one still fits on a
+    screen, and the aspect always matches the grid.
+    """
+    per_cell = 0.5
+    lo, hi = 3.2, 11.0
+    w = min(max(world.avenues * per_cell, lo), hi)
+    h = min(max(world.streets * per_cell, lo), hi)
+    return (w, h)
+
+
+def _draw_frame(ax, frame, world, title=None):
+    ax.clear()
+    av, st = world.avenues, world.streets
+    ax.set_xlim(0.3, av + 0.7)
+    ax.set_ylim(0.3, st + 0.7)
+    ax.set_aspect("equal")
+    ax.set_xticks(range(1, av + 1))
+    ax.set_yticks(range(1, st + 1))
+    ax.set_xlabel("avenue")
+    ax.set_ylabel("street")
+    ax.grid(True, color="0.85", linewidth=0.8, zorder=0)
+    for spine in ax.spines.values():
+        spine.set_visible(False)
+
+    # world border
+    ax.add_patch(Rectangle((0.5, 0.5), av, st, fill=False,
+                           edgecolor="0.25", linewidth=2.5, zorder=3))
+
+    # Walls, in doubled coordinates, sit *between* cells.
+    #   even col -> vertical wall east of avenue col/2, at x = col/2 + 0.5
+    #   even row -> horizontal wall north of street row/2, at y = row/2 + 0.5
+    for (col, row) in world.walls:
+        if col % 2 == 0:                      # vertical
+            x = col / 2 + 0.5
+            s = (row + 1) / 2
+            ax.plot([x, x], [s - 0.5, s + 0.5], color="0.25", linewidth=4,
+                    zorder=4, solid_capstyle="butt")
+        else:                                 # horizontal
+            y = row / 2 + 0.5
+            a = (col + 1) / 2
+            ax.plot([a - 0.5, a + 0.5], [y, y], color="0.25", linewidth=4,
+                    zorder=4, solid_capstyle="butt")
+
+    # carrots
+    for (a, s), n in frame["world"].items():
+        ax.add_patch(Circle((a, s), 0.17, color=UMN_GOLD,
+                            ec="0.3", lw=1.0, zorder=2))
+        if n > 1:
+            ax.text(a, s, str(n), ha="center", va="center",
+                    fontsize=8, fontweight="bold", zorder=3)
+
+    # trace
+    if len(frame["trace"]) > 1:
+        xs = [p[0] for p in frame["trace"]]
+        ys = [p[1] for p in frame["trace"]]
+        ax.plot(xs, ys, color=UMN_MAROON, linewidth=1.8, alpha=0.55, zorder=1)
+
+    _draw_gopher(ax, frame["avenue"], frame["street"], frame["dir"], UMN_MAROON)
+
+    head = title or (f"steps: {frame['steps']}   carrots carried: "
+                     f"{frame['carried']}")
+    ax.set_title(head, fontsize=10)
+
+
+def show(fps=3, figsize=None, controls=False):
+    """Replay the recorded run as an inline animation, and start it playing.
+
+    The animation is **displayed as a side effect**, not returned, so it appears
+    wherever you call it -- including with `print()` lines after it. (Returning
+    it would rely on Jupyter auto-displaying the last expression of the cell,
+    which silently drops the animation the moment anything follows.)
+
+    The player's slider and buttons are hidden by default; pass
+    ``controls=True`` to get them back.
+
+    Outside a notebook there is nothing to animate into, so the final frame is
+    returned as a figure instead.
+    """
+    world = get_world()
+    if not _frames:
+        raise GopherError("Nothing to show -- create a Gopher and move it first.")
+    if figsize is None:
+        figsize = _auto_figsize(world)
+
+    # Decide *before* building anything: outside a notebook the animation would
+    # be built and thrown away, which also trips a matplotlib warning.
+    try:
+        from IPython import get_ipython
+        from IPython.display import HTML, display
+        in_notebook = get_ipython() is not None
+    except ImportError:
+        in_notebook = False
+    if not in_notebook:
+        return show_final(figsize=figsize)
+
+    plt.close("all")
+    fig, ax = plt.subplots(figsize=figsize)
+    plt.close(fig)                     # keep the static figure out of the output
+
+    def update(i):
+        _draw_frame(ax, _frames[i], world)
+        return ax.patches + ax.lines
+
+    anim = animation.FuncAnimation(
+        fig, update, frames=len(_frames),
+        interval=max(1000 // max(fps, 1), 1), blit=False, repeat=True)
+    # Keep a reference: matplotlib warns (and can garbage-collect the animation)
+    # if nothing holds on to it.
+    global _last_anim
+    _last_anim = anim
+
+    display(HTML(_present(anim.to_jshtml(default_mode="once"), controls)))
+    return None
+
+
+def show_final(figsize=None):
+    """Draw just the last frame. Useful for a static figure in slides or a PDF."""
+    world = get_world()
+    if not _frames:
+        raise GopherError("Nothing to show -- create a Gopher and move it first.")
+    if figsize is None:
+        figsize = _auto_figsize(world)
+    plt.close("all")            # do not leak a figure per call
+    fig, ax = plt.subplots(figsize=figsize)
+    _draw_frame(ax, _frames[-1], world, title="final state")
+    return fig

cege_gopher-0.1.0/src/cege_gopher/worlds/around1.wld

@@ -0,0 +1,5 @@
+avenues = 5
+streets = 5
+robot = (1, 1, 'E', 1)
+walls = []
+coins = {}

cege_gopher-0.1.0/src/cege_gopher/worlds/around2.wld

@@ -0,0 +1,14 @@
+avenues = 7
+streets = 7
+robot = (1, 1, 'E', 1)
+walls = [
+    (6, 13), 
+    (6, 11), 
+    (6, 9), 
+    (13, 6), 
+    (11, 6), 
+    (9, 6), 
+    (7, 6), 
+    (6, 7)
+]
+coins = {}

cege_gopher-0.1.0/src/cege_gopher/worlds/around3.wld

@@ -0,0 +1,15 @@
+avenues = 7
+streets = 7
+robot = (1, 1, 'E', 1)
+walls = [
+    (2, 1), 
+    (3, 2), 
+    (5, 2), 
+    (6, 3), 
+    (6, 5), 
+    (6, 7), 
+    (6, 9), 
+    (6, 11), 
+    (6, 13)
+]
+coins = {}

cege_gopher-0.1.0/src/cege_gopher/worlds/harvest1.wld

@@ -0,0 +1,42 @@
+avenues = 7
+streets = 7
+robot = (1, 1, 'E', 0)
+walls = []
+coins = {
+    (3, 3): 1, 
+    (3, 2): 1, 
+    (3, 1): 1, 
+    (5, 6): 1, 
+    (5, 1): 1, 
+    (3, 6): 1, 
+    (5, 3): 1, 
+    (5, 2): 1, 
+    (7, 6): 1, 
+    (7, 5): 1, 
+    (7, 4): 1, 
+    (7, 3): 1, 
+    (7, 2): 1, 
+    (7, 1): 1, 
+    (3, 5): 1, 
+    (3, 4): 1, 
+    (2, 4): 1, 
+    (2, 5): 1, 
+    (2, 6): 1, 
+    (2, 1): 1, 
+    (2, 2): 1, 
+    (2, 3): 1, 
+    (4, 6): 1, 
+    (4, 4): 1, 
+    (4, 5): 1, 
+    (4, 2): 1, 
+    (4, 3): 1, 
+    (4, 1): 1, 
+    (6, 1): 1, 
+    (6, 2): 1, 
+    (6, 3): 1, 
+    (6, 4): 1, 
+    (6, 5): 1, 
+    (6, 6): 1, 
+    (5, 5): 1, 
+    (5, 4): 1
+}

cege_gopher-0.1.0/src/cege_gopher/worlds/harvest2.wld

@@ -0,0 +1,36 @@
+avenues = 7
+streets = 7
+robot = (1, 1, 'E', 0)
+walls = []
+coins = {
+    (7, 3): 1, 
+    (6, 6): 1, 
+    (5, 6): 1, 
+    (3, 2): 1, 
+    (2, 1): 1, 
+    (6, 2): 1, 
+    (5, 1): 1, 
+    (2, 5): 1, 
+    (7, 2): 1, 
+    (7, 6): 1, 
+    (4, 4): 1, 
+    (3, 6): 1, 
+    (2, 2): 1, 
+    (3, 5): 1, 
+    (4, 1): 1, 
+    (6, 4): 1, 
+    (5, 4): 1, 
+    (7, 1): 1, 
+    (4, 5): 1, 
+    (5, 5): 1, 
+    (2, 3): 1, 
+    (4, 2): 1, 
+    (6, 5): 1, 
+    (5, 3): 1, 
+    (4, 6): 1, 
+    (3, 4): 1, 
+    (6, 1): 1, 
+    (7, 4): 1, 
+    (4, 3): 1, 
+    (2, 4): 1
+}

cege_gopher-0.1.0/src/cege_gopher/worlds/harvest3.wld

@@ -0,0 +1,36 @@
+avenues = 7
+streets = 7
+robot = (1, 1, 'E', 99)
+walls = []
+coins = {
+    (7, 3): 1, 
+    (6, 6): 1, 
+    (5, 6): 1, 
+    (3, 2): 1, 
+    (2, 1): 1, 
+    (6, 2): 1, 
+    (5, 1): 2, 
+    (2, 5): 1, 
+    (7, 2): 1, 
+    (5, 5): 1, 
+    (7, 6): 1, 
+    (4, 4): 1, 
+    (3, 6): 1, 
+    (2, 2): 2, 
+    (3, 5): 1, 
+    (4, 1): 1, 
+    (6, 4): 1, 
+    (5, 4): 1, 
+    (7, 1): 1, 
+    (4, 5): 1, 
+    (2, 3): 1, 
+    (4, 2): 1, 
+    (6, 5): 2, 
+    (5, 3): 2, 
+    (4, 6): 1, 
+    (6, 1): 1, 
+    (7, 4): 1, 
+    (4, 3): 1, 
+    (3, 4): 2, 
+    (2, 4): 1
+}

cege_gopher-0.1.0/src/cege_gopher/worlds/harvest5.wld

@@ -0,0 +1,42 @@
+avenues = 12
+streets = 12
+robot = (1, 1, 'E', 36)
+walls = []
+coins = {
+    (7, 3): 1, 
+    (6, 10): 1, 
+    (6, 6): 1, 
+    (2, 8): 1, 
+    (10, 6): 1, 
+    (7, 7): 1, 
+    (4, 6): 1, 
+    (6, 2): 1, 
+    (7, 11): 1, 
+    (3, 7): 1, 
+    (10, 8): 1, 
+    (5, 5): 1, 
+    (4, 4): 1, 
+    (8, 10): 1, 
+    (4, 8): 1, 
+    (8, 6): 1, 
+    (5, 3): 1, 
+    (9, 7): 1, 
+    (4, 10): 1, 
+    (2, 6): 1, 
+    (5, 11): 1, 
+    (5, 9): 1, 
+    (7, 5): 1, 
+    (6, 12): 1, 
+    (6, 4): 1, 
+    (3, 5): 1, 
+    (11, 7): 1, 
+    (6, 8): 1, 
+    (5, 7): 1, 
+    (9, 9): 1, 
+    (8, 8): 1, 
+    (7, 9): 1, 
+    (1, 7): 1, 
+    (9, 5): 1, 
+    (3, 9): 1, 
+    (8, 4): 1
+}

cege_gopher-0.1.0/src/cege_gopher/worlds/hurdles1.wld

@@ -0,0 +1,12 @@
+avenues = 10
+streets = 10
+robot = (1, 1, 'E', 0)
+walls = [
+    (4, 1), 
+    (8, 1), 
+    (12, 1), 
+    (16, 1)
+]
+coins = {
+    (10, 1): 1
+}

cege_gopher-0.1.0/src/cege_gopher/worlds/hurdles2.wld

@@ -0,0 +1,12 @@
+avenues = 10
+streets = 10
+robot = (1, 1, 'E', 0)
+walls = [
+    (4, 1), 
+    (8, 1), 
+    (12, 1), 
+    (16, 1)
+]
+coins = {
+    (7, 1): 1
+}

cege_gopher-0.1.0/src/cege_gopher/worlds/hurdles3.wld

@@ -0,0 +1,15 @@
+avenues = 10
+streets = 10
+robot = (1, 1, 'E', 0)
+walls = [
+    (4, 1), 
+    (8, 1), 
+    (16, 1), 
+    (2, 1), 
+    (10, 1), 
+    (18, 1), 
+    (12, 1)
+]
+coins = {
+    (10, 1): 1
+}

cege_gopher-0.1.0/src/cege_gopher/worlds/hurdles4.wld

@@ -0,0 +1,18 @@
+avenues = 10
+streets = 10
+robot = (1, 1, 'E', 0)
+walls = [
+    (4, 1), 
+    (8, 1), 
+    (16, 1), 
+    (2, 1), 
+    (10, 1), 
+    (18, 1), 
+    (12, 1), 
+    (4, 3), 
+    (10, 3), 
+    (10, 5)
+]
+coins = {
+    (10, 1): 1
+}

cege_gopher-0.1.0/src/cege_gopher/worlds/maze1.wld

@@ -0,0 +1,32 @@
+avenues = 10
+streets = 10
+robot = (1, 1, 'E', 0)
+walls = [
+    (10, 1), 
+    (10, 3), 
+    (10, 5), 
+    (1, 10), 
+    (3, 10), 
+    (5, 10), 
+    (2, 1), 
+    (2, 3), 
+    (1, 6), 
+    (3, 6), 
+    (4, 5), 
+    (4, 3), 
+    (5, 2), 
+    (6, 3), 
+    (7, 8), 
+    (5, 8), 
+    (2, 7), 
+    (7, 10), 
+    (8, 7), 
+    (9, 6), 
+    (8, 3), 
+    (9, 4), 
+    (9, 10), 
+    (10, 9)
+]
+coins = {
+    (6, 4): 1
+}

cege_gopher-0.1.0/src/cege_gopher/worlds/newspaper.wld

@@ -0,0 +1,18 @@
+avenues = 10
+streets = 10
+robot = (1, 1, 'E', 1)
+walls = [
+    (4, 1), 
+    (5, 2), 
+    (7, 2), 
+    (8, 3), 
+    (9, 4), 
+    (11, 4), 
+    (12, 5), 
+    (13, 6), 
+    (15, 6), 
+    (16, 7), 
+    (17, 8), 
+    (19, 8)
+]
+coins = {}

cege_gopher-0.1.0/src/cege_gopher.egg-info/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: cege-gopher
+Version: 0.1.0
+Summary: A Karel-style grid robot for teaching Python, themed as Goldy Gopher. Records and replays, so it works in Colab.
+Author-email: Seongjin Choi <chois@umn.edu>
+License: MIT License
+        
+        Copyright (c) 2026 Seongjin Choi
+        
+        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.
+        
+Keywords: education,karel,robot,colab,cege3101
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Education
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.5
+Dynamic: license-file
+
+# cege_gopher
+
+A Karel-style grid robot for teaching introductory Python, themed as Goldy
+Gopher. Written for **CEGE 3101 — Computer Applications I** at the University of
+Minnesota.
+
+Ported from the MATLAB robot used in earlier offerings of the course, which was
+itself a port of the KAIST CS101 HUBO exercise
+([otfried/cs101](https://github.com/otfried/cs101)) — Karel the Robot, at the
+root of it.
+
+## Why this exists
+
+The original libraries open a live window and animate each command as it runs.
+**Google Colab cannot host one.**
+
+So this version **records, then replays**. Every command appends a frame to a
+buffer; nothing is drawn until `show()`, which renders the whole run as an
+inline animation:
+
+> write the whole program → run the cell → watch it play back
+
+Students never drive the robot interactively; every program is pre-coded, which
+is also how the homework is graded.
+
+## Install
+
+```bash
+pip install cege-gopher
+```
+
+Or, from the course repository:
+
+```bash
+pip install "git+https://github.com/benchoi93/CEGE3101_Computer_Applications.git#subdirectory=packages/cege-gopher"
+```
+
+The 13 world files ship **inside the package**, so nothing needs uploading —
+`load_world("harvest1.wld")` just works.
+
+## Use
+
+```python
+from cege_gopher import *
+
+load_world("harvest1.wld")       # or: create_world(10, 10)
+goldy = Gopher()
+goldy.set_trace("maroon")
+
+while goldy.front_is_clear():
+    if goldy.on_carrot():
+        goldy.pick_carrot()
+    goldy.move()
+
+show()                           # the animation renders here
+```
+
+`list_worlds()` returns the bundled world names.
+
+## API
+
+| | |
+|---|---|
+| Module | `create_world(avenues, streets)`, `load_world(name)`, `list_worlds()`, `show(fps=)`, `show_final()`, `get_world()` |
+| Move | `move()`, `turn_left()`, `turn_right()` |
+| Carrots | `pick_carrot()`, `drop_carrot()` |
+| Sense | `front_is_clear()`, `left_is_clear()`, `right_is_clear()`, `facing_north()`, `on_carrot()`, `carries_carrots()` |
+| Display | `set_trace(color)`, `get_pos()` |
+
+`Robot` is an alias for `Gopher`, and `pick_beeper`/`pick_coin` for
+`pick_carrot`, so code written against `cs1robots` or the MATLAB version still
+runs.
+
+## A bug fixed in this port
+
+The MATLAB version had `leftIsClear` and `rightIsClear` **swapped** — facing
+east it checked south for "left", when `turnLeft` rotates counter-clockwise
+(E→N) so left of east is north. This port uses `left = (-dy, dx)`,
+`right = (dy, -dx)`.
+
+## License
+
+MIT.

cege_gopher-0.1.0/src/cege_gopher.egg-info/SOURCES.txt

@@ -0,0 +1,26 @@
+LICENSE
+README.md
+pyproject.toml
+src/cege_gopher/__init__.py
+src/cege_gopher.egg-info/PKG-INFO
+src/cege_gopher.egg-info/SOURCES.txt
+src/cege_gopher.egg-info/dependency_links.txt
+src/cege_gopher.egg-info/requires.txt
+src/cege_gopher.egg-info/top_level.txt
+src/cege_gopher/sprites/E.png
+src/cege_gopher/sprites/N.png
+src/cege_gopher/sprites/S.png
+src/cege_gopher/sprites/W.png
+src/cege_gopher/worlds/around1.wld
+src/cege_gopher/worlds/around2.wld
+src/cege_gopher/worlds/around3.wld
+src/cege_gopher/worlds/harvest1.wld
+src/cege_gopher/worlds/harvest2.wld
+src/cege_gopher/worlds/harvest3.wld
+src/cege_gopher/worlds/harvest5.wld
+src/cege_gopher/worlds/hurdles1.wld
+src/cege_gopher/worlds/hurdles2.wld
+src/cege_gopher/worlds/hurdles3.wld
+src/cege_gopher/worlds/hurdles4.wld
+src/cege_gopher/worlds/maze1.wld
+src/cege_gopher/worlds/newspaper.wld

cege_gopher-0.1.0/src/cege_gopher.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cege_gopher-0.1.0/src/cege_gopher.egg-info/requires.txt

@@ -0,0 +1 @@
+matplotlib>=3.5

cege_gopher-0.1.0/src/cege_gopher.egg-info/top_level.txt

@@ -0,0 +1 @@
+cege_gopher