Production-Grade Real-Time General Relativistic Raymarching, Boyer–Lindquist Spacetime Tensor Simulation & Astrophysical Telemetry Platform
Visual Overview · Architecture · GPU Shader Pipeline · Mathematical Formulation · Celestial Catalog · Diagnostics & Telemetry · Quick Start · Academic References
Kerr Relativistic Engine (v1.4 PRIME) is a high-precision, hardware-accelerated astrophysics visualization and numerical relativity platform engineered for the web. Built on a native WebGL2 / Three.js pipeline with custom GLSL raymarching and volumetric shaders, it solves and renders the exact Boyer–Lindquist Kerr metric around rotating black holes, Roche-lobe overflow binary X-ray systems, relativistic pulsars/magnetars, and hypergiant stars at 60–120 FPS.
Unlike simplified visualizers that rely on static textures or post-process screen-space distortion, Kerr Relativistic Engine couples analytical general-relativistic solvers directly to GPU shader uniforms and real-time scientific telemetry overlays—modeling Bardeen D-shaped event horizon shadows, prograde/retrograde ISCO migration, Novikov–Thorne radiative blackbody profiles, Lense–Thirring frame dragging, asymmetric Doppler beaming (𝒟³⁺ᵅ), and Paczyński gravitational microlensing.
- Multi-Stage IMAX Camera Spline: Initializes at maximum orbital distance (
r₀ = 260.0 world units ≈ 148.6 Rₛ, θ = 62°, φ = 132°) with HUD chrome and grid suppressed for an unobstructed deep-space approach. - Autonomous Singularity Ignition: Glides along a helical arc to a suspended Singularity Seed (
r = 95.0), holds in weightless orbital drift, and automatically triggers a relativistic N-wave shockwave detonation—unfurling the Kerr event horizon, photon ring, accretion disk, and 3D spacetime curvature grid simultaneously. - Quintic S-Curve Dolly & Late-Stage HUD Flow: Executes a 3.2-second quintic smoothstep (
6t⁵ − 15t⁴ + 10t³) spherical dolly pan into the canonical observer lock (r = 16.5 Rₛ, θ = 71°, φ = 96°) with dynamic FOV breathing, revealing the UI HUD only as the camera settles.
- Rendering Architecture: Instant switching between Classic Multi-Layer Volumetric Torus and Full-Screen Billboard Volumetric Geodesic Raymarcher.
- Multi-Band Spectral Filters:
- Optical Blackbody (
blackbody): True Novikov–Thorne radial temperature gradient (10⁵ K → 10⁷ K). - Event Horizon Telescope (
eht230ghz):230 GHz(1.3 mm) interferometric synchrotron false-color palette matching M87* and Sgr A* reconstructions. - Chandra X-Ray (
xray): High-energy coronal Bremsstrahlung andFe Kα (6.4 keV)fluorescence mapping. - Relativistic Velocity Map (
doppler): Direct blue/red continuum diagnostic isolating approaching (+β∥) vs. receding (−β∥) Keplerian plasma shear.
- Optical Blackbody (
- Dual-canvas WebGL2 split-screen mode enabling real-time comparative astrophysics between any two celestial presets or one-click Kerr Spin Contrast benchmarks (
a* = 0.000Schwarzschild vs.a* = 0.998Near-Extremal Kerr) with synchronized camera quaternions and live ISCO/ergosphere differentials.
- Custom polyphonic Web Audio synthesizer featuring 5 procedural interstellar scores (Gargantua Organ Cathedral, Event Horizon Noir, Singularity Pulse, Lense–Thirring Drift, Hawking Whisper), a real-time 60 FPS FFT Spectrum & Waveform Analyzer, 3-Band Mastering EQ (Sub-Bass, Presence, Air), stereo widener, and camera-distance-coupled gravitational redshift low-pass filtering.
- Kerr Metric Obsidian (
kerr_claude): Warm obsidian-black carbon (#0b0908) with terracotta-amber (#d97757) accents and high-legibility parchment ivory (#f7f4ee) typography. - Schwarzschild Monolith (
observatory_gold): Pure carbon-black (#050506) monochrome academic publication aesthetic with chalk-ivory (#fafafa) typography and classical gold (#d4af37) metric rules. - Planck Laboratory (
cryo_quantum): Pure obsidian-black (#040605) university laboratory aesthetic with calibrated phosphor-emerald (#34d399) readouts and warm brass (#eab308) instrumentation.
flowchart TB
subgraph Client["React 19 + TypeScript UI Layer"]
TopBar["TopBar & Preset Selector"]
ControlDock["4-Tab Relativistic Control Dock"]
TelemetryHUD["Metric Tensor g_μν & Overhead Radar HUD"]
Diagnostics["Spacetime Stress-Test & IQ Assessment Modules"]
AudioDeck["24-Bit / 96 kHz Web Audio Mastering Deck"]
end
subgraph Physics["Analytical General Relativity Core (gravitationalPhysics.ts)"]
KerrSolver["Boyer–Lindquist Metric & Horizon Solver (r₊, r₋, r_ergo)"]
ISCOSolver["Bardeen–Press–Teukolsky ISCO & Photon Sphere (Z₁, Z₂)"]
GeodesicRK4["Null Geodesic Ray Integrator & Impact Classifier (b_crit)"]
LogGen["Structured Tensor Calculation Logger (kerrCalculationLogger.ts)"]
end
subgraph Engine["Native WebGL2 Rendering Engine (BlackHoleScene.ts)"]
UniformBuf["Zero-GC Pre-Allocated Uniform & Matrix Pool"]
GPUCache["Singleton GPU Resource Cache (gpuResourceCache.ts)"]
Pass1["Pass 1: Hardware-Instanced Starfield (5,500 Stars + Einstein Lensing)"]
Pass2["Pass 2: Flamm Paraboloid Spacetime Manifold (7,225 Dynamic Vertices)"]
Pass3["Pass 3: Volumetric Geodesic Raymarcher & Einstein Ring Billboard"]
Pass4["Pass 4: Multi-Octave fBM Accretion Torus / Roche-Lobe Binary Stream"]
Pass5["Pass 5: Anamorphic Optical Lens Flare & Ping-Pong Temporal Post-Pass"]
end
Client -->|State & Parameter Updates| Physics
Physics -->|Derived Relativistic Metrics| TelemetryHUD
Physics -->|Packed Uniform Vectors| UniformBuf
UniformBuf --> Pass1 & Pass2 & Pass3 & Pass4 & Pass5
GPUCache -.->|Zero-Allocation Preset Switching| Engine
├── public/
│ └── assets/ # High-DPI simulation captures & OpenGraph assets
├── src/
│ ├── components/
│ │ ├── TopBar.tsx # Preset switcher, Compare toggle, Video Recorder & v1.4 Changelog pill
│ │ ├── ControlDock.tsx # 4-tab parameter dock (Spacetime, Spectral, Camera, Geodesics)
│ │ ├── SettingsModal.tsx # Graphics, UI Themes, 96kHz Audio Deck, IQ Test & Stress-Test Diagnostics
│ │ ├── IQTestModule.tsx # 10-question General Relativity & Astrophysics cognitive assessment
│ │ ├── KerrEngineLogViewer.tsx # Tensor calculation log archive & interactive terminal replay
│ │ ├── ChangelogModal.tsx # Terminal-style engine milestone viewer (v1.2 – v1.4 PRIME)
│ │ ├── MetricTelemetryOverlay.tsx # Live Boyer–Lindquist metric tensor g_μν & Kretschmann scalar HUD
│ │ ├── PerformanceMonitorOverlay.tsx # Real-time GPU pass profiler, frame-time histogram & VRAM monitor
│ │ ├── OverheadMapWidget.tsx # 2D equatorial polar radar tracking S2 star & live photon rays
│ │ ├── BlackHoleAnatomyOverlay.tsx # 3D-projected anatomical callouts & leader lines
│ │ ├── CompareModeOverlay.tsx # Dual-viewport spin contrast & differential metric header
│ │ ├── CosmicScaleModal.tsx # Logarithmic horizon size comparator (Solar System vs. TON 618)
│ │ ├── ArchetypeExplorerModal.tsx # Taxonomic encyclopedia of relativistic compact objects
│ │ ├── PhysicsModal.tsx # Effective potential V_eff(r) curves & CSV export portal
│ │ └── QuickGuideModal.tsx # Plain-English illustrated guide to relativistic optics
│ ├── hooks/
│ │ ├── useHaptics.ts # Web Vibration API tactile feedback synthesizer
│ │ └── useViewportCategory.ts # Responsive desktop / tablet / mobile layout detector
│ ├── i18n/
│ │ └── translations.ts # Multi-language localization dictionary (EN, ES, FR, DE, JA, ZH)
│ ├── physics/
│ │ ├── gravitationalPhysics.ts # Exact Kerr metric solver, presets, geodesics & CSV serializer
│ │ ├── kerrCalculationLogger.ts # Multi-tier numerical tensor log generator (Standard / Deep / Extreme)
│ │ └── compactStarShaders.ts # Neutron star crust, dipole precession & synchrotron beam GLSL shaders
│ ├── scene/
│ │ ├── BlackHoleScene.ts # Core WebGL2 Three.js engine, GLSL raymarcher & camera choreography
│ │ └── gpuResourceCache.ts # Singleton geometry/texture/shader pool for zero-GC transitions
│ ├── utils/
│ │ └── relativisticAudio.ts # Polyphonic Web Audio synthesizer & 24-bit/96kHz mastering chain
│ ├── App.tsx # Root application state orchestrator & keyboard shortcut controller
│ ├── index.css # Theme token variables & scientific UI styling
│ └── main.tsx # React 19 DOM entry point
├── index.html # HTML5 entry point with typography preconnects
├── package.json # Dependencies & build scripts
├── tsconfig.json # Strict TypeScript 5.8 configuration
└── vite.config.ts # Vite 8 bundler configuration
The rendering engine (src/scene/BlackHoleScene.ts) is architected around zero per-frame heap allocations and IEEE-754 NaN/Inf fragment guards across 7 specialized GPU passes:
| Pass | Shader / Mesh Layer | Mathematical & Visual Responsibility | GPU Cost Tier |
|---|---|---|---|
| 1 | Deep-Space Starfield (InstancedMesh · 5,500 stars) |
Evaluates Harvard B–V blackbody colors, per-star scintillation, and O(1) vertex-stage Einstein deflection (Δθ = 4GM / c²b) with shockwave refraction. |
LOW (~5%) |
| 2 | Flamm Paraboloid Manifold (84×84 polar-indexed grid) |
Deforms radial proper distance (dρ = dr / √(1 − Rₛ/r)), applies Lense–Thirring azimuthal frame-dragging twist, and propagates concentric N-wave ripples. |
MODERATE (~8%) |
| 3 | Volumetric Geodesic Raymarcher (Billboard Quad · GLSL) |
Raymarches curved photon trajectories in Boyer–Lindquist coordinates; synthesizes Bardeen D-shaped shadow, n = 1 Einstein arches, and n = 2 photon-ring caustics. |
HIGH (~32–44%) |
| 4 | Relativistic Accretion Torus (Multi-Layer 3D Torus) |
Computes Novikov–Thorne radial temperature, 4-octave 3D gyroid fBM turbulence, Keplerian spiral shear, and 𝒟³⁺ᵅ Doppler beaming. |
HIGH (~28%) |
| 5 | Roche-Lobe Binary Stream (Teardrop Star + 560 Parcels) |
Deforms companion star photosphere toward Lagrange point L₁, advects 560 instanced plasma parcels along a cubic Bézier curve, and renders disk impact shock. |
MODERATE (~10%) |
| 6 | Camera-Space Anamorphic Flare (Full-Screen NDC Quad) |
Projects prograde Doppler hotspot into NDC space; renders 5-element hexagonal iris ghosts, chromatic dispersion ring, and 12-ray diffraction starburst. | MODERATE (~12%) |
| 7 | Temporal Post-Processor (Ping-Pong RGBA8 Targets) |
Executes 9-tap directional velocity chromatic blur during rapid camera slews and multi-frame exponential accumulation in Time-Lapse Exposure Mode. | LOW–HIGH (Standby / Active) |
All telemetry readouts and shader uniforms are computed from analytical expressions in Boyer–Lindquist coordinates (t, r, θ, φ) with metric signature (−, +, +, +) and gravitational radius r_g = GM/c² = ½ Rₛ:
- Outer Event Horizon (
r₊) & Inner Cauchy Horizon (r₋) + Static Limit (g_tt = 0):
- Lense–Thirring Frame-Dragging Angular Velocity (
ω):
For a non-rotating Schwarzschild black hole (a* = 0), r_ISCO = 6 r_g = 3 Rₛ (radiative efficiency η ≈ 5.72%). At maximal Kerr spin (a* → 1), the prograde ISCO plunges to r_ISCO → 1 r_g = 0.5 Rₛ, raising radiative efficiency up to η ≈ 42.3%.
To verify absence of coordinate pathologies across horizons and stress-test near-extremal spin states, the engine evaluates the exact Kerr Kretschmann curvature invariant:
The engine ships with 15 astrophysically calibrated presets spanning 11 orders of magnitude in mass (1.0 M☉ → 6.6 × 10¹⁰ M☉). Non-accreting isolated stars and pulsars automatically disable the accretion disk layer, while active binary and circumstellar systems enable their physically appropriate disk/outflow geometry:
| Preset ID | Name | Classification | Mass (M☉) |
Spin (a*) |
Default Disk | Physical Signature |
|---|---|---|---|---|---|---|
ton618 |
TON 618 | Ultramassive Quasar BH | 6.6 × 10¹⁰ |
0.980 |
Active | 3.9 × 10¹¹ km (2,600 AU) shadow diameter |
m87 |
M87* | Supermassive Galactic BH | 6.5 × 10⁹ |
0.900 |
Active | Messier 87 core; EHT 230 GHz benchmark target |
sgra |
Sagittarius A* | Supermassive Galactic BH | 4.3 × 10⁶ |
0.940 |
Quiescent | Milky Way nuclear SMBH with S2 star orbit |
gw190521 |
GW190521 | Intermediate Merger BH | 142 |
0.720 |
Active | Heaviest LIGO–Virgo–KAGRA binary coalescence remnant |
gw150914 |
GW150914 | Stellar Binary Merger BH | 62.0 |
0.680 |
Quiescent | First direct gravitational-wave detection remnant |
cygnus_x1 |
Cygnus X-1 | High-Mass X-Ray Binary BH | 21.2 |
0.998 |
Active (Binary) | Near-extremal spin fed by O9.7 Iab supergiant wind |
v404_cygni |
V404 Cygni | Low-Mass X-Ray Binary BH | 9.0 |
0.850 |
Active (Binary) | Roche-lobe overflow microquasar with Eddington flares |
psr_b1919 |
PSR B1919+21 | Radio Pulsar (Neutron Star) | 1.40 |
0.150 |
Disabled | 1.337 s period; dipole magnetosphere & radio cones |
magnetar_sgr |
SGR 1806-20 | Hyper-Magnetic Magnetar | 1.80 |
0.320 |
Fallback Ring | 10¹⁵ G crustal field with X-ray fallback debris |
rx_j1856 |
RX J1856.5-3754 | Isolated Neutron Star | 1.50 |
0.120 |
Disabled | Magnificent Seven thermal X-ray surface (R∞ > R) |
ztf_j1901 |
ZTF J1901+1458 | Ultra-Massive White Dwarf | 1.35 |
0.280 |
Disabled | Near-Chandrasekhar limit (R ≈ 4,280 km) |
eta_carinae |
Eta Carinae A | Luminous Blue Variable | 100 |
0.680 |
Circumstellar | Super-Eddington wind + equatorial Homunculus torus |
r136a1 |
R136a1 | Wolf–Rayet Hypergiant | 215 |
0.620 |
Disabled | 8.7 × 10⁶ L☉; intense UV radiation-driven wind |
betelgeuse |
Betelgeuse | Red Supergiant (α Ori) |
16.5 |
0.180 |
Disabled | Giant convective boiling cells (R ≈ 764 R☉) |
sol_sun |
Sol (The Sun) | G2V Main-Sequence Star | 1.00 |
0.050 |
Disabled | Weak-field hydrostatic reference (Rₛ ≈ 2.95 km) |
When the Diagnostic tab is opened, the engine automatically sequences through 5 extreme spacetime curvature stress tests (SPACETIME_CURVATURE_STRESS_TESTS), applying each parameter regime to the live 3D WebGL2 engine, triggering an event-horizon shockwave, computing a multi-step Boyer–Lindquist Tensor Run (KerrEngineRunLog), and archiving the results to the Kerr Engine Log Viewer:
- Test 01 — Thorne Spin Limit (
a* = 0.998·cygnus_x1): Verifies absence of naked ring-singularity division-by-zero asr₊ → 1.063 r_gandr_ISCO → 1.237 r_g. - Test 02 — Schwarzschild Degeneracy (
a* = 0.000·gw150914): Confirms spherical symmetry restoration (g_tφ = 0,r_ISCO = 6.000 r_g,r_ph = 3.000 r_g). - Test 03 — Ultramassive Horizon Scaling (
M = 6.6 × 10¹⁰ M☉·ton618): Validates IEEE-754 floating-point stability acrossRₛ = 1.95 × 10¹¹ km. - Test 04 — Super-Eddington Accretion Surge (
ṁ = 2.85·v404_cygni): Stress-tests ACES filmic tone mapping and volumetric raymarching under extreme radiative flux and5.0×Flamm funnel depth. - Test 05 — Grazing Photon-Ring Caustic (
i = 86°·m87): Validates secondary (n = 2) Einstein arch raymarching and𝒟⁴Doppler beaming at near-equatorial grazing incidence.
Launching photon trajectories from the Geodesics tab (or via double-click) allows exporting step-by-step integration data as a standard RFC-4180 CSV file with metadata headers:
# Kerr Relativistic Geodesic Telemetry Export
# Mass_Solar,Spin_a*,Inclination_Deg,EventHorizon_Rg,PhotonSphere_Rg,ISCO_Prograde_Rg
# 6500000000,0.900,17,1.436,1.558,2.321
trajectory_id,outcome,impact_parameter_b_Rs,closest_approach_Rs,deflection_rad,step_index,x_scene,y_scene,z_scene,r_Rs,phi_deg,gravitational_redshift_z
live-geodesic-1,critical-orbit,2.600,1.520,4.8120,0,-24.0000,0.0000,4.5500,13.9421,169.26,0.0379| Input / Shortcut | Function |
|---|---|
| Left-Click + Drag | Orbit camera in spherical coordinates (θ, φ) around primary mass |
| Scroll Wheel / Pinch | Dolly zoom along radial coordinate r ∈ [3.5, 260.0] world units |
| Double-Click Canvas | Fire a live null geodesic photon ray at the clicked impact parameter b |
| Click Central Horizon | Collapse black hole into a Singularity Seed / Replay relativistic expansion |
Space |
Skip startup boot intro / Pause or resume simulation time (Δt) |
H |
Collapse or expand the bottom Control Dock |
C |
Toggle Clean Mode (hide all HUD overlays for unobstructed 3D capture) |
Esc |
Exit Clean Mode / Close active modal window |
- Node.js:
v18.0.0or newer (v20 LTSrecommended) - Package Manager:
npm v9+orpnpm - Browser: Any modern browser with WebGL 2.0 hardware acceleration enabled (Chrome, Edge, Firefox, Safari 16+)
# 1. Clone the repository
git clone https://github.com/your-username/Kerr-Relativistic-Engine.git
cd Kerr-Relativistic-Engine
# 2. Install dependencies
npm install
# 3. Start the Vite development server on port 3000
npm run devOpen http://localhost:3000 in your browser.
| Command | Description |
|---|---|
npm run dev |
Starts the local development server on http://0.0.0.0:3000 |
npm run build |
Compiles production TypeScript & bundles optimized assets into dist/ |
npm run preview |
Serves the production build locally for verification |
npm run lint |
Runs strict TypeScript type-checking (tsc --noEmit) across the codebase |
npm run clean |
Removes build artifacts (dist/) |
The physical models, geodesic integrators, and relativistic rendering algorithms implemented in this engine are grounded in the following foundational papers:
- Bardeen, J. M., Press, W. H., & Teukolsky, S. A. (1972). Rotating Black Holes: Locally Nonrotating Frames, Energy Extraction, and Scalar Synchrotron Radiation. The Astrophysical Journal, 178, 347–370. (ISCO radii
Z₁, Z₂and Kerr shadow geometry) - Novikov, I. D., & Thorne, K. S. (1973). Astrophysics of Black Holes. In Black Holes (Les Astres Occlus), pp. 343–450. (Relativistic thin-disk radial temperature and radiative efficiency
η) - Luminet, J.-P. (1979). Image of a Spherical Black Hole with Thin Accretion Disk. Astronomy and Astrophysics, 75, 228–235. (Primary and secondary lensed disk images and Doppler asymmetry)
- James, O., von Tunzelmann, E., Franklin, P., & Thorne, K. S. (2015). Gravitational Lensing by Spinning Black Holes in Astrophysics, and in the Movie Interstellar. Classical and Quantum Gravity, 32(6), 065001. (Kerr raymarching, camera-space lensing, and Doppler beaming)
- Paczyński, B. (1986). Gravitational Microlensing by the Galactic Halo. The Astrophysical Journal, 304, 1–5. (Point-lens microlensing amplification
A(u)and doublet image positions) - Event Horizon Telescope Collaboration (2019 / 2022). First M87 Event Horizon Telescope Results. I. The Shadow of the Supermassive Black Hole & First Sagittarius A* Event Horizon Telescope Results. I. The Astrophysical Journal Letters, 875(1), L1 & 930(2), L12. (230 GHz synchrotron ring calibration)
Distributed under the MIT License. See LICENSE for full license text.

