Earth and moon eclipse

docs/optics.md

@@ -690,7 +690,76 @@ The renderer counts both Earth and the Moon as occulters. The fraction is
 computed once per target, at its center. The whole target
 dims together, which is accurate unless the target is a sizable fraction of
 the penumbra's width. Light reaching the target from Earth itself is the
-next section.
+next section but one.
+
+### Eclipses on Earth and the Moon
+
+Code: `shaders/common.wgsl` (`sun_visible`), `shaders/bodies.wgsl`. From
+lighting L1.
+
+Earth and the Moon also shadow each other. When the Moon passes through
+Earth's shadow it is a lunar eclipse; when the Moon's shadow falls on Earth,
+a solar eclipse. For every pixel that sees Earth or the Moon, the shader
+works out the fraction of the Sun's disk visible from that point on the
+surface, past the other body, with the same overlap of circles as for the
+target, and multiplies the point's sunlight by it.
+
+The sizes involved:
+
+- At the Moon's distance, Earth's umbra reaches 4600 km from the shadow's
+  axis and its penumbra 8200 km. The Moon, 3474 km across, fits inside the
+  umbra with room to spare, so a total lunar eclipse lasts over an hour.
+- The Moon's umbra only just reaches Earth. When the Moon is near its
+  closest, the umbra touches down as a dark spot up to about 270 km across:
+  a total solar eclipse. When it is farther, the umbra ends in space, and
+  beyond its tip the Moon covers only the middle of the Sun's disk, leaving a
+  ring: an annular eclipse, where a few percent of the Sun still shows. The
+  penumbra around either is about 7000 km across.
+
+The overlap is computed in 32-bit floats, which is enough: a lunar surface
+point is placed to about 20 m out of 384,000 km, 6e-8 radians against a
+solar radius of 4.6e-3 radians seen from there. One formula needed care. The
+area where the two circles overlap involves angles whose cosines are close
+to 1 when a sliver of the Sun is covered, and the inverse cosine of a number
+near 1 loses most of its precision in 32 bits. The shader finds those angles
+from their sine and cosine together instead. With the inverse cosine,
+pixels at the shadow's edges came out wrong: a point the 64-bit model puts
+fully in the umbra read slightly lit, and one just outside the shadow
+slightly dimmed.
+
+Tests (`tests/eclipses.rs`), on the GPU and lavapipe, compare each pixel of
+Earth and the Moon against the 64-bit model at that pixel's surface point:
+the Moon entirely in Earth's umbra, the Moon across the umbra's edge, a
+total solar eclipse and an annular one. Pixels the model puts fully in shadow
+read exactly zero, those it puts fully outside are unchanged, and the rest
+agree to within 1e-4 of the Sun's light (9e-7 at most on the GPU, 5e-5 on
+lavapipe). The command-line tests render two real eclipses from their
+epochs: the total lunar eclipse of 2025 March 14 at mid-totality, where the
+whole Moon reads the bias, and the total solar eclipse of 2026 August 12,
+where the point of greatest eclipse in NASA's bulletin (65.2 N 25.2 W) is in
+the umbra (`examples/scenes/lunar-eclipse.toml`, `solar-eclipse.toml`). In
+the second, the umbra is 220 by 410 km in the image, stretched along the
+direction of the Sun, which is 26 degrees high there; NASA gives the path as
+294 km wide.
+
+The light Earth and the Moon reflect onto targets (next section) includes
+these shadows, so an eclipsed Moon sheds less light.
+
+On the RTX 3060 this adds nothing measurable to the bodies pass (0.202 to
+0.205 ms with Earth filling the image). On lavapipe it adds about 1 ms when
+Earth or the Moon fills much of the image.
+
+Limitations:
+
+- **Earth's atmosphere.** It bends sunlight into the umbra, mostly red, so a
+  real eclipsed Moon glows a dim copper color instead of going black, and it
+  makes the umbra about 2 % larger. Both come with the atmosphere (M4).
+- **Smooth shapes.** Earth's shadow is cast by a sphere of its equatorial
+  radius, as for the target's eclipses; its flattening would move the
+  shadow's edge on the Moon by about 20 km. The Moon's mountains and valleys,
+  which shape the edge of a solar eclipse's path, are not modeled.
+- **Uniform Sun.** The Sun's disk is taken as uniformly bright until limb
+  darkening (M2) arrives.
 
 ### Light from Earth and the Moon
 
@@ -781,9 +850,6 @@ Limitations:
   here, as they do in the camera's view. The Moon's real reflection is
   brighter toward the Sun (M4), and Earth has no clouds or atmosphere yet
   beyond the stand-in haze.
-- **No eclipses on the bodies.** Earth's shadow on the Moon and the Moon's
-  shadow on Earth are not modeled yet (M2), so a Moon in eclipse still lights
-  the target.
 
 ## Where the Sun and Moon appear
 
@@ -815,7 +881,6 @@ velocity as an input, which the scene does not carry yet.
 
 | Effect | Where |
 |---|---|
-| Eclipses seen on the bodies: Earth's shadow on the Moon, the Moon's on Earth | M2 |
 | Earthshine on the Moon's night side | M4 |
 | The Sun as a disk that is darker toward its edge (limb darkening) | M2 |
 | Pixel-area sampling (anti-aliasing): graded edges, thin parts | M3 |