Bus Line Sorting: Python Bindings, Memory Visualizer & Moovit GUI

University Repository: https://github.cs.huji.ac.il/shirazmarom/ex2_bonus.git
Public Repository: https://github.com/Shiraz-Tehila-Marom/ai-c-python-project.git

This repository contains the ctypes bindings and extensions for the Bus Line Sorting assignment. It integrates the high-performance sorting algorithms written in C with a clean Python interface, provides an educational console memory visualizer for pointer arithmetic, and extends the project with an interactive Moovit-inspired routing GUI.

---

1. Implemented Parts

A. Python Bindings for Bus Line Sorting

• Library Compilation: The original C sorting logic (sort_bus_lines.c) is compiled into a shared library (libsort_bus_lines.so) with no modifications.
• Wrapper Module (bus_sort_module.py):
  • Maps the C BusLine structure and SortType enum to C-compatible ctypes data structures.
  • Implements bubble_sort (lexicographical sorting by name) and quick_sort (numerical sorting by distance, duration, or frequency).
  • Validates inputs, handles Unicode conversions, and marshals Python dictionary lists to C structures.
  • Preserves exact pointer boundaries matching the C backend's &lines[n-1] endpoint layout.
• Automated Tests (test_bus_sort.py): Includes a pytest suite validating sort correctness, boundary/edge conditions, and argument types.

B. Memory Pointer Visualizer (visualizer.c)

• Simulates how bubble_sort and quick_sort navigate through array slots in memory using pointers.
• Uses the 3-element dataset ["Dan", "Alice", "Charlie"] and displays fake memory addresses (0x1000, 0x1040, 0x1080).
• Generates step-by-step memory layout diagrams indicating where pointers (start, end/pivot, smaller_ptr, p) point at each pass and loop comparison.

---

2. Implemented Extensions

Moovit-styled Transit GUI (gui_app.py)

• Moovit Styling: Implements a dark slate, orange, and green themed transit dashboard using Python's native tkinter library.
• C Backend Integration: Interfaces directly with bus_sort_module.py to sort transit options in real-time using compiled C algorithms.
• Vector Transit Map: A custom vector map engine running on a tkinter.Canvas displaying grid roads, green parks, a river, and active starting nodes.
• Route Animation: Animates a transit marker dot moving step-by-step from the selected starting district along coordinates to the University.
• Travel Instructions: Displays a structured instruction card panel showing navigation directions.

---

3. Code Structure Blueprint

├── main.c                   # Original C assignment entry point
├── sort_bus_lines.c         # C sorting algorithms (Bubble & Quick Sort)
├── sort_bus_lines.h         # C function declarations and structures
├── libsort_bus_lines.so     # Compiled C shared library
├── bus_sort_module.py       # Python ctypes binding layer and wrapper functions
├── gui_app.py               # Moovit-styled Python GUI application
├── visualizer.c             # Standalone C program for pointer visualization
├── test_bus_sort.py         # Pytest verification suite
├── test_fib.py              # Pytest for Fibonacci ctypes basics
├── fib_module.py            # Basic Fibonacci ctypes example
└── README.md                # Project documentation

---

4. Execution Instructions

Ensure you are working inside a Linux environment (such as WSL on Windows) with gcc, make, and python3 installed.

1. Compile the Shared C Library

Compile sort_bus_lines.c into the .so shared library:

gcc -shared -o libsort_bus_lines.so -fPIC sort_bus_lines.c

2. Run the Automated Python Tests

Verify Python bindings and ctypes marshalling using pytest:

python3 -m pytest test_bus_sort.py

3. Compile and Run the Memory Visualizer

Compile and run the educational pointer visualizer:

gcc visualizer.c -o visualizer && ./visualizer

4. Launch the Moovit Transit GUI

Run the interactive Python interface (ensure X11 or WSLg is enabled if running inside WSL):

python3 gui_app.py