151 lines
6.4 KiB
Markdown
151 lines
6.4 KiB
Markdown
# 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.
|
|
|
|
[](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
|
|
```
|
|
|
|
[](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
|
|
```
|
|
|
|
[](assets/images/schwarzschild_test_grid.png)
|
|
|
|
*4K test-grid reference image. Click to view at full resolution.*
|