Explore the mysteries of spacetime through cutting-edge visualization
🚀 Live Demo • 📖 Documentation • 🐛 Report Bug • ✨ Request Feature • 📝 Article on Medium
- 🌟 Features
- 🔬 Physics Implementation
- 🛠️ Technologies
- 🚀 Quick Start
- 📱 Usage
- 🏗️ Project Structure
- ⚙️ Configuration
- 🎯 Controls
- 📐 Physics Parameters
- 🤝 Contributing
- 📄 License
- 👏 Acknowledgments
A physics-based black hole simulation built with React, TypeScript, Three.js, and WebGL shaders, showcasing relativistic effects including gravitational lensing and accretion disk dynamics. Here are the live demo links hosted on GitHub pages and Vercel. Please read my Medium article for further explanation.
- 🌀 Real-time gravitational lensing - Watch light bend around massive objects
- 💫 Interactive accretion disk - Visualize matter spiraling into the black hole
- 🎮 Responsive controls - Desktop navigation bar and mobile-friendly interface
- 🔄 Real-time physics - GPU-accelerated calculations for smooth performance
- 📱 Cross-platform - Works seamlessly on desktop, tablet, and mobile devices
- 🎨 Stunning visuals - Realistic rendering with custom WebGL shaders
- GPU-Accelerated Physics - Utilizing WebGL fragment shaders for real-time calculations
- Responsive Design - Adaptive UI that works across all screen sizes
- Modern Architecture - Built with React 18, TypeScript, and Vite
- Educational Focus - Perfect for physics students and space enthusiasts
Our simulation implements cutting-edge astrophysics concepts with mathematical precision:
- Schwarzschild Metric - Proper spacetime curvature around a black hole
- Geodesic Integration - Runge-Kutta 4th order integration for accurate light path calculations
- Gravitational Lensing - Light bending effects around massive objects
- Event Horizon - Proper black hole boundary visualization with Schwarzschild radius
- Doppler Shift - Relativistic frequency shifts in the accretion disk
- Gravitational Redshift - Energy loss of light escaping gravitational wells
- Angular Momentum Conservation - Realistic orbital mechanics
- Fractal Noise Generation - Procedural accretion disk structure
| Frontend | Physics & Graphics | Development | Deployment |
|---|---|---|---|
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
- React 18 - Modern React with hooks and functional components
- TypeScript - Full type safety and enhanced developer experience
- Three.js - 3D graphics engine and WebGL abstraction
- Custom GLSL Shaders - GPU-accelerated physics calculations
- Vite - Lightning-fast build tool and development server
- Responsive CSS - Mobile-first design with breakpoints
Ensure you have the following installed:
- Node.js
>=18.0.0(Download here) - npm
>=8.0.0(comes with Node.js) - Modern browser with WebGL 2.0 support
-
Clone the repository
git clone https://github.com/chrismatgit/black-hole-simulation.git cd black-hole-simulation -
Install dependencies
npm install
-
Start development server
npm run dev
-
Open in browser Navigate to http://localhost:5173
# Build the project
npm run build
# Preview production build
npm run preview
# Run linting
npm run lint# Build Docker image
docker build -t black-hole-simulation .
# Run container
docker run -p 5173:80 black-hole-simulation- Navigation Bar - Full-featured controls with dropdown menus
- Real-time Sliders - Adjust physics parameters instantly
- Keyboard Shortcuts - Quick access to common functions
- Mouse Interaction - Zoom with scroll wheel
- Slide-out Panel - Touch-friendly control interface
- Gesture Support - Pinch to zoom, tap to control
- Optimized Layout - Responsive design for all screen sizes
- Play/Pause Simulation - Control time flow
- Adjust Physics Parameters - Real-time parameter modification
- Toggle Accretion Disk - Show/hide matter visualization
- Camera Animation - Automated cinematic views
- Reset to Defaults - Quick restoration of initial settings
black-hole-simulation/
├── 📁 src/
│ ├── 📁 components/ # React components
│ │ ├── BlackHoleSimulation.tsx # Main simulation engine
│ │ ├── NavigationBar.tsx # Desktop navigation
│ │ ├── MobileControlPanel.tsx # Mobile interface
│ │ └── GitHubLink.tsx # Attribution component
│ ├── 📁 shaders/ # WebGL shaders
│ │ ├── canvasVertexShader.ts # Vertex transformations
│ │ └── canvasFragmentShader.ts # Physics calculations
│ ├── 📁 utils/ # Utility functions
│ │ └── math.ts # Mathematical helpers
│ ├── 📄 App.tsx # Root application component
│ ├── 📄 main.tsx # React entry point
│ └── 🎨 *.css # Styling files
├── 📁 public/ # Static assets
│ └── 🖼️ *.jpg # Background textures
├── 📁 dist/ # Production build output
├── 📄 package.json # Dependencies and scripts
├── 📄 vite.config.ts # Vite configuration
├── 📄 tsconfig.json # TypeScript configuration
└── 📄 README.md # This file
| Component | Purpose | Features |
|---|---|---|
BlackHoleSimulation |
Core physics engine | WebGL rendering, Three.js scene management |
NavigationBar |
Desktop controls | Dropdown menus, real-time sliders |
MobileControlPanel |
Mobile interface | Touch-friendly slide-out panel |
Fragment Shader |
Physics calculations | GPU-accelerated ray tracing |
Customize the simulation by modifying these constants in the fragment shader:
// Core physics constants
#define SPEED_OF_LIGHT 1.0 // Normalized light speed
#define EVENT_HORIZON_RADIUS 1.0 // Schwarzschild radius
#define BACKGROUND_DISTANCE 10000.0 // Distance to background stars
#define PROJECTION_DISTANCE 1.0 // Camera projection distance
// Accretion disk parameters
float innerDiskRadius = 2.0; // Inner disk boundary
float outerDiskRadius = 8.0; // Outer disk boundary
float disk_flow = 10.0; // Orbital flow rateAdjust visual quality and performance:
interface SimulationSettings {
accretion_disk: boolean; // Show/hide accretion disk
animate: boolean; // Enable camera animation
speed: number; // Animation speed (0-1)
max_iterations: number; // Ray tracing precision (50-2000)
}/* Desktop navigation */
@media (min-width: 1200px) {
...;
}
/* Tablet and mobile */
@media (max-width: 1199px) {
...;
}| Action | Control | Description |
|---|---|---|
| Zoom | Mouse Wheel | Zoom in/out of the simulation |
| Pause | Spacebar | Toggle simulation pause/play |
| Reset | R Key | Reset to default parameters |
- ⚛️ Physics - Adjust simulation parameters
- Max Iterations (50-2000) - Ray tracing precision
- Animation Speed (0-1) - Camera movement speed
- 🎨 Visuals - Control visual elements
- Accretion Disk toggle - Show/hide disk visualization
- Auto-animate Camera - Enable cinematic movement
- ❓ Help - Usage instructions and tips
- 🎮 Controls - Play/Pause/Restart buttons
- ⚙️ Settings - Same parameters as desktop in touch-friendly format
- 📱 Responsive - Optimized for touch interaction
The simulation implements real physics with these carefully chosen parameters:
// Fundamental Constants (Normalized Units)
#define SPEED_OF_LIGHT 1.0 // c = 1 (natural units)
#define EVENT_HORIZON_RADIUS 1.0 // rs = 2GM/c²
#define BACKGROUND_DISTANCE 10000.0 // Distance to celestial sphere
#define PROJECTION_DISTANCE 1.0 // Observer screen distance
// Accretion Disk Parameters
float innerRadius = 2.0; // Inner stable circular orbit (3rs)
float outerRadius = 8.0; // Outer disk boundary
float angularVelocity = 10.0; // Orbital flow rate| Parameter | Range | Description | Physics Impact |
|---|---|---|---|
| Max Iterations | 50-2000 | Ray tracing precision | Higher = more accurate lensing |
| Animation Speed | 0.0-1.0 | Camera orbit rate | Cinematic effect control |
| Accretion Disk | On/Off | Matter visualization | Shows infalling material |
- Low Settings (Mobile): 50-200 iterations, disk off
- Medium Settings (Desktop): 200-800 iterations, disk on
- High Settings (High-end): 800-2000 iterations, all effects
We welcome contributions from the physics and programming community! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.
-
🍴 Fork the repository
git clone https://github.com/chrismatgit/black-hole-simulation.git cd black-hole-simulation -
🌟 Create a feature branch
git checkout -b feature/amazing-new-feature
-
✨ Make your changes
- Follow the existing code style
- Add tests for new features
- Update documentation as needed
-
🧪 Test your changes
npm run lint # Check code quality npm run build # Ensure production build works npm run preview # Test production build
-
📝 Commit and push
git add . git commit -m "✨ Add amazing new feature" git push origin feature/amazing-new-feature
-
🎯 Create a Pull Request
- Use clear, descriptive titles
- Explain the changes and their purpose
- Reference any related issues
Found a bug? Please create an issue with:
- Clear description of the problem
- Steps to reproduce the issue
- Expected vs actual behavior
- Browser/device information
- Screenshots if applicable
Have an idea? We'd love to hear it! Please include:
- Use case - Why is this feature needed?
- Description - What should it do?
- Implementation ideas - Any technical thoughts?
Contributors will be added to our Contributors section. Significant contributions may be highlighted in release notes.
This project is licensed under the MIT License - see the LICENSE file for details.
MIT License
Copyright (c) 2025 Chris Matabaro
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.
- Chris Matabaro - Original black hole simulation implementation
- Three.js Community - 3D graphics framework and ecosystem
- WebGL Specification - Graphics API standards
- Karl Schwarzschild - Schwarzschild metric and black hole geometry
- Einstein's General Relativity - Theoretical foundation for spacetime curvature
- Chandrasekhar - Black hole physics and accretion disk theory
- NASA/ESA - Reference imagery and astrophysical data
- React Team - Modern UI framework
- TypeScript Team - Type-safe JavaScript development
- Vite Team - Fast build tool and development server
- ESLint Team - Code quality and consistency
- Space Background Textures - NASA/ESA public domain imagery
- Mathematical Formulations - Open physics literature
- Shader Techniques - WebGL and OpenGL communities
Special thanks to:
- Physics simulation enthusiasts who provided feedback
- Open source contributors who suggest improvements
- Educational institutions using this for physics demonstrations
- The broader scientific computing community
Made with ❤️ for physics education and space exploration
"The most beautiful thing we can experience is the mysterious." - Albert Einstein