Collision Simulation

1. Project Overview

	Interactive physics simulation of elastic collisions between multiple spherical bodies in 2D space. Built with OpenGL 4.6, GLFW, PyGLM, numpy, and ImGui.

Key Features:

• N-body simulation with random initial parameters
• Elastic collision detection and resolution
• Spatial grid optimization
• Boundary reflections with energy conservation
• Real-time gravity vector control (X and Y axes)
• Dynamic velocity-based coloring
• Interactive color gradient editing
• Real-time velocity threshold adjustment
• Pause/resume and speed control
• Adaptive aspect ratio handling
• FPS display

---

2. Architecture

2.1. Body Class (body.py)

Represents a physical body with position, velocity, acceleration, mass, size, and colors. Handles position updates, boundary collisions, dynamic coloring, and collision detection/resolution between pairs.

2.2. SpatialGrid Class (spatial_grid.py)

Implements spatial partitioning for collision optimization. Divides space into cells and maintains body references per cell, reducing collision checks from O(n²) to O(n) average.

2.3. Simulation Class (simulation.py)

Core simulation manager. Initializes bodies, manages collision detection via spatial grid, updates simulation state, applies global forces (gravity), handles aspect ratio changes, and provides data for visualization.

2.4. GUI Class (gui.py)

ImGui-based user interface with GLFW backend. Provides pause/resume, speed control, gravity sliders (X/Y), dynamic coloring toggle, velocity threshold sliders, and color gradient selectors.

2.5. Renderer Class (renderer.py)

OpenGL rendering layer. Compiles shaders, manages GPU buffers (VAO, VBO), updates buffers with simulation data, configures rendering pipeline (blending, antialiasing), and renders particles as points.

Shaders:

• Vertex: Transforms positions, sets size and color
• Fragment: Draws smooth circles with alpha blending and antialiasing

2.6. main.py

Application entry point. Initializes GLFW window with OpenGL 4.6 Core Profile and 4x MSAA, creates Simulation/GUI/Renderer instances, runs main loop (events → update → render), calculates deltaTime and FPS, handles window resize with aspect ratio updates, and manages cleanup.

---

3. User Guide

3.1. Requirements

• Python 3.14.0+
• OpenGL 4.6 support

3.2. Installation

pip install -r requirements.txt

3.3. Usage

python main.py [-width WIDTH] [-height HEIGHT] [-particles PARTICLES]

Parameters (all optional):

• -width: Window width in pixels (default: 800, min: 400, max: 2560)
• -height: Window height in pixels (default: 700, min: 300, max: 1440)
• -particles: Number of bodies (default: 1500)

Example:

python main.py -width 2137 -height 1000 -particles 1500

3.4. Controls

Control Panel (top-left):

1. Pause/Resume Button

   • Pauses/resumes physics simulation
   • Rendering continues during pause

2. Gravity Vector

   • Horizontal (X): -0.1 to 0.1 (default: 0.0)
   • Vertical (Y): -0.1 to 0.1 (default: 0.0, negative = downward gravity)

3. Visual Options

   • Color based on speed: Toggle dynamic coloring
   • Min speed threshold: Lower velocity bound for gradient
   • Min color selector: Color for slow bodies (default: blue [0,0,1])
   • Max speed threshold: Upper velocity bound for gradient
   • Max color selector: Color for fast bodies (default: red [1,0,0])

Window:

• Resize supported (400x300 to 2560x1440)
• FPS displayed in title bar

3.5. Configuration

Main parameters (main.py):

SCR_WIDTH = 1000
SCR_HEIGHT = 500
N = 1500

Body initialization ranges (simulation.py):

• Position X: (-0.9 * aspect_ratio, 0.9 * aspect_ratio)
• Position Y: (-0.9, 0.9)
• Initial velocity: (-0.2, 0.2) per axis
• Size: Dynamically scaled based on body count
• Mass: (max_radius, max_radius * 2)
• RGB colors: 0.3 to 1.0 per channel

Color visualization (gui.py):

• min_speed_threshold: 0.01
• max_speed_threshold: 0.4
• Gradient: blue (slow) → purple (medium) → red (fast)

---

4. Reflection

4.1. Completed Work

• Complete elastic collision physics with spatial grid optimization
• Advanced UI with real-time parameter control
• Interactive gradient editing with velocity thresholds
• Speed control (including reverse playback)
• Modern OpenGL 4.6 rendering with custom shaders
• Dynamic window resizing with aspect ratio adaptation
• Velocity-based dynamic coloring
• Body size scaling based on particle count
• Command-line parameterization
• Comprehensive documentation

4.2. Future Enhancements

• Quadtree spatial partitioning for O(n log n) collisions
• Multithreading with Numba (requires data-oriented refactoring)
• Multiple object types (static walls, polygons)
• Mouse interaction (add/remove/drag objects)
• Save/load simulation states
• Advanced visualization filters (trajectories, force vectors)
• 3D physics support

---

5. References

• Elastic Collisions from Dipam's Notebook
• 2-Dimensional Elastic Collisions without Trigonometry, Chad Berchek
• OpenGL Reference Pages
• Learn OpenGL
• Rendering logic from N-body problem project