https://github.com/Harislang/Interactive-3D-Black-Hole-Merger/releases

Interactive 3D Black Hole Merger: Realistic Physics in WebGL

A calm, immersive 3D visualization of binary black hole mergers. Explore the dynamics of two massive objects, see gravitational lensing bend light around them, and watch shimmering wave effects ripple through the scene. Built with Three.js and WebGL for smooth, interactive performance in modern browsers.

Table of Contents

• Overview
• Why this project matters
• Core features
• How it works under the hood
• Live previews and media
• Getting started
• How to run locally
• Controls and interaction model
• Visual and physical fidelity
• Educational use cases
• Architecture and code layout
• Data, assets, and performance
• Accessibility and inclusivity
• Community, collaboration, and contribution
• Roadmap
• FAQ
• Licensing and credits

Overview This project provides an interactive 3D scene that models a binary black hole merger with attention to physically motivated visuals. You’ll see gravitational lensing shaping the light paths around the black holes, and wave-like disturbances that resemble gravitational waves in the scene. The experience is designed to be approachable for students, educators, and curious minds who want a tangible feel for this cosmic phenomenon. The engine behind the visuals is Three.js, with WebGL handling the GPU work for fast rendering on typical laptops, tablets, and desktops.

Why this project matters

• Education in a visual medium: Complex astrophysical phenomena become accessible when students can manipulate parameters and observe outcomes in real time.
• Safe exploration of extreme physics: The model simplifies some details for clarity, while preserving the essential relationships between mass, distance, lensing, and waveform appearance.
• Reproducibility and open science: The codebase invites educators to tailor demonstrations, capture screenshots, and craft lesson plans grounded in interactive experiments.
• Cross-disciplinary learning: The project blends physics, computer graphics, and software engineering, supporting STEM education and maker workflows.

Core features

• Realistic 3D visualization: A pair of black holes orbit and merge in a dynamic, room-scale space.
• Gravitational lensing: Light paths bend around each mass, producing warped, luminous rings and arcs that shift as the system evolves.
• Wave effects: Subtle, wave-like ripples propagate through the scene to evoke gravitational waves without requiring heavy instrumentation.
• Interactive camera controls: Orbit, pan, and zoom to explore the merger from any angle.
• parameter tuning: Adjust mass ratio, orbital separation, spin, and distance to see how the merger evolves.
• High-fidelity shading: Physically inspired shading and lensing effects that respond to camera position and object motion.
• WebGL and Three.js backbone: Smooth performance on modern hardware with broad browser support.
• Educational annotations: In-scene labels and overlays to highlight key concepts like event horizons, photon orbits, and lensing caustics.

How it works under the hood

• Scene graph and rendering: The core scene uses Three.js to manage geometries, lights, cameras, and post-processing. Shaders handle lensing distortions and wave-like textures.
• Binary black hole model: Each black hole is represented as a compact, moving mass that exerts gravitational influence on light in the scene. The orbital motion follows a simplified two-body dynamics model that captures essential features of a merger.
• Gravitational lensing: Instead of full general relativistic ray tracing, the project uses an efficient approximation that bends light as it travels near the masses. The result is visually faithful and fast to compute in real time.
• Wave effects: Time-varying shader parameters create concentric wave patterns that propagate through space, reinforcing the sense of a dynamic gravitational field without heavy computation.
• Interactivity: Mouse and touch input are mapped to camera transforms and parameter controls. The app updates in a requestAnimationFrame loop to keep visuals fluid.
• Asset pipeline: Lightweight textures and procedural noise drive surface detail, while vector data and shader uniforms encode the physics cues students need to observe.

Live previews and media

• Concept art and still frames demonstrate the visual language: lensing ribbons, bright arcs spiraling around the black holes, and subtle ripples in the space between objects.
• Screenshots illustrate common viewpoints, such as a side-on view showing lensing caustics and a top-down view of the binary dance.
• A short demo video (where available) summarizing the visual effects and user interactions can be linked on the release page for quick orientation.

Getting started

• System requirements

  • A modern browser with WebGL support (Chrome, Firefox, Edge, Safari on recent versions).
  • A reasonably up-to-date GPU to render shaders smoothly.
  • Optional: a high-refresh monitor can improve the sense of motion when orbiting and zooming.

• What you’ll get

  • A self-contained, browser-based demo that you can run offline or online.
  • An inherently educational experience suitable for classrooms, libraries, and personal exploration.
  • Source code designed for readability and teaching—easy to instrument or extend.

• Prerequisites and environment

  • A development machine with Node.js installed for local builds and testing.
  • Basic familiarity with npm or yarn to install dependencies.
  • A modern text editor to read and modify the code.

• Install and run (typical workflow)

  • Step 1: Clone the repository
    • Run: git clone https://github.com/Harislang/Interactive-3D-Black-Hole-Merger.git
  • Step 2: Install dependencies
    • Run: npm install
  • Step 3: Start a local development server
    • Run: npm run dev
  • Step 4: Open the local URL provided by the dev script (usually http://localhost:3000)
  • Step 5: Interact with the scene, tweak parameters, and observe results
  • For production builds
    • Run: npm run build
    • Serve the dist directory with a static server of your choice

• Alternative: Download the release asset

  • The project’s releases contain prebuilt bundles suitable for quick start. From the Releases page, download the asset and run the included executable or bundle. The Releases page is available at the link above, and the downloadable asset is part of that page. The asset is designed to run without requiring a full development environment.
  • Note: The release page includes a path, so you should download the specified asset and execute it to start the demonstration.

Controls and interaction model

• Camera and navigation
  • Left mouse drag: orbit around the scene’s center.
  • Right mouse drag or Ctrl+drag (or two-finger drag on touch): pan the camera.
  • Scroll wheel or pinch: zoom in and out to adjust scale and perspective.
  • Middle mouse button drag: dolly in some workflows; check device mappings.
• In-scene adjustments
  • Mass ratio slider: balance the two black holes to see asymmetrical dynamics.
  • Distance and orbital parameters: tune initial separation and orbital characteristics.
  • Spin orientation: adjust spin vectors of the black holes to influence frame dragging visuals.
  • Time scale: speed up or slow down the merger to study phases more clearly.
• Annotations and overlays
  • Toggle labels for event horizons, lensing caustics, and photon rings.
  • Enable a waveform overlay to visualize the “waves” as time-varying color patterns across the space.
• Accessibility
  • Keyboard navigation for the camera: arrow keys to rotate, plus/minus to zoom, and number keys to switch scenes or presets.
  • Screen reader-friendly labels and alt text for major UI elements.
  • High-contrast color options for viewers with visual sensitivity.

Visual and physical fidelity

• Physics-inspired realism
  • The model emphasizes how mass and distance influence the light paths and the apparent shape of the scene.
  • Lensing distortions grow stronger as the black holes approach each other, creating dramatic arcs and multiple images in the viewer’s frame.
  • The wave-like effects convey the concept of spacetime perturbations without requiring complex gravitational wave computation.
• Aesthetic choices
  • Color palettes highlight hot regions near the event horizons and cooler space far from the masses.
  • Subtle glow and glow radius controls add depth without overwhelming the main actions.
  • Particles and streaks emphasize motion and energy exchange during the merger.
• Performance considerations
  • The rendering pipeline uses GPU shaders for lensing and wave effects, keeping updates smooth on mid-range hardware.
  • LOD (level of detail) strategies are employed so the scene remains responsive when the camera is in busy regions or when many particles are present.
  • Optional post-processing can be toggled to reduce GPU load on older devices.

Educational use cases

• Classroom demonstrations
  • Use the parameter controls to illustrate how mass and distance affect gravitational lensing and merger dynamics.
  • Highlight the concept of photon paths bending near massive objects and how this leads to multiple images and arcs.
  • Show how the merger emits energy and how the time scale influences perception of the event.
• Student-led explorations
  • Students can create a guided exploration by setting up presets that demonstrate specific phenomena (for example, a near-equal mass merger vs. a high mass ratio scenario).
  • Worksheets can prompt students to predict visual outcomes before running simulations and then compare with observed results.
• Teachers and educators
  • A resource to complement astrophysics units, space science fairs, and STEM outreach programs.
  • A safe, self-contained environment for urban or remote classrooms without needing specialized hardware beyond a browser.

Architecture and code layout

• Top-level structure
  • src/: Core application code, including the scene setup, renderer, camera controls, and physics helpers.
  • shaders/: Custom GLSL shaders implementing lensing, wave effects, and lighting tricks.
  • assets/: Textures and lightweight data used for visuals and UI.
  • components/: Reusable UI components and modular scene elements.
  • examples/: Quick-start snippets, small demos, and sample presets for instructors.
  • public/: Static assets and the HTML entry point.
• How to customize
  • Locate the scene initialization in src/scene.js (or similar) to tweak scaling, object properties, and render loop behavior.
  • Modify the lensing shader in shaders/lens.js to adjust distortion strength and color response.
  • Extend with new presets by duplicating a preset file in examples/presets and changing parameters to create new demonstrations.

Data, assets, and performance

• Textures and materials
  • The visuals rely on lightweight textures and procedural layers to simulate surface detail and energy patterns around the black holes.
  • Procedural noise and gradient ramps are used for speed and to avoid heavy texture memory usage.
• Shader design
  • Lens distortion is performed in screen space to keep calculations efficient.
  • Wave effects are implemented as time-varying textures modulated by the global time parameter, creating a sense of dynamic spacetime.
• Asset management
  • All assets are kept small in this project to reduce load times and improve responsiveness on a wide range of devices.
  • The code includes fallback paths for devices with limited GPU capabilities, ensuring a graceful degradation rather than a crash.

Accessibility and inclusivity

• Clear keyboard navigation is provided to reach the main controls without a mouse.
• Textual labels accompany visual elements to aid screen readers.
• Color palettes are designed with color contrast in mind; users can switch to high-contrast mode.
• Documentation and tutorials are written with plain language and step-by-step guidance to support learners with different backgrounds.

Community, collaboration, and contribution

• How to contribute
  • Fork the repository, create feature branches, and submit pull requests with concise, focused changes.
  • Use the issue tracker to propose enhancements, report bugs, or request new presets and educational use cases.
  • Follow the project’s contribution guidelines and code of conduct to maintain a welcoming and constructive environment.
• Local development tips
  • Use a live-reload server to see changes quickly.
  • Keep shader changes small and test across different parameter sets to verify visual fidelity.
  • Add unit-like tests for non-visual logic where feasible, and descriptive manual tests for rendering fidelity.
• Documentation and learning resources
  • Provide lesson plans and student-facing materials that explain the science behind the visuals in accessible terms.
  • Include a glossary for terms like gravitational lensing, event horizon, photon sphere, and gravitational waves.

Roadmap

• Short-term goals
  • Expand preset library to cover more mass ratios and spin configurations.
  • Improve guided tours and annotated explanations within the scene.
  • Add export options for images and short video clips to support classroom use.
• Mid-term goals
  • Integrate additional educational modules, such as comparing Newtonian intuition vs. relativistic effects via side-by-side views.
  • Build a guided “lesson mode” that steps students through concepts with questions and observations.
• Long-term goals
  • Extend the visualization to include a modular "toy universe" with multiple binary systems and perturbations from nearby masses.
  • Introduce more realistic waveform representations and a simple, safe approximation of gravitational-wave signatures.

FAQ

• Is this project a literal simulation of general relativity?
  • No. The visuals are inspired by relativistic effects and aim to convey intuition. The physics is simplified to keep the experience interactive and approachable.
• Can I run this offline?
  • Yes. The release bundles are designed to work without a network connection after download.
• Do I need special software?
  • No. A modern web browser with WebGL is enough for the core experience. Development builds require Node.js if you want to run the local dev server.
• Can students modify the visuals?
  • Absolutely. The code is structured to be approachable and modifiable, with clear entry points for new parameters and shaders.

Licensing and credits

• This project is released under a permissive license that favors open education and experimentation.
• Credits go to the Three.js community for the core rendering framework and to the broader space science visualization community for inspiration on how to convey difficult concepts with clarity.
• If you reuse parts of the code in your own project, please attribute accordingly and respect the contributor guidelines.

Credits and acknowledgments

• Three.js library and ecosystem.
• Publicly available educational resources that inspired the design of visual cues for lensing and wave effects.
• Educators who shared classroom experiences that informed the teaching approach behind this visualization.
• Open science communities that advocate accessible, interactive learning tools.

Changelog

• Version 1.x.x: Initial release with core binary merger visualization, basic lensing, and interactive camera.
• Version 1.x.y: Added wave visuals and improved shading; introduced parameter presets.
• Version 2.0: Expanded educational materials, new presets, and accessibility improvements.
• Version 2.x: Ongoing enhancements to performance, UI, and export capabilities.

Downloads and releases

• For the latest build, visit the Releases page. The page contains downloadable assets and setup instructions. If you prefer a quick start, download the prebuilt bundle and run the included executable or bundle. The Releases page is linked earlier and again here for convenience.
• Direct link to the Releases: https://github.com/Harislang/Interactive-3D-Black-Hole-Merger/releases

Topics

• aied
• astrophysics
• blackhole
• cosmic
• education
• educators
• interactive
• phenomenon
• science
• simulation
• stem
• teachers
• technology

Screenshots and media gallery

• Scene concept render: a pair of dimly glowing masses with arcs of light bending around them.
• Lens effect close-up: bright caustics and curved light paths wrapping the scene.
• Wave overlay: subtle, translucent ripples propagating through the space between the black holes.
• Educational overlay: callouts explaining event horizons, photon rings, and lensing regions.

How to customize for a classroom or outreach event

• Create a guided tour preset: Script a sequence of camera angles and parameter changes, with accompanying narration text that explains what the students should observe at each stage.
• Prepare worksheets: For each preset, provide prompts like “Describe how lensing changes when the mass ratio increases” and “Explain why the arcs shift as the black holes move closer.”
• Set up a device-friendly interface: Ensure the UI is visible from a projector and accessible to students with a range of screen sizes.
• Integrate with lesson plans: Align specific presets with standard astrophysics topics (gravity, light, curvature of spacetime, wave phenomena).

Security and safety notes

• The demo runs entirely in the browser; there is no need to grant permissions beyond standard web usage.
• No external data fetching is required for the core experience in offline mode.
• If you host this on a school network, verify content policies for third-party resources and fonts used in UI elements.

Appendix: glossary of terms

• Gravitational lensing: The bending of light by gravity, causing distortions in the apparent position and shape of background objects.
• Event horizon: A boundary around a black hole beyond which nothing can escape.
• Photon ring: A ring-like light feature formed by photons skimming near a black hole.
• Gravitational waves: Ripples in spacetime produced by accelerating masses, such as merging black holes.
• Spin: The intrinsic angular momentum of a massive object, which can affect spacetime around it.
• Mass ratio: The ratio of the masses of the two black holes, influencing their orbital dynamics and the resulting visuals.

Notes on style and accessibility

• The user-facing text uses direct, plain language with an active voice.
• Sentences aim for clarity and brevity where possible, avoiding unnecessary adverbs.
• Where technical terms appear, they are explained or introduced with simple definitions.
• Visuals are complemented by textual descriptions to support readers who rely on assistive technologies.

End of README content.