feat(intro): add the First Light intro sequence

A deterministic WebGL film of God's Eye View coming online: a seed on Null
Island grows into a culture that draws the planet, indexes the surface
tile by tile, ingests the live feeds and outgrows its dish, ending on the
logo. Renders 16:9 and 9:16 frame by frame in headless Chromium; the
procedural score is locked to the same clock. Data and imagery are
fetched by the scripts in tools/ and are not committed.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01KqP857pippaUs6konSDfe8
This commit is contained in:
Claude committed 2026-10-18 03:21:30 +00:00
1 parent 93ea088f45
commit c9421a3f33
37 files changed
+15507

No files matched your search

+1
View File
@@ -0,0 +1 @@
cache/
@@ -0,0 +1,76 @@
"""Deliverable 3: clouds.jpg (4096x2048) grayscale cloud opacity map for one recent day.
Source: NASA GIBS daily VIIRS Corrected Reflectance True Colour for the same UTC
date from three satellites (NOAA-20, NOAA-21, Suomi NPP), EPSG:4326 level 3
(10x5 tiles of 512px = 5120x2560), downsampled to 4096x2048.
Cloud metric per satellite:
whiteness = min(R,G,B) (clouds are bright in every channel)
greyness = 1 - saturation (clouds are colourless)
c = ramp(whiteness) * smoothstep(greyness)
The same metric computed on the Esri base map (earth_day_4k.jpg) is subtracted
to suppress bright deserts, salt flats, snow and ice that would otherwise read
as cloud. The three per-satellite results are combined with a per-pixel median
(nan-aware), which removes swath-edge haze / glint streaks that only one
satellite shows, and fills swath gaps. Remaining no-data (polar night) -> 0.
Usage: python3 build_clouds.py [YYYY-MM-DD]
"""
import os
import sys
import numpy as np
from PIL import Image
from common import OUT, gibs_mosaic
Image.MAX_IMAGE_PIXELS = None
DATE = sys.argv[1] if len(sys.argv) > 1 else "2026-10-15"
LAYERS = [
"VIIRS_NOAA20_CorrectedReflectance_TrueColor",
"VIIRS_NOAA21_CorrectedReflectance_TrueColor",
"VIIRS_SNPP_CorrectedReflectance_TrueColor",
]
W, H = 4096, 2048
def smooth(x, a, b):
t = np.clip((x - a) / (b - a), 0, 1)
return t * t * (3 - 2 * t)
def metric(rgb):
rgb = rgb.astype(np.float32) / 255.0
mn = rgb.min(2)
mx = rgb.max(2)
sat = (mx - mn) / (mx + 1e-4)
white = np.clip((mn - 0.14) / 0.86, 0, 1) ** 1.15 # linear-ish: keeps texture inside thick cloud
return white * smooth(1.0 - sat, 0.65, 0.95), mx
def main():
base = np.asarray(Image.open(os.path.join(OUT, "earth_day_4k.jpg")).convert("RGB"))
base_c, _ = metric(base)
# dilate the base metric a few px so small Esri/VIIRS coastline misregistration
# does not leave bright outlines along desert and ice coasts
from PIL import ImageFilter
base_c = np.asarray(Image.fromarray((base_c * 255).astype(np.uint8)).filter(ImageFilter.MaxFilter(3)).filter(ImageFilter.GaussianBlur(2))).astype(np.float32) / 255
stack = []
for L in LAYERS:
m = gibs_mosaic(L, DATE, "250m", 3, 5, 10, "jpg").resize((W, H), Image.LANCZOS)
c, mx = metric(np.asarray(m))
c = np.clip(c - base_c * 1.1, 0, 1)
c[mx < 0.03] = np.nan # no-data (black)
stack.append(c)
stack = np.stack(stack)
with np.errstate(all="ignore"):
import warnings
warnings.simplefilter("ignore")
cloud = np.nanmedian(stack, axis=0)
cloud = np.nan_to_num(cloud, nan=0.0)
cloud = np.clip((cloud - 0.06) / 0.94, 0, 1) # black point: kill faint surface/haze residue
img = Image.fromarray(np.clip(cloud * 255 + 0.5, 0, 255).astype(np.uint8), "L")
img.save(os.path.join(OUT, "clouds.jpg"), quality=92, optimize=True, progressive=True)
print("done", DATE, "mean opacity %.3f" % cloud.mean())
if __name__ == "__main__":
main()
+91
View File
@@ -0,0 +1,91 @@
"""Deliverable 1: earth_day.jpg (8192x4096) + earth_day_4k.jpg (4096x2048).
Esri World Imagery z5 (32x32 tiles, 8192x8192 Web Mercator) reprojected to
equirectangular with bilinear sampling. Because both grids are 8192 px wide and
linear in longitude, the horizontal axis maps 1:1 and only latitude needs
resampling (linear interpolation between Mercator rows = bilinear).
Polar caps beyond the Mercator limit (+-85.0511 deg) come from NASA GIBS
BlueMarble_ShadedRelief_Bathymetry (EPSG:4326, level 4 = 10240x5120; its shaded
bathymetry matches Esri's small-scale ocean rendering), colour-matched to Esri
with a least-squares affine colour transform fitted on co-registered overlap pixels and cross-faded between 80 and 84.5 deg.
"""
import os
import numpy as np
from PIL import Image
from common import OUT, esri_jobs, fetch_many, decode, gibs_mosaic
Image.MAX_IMAGE_PIXELS = None
W, H = 8192, 4096
Z = 5
N = 2 ** Z
TS = 256
MERC = N * TS # 8192
MERC_LIMIT = np.degrees(np.arctan(np.sinh(np.pi))) # 85.0511
FADE_A, FADE_B = 80.0, 84.5 # pure Esri below A, pure Blue Marble above B
CAP_LAYER = os.environ.get("CAP_LAYER", "BlueMarble_ShadedRelief_Bathymetry")
def esri_mercator():
coords = [(x, y) for y in range(N) for x in range(N)]
res = fetch_many(esri_jobs(Z, coords), desc="esri z5")
merc = np.zeros((MERC, MERC, 3), np.uint8)
for (x, y), b in res.items():
if b is None:
raise SystemExit(f"missing esri tile {x},{y}")
merc[y * TS:(y + 1) * TS, x * TS:(x + 1) * TS] = np.asarray(decode(b))
return merc
def main():
merc = esri_mercator()
print("reprojecting")
lat = 90.0 - (np.arange(H) + 0.5) * 180.0 / H
latc = np.clip(lat, -MERC_LIMIT + 1e-6, MERC_LIMIT - 1e-6)
yn = (1.0 - np.log(np.tan(np.pi / 4 + np.radians(latc) / 2)) / np.pi) / 2.0
v = yn * MERC - 0.5
v0 = np.clip(np.floor(v).astype(int), 0, MERC - 1)
v1 = np.clip(v0 + 1, 0, MERC - 1)
f = np.clip(v - np.floor(v), 0, 1).astype(np.float32)[:, None, None]
eq = np.empty((H, W, 3), np.float32)
for s in range(0, H, 256):
e = s + 256
eq[s:e] = merc[v0[s:e]].astype(np.float32) * (1 - f[s:e]) + merc[v1[s:e]].astype(np.float32) * f[s:e]
del merc
print("fetching polar caps:", CAP_LAYER)
bm = gibs_mosaic(CAP_LAYER, None, "500m", 4, 10, 20, "jpg")
bm = np.asarray(bm.resize((W, H), Image.LANCZOS)).astype(np.float32)
# colour-match Blue Marble to Esri per hemisphere: fit an affine 3x3+offset colour
# transform (least squares) on co-registered pixels in the 76-84.5 deg overlap band
alat = np.abs(lat)
band = (alat > 76) & (alat < 84.5)
t = np.clip((alat - FADE_A) / (FADE_B - FADE_A), 0, 1)
t = (t * t * (3 - 2 * t)).astype(np.float32)[:, None, None] # smoothstep
out = eq.copy()
for hemi in (lat > 0, lat < 0):
rows = band & hemi
a = eq[rows][:, ::4].reshape(-1, 3)
b = bm[rows][:, ::4].reshape(-1, 3)
X = np.hstack([b, np.ones((len(b), 1), np.float32)])
# ridge-regularised toward identity: near-grey ice makes the plain fit ill-conditioned
lam = len(b) * 50.0
D = np.diag([1.0, 1.0, 1.0, 0.0])
I0 = np.vstack([np.eye(3), np.zeros((1, 3))])
X64, a64 = X.astype(np.float64), a.astype(np.float64)
M = np.linalg.solve(X64.T @ X64 + lam * D, X64.T @ a64 + lam * D @ I0)
print(" colour transform\n", M.round(3))
h = bm[hemi]
bm[hemi] = (h.reshape(-1, 3) @ M[:3] + M[3]).reshape(h.shape)
out[hemi] = eq[hemi] * (1 - t[hemi]) + bm[hemi] * t[hemi]
img = Image.fromarray(np.clip(out + 0.5, 0, 255).astype(np.uint8))
os.makedirs(OUT, exist_ok=True)
img.save(os.path.join(OUT, "earth_day.jpg"), quality=92, optimize=True, progressive=True)
img.resize((4096, 2048), Image.LANCZOS).save(os.path.join(OUT, "earth_day_4k.jpg"), quality=92, optimize=True, progressive=True)
print("done")
if __name__ == "__main__":
main()
+133
View File
@@ -0,0 +1,133 @@
"""Deliverable 4: Esri World Imagery 'synthetic screenshots' of iconic places.
For each location: <slug>_wide.jpg (zoom 13) and <slug>_close.jpg (zoom 18,
falling back to 17/16 when Esri serves "Map data not yet available"
placeholder tiles), both 1536x1024 centred on the point. Writes index.json.
Usage: python3 build_hero.py [--contact DIR] (contact sheets for visual QA)
Per-location overrides: CLOSE_ZOOM_OVERRIDES below.
"""
import io
import json
import math
import os
import sys
import numpy as np
from PIL import Image
from common import OUT, esri_jobs, fetch_many
HERO = os.path.join(OUT, "hero")
CW, CH = 1536, 1024
TS = 256
LOCATIONS = [
("manhattan", "Midtown Manhattan", 40.7580, -73.9855),
("palm_jumeirah", "Palm Jumeirah", 25.1124, 55.1390),
("singapore_port", "Port of Singapore (Pasir Panjang Terminal)", 1.2730, 103.7690), # was 1.2650,103.8180 (Keppel Bay residential, no port),
("shibuya", "Shibuya Crossing", 35.6595, 139.7005),
("arc_de_triomphe", "Arc de Triomphe", 48.8738, 2.2950),
("giza", "Giza Pyramids", 29.9792, 31.1342),
("rotterdam_port", "Port of Rotterdam", 51.9500, 4.0500),
("lax", "Los Angeles International Airport", 33.9416, -118.4085),
("hong_kong", "Victoria Harbour, Hong Kong", 22.2930, 114.1700),
("panama_canal", "Panama Canal, Miraflores Locks", 8.9966, -79.5915), # was 9.0800,-79.6800 (blurry jungle/lake shore),
("sydney_opera", "Sydney Opera House", -33.8568, 151.2153),
("kennedy_lc39a", "Kennedy Space Center LC-39A", 28.6083, -80.6041),
("heathrow", "London Heathrow Airport", 51.4700, -0.4543),
("rio_maracana", "Maracana Stadium, Rio de Janeiro", -22.9122, -43.2302),
("venice", "Venice", 45.4340, 12.3388),
("las_vegas_strip", "Las Vegas Strip", 36.1147, -115.1728),
("vatican", "Vatican City", 41.9022, 12.4539),
("burj_khalifa", "Burj Khalifa, Dubai", 25.1972, 55.2744),
("golden_gate", "Golden Gate Bridge", 37.8199, -122.4783),
("kremlin", "Moscow Kremlin", 55.7520, 37.6175),
("tiananmen", "Tiananmen Square, Beijing", 39.9037, 116.3917), # was 39.9055,116.3976 (east of the square),
("mumbai_port", "Mumbai Port", 18.9400, 72.8400),
("suez_canal", "Suez Canal, Ismailia", 30.6141, 32.3228), # was 30.5850,32.2650 (Ismailia city blocks, canal off-frame),
("pentagon", "The Pentagon", 38.8719, -77.0563),
]
WIDE_ZOOM = 13
CLOSE_ZOOM = 18
CLOSE_ZOOM_OVERRIDES = {} # slug -> zoom, set after visual QA if needed
DROP = set() # slugs rejected after visual QA
def world_px(lat, lon, z):
n = TS * 2 ** z
x = (lon + 180.0) / 360.0 * n
s = math.sin(math.radians(lat))
y = (0.5 - math.log((1 + s) / (1 - s)) / (4 * math.pi)) * n
return x, y
def is_placeholder(tile):
a = np.asarray(tile).astype(np.float32)
m = a.reshape(-1, 3).mean(0)
return a.std() < 8 and abs(m[0] - m[1]) < 4 and abs(m[1] - m[2]) < 4
def render(lat, lon, z):
"""Return (image, placeholder_fraction)."""
cx, cy = world_px(lat, lon, z)
x0, y0 = int(round(cx - CW / 2)), int(round(cy - CH / 2))
tx0, ty0 = x0 // TS, y0 // TS
tx1, ty1 = (x0 + CW - 1) // TS, (y0 + CH - 1) // TS
n = 2 ** z
coords = [(tx % n, ty) for ty in range(ty0, ty1 + 1) for tx in range(tx0, tx1 + 1)]
data = fetch_many(esri_jobs(z, coords), desc=f"z{z}")
canvas = Image.new("RGB", ((tx1 - tx0 + 1) * TS, (ty1 - ty0 + 1) * TS))
ph = 0
for ty in range(ty0, ty1 + 1):
for tx in range(tx0, tx1 + 1):
b = data.get((tx % n, ty))
if b is None:
ph += 1
continue
t = Image.open(io.BytesIO(b)).convert("RGB")
if is_placeholder(t):
ph += 1
canvas.paste(t, ((tx - tx0) * TS, (ty - ty0) * TS))
crop = canvas.crop((x0 - tx0 * TS, y0 - ty0 * TS, x0 - tx0 * TS + CW, y0 - ty0 * TS + CH))
return crop, ph / len(coords)
def main():
os.makedirs(HERO, exist_ok=True)
contact = None
if "--contact" in sys.argv:
contact = sys.argv[sys.argv.index("--contact") + 1]
os.makedirs(contact, exist_ok=True)
index = []
for slug, name, lat, lon in LOCATIONS:
if slug in DROP:
for k in ("wide", "close"):
p = os.path.join(HERO, f"{slug}_{k}.jpg")
if os.path.exists(p):
os.remove(p)
print(f"{slug}: dropped")
continue
wide, _ = render(lat, lon, WIDE_ZOOM)
z = CLOSE_ZOOM_OVERRIDES.get(slug, CLOSE_ZOOM)
while True:
close, ph = render(lat, lon, z)
if ph == 0 or z <= 16:
break
print(f" {slug}: {ph:.0%} placeholder tiles at z{z}, falling back")
z -= 1
wide.save(os.path.join(HERO, f"{slug}_wide.jpg"), quality=92, optimize=True)
close.save(os.path.join(HERO, f"{slug}_close.jpg"), quality=92, optimize=True)
index.append({"slug": slug, "name": name, "lat": lat, "lon": lon, "close_zoom": z})
print(f"{slug}: close z{z}")
if contact:
sheet = Image.new("RGB", (1536, 512))
sheet.paste(wide.resize((768, 512), Image.LANCZOS), (0, 0))
sheet.paste(close.resize((768, 512), Image.LANCZOS), (768, 0))
sheet.save(os.path.join(contact, f"{slug}.jpg"), quality=85)
with open(os.path.join(HERO, "index.json"), "w") as f:
json.dump(index, f, indent=2)
print(f"{len(index)} locations written")
if __name__ == "__main__":
main()
@@ -0,0 +1,20 @@
"""Deliverable 2: earth_night.jpg (8192x4096) + earth_night_4k.jpg (4096x2048).
NASA Black Marble (layer VIIRS_Black_Marble, 2016 annual composite) from GIBS
EPSG:4326 level 4 (20x10 tiles of 512px = 10240x5120), Lanczos-downsampled.
Colour kept as served.
"""
import os
from PIL import Image
from common import OUT, gibs_mosaic
Image.MAX_IMAGE_PIXELS = None
LAYER = os.environ.get("NIGHT_LAYER", "VIIRS_Black_Marble")
TIME = os.environ.get("NIGHT_TIME", "2016-01-01")
EXT = "png" if LAYER == "VIIRS_Black_Marble" else "jpg"
m = gibs_mosaic(LAYER, TIME if LAYER == "VIIRS_Black_Marble" else None, "500m", 4, 10, 20, EXT)
big = m.resize((8192, 4096), Image.LANCZOS)
big.save(os.path.join(OUT, "earth_night.jpg"), quality=92, optimize=True, progressive=True)
big.resize((4096, 2048), Image.LANCZOS).save(os.path.join(OUT, "earth_night_4k.jpg"), quality=92, optimize=True, progressive=True)
print("done", LAYER, TIME)
@@ -0,0 +1,15 @@
"""Deliverable 5: Esri World Imagery z3 (8x8) and z4 (16x16) tiles for the quadtree indexing effect."""
import os, shutil
from common import OUT, esri_jobs, fetch_many, esri_tile_path
for z in (3, 4):
n = 2 ** z
d = os.path.join(OUT, f"tiles_z{z}")
os.makedirs(d, exist_ok=True)
coords = [(x, y) for y in range(n) for x in range(n)]
res = fetch_many(esri_jobs(z, coords), desc=f"esri z{z}")
bad = [k for k, v in res.items() if v is None]
for x, y in coords:
if res[(x, y)] is not None:
shutil.copyfile(esri_tile_path(z, x, y), os.path.join(d, f"z{z}_{x}_{y}.jpg"))
print(f"z{z}: {len(coords)-len(bad)} tiles written, {len(bad)} failed")
+116
View File
@@ -0,0 +1,116 @@
"""Shared helpers: polite cached tile fetching for Esri World Imagery and NASA GIBS."""
import io
import os
import sys
import time
import threading
from concurrent.futures import ThreadPoolExecutor, as_completed
import requests
from PIL import Image
HERE = os.path.dirname(os.path.abspath(__file__))
CACHE = os.path.join(HERE, "cache")
ROOT = os.path.abspath(os.path.join(HERE, "..", ".."))
OUT = os.path.join(ROOT, "imagery")
MAX_WORKERS = 8
UA = "gods-eye-view-intro/1.0 (texture prep; contact: project maintainer)"
ESRI = "https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}"
GIBS4326 = "https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/{layer}/default/{time}/{tms}/{z}/{row}/{col}.{ext}"
_local = threading.local()
def _session():
s = getattr(_local, "s", None)
if s is None:
s = requests.Session()
s.headers["User-Agent"] = UA
_local.s = s
return s
def fetch(url, cache_path, retries=6):
"""Return raw bytes for url, caching to cache_path. Retries with backoff."""
if os.path.exists(cache_path) and os.path.getsize(cache_path) > 0:
with open(cache_path, "rb") as f:
return f.read()
os.makedirs(os.path.dirname(cache_path), exist_ok=True)
last = None
for attempt in range(retries):
try:
r = _session().get(url, timeout=60)
if r.status_code == 200 and r.content:
tmp = cache_path + ".part"
with open(tmp, "wb") as f:
f.write(r.content)
os.replace(tmp, cache_path)
return r.content
if r.status_code in (400, 404):
last = f"HTTP {r.status_code}"
break
last = f"HTTP {r.status_code}"
except Exception as e: # network hiccup
last = repr(e)
time.sleep(min(30, 1.5 * 2 ** attempt))
raise RuntimeError(f"failed {url}: {last}")
def fetch_many(jobs, desc=""):
"""jobs: list of (key, url, cache_path). Returns {key: bytes or None}."""
out = {}
done = 0
with ThreadPoolExecutor(MAX_WORKERS) as ex:
futs = {ex.submit(fetch, u, p): k for k, u, p in jobs}
for f in as_completed(futs):
k = futs[f]
try:
out[k] = f.result()
except Exception as e:
print(f" ! {e}", file=sys.stderr)
out[k] = None
done += 1
if done % 100 == 0 or done == len(jobs):
print(f" {desc} {done}/{len(jobs)}", flush=True)
return out
def esri_tile_path(z, x, y):
return os.path.join(CACHE, "esri", str(z), str(y), f"{x}.jpg")
def esri_jobs(z, coords):
return [((x, y), ESRI.format(z=z, x=x, y=y), esri_tile_path(z, x, y)) for x, y in coords]
def gibs_path(layer, time_, tms, z, row, col, ext):
return os.path.join(CACHE, "gibs", layer, time_ or "default", tms, str(z), str(row), f"{col}.{ext}")
def gibs_jobs(layer, time_, tms, z, rows, cols, ext):
t = time_ or "default"
return [((r, c), GIBS4326.format(layer=layer, time=t, tms=tms, z=z, row=r, col=c, ext=ext),
gibs_path(layer, time_, tms, z, r, c, ext)) for r in range(rows) for c in range(cols)]
def decode(b, mode="RGB"):
return Image.open(io.BytesIO(b)).convert(mode)
def gibs_mosaic(layer, time_, tms, z, rows, cols, ext, mode="RGB"):
"""Fetch and stitch a full-globe GIBS EPSG:4326 level (512px tiles)."""
jobs = gibs_jobs(layer, time_, tms, z, rows, cols, ext)
data = fetch_many(jobs, desc=f"{layer} z{z}")
W, H = cols * 512, rows * 512
canvas = Image.new(mode, (W, H))
missing = 0
for (r, c), b in data.items():
if b is None:
missing += 1
continue
canvas.paste(decode(b, mode), (c * 512, r * 512))
if missing:
print(f" {missing} tiles missing for {layer}", file=sys.stderr)
return canvas