This is a lightweight Python simulator for experimenting with car dynamics and collision handling, built using Pygame and NumPy. It provides a simple environment where you can load maps, drive a car around, and test motion, boundary, and obstacle interactions.
The simulator supports:
-
Custom Maps: Load
.pngor.jpgmaps in color or black/white.- Color images are automatically converted to grayscale and thresholded into obstacles (black) and free space (white).
-
Collision Handling: The car stops when colliding with obstacles or boundaries.
-
Kinematic Car Model: Includes acceleration, friction, max speed, and steering limits.
-
Built-in Map Generator: If no map is provided, a default test track is created.
-
HUD Display: Shows velocity, angular rate, position, and heading in real-time.
Install dependencies with:
pip install pygame numpyRun the simulator with:
python main.py-
--map <path>: Path to a map image (.png/.jpg).- Color images will be converted to black/white automatically.
- Black = obstacle, White = free space.
-
--car <path>: Path to the car sprite image (.png). Defaults toplayer.png. -
--scale <float>: Scale factor for the input map before rendering.
Example:
python main.py --map track.png --car f1car.png --scale 0.5- Up Arrow → Accelerate forward
- Down Arrow → Accelerate backward
- Left Arrow → Steer left
- Right Arrow → Steer right
- R → Reset car position
- Q or Esc → Quit simulator
✅ Load color or black/white maps ✅ Drive the car around obstacles ✅ Real-time physics and collision detection ✅ Reset and re-run experiments quickly
main.py— Core simulator loopCarclass — Kinematic car dynamics and drawingload_bw_map()— Utility for map loading, grayscale conversion, and thresholdinggenerate_builtin_map()— Creates a default rectangular track
- Add LiDAR/raycasting sensors
- Logging & replay tools
- Multi-car racing support
- Gym-compatible wrapper for RL training
MIT License — free to use and modify.