# GR 4D ray tracing

**English** | [简体中文](README.zh-CN.md)

An offline spacetime renderer focused on physical accuracy. The project aims
to turn time-dependent numerical-relativity simulations, including binary
black-hole mergers, into 4K movies by tracing light rays backward through the
four-dimensional spacetime.

[![Schwarzschild black-hole lensing of the 2MASS Galactic-center star field](assets/images/schwarzschild_galactic_center.png)](assets/images/schwarzschild_galactic_center.png)

*The 2MASS Galactic-center star field seen through Schwarzschild spacetime,
from a camera at radius 100 M. Click the image for the full 4K render;
[rendering command below](#example-galactic-center-field-through-schwarzschild-spacetime).*

Stars are individual catalog point sources with direction, temperature, and
amplitude. The renderer maps them into the camera image, accounting for
multiple images, gravitational lensing magnification, and frequency shifts,
then accumulates their sub-pixel point-spread functions (PSFs) into an HDR
image. Moving cameras are described by worldline and tetrad tracks.

## Current status

The current implementation supports analytic **Minkowski** and
**Schwarzschild** spacetimes, single images and observer-track image sequences,
adaptive lens meshes, and reusable lens-map files. It is written primarily in
C with OpenMP CPU parallelism; an optional HIP backend accelerates PSF
accumulation.

The [Nmesh](https://github.com/nmeshsource/nmesh) numerical-spacetime backend and BBH rendering are still planned.
The current scope is black-hole capture and distant stellar backgrounds;
local matter emission, accretion disks, and plasma are outside this stage.
See the [design document](nr_spacetime_movie_renderer_design.md) for the
architecture and development roadmap.

## Build

The default build requires a C11 compiler with OpenMP support, GNU Make, and
libpng development files. From the repository root:

```sh
make -j
```

This builds both `build/Release/minkowski_sky` and
`build/Release/schwarzschild_sky`. For individual backends, Debug builds,
optional HDR/FITS output, HIP support, and regression checks, see
[build.md](build.md).

## Prepare the stellar catalog

The renderer accepts **any stellar catalog converted to the supported CSV
format**: four columns containing ICRS right ascension and declination in
degrees, temperature in kelvin, and amplitude, in that order. Use
`--catalog PATH` to load a single CSV.

**2MASS is the recommended survey catalog**, with download and processing
scripts provided by this project. Instructions are in
[assets/2mass/README.md](assets/2mass/README.md).
The full download takes approximately **three to four days**, so **contact me
for a compressed archive first** if possible. Place the processed tile files
under `assets/2mass/processed/all_sky/` for the commands below.

The included [assets/sky_grid_5deg.csv](assets/sky_grid_5deg.csv) is a synthetic
stellar grid for geometry and regression tests. It can be used directly with
`--catalog assets/sky_grid_5deg.csv`, without downloading survey data; see the
[test-grid example below](#example-synthetic-test-grid-with-mesh-overlay).

## Rendering examples

The examples below illustrate a few choices of sky field, spacetime, and
camera settings. After building and preparing the catalog, adapt these
commands to your own field of view, observer position, and rendering settings.
See [usage.md](usage.md) for the available controls and workflows.

### Example: Summer Triangle in flat spacetime

This example renders a field around the Summer Triangle:

```sh
mkdir -p output/imgs
./build/Release/minkowski_sky \
  --all-sky-catalog assets/2mass/processed/all_sky \
  --look-ra-deg 296 --look-dec-deg 27 --fov-deg 72 \
  --width 3840 --height 2160 --exposure 1e12 \
  --output output/imgs/summer_triangle.png
```

[![Summer Triangle in flat spacetime, exposure 1e12](assets/images/summer_triangle.png)](assets/images/summer_triangle.png)

*4K reference image with exposure `1e12`. Click to view at full resolution.*

Angles are in degrees; `--fov-deg` is the horizontal field of view. Exposure
is an adjustable display multiplier. Use `--verbose` for progress during long
renders.

### Example: Galactic-center field through Schwarzschild spacetime

This example uses a camera at radius 100 M to render the lensed
Galactic-center field shown at the top of this page:

```sh
mkdir -p output/imgs
./build/Release/schwarzschild_sky \
  --all-sky-catalog assets/2mass/processed/all_sky \
  --width 3840 --height 2160 \
  --look-ra-deg 262.5 --look-dec-deg -30 --fov-deg 45 \
  --observer-radius 100 --exposure 1e13 \
  --coarse-cell-pixels 16 --refine-max-level 4 --refine-jacobian-min 0.2 \
  --psf-fwhm-pixels 2.7 --psf-moffat-beta 4.5 \
  --psf-relative-tail 1e-8 --psf-min-y 0 --max-cache-psf-flux 1e8 \
  --catalog-load-workers 4 \
  --output output/imgs/schwarzschild_galactic_center.png
```

This uses the reference image's rendering settings, including its
`--max-cache-psf-flux 1e8` preview approximation, which clips bright PSF wings
to the cache radius. The [original benchmark record](benchmarks/2mass_galactic_center_blackhole.md)
preserves the command and terminal output; the command above omits the optional
HDR export.

The Schwarzschild camera points toward the hole. Adaptive refinement should
be configured for the desired image accuracy; it is disabled by default.
Camera controls, movie sequences, lens-map reuse, PSF settings, and HDR output
are described in [usage.md](usage.md). Both binaries provide a complete option
list with `--help`.

### Example: Synthetic test grid with mesh overlay

This example uses `assets/sky_grid_5deg.csv` to inspect lensing and adaptive
mesh refinement in Schwarzschild spacetime. `--draw-mesh` overlays the final
image-plane triangles.

```sh
mkdir -p output/imgs
./build/Release/schwarzschild_sky \
  --max-cache-psf-flux 1e8 \
  --catalog assets/sky_grid_5deg.csv \
  --refine-max-level 3 --refine-jacobian-min 0.2 \
  --width 3840 --height 2160 \
  --look-ra-deg 0.1 --look-dec-deg 0.1 --fov-deg 45 \
  --coarse-cell-pixels 32 \
  --observer-radius 100 --exposure 0.2 \
  --psf-fwhm-pixels 2.7 --psf-moffat-beta 4.5 --draw-mesh \
  --output output/imgs/schwarzschild_test_grid.png
```

[![Synthetic stellar grid lensed by a Schwarzschild black hole, with adaptive mesh overlay](assets/images/schwarzschild_test_grid.png)](assets/images/schwarzschild_test_grid.png)

*4K test-grid reference image. Click to view at full resolution.*