Example and docs for blooming

scripts/make-example-scenes.py

@@ -2,9 +2,11 @@
 """Writes examples/scenes/<model>.toml for the NASA models fetch-models.sh downloads,
 two scenes with Earth, the Moon and a spacecraft together (below):
 examples/scenes/earthrise.toml from lunar orbit and examples/scenes/moonrise.toml
-from geostationary height, and scenes for the stars of camera tier C1: a star field,
-examples/scenes/stars-pleiades.toml, and a telescope on one geostationary satellite
-imaging another along the arc, examples/scenes/geo-telescope-*.toml.
+from geostationary height, examples/scenes/sun-glare.toml with the Sun in the frame
+of a camera whose CCD blooms (camera tier C1), and scenes for the stars of lighting
+tier L1: a star field, examples/scenes/stars-pleiades.toml, and a telescope on one
+geostationary satellite imaging another along the arc,
+examples/scenes/geo-telescope-*.toml.
 
 Every scene has the same composition: the spacecraft in an isometric view (the
 camera looks along its body (+1, +1, +1) diagonal, body +Z toward image up) with
@@ -467,6 +469,68 @@ def earth_velocity(sun):
     return [EARTH_SPEED * x for x in norm(cross(ECLIPTIC_POLE, [-x for x in sun]))]
 
 
+# Sun glare: an inspector below Landsat 8, looking up at it against the Sun high over
+# Earth's day side, seen by a CCD that lets a saturated pixel's excess run along its
+# column (camera tier C1's blooming).
+GLARE_ELEVATION = 75.0  # degrees, boresight above the inspector's horizon
+GLARE_SUN = (3.0, 0.7)  # degrees above and to the side of the boresight
+GLARE_EXPOSURE = 4e-4  # s, for the Earth-lit satellite; the Sun saturates anyway
+
+
+def sun_glare():
+    file, scale, center, radius, orbit = "landsat8.glb", 1.0, MODELS[0][3], MODELS[0][4], MODELS[0][5]
+    camera = [orbit, 0.0, 0.0]
+    up = [1.0, 0.0, 0.0]
+
+    def toward(elevation, across=0.0):
+        e, a = math.radians(elevation), math.radians(across)
+        return norm([math.cos(a) * math.sin(e), math.cos(a) * math.cos(e), math.sin(a)])
+
+    boresight = toward(GLARE_ELEVATION)
+    sun = toward(GLARE_ELEVATION + GLARE_SUN[0], GLARE_SUN[1])
+    distance = radius / math.tan(math.radians(2.8))
+    look = [camera[i] + distance * boresight[i] for i in range(3)]
+    attitude = triad([1, 1, 1], [0, 0, 1], [-x for x in boresight], up)
+    offset = mul(attitude, center)
+    position = [look[i] - offset[i] for i in range(3)]
+    fmt = lambda v, d=2: "[" + ", ".join(f"{x:.{d}f}" for x in v) + "]"
+    return f"""# Sun glare: an inspector {distance:.0f} m below Landsat 8 in its 705 km orbit, looking up at
+# it {GLARE_ELEVATION:g} degrees above the horizon, with the Sun {GLARE_SUN[0]:g} degrees above and {GLARE_SUN[1]:g} to the side of
+# it, about 26,000 full wells at its center. The satellite is back-lit: dark at
+# lighting L0, and at L1 lit from below by the sunlit Earth. The camera is the
+# example camera with a CCD that has no anti-blooming drain: from camera tier C1 every
+# saturated pixel's excess runs up and down its column, and the Sun's columns streak
+# through the whole frame and across the end of the solar array. Generated by
+# scripts/make-example-scenes.py; the model comes from scripts/fetch-models.sh.
+#
+#   resolved render --scene examples/scenes/sun-glare.toml --camera C1 --pretty --preview glare.png
+#   resolved render --scene examples/scenes/sun-glare.toml --lighting L1 --camera C1 --pretty --preview glare.png
+
+sun = {fmt([camera[i] + AU * sun[i] for i in range(3)], 0)}
+moon = [0, 0, -3.844e8]
+
+[camera]
+exposure = {GLARE_EXPOSURE}
+blooming = {{ column = 1.0 }}
+
+[observer]
+position = {fmt(camera)}
+look_at = {fmt(look)}
+up = [1, 0, 0]
+
+# At lighting L1, Earth's surface shows July (from scripts/fetch-earth.sh), and lights
+# the satellite's Earth-facing side.
+[appearance]
+earth_month = 7
+
+[[target]]
+model = "../models/nasa/{file}"
+scale = {scale}
+position = {fmt(position, 4)}
+attitude = {fmt(quaternion(attitude), 9)}
+"""
+
+
 def stars_pleiades():
     # The Pleiades, right ascension 56.75 and declination 24.12 degrees, from
     # geostationary orbit, with the Sun behind the camera.
@@ -589,6 +653,9 @@ print(f"wrote {path}")
 path = out / "moonrise.toml"
 path.write_text(moonrise())
 print(f"wrote {path}")
+path = out / "sun-glare.toml"
+path.write_text(sun_glare())
+print(f"wrote {path}")
 path = out / "stars-pleiades.toml"
 path.write_text(stars_pleiades())
 print(f"wrote {path}")