init

README.md

@@ -0,0 +1,125 @@
+# GR 4D ray tracing — Phase 0 prototype
+
+`minkowski_sky` is a deliberately small, CPU-only, single-frame Phase 0
+benchmark. It renders point sources from a sky catalog through an analytic
+backend. It is not a sky texture: each source remains a direction, temperature,
+and amplitude until its sub-pixel Gaussian PSF is splatted.
+
+Build and render the default 1280 x 720 image:
+
+```sh
+make run
+```
+
+The program first creates `assets/sky_grid_5deg.csv` when it is missing. The
+synthetic catalog places stars every 2 degrees on the union of longitude and
+latitude lines spaced 10 degrees apart; the two poles are stored only once.
+The eight octants (four 90-degree longitude sectors in each hemisphere)
+alternate red `temperature_K = 3000` and blue `temperature_K = 12000`.
+Red stars use `amplitude = 1`; blue stars use `amplitude = 0.00141095580387`,
+which equalizes their CIE/linear-sRGB luminance under the renderer's blackbody
+integration. Longitude boundaries belong to the sector to their east and the
+equator to the northern hemisphere, so boundary stars have a deterministic
+color.
+The output is a binary PPM at `output/imgs/minkowski_sky.ppm`; it can be inspected by
+most image viewers or converted to PNG with ImageMagick.
+
+PNG output is optional so the default build has no `libpng` dependency. Build
+with `make ENABLE_PNG=1`, then select it with a `.png` output path:
+
+```sh
+make clean && make ENABLE_PNG=1
+mkdir -p output/imgs
+./build/minkowski_sky --output output/imgs/minkowski_sky.png
+```
+
+Run the flat-spacetime geodesic regression with:
+
+```sh
+make test
+```
+
+This also checks that the Kerr--Schild metric remains finite at `r=2M` and
+that the central ray from the default Schwarzschild camera is classified as
+captured.
+
+Build an independent analytic Schwarzschild executable in Cartesian ingoing
+Kerr--Schild coordinates (regular at the horizon), then render the test catalog
+to PNG:
+
+```sh
+make clean && make SPACETIME=schwarzschild ENABLE_PNG=1
+mkdir -p output/imgs
+./build/schwarzschild_sky --catalog assets/sky_grid_5deg.csv \
+  --width 640 --height 360 --coarse-cell-pixels 8 --fov-deg 60 \
+  --output output/imgs/schwarzschild_test_catalog.png
+```
+
+`SPACETIME=minkowski` (the default) and `SPACETIME=schwarzschild` select source
+files at compile time, so each executable contains exactly one metric provider.
+The Schwarzschild demonstration uses mass `M=1`, a static camera at Cartesian
+Kerr--Schild position `(30, 0, 0)`, directed at the hole, escapes at `r=256`,
+and declares capture at `r=1.5`, safely inside the horizon at `r=2`.  Those
+rendering thresholds are Phase-1 demonstration values, not settled production
+refinement or integration settings.
+
+For a local radial boost relative to that static camera, pass
+`--observer-inward-speed V`, where `0 <= V < 1` is measured in the static
+observer's orthonormal frame and positive values point toward the hole.  The
+default is `0`, preserving the static camera.
+
+For rays that asymptote to the future horizon in coordinate-time backward
+integration, the Schwarzschild demo also terminates at
+`log(alpha p^0) = 8`.  This is the normalized-momentum horizon diagnostic
+already evolved by the integrator; it is disabled by default and does not
+replace the AH-calibrated spatial capture criterion planned for nmesh data.
+
+Useful options:
+
+```sh
+./build/minkowski_sky --width 1920 --height 1080 --fov-deg 30 \
+  --catalog assets/sky_grid_5deg.csv --output output/imgs/frame.ppm
+./build/minkowski_sky --catalog assets/2mass/processed/2mass_psc_m31_0p5deg_stars.csv \
+  --look-ra-deg 10.6847083 --look-dec-deg 41.26875 --fov-deg 1.8 \
+  --exposure 1e15 --output output/imgs/2mass_m31.ppm
+./build/minkowski_sky --catalog assets/2mass/processed/2mass_psc_m44_1p0deg_stars.csv \
+  --look-ra-deg 129.99165 --look-dec-deg 19.54139 --fov-deg 2.0 \
+  --exposure 1e15 --width 1920 --height 1920 --output output/imgs/2mass_m44.ppm
+./build/minkowski_sky --write-catalog assets/sky_grid_5deg.csv
+```
+
+The camera is a fixed inertial observer at coordinate position `(0,0,0)`,
+with a tetrad whose forward direction is coordinate `-Z` and whose vertical
+direction is `+Y`. The frame first triangulates the image plane, then traces
+only its vertices backwards. Escaped endpoints form a triangulation on the
+source sky. For every locally invertible triangle, catalog stars inside its
+spherical source triangle are interpolated back to the image triangle and
+splatted as PSFs. Consequently multiple image triangles naturally create
+multiple images of the same star.
+
+The ray state evolves `(x^i, Pi_i, log(alpha p^0))` in coordinate time with
+RK4 using the 3+1 equations in Bohn et al. II.A, until the spacetime backend
+classifies the ray. `spacetime.c` is the only module containing the Minkowski
+metric or its infinity criterion; frame, observer, and integrator use only
+`SpacetimeSource` and `MetricData`. The initial regular mesh size is exposed
+as `--coarse-cell-pixels`; it is a Phase-0 sampling knob, not a settled
+production refinement threshold.
+
+`--look-ra-deg` and `--look-dec-deg` rotate that fixed tetrad so its forward
+axis is the corresponding catalog direction; their defaults reproduce the
+original `-Z` view. `--exposure` converts a catalog's physical flux
+normalization to the prototype HDR scale. Its default preserves the synthetic
+catalog benchmark; a 2MASS blackbody normalization in steradians requires a
+much larger display exposure such as the example above. The optics path
+integrates each fitted Planck spectrum through CIE 1931 color-matching functions
+and converts the resulting radiance to linear sRGB; it does not use an empirical
+color-temperature RGB approximation.
+
+Point sources use a flux-normalized circular Moffat PSF by default
+(`--psf-fwhm-pixels 2.7 --psf-moffat-beta 4.5`). The FWHM matches the former
+1.15-pixel Gaussian core while the Moffat wings remain continuous; both values
+are display/optics calibration parameters.
+
+Pass `--draw-mesh` to alpha-composite image-plane triangle edges as
+one-pixel-wide 0.5 linear-gray diagnostic lines at 0.5 opacity. The line
+rasterizer uses coverage-based antialiasing.