Added earth surface texture

docs/optics.md

@@ -459,6 +459,64 @@ lit) right. It misses some things that are visible in real images:
 - Earth's atmosphere softens the limb and adds a thin bright band around it
   (M4). Here Earth's edge is a sharp line.
 
+### Earth's surface
+
+Code: `earth.rs`, `shaders/bodies.wgsl`; data from `scripts/fetch-earth.sh`.
+
+At lighting tier L1 (`RendererOptions::fidelity`, with the image in
+`RendererOptions::earth_texture`; `--lighting L1` on the command line), Earth's
+reflectance comes from an image of the whole surface instead of one spectrum. The image is NASA's
+Blue Marble Next Generation: a cloud-free mosaic of the 2004 MODIS satellite
+record, one image per month, so snow cover and vegetation follow the season.
+The CLI picks the month from the scene's epoch.
+
+The image is equirectangular: each column is a longitude and each row a
+latitude. For every pixel that sees Earth, the shader finds the surface
+point's geodetic latitude and longitude from the ellipsoid's normal there, in
+Earth-fixed axes, and reads the image at that place. Earth's orientation from
+the scene turns the continents with the epoch.
+
+The full image is 500 m per pixel at the equator, resized to 660 m to fit the
+largest texture lavapipe allows (16384 x 8192). Whether that is fine or coarse
+depends on the view:
+
+- From low orbit looking straight down, a camera pixel of the example camera
+  covers 77 m of ground, so each texture pixel spans about 8 image pixels and
+  looks soft.
+- From geostationary orbit, a camera pixel covers about 4 km, so each image
+  pixel averages about 35 texture pixels (6 x 6).
+
+For the second case the texture is stored with mipmaps: copies at half, a
+quarter, an eighth of the size, and so on. The GPU reads from the copy whose
+pixels best match the image pixel, so a far view shows the true average color
+of a region rather than a shimmering sample of individual texture pixels.
+
+Two details matter for brightness:
+
+- Averaging has to happen on reflectance, not on the encoded values image files
+  store (sRGB, which compresses the darks). Averaging encoded black and white
+  gives a reflectance of 21 %, not 50 %. So the texture is decoded to linear
+  reflectance once at load and kept in 16-bit floating point, and both the
+  mipmaps and the GPU's blending between neighboring texture pixels work on
+  those values. A coastline seen up close blends correctly from sea to land.
+- Blue Marble is surface reflectance with no atmosphere, and open ocean is
+  dark, a few percent. From orbit the ocean looks bright blue because the air
+  above it scatters sunlight toward the camera: Rayleigh scattering, which
+  grows as 1 / wavelength^4, which is also why the sky is blue. Until the
+  atmosphere is modeled (M4), a stand-in adds a reflectance of that shape,
+  0.07 at 450 nm falling to 0.017 at 650 nm (`Appearance::earth_haze`). It
+  brightens and blues the whole lit disk evenly, where the real effect grows
+  toward the limb, where the line of sight crosses more air.
+
+The texture's red, green and blue are reflectances in the same three bands a
+glTF base color uses (see the target model section), folded into the camera's
+channels once at setup as a small matrix, so any channel layout works.
+
+Blue Marble is a visual product built from calibrated MODIS reflectances, not a
+calibrated reflectance product itself, so its values are close but not exact
+reflectances. A calibrated alternative (MODIS's albedo product) is a possible
+later refinement.
+
 ### Depth from the bodies
 
 The pass also writes each hit's depth, near / z, as described in the
@@ -591,7 +649,8 @@ velocity as an input, which the scene does not carry yet.
 | Noise: photon shot noise, read noise, dark current, pixel-to-pixel variation | M3 |
 | Saturation spilling into neighbors (blooming) | M3 |
 | Non-Lambertian materials (BRDFs), glints, lunar backscatter | M4 |
-| Earth and Moon albedo maps | M2 |
+| Moon albedo map | M2 |
+| Clouds on Earth | M4 |
 | Earth's atmosphere: scattering, the bright limb | M4 |
 | Motion blur, rolling shutter, stray light | M6 |
 | Apparent positions: light time and aberration | M3 |