Added stars at L1

docs/optics.md

@@ -1359,6 +1359,104 @@ under 0.01 microradians; the rotation and lighting of a body during its
 light time (the Moon turns 3 microradians in 1.3 s); and the light-time
 delay between the Sun lighting a body and the camera seeing it.
 
+## Stars
+
+Code: `stars.rs` (`StarCatalog`, `StarPhotometry`); `gpu/stars.rs`,
+`shaders/stars.wgsl`; `scripts/fetch-stars.py`.
+
+Below lighting tier L1 the sky is black. A real camera shows stars wherever
+its exposure is long enough, and they matter: star trackers find their
+attitude from them, a camera measuring the Moon or a target measures it
+against them, and to an algorithm looking for a target a star is a false one.
+
+Stars are part of the scene, so they come with lighting tier L1, but only a
+camera at tier C1 or above shows them. A C0 pixel takes its value from the
+one point at its center, and a star is a point that almost never lies
+exactly there; from C1 each pixel collects the light over its whole area,
+which is what records a star.
+
+**The catalogs.** `scripts/fetch-stars.py` merges three of ESA's catalogs
+into `data/stars/stars.bin`: Hipparcos, 118,000 stars complete to about
+magnitude 7.3; Tycho-2, 2.5 million stars to about 11.5 (99 % complete to
+11.0); and Gaia DR3, from which it takes every star brighter than G 15 by
+default, 37 million. Each star comes from the first catalog that has it, so
+the brightest, which saturate Gaia's detectors, keep their Hipparcos or Tycho
+measurements. Gaia measures brightness in its own bands, G and the color
+BP - RP: V comes from them by Gaia's published relation (to 0.03 mag), and
+B - V by a fit to the Hipparcos stars Gaia matched. Each star
+keeps its position on the sky (ICRS, at epoch J2000), its proper motion and
+its brightness and color. The renderer moves each star by its proper motion
+to the scene's epoch when the catalog is loaded. Barnard's star, the
+fastest, moves 10 arcseconds a year; most move under 0.1. Parallax, under 1
+arcsecond for every star, is left out.
+
+**Magnitudes.** A star's brightness is given as a magnitude: each step of 5
+is a factor of 100, and larger is fainter. Vega is about 0, the faintest
+stars the eye sees about 6, Tycho-2's limit about 11.5, 25,000 times fainter
+than 0. The magnitude in the Johnson V band, a filter close to the eye's
+green-yellow, fixes how much light the star sends through that band: V = 0
+is 3.631e-11 W/m^2/nm averaged over it (Bessell, Castelli and Plez 1998).
+The color index B - V, the difference between the star's magnitudes in blue
+and in V, fixes its temperature: hot stars are blue, B - V below 0, and cool
+ones red, up to about 2. The renderer takes the temperature from B - V
+(Ballesteros 2012: the Sun's 0.65 gives 5,780 K), takes a blackbody spectrum
+at that temperature, scales it so its light through the V band matches the
+star's magnitude, and folds it through the camera's optics and channels, as
+for sunlight. A star's spectrum is not a blackbody's: absorption lines and,
+in cool stars, molecular bands move a few percent of the light between
+channels. For the example camera, a Sun-colored star of V = 0 on the
+boresight gives 56 electrons in green in the 0.1 ms exposure, against an
+independent estimate of 56.4.
+
+**Exposure.** That 56 electrons is why the example scenes show no stars: an
+exposure set for a sunlit spacecraft or Earth, a fraction of a millisecond,
+leaves even the brightest stars at a few hundred electrons and the rest
+below one. Star trackers expose for 10 to 200 ms, and a telescope's larger
+aperture collects more: a 1 m f/8 telescope, with a 12.5 cm aperture, gives
+100 times what the example camera does.
+
+**Drawing.** Each frame the renderer finds the stars in the field on the
+CPU, from bands of declination sorted by right ascension, so it looks only
+at the stars near the field. It places each at its apparent position, the
+annual aberration of the observer's motion (about 20 arcseconds, see the
+previous section) through the lens's distortion. It works out its electrons
+in each channel: a point source loses light off axis only to the aperture's
+foreshortening, cos(theta), not the cos^4(theta) of an extended surface,
+since all of a star's light that enters lands in its spot. A star is not
+rendered and then blurred: a point of light rendered into a pixel loses
+where in the pixel it fell (see the blur section). Instead its electrons are
+spread over the pixels around it as the Gaussian PSF integrated over each
+pixel's area, which is exact for any position within a pixel. The detector
+adds them to the light from everything else before the full well, so a
+bright star saturates like any other light. A star is hidden wherever
+anything nearer is drawn, Earth, the Moon or a target: stars are at
+infinity, so a star shows only where the depth image is empty. Stars giving
+fewer than 0.1 electrons in every channel, far below any detector's noise, are
+skipped, and the catalog is loaded only to the magnitude that can reach that.
+
+Measured: a star moved across a pixel in tenths, behind a lens with
+distortion and with Earth's 30 km/s of aberration, lands where the
+projection puts its apparent direction to 0.01 px, with its electrons
+matching the photometry to 0.2 %. A star behind Earth's night side or
+behind a target leaves the bias alone.
+
+Costs. A catalog is loaded only as deep as the camera's exposure can show:
+for the example camera at 0.1 ms that is V 7.9, 42,000 stars, in 6 ms and 7
+MB; at 50 ms, V 14.7, 21 million stars, in 2.8 s and 670 MB; for a 1 m
+telescope at 0.2 s, the whole catalog, 37 million stars, in 5 s and 1.2 GB.
+Each frame, finding and placing the stars takes 23 microseconds for the
+telescope's 0.6 degree field (490 stars toward the Milky Way in Monoceros)
+and 4.8 ms for the example camera's 12 degree field at 50 ms (52,000 stars).
+Drawing them takes 0.24 ms for 40,000 stars on an RTX 3060, and 5.6 ms on
+the CPU through lavapipe.
+
+A catalog's depth matters most for a telescope's narrow field. Tycho-2 alone
+averages 60 stars per square degree, so a 1 m telescope's 0.2 square degrees
+would hold about a dozen; with no sky background in space such a telescope
+records stars to magnitude 14 or 15 in half a second, and Gaia to G 15
+averages about 900 per square degree. Deeper still (G 16, 78 million stars)
+is a run of the script with `--gaia 16`, at twice the size.
+
 ## Not modeled yet
 
 - Earthshine on the Moon's night side