General Relativity Raytracer (Rust)

A Rust ray tracer for general relativity and black hole visualization.
It solves geodesic equations numerically and renders gravitational lensing, redshift, beaming, accretion disks, and photon trajectories in Schwarzschild and Kerr spacetimes.

Inspired by Seeing relativity -- I. Ray tracing in a Schwarzschild metric to explore the maximal analytic extension of the metric and making a proper rendering of the stars and BlackHoleViz_v2.

See the Image Gallery for more rendered outputs.

Table of Contents

• Features
• Quick Start
• How Rendering Works
• Scripts
• Examples
• References
• License

Features

• Multi-geometry ray tracing: Euclidean, EuclideanSpherical, Schwarzschild, Kerr (Kerr-Schild), and KerrBL (Boyer-Lindquist).
• Geodesic integration with RKF45; KerrBL uses separated equations of motion via Carter's constant (therefore faster than Kerr).
• Relativistic shading effects: gravitational and Doppler redshift plus relativistic beaming.
• Physically motivated emission: black-body spectrum integration in CIE XYZ.
• Scene primitives: Sphere, Disc, and Perlin-noise-based VolumetricDisc.
• Flexible materials and textures: bitmap, checker, and black-body mappers.
• Image output formats: standard image export plus HDR (.hdr).
• Debug and analysis tools: per-pixel ray export and arbitrary ray-at-position export.
• Config-driven scenes through TOML definitions.

Note: VolumetricDisc is primarily a visual effect for accretion-disk appearance rather than a strict physical model.

Quick Start

Requirements

• Rust toolchain (cargo)
• uv for Python helper scripts (brew install uv on macOS)

Build

cargo build --release

Render a First Image

cargo run --release -- --width=1500 --height=1500 --camera-position=-16.0,0.0,3.5 --theta=-3.142 --psi=0.0 --phi=0.0 --config-file scene-definitions/schwarzschild.toml render --filename=render.png

• --width and --height: output resolution.
• --camera-position: camera location.
• render: full image render command.
• --filename: output image path.

How Rendering Works

Predefined scenes live in scene-definitions as TOML files.
You can swap geometry, textures, and objects by choosing or editing a scene file.

Scripts

This repository includes helper scripts for rendering workflows, ray export, plotting, and animation.

Create rays

• scripts/rays/create_rays_positions.sh: Generates rays in Schwarzschild spacetime from a position and direction, then writes CSV files to rays/.
• scripts/rays/create_rays_from_camera.sh: Generates Schwarzschild rays starting from a camera and selected pixel, then writes CSV files to rays/.

Plot/animate rays

uv run manim scripts/animate-rays/main.py AnimateRays

This command renders an animation from CSV ray data in rays/.

For the full script catalog and grouped layout, see scripts/Readme.md.

Examples

Schwarzschild black hole with accretion disk

Checkerboard texturing helps visualize lensing and warped geometry.

Rays in a Schwarzschild metric (video)

schwarzschild-black-hole-rays.mp4

Flyover of a Schwarzschild black hole (video)

flyover_schwarzschild_black_hole_with_accretion_disk.mp4

Background image source: https://commons.wikimedia.org/wiki/File:Messier_object_025.jpg

Lensing with background object (video)

A Schwarzschild black hole with a spherical object behind it, showing lensing while the camera moves.

schwarzschild_black_hole_lensing_object_behind.mp4

Background image source: https://commons.wikimedia.org/wiki/File:Messier_object_025.jpg

Kerr black hole with accretion disk

Example render command:

gr_raytracer --width=500 --height=500 --max-steps=1000000 --camera-position=-10,0,-0.5 --theta=1.52 --psi=-1.57 --phi=0 --config-file scene-definitions/kerr.toml render

Kerr scenes often require a high --max-steps value because of complex geodesic behavior near the black hole.

Example 1: r_s = 1.0, a = 0.5

Near-horizon trajectory

gr_raytracer --width=501 --height=501 --max-steps=1000000 --camera-position=-5,0,0.5 --theta=1.57 --psi=1.57 --phi=0 --config-file scene-definitions/kerr.toml render-ray --col=195 --row=250

Example 2: r_s = 1.0, a = 0.51

Kerr spin animation

Animation of a Kerr black hole with r_s = 1.0 and spin parameter a increasing from 0.0 to 0.5.

References

• Seeing relativity -- I. Ray tracing in a Schwarzschild metric to explore the maximal analytic extension of the metric and making a proper rendering of the stars
• BlackHoleViz_v2
• Novikov, I. D., & Thorne, K. S. (1973). Astrophysics of black holes. In C. DeWitt & B. S. DeWitt (Eds.), Black Holes (Les Astres Occlus), p. 343. Chapter bibliographic entry, Book record
• https://commons.wikimedia.org/wiki/File:Messier_object_025.jpg

License

This project is licensed under the terms in LICENSE.