From ab56e23fc95ecaacb84bd20a4936771172085e27 Mon Sep 17 00:00:00 2001
From: Yingjie Wang <phywyj@gmail.com>
Date: Thu, 3 Sep 2026 20:58:20 -0400
Subject: [PATCH] Doc: document reusable lens maps

---
 README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/README.md b/README.md
index 3fc2d63..9a71843 100644
--- a/README.md
+++ b/README.md
@@ -54,6 +54,55 @@ synthetic test catalog uses global default exposure `1e-3`; the accelerated
 benchmark explicitly uses `1e-5` because its physical Doppler blue shift
 otherwise clips the later frames.
 
+## Reuse a completed lens map
+
+Ray tracing and adaptive mesh refinement are independent of catalog lookup,
+PSF evaluation, exposure, and tone mapping.  `--lens-map-output FILE` writes
+the finalized local inverse-lens mesh to one versioned `.grlens` file after all
+ray-trace/refinement generations finish; the same invocation still renders its
+ordinary image.  The file stores every final vertex's image position, camera
+direction, infinity direction, frequency shift, terminal status, and the
+triangle topology.  It also stores the frame dimensions, horizontal FOV, and,
+for a movie, all frame IDs and times.
+
+For example, trace an analytic Schwarzschild frame once and retain the map:
+
+```sh
+make SPACETIME=schwarzschild backend
+mkdir -p output/imgs output/maps
+./build/Release/schwarzschild_sky --catalog assets/sky_grid_5deg.csv \
+  --width 640 --height 360 --coarse-cell-pixels 8 --fov-deg 60 \
+  --refine-max-level 2 --lens-map-output output/maps/schwarzschild.grlens \
+  --output output/imgs/schwarzschild_trace.png
+```
+
+Later, render that saved map with a different catalog, PSF, or exposure without
+constructing an observer, spacetime source, or geodesic rays:
+
+```sh
+./build/Release/schwarzschild_sky --lens-map-input output/maps/schwarzschild.grlens \
+  --catalog assets/sky_grid_5deg.csv --psf-fwhm-pixels 6 --psf-moffat-beta 3 \
+  --exposure 0.002 --output output/imgs/schwarzschild_restyled.png
+```
+
+`--lens-map-input` and `--lens-map-output` are mutually exclusive.  An imported
+map always retains its original pixel width, height, and horizontal FOV; an
+explicit conflicting `--width`, `--height`, or `--fov-deg` is rejected.  This is
+intentional: the stored inverse map and PSF coordinates are in the original
+pixel geometry.  The reader validates the format version, finite values, unit
+directions, triangle indices, and a per-frame CRC before rendering.
+
+A movie export writes every final frame mesh into the same `.grlens` file.
+Export it during the usual movie render, then import it with `--frames-dir` and
+`--frames-prefix`; importing a multi-frame map does not require
+`--observer-track`:
+
+```sh
+./build/Release/minkowski_sky --lens-map-input output/maps/movie.grlens \
+  --catalog assets/sky_grid_5deg.csv --frames-dir output/imgs \
+  --frames-prefix restyled
+```
+
 PNG is the default output and the default build links `libpng`:
 
 ```sh