CinematicEarth 0.2.0__py3-none-any.whl

cinematicearth/__init__.py

@@ -0,0 +1,45 @@
+"""CinematicEarth: cinematic multi-stop flyovers for Google Earth Studio.
+
+    import cinematicearth as ce
+    plan = ce.build("stops.md", out="flyover.esp")      # also writes .kml + .plan.json
+    print(plan.summary())
+"""
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from .model import Settings, Stop, parse_moves, SPEED_PRESETS
+from .io import load, parse_markdown, parse_stop_line
+from .planner import plan_flyover, Plan
+from .esp import build_esp, write_esp, decode_tracks
+from .kml import build_kml, write_kml
+
+__version__ = "0.2.0"
+__all__ = ["Settings", "Stop", "Plan", "load", "plan_flyover", "build", "write_esp", "write_kml",
+           "build_esp", "decode_tracks", "parse_moves", "SPEED_PRESETS", "__version__"]
+
+
+def build(source, out: Optional[str] = "flyover.esp", kml: bool = True, plan_json: bool = True,
+          template: Optional[str] = None, geocode: bool = False, elevation: bool = False,
+          verbose: bool = True, **overrides) -> Plan:
+    """Load stops (path / markdown text / list), plan the camera, write outputs.
+
+    overrides: any Settings field, e.g. duration=150, speed="slow", stop_duration=10, orbit=45.
+    """
+    settings, stops = load(source, **overrides)
+    if geocode or elevation:
+        from .geocode import resolve
+        resolve(stops, need_coords=geocode, need_elev=elevation, verbose=verbose)
+    plan = plan_flyover(stops, settings)
+    plan.esp_files = []
+    if out:
+        plan.esp_files = write_esp(plan, out, template)
+        base = os.path.splitext(out)[0]
+        if kml:
+            write_kml(plan, base + ".kml")
+        if plan_json:
+            plan.save_json(base + ".plan.json")
+    if verbose:
+        print(plan.summary())
+    return plan

cinematicearth/cli.py

@@ -0,0 +1,176 @@
+"""Command line interface.
+
+    cinematicearth build stops.md -o flyover.esp --speed slow --duration 180
+    cinematicearth build "Huntsville, AL; Santa Fe, NM" --geocode
+    cinematicearth preview stops.md -o preview.png
+    cinematicearth annotate flyover.plan.json render.zip -o flyover_final.mp4
+    cinematicearth annotate flyover.plan.json part01.zip part02.zip ...   (split projects)
+    cinematicearth moves          # print the camera-move reference
+    cinematicearth init stops.md  # write an example stop file
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from . import build as _build, load, plan_flyover, __version__
+from .model import Settings
+
+EXAMPLE = """---
+title: My flyover
+speed: slow          # glacial | slow | medium | fast | number
+stop_duration: 8     # seconds circling each stop
+orbit: 45            # degrees of orbit per stop
+tilt: 60             # 0 = straight down, 90 = horizon
+# duration: 150      # optional total length (s); transits are re-paced to fit
+---
+
+# Stops:  name | lat, lon[, elev] | camera moves | key=value ...
+- Huntsville, AL | 34.7304, -86.5861, 190 | orbit 60 + zoom 8km>3km | note=NASA EarthRISE
+- Santa Fe, NM | 35.6870, -105.9378, 2130 | orbit 30 + tilt 55>68 @5s; truck 2km + zoom 2.5km
+- Fort Collins, CO | 40.5853, -105.0844, 1525 | slow 1.5
+"""
+
+
+def _overrides(a):
+    keys = ["duration", "speed", "stop_duration", "orbit", "tilt", "fps", "width", "height",
+            "range_start", "range_end", "title", "ease", "max_part_seconds", "keyframe_tol_px", "cut_km",
+            "direction"]
+    ov = {k: getattr(a, k) for k in keys if getattr(a, k, None) is not None}
+    if getattr(a, "no_intro", False):
+        ov["intro"] = False
+    if getattr(a, "no_outro", False):
+        ov["outro"] = False
+    if getattr(a, "every_frame", False):
+        ov["keyframe_every_frame"] = True
+    return ov
+
+
+def _source(src):
+    if os.path.exists(src):
+        return src
+    if src == "-":
+        return sys.stdin.read()
+    # inline list: "A; B; C" or newline separated
+    return "\n".join("- " + s.strip() for s in src.replace("\n", ";").split(";") if s.strip())
+
+
+def _add_common(p):
+    p.add_argument("source", help=".md/.csv/.json/.yaml/.txt file, '-' for stdin, or 'A; B; C' inline list")
+    p.add_argument("--duration", type=float, help="total seconds (default: auto from pacing)")
+    p.add_argument("--speed", help="glacial | slow | medium | fast | number")
+    p.add_argument("--stop-duration", dest="stop_duration", type=float)
+    p.add_argument("--orbit", type=float, help="default orbit degrees per stop")
+    p.add_argument("--tilt", type=float)
+    p.add_argument("--range-start", dest="range_start", type=float)
+    p.add_argument("--range-end", dest="range_end", type=float)
+    p.add_argument("--fps", type=int)
+    p.add_argument("--width", type=int)
+    p.add_argument("--height", type=int)
+    p.add_argument("--ease", choices=["smooth", "sine", "linear"])
+    p.add_argument("--split", dest="max_part_seconds", type=float,
+                   help="split into several .esp projects of at most N seconds (lighter for Earth Studio)")
+    p.add_argument("--keyframe-tol", dest="keyframe_tol_px", type=float, help="px drift allowed at stops (default 3)")
+    p.add_argument("--cut-km", dest="cut_km", type=float, help="hops longer than this become hard cuts")
+    p.add_argument("--direction", help="orbit direction: alternate | 1 | -1")
+    p.add_argument("--every-frame", action="store_true", help="one keyframe per frame (big .esp)")
+    p.add_argument("--title")
+    p.add_argument("--no-intro", action="store_true")
+    p.add_argument("--no-outro", action="store_true")
+    p.add_argument("--geocode", action="store_true", help="look up missing lat/lon (Nominatim)")
+    p.add_argument("--elevation", action="store_true", help="look up missing ground elevation (Open-Meteo)")
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="cinematicearth", description="Cinematic Google Earth Studio flyovers")
+    ap.add_argument("--version", action="version", version=__version__)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    b = sub.add_parser("build", help="write .esp (+ .kml, .plan.json)")
+    _add_common(b)
+    b.add_argument("-o", "--out", default="flyover.esp")
+    b.add_argument("--template", help="an .esp exported from Earth Studio to inject keyframes into")
+    b.add_argument("--no-kml", action="store_true")
+
+    pv = sub.add_parser("preview", help="plot ground track / altitude / pacing")
+    _add_common(pv)
+    pv.add_argument("-o", "--out", default="flyover_preview.png")
+
+    an = sub.add_parser("annotate", help="burn annotations into an Earth Studio render")
+    an.add_argument("plan", help="the .plan.json written by build")
+    an.add_argument("render", nargs="+", help="Earth Studio render(s): .zip of frames, frame folder, or video; "
+                                               "one per project part, in order")
+    an.add_argument("-o", "--out", default="flyover_final.mp4")
+    an.add_argument("--accent", default="#FFB000")
+    an.add_argument("--no-coords", action="store_true")
+    an.add_argument("--no-counter", action="store_true")
+    an.add_argument("--attribution", default="Google Earth")
+
+    sm = sub.add_parser("simulate", help="wireframe preview MP4 of an .esp (check motion before Earth Studio)")
+    sm.add_argument("esp")
+    sm.add_argument("plan", help="the .plan.json written by build")
+    sm.add_argument("-o", "--out", default="flyover_wireframe.mp4")
+    sm.add_argument("--width", type=int, default=640)
+    sm.add_argument("--height", type=int, default=360)
+    sm.add_argument("--fps", type=int, default=15)
+    sm.add_argument("--start", type=float, default=0.0)
+    sm.add_argument("--seconds", type=float)
+
+    sk = sub.add_parser("smoketest", help="write a tiny 10 s one-city .esp to check Earth Studio import")
+    sk.add_argument("-o", "--out", default="test_tiny.esp")
+
+    sub.add_parser("moves", help="print the camera-move reference")
+    ini = sub.add_parser("init", help="write an example stops file")
+    ini.add_argument("path", nargs="?", default="stops.md")
+
+    a = ap.parse_args(argv)
+    if a.cmd == "build":
+        plan = _build(_source(a.source), out=a.out, kml=not a.no_kml, template=a.template,
+                      geocode=a.geocode, elevation=a.elevation, **_overrides(a))
+        for f in plan.esp_files:
+            print(f"wrote {f}")
+    elif a.cmd == "preview":
+        from .preview import plot_plan
+        settings, stops = load(_source(a.source), **_overrides(a))
+        if a.geocode or a.elevation:
+            from .geocode import resolve
+            resolve(stops, need_coords=a.geocode, need_elev=a.elevation)
+        plan = plan_flyover(stops, settings)
+        print(plan.summary())
+        plot_plan(plan, a.out, show=False)
+        print(f"wrote {a.out}")
+    elif a.cmd == "annotate":
+        from .overlay import annotate_video, OverlayStyle
+        st = OverlayStyle(accent=a.accent, show_coords=not a.no_coords, show_counter=not a.no_counter,
+                          attribution=a.attribution)
+        annotate_video(a.render if len(a.render) > 1 else a.render[0], a.plan, a.out, st)
+        print(f"wrote {a.out}")
+    elif a.cmd == "simulate":
+        import json
+        from .simulate import render_preview, PlanWindows
+        with open(a.esp) as f:
+            esp = json.load(f)
+        render_preview(esp, PlanWindows(a.plan), a.out, a.width, a.height, a.fps, a.seconds, a.start)
+        print(f"wrote {a.out}")
+    elif a.cmd == "smoketest":
+        plan = _build("- Huntsville, AL | 34.7304, -86.5861, 190 | orbit 45 + zoom 7km>3.5km @10s",
+                      out=a.out, kml=False, plan_json=False, intro=False, outro=False, verbose=False,
+                      title="CinematicEarth smoke test")
+        print(f"wrote {a.out}: {plan.frames} frames, {len(plan.keyframes()[0])} keyframes")
+    elif a.cmd == "moves":
+        from . import model
+        src = model.__file__
+        with open(src) as f:
+            txt = f.read()
+        start = txt.index("# ---------------- move language")
+        end = txt.index("_DUR =")
+        print("\n".join(l[2:] if l.startswith("# ") else l.lstrip("#") for l in txt[start:end].splitlines()[1:]))
+    elif a.cmd == "init":
+        with open(a.path, "w") as f:
+            f.write(EXAMPLE)
+        print(f"wrote {a.path}")
+
+
+if __name__ == "__main__":
+    main()

cinematicearth/esp.py

@@ -0,0 +1,206 @@
+"""Write Google Earth Studio project files (.esp).
+
+The layout and value encodings follow a real Earth Studio export
+(modelVersion 17) as documented by mkatzef/google-studio-utils:
+
+* keyframe ``time`` is a fraction 0..1 of the project duration
+* longitude: value = (lon - min) / (180 - min), ``minValueRange`` = min
+* latitude:  value = (lat - min) / (90 - min),  ``minValueRange`` = min
+* altitude:  value = alt_m * 1.5356706349899208e-08 (linear, not logarithmic)
+* rotationX (pan / heading, compass deg): value = (pan - min) / (max - min), with
+  ``minValueRange`` / ``maxValueRange``; pans may be unwrapped beyond 0..360
+* rotationY (tilt, 0 = down, 90 = horizon): value = tilt / 180
+
+Camera Target is written disabled: pan/tilt are computed exactly per keyframe,
+so the camera always aims at the city without relying on target influence.
+"""
+from __future__ import annotations
+
+import copy
+import json
+from typing import Optional
+
+import numpy as np
+
+ALT_SCALE = 1.5356706349899208e-08
+
+
+def _block(label, vals, times, min_val=None, max_val=None):
+    blk = {
+        "type": label,
+        "value": {"relative": 0},
+        "keyframes": [{"time": float(t), "value": float(v)} for t, v in zip(times, vals)],
+        "intimeline": True,
+    }
+    if min_val is not None:
+        blk["value"]["minValueRange"] = float(min_val)
+    if max_val is not None:
+        blk["value"]["maxValueRange"] = float(max_val)
+    if label == "altitude":
+        blk["value"]["logarithmic"] = False
+    return blk
+
+
+def encode_tracks(times, cam, rot, duration):
+    """Return (position_blocks, rotation_blocks) in Earth Studio encoding."""
+    tn = np.clip(np.asarray(times) / duration, 0.0, 1.0)
+    lat, lon, alt = cam[:, 0], cam[:, 1], cam[:, 2]
+    pan, tilt = rot[:, 0], rot[:, 1]
+    lon_min = float(lon.min()) - 1e-6
+    lat_min = float(lat.min()) - 1e-6
+    pmin, pmax = float(pan.min()), float(pan.max())
+    if pmax - pmin < 1e-3:
+        pmin, pmax = pmin - 1.0, pmax + 1.0
+    pos = [
+        _block("longitude", (lon - lon_min) / (180.0 - lon_min), tn, lon_min),
+        _block("latitude", (lat - lat_min) / (90.0 - lat_min), tn, lat_min),
+        _block("altitude", alt * ALT_SCALE, tn),
+    ]
+    rotb = [
+        _block("rotationX", (pan - pmin) / (pmax - pmin), tn, pmin, pmax),
+        _block("rotationY", tilt / 180.0, tn),
+        {"type": "rotationZ", "value": {}},
+    ]
+    return pos, rotb
+
+
+def decode_tracks(esp: dict):
+    """Inverse of encode_tracks (for verification / round-trip tests)."""
+    found = {}
+
+    def walk(o):
+        if isinstance(o, dict):
+            if o.get("type") in ("longitude", "latitude", "altitude", "rotationX", "rotationY") and "keyframes" in o:
+                found[o["type"]] = o
+            for v in o.values():
+                walk(v)
+        elif isinstance(o, list):
+            for v in o:
+                walk(v)
+
+    walk(esp)
+    dur = esp["settings"]["duration"] / esp["settings"]["frameRate"]
+    t = np.array([k["time"] for k in found["longitude"]["keyframes"]]) * dur
+    g = lambda k: np.array([x["value"] for x in found[k]["keyframes"]])
+    lon_min = found["longitude"]["value"]["minValueRange"]
+    lat_min = found["latitude"]["value"]["minValueRange"]
+    lon = lon_min + g("longitude") * (180 - lon_min)
+    lat = lat_min + g("latitude") * (90 - lat_min)
+    alt = g("altitude") / ALT_SCALE
+    rx = found["rotationX"]["value"]
+    pan = rx["minValueRange"] + g("rotationX") * (rx["maxValueRange"] - rx["minValueRange"])
+    tilt = g("rotationY") * 180
+    return t, np.c_[lat, lon, alt], np.c_[pan, tilt]
+
+
+def _template(name, fps, width, height, frames, pos, rotb):
+    return {
+        "modelVersion": 17,
+        "settings": {"name": name, "frameRate": fps,
+                     "dimensions": {"width": width, "height": height},
+                     "duration": frames, "timeFormat": "frames"},
+        "scenes": [{
+            "animationModel": {"roving": False, "logarithmic": False, "groupedPosition": True},
+            "duration": frames,
+            "attributes": [
+                {"type": "cameraGroup", "inTimeline": True, "attributes": [
+                    {"type": "cameraPositionGroup", "inTimeline": True, "attributes": pos},
+                    {"type": "cameraTargetEffect", "attributes": [
+                        {"type": "enabled", "value": {}},
+                        {"type": "poi", "attributes": [
+                            {"type": "longitudePOI", "value": {}},
+                            {"type": "latitudePOI", "value": {}},
+                            {"type": "altitudePOI", "value": {"logarithmic": False}}]},
+                        {"type": "influence", "value": {}}]},
+                    {"type": "cameraRotationGroup", "inTimeline": True, "attributes": rotb},
+                    {"type": "cameraLensGroup", "attributes": [
+                        {"type": "fov", "value": {}}, {"type": "exposure", "value": {}},
+                        {"type": "aperture", "value": {}}, {"type": "minFocusLength", "value": {}}]},
+                ]},
+                {"type": "environmentGroup", "attributes": [
+                    {"type": "sunGroup", "attributes": [
+                        {"type": "sunVisibility", "value": {}},
+                        {"type": "worldTime", "value": {"relative": 0.5}}]},
+                    {"type": "cloudGroup", "attributes": [
+                        {"type": "cloudVisibility", "value": {}}, {"type": "cloudopacity", "value": {}},
+                        {"type": "cloudheight", "value": {}}, {"type": "clouddate", "value": {"relative": 0.95}}]},
+                    {"type": "starsPlanetsGroup", "attributes": [{"type": "starsEnabled", "value": {}}]},
+                    {"type": "seawaterGroup", "attributes": [
+                        {"type": "seawater", "value": {}}, {"type": "influence", "value": {"relative": 1}}]},
+                    {"type": "buildingsEnabled", "value": {}},
+                ]},
+            ],
+            "cameraExport": {"logarithmic": False, "modelVersion": 2},
+        }],
+        "playbackManager": {"range": {"start": 0, "end": frames}},
+    }
+
+
+def _inject(template: dict, pos, rotb, frames, fps, width, height, name):
+    esp = copy.deepcopy(template)
+    hit = {"pos": False, "rot": False}
+
+    def walk(o):
+        if isinstance(o, dict):
+            if o.get("type") == "cameraPositionGroup":
+                o["attributes"] = pos
+                hit["pos"] = True
+            elif o.get("type") == "cameraRotationGroup":
+                o["attributes"] = rotb
+                hit["rot"] = True
+            elif o.get("type") == "cameraTargetEffect":
+                for a in o.get("attributes", []):          # make sure target is OFF
+                    if a.get("type") == "enabled":
+                        a["value"] = {}
+                        a.pop("keyframes", None)
+            for v in o.values():
+                walk(v)
+        elif isinstance(o, list):
+            for v in o:
+                walk(v)
+
+    walk(esp)
+    if not (hit["pos"] and hit["rot"]):
+        raise ValueError("template has no cameraPositionGroup/cameraRotationGroup")
+    esp.setdefault("settings", {}).update(name=name, frameRate=fps, duration=frames, timeFormat="frames",
+                                          dimensions={"width": width, "height": height})
+    for sc in esp.get("scenes", []):
+        sc["duration"] = frames
+    esp["playbackManager"] = {"range": {"start": 0, "end": frames}}
+    return esp
+
+
+def build_esp(plan, template: Optional[dict] = None, part: Optional[int] = None) -> dict:
+    """Project dict for the whole plan, or for one part (see Settings.max_part_seconds)."""
+    st = plan.settings
+    parts = plan.parts()
+    a, b = parts[part or 0] if part is not None or len(parts) == 1 else (0.0, plan.frames / st.fps)
+    t, cam, rot, _ = plan.keyframes(a, b)
+    frames = int(round((b - a) * st.fps))
+    pos, rotb = encode_tracks(t, cam, rot, frames / st.fps)
+    name = st.title if len(parts) == 1 or part is None else f"{st.title} part {part + 1}"
+    if template is not None:
+        return _inject(template, pos, rotb, frames, st.fps, st.width, st.height, name)
+    return _template(name, st.fps, st.width, st.height, frames, pos, rotb)
+
+
+def write_esp(plan, path, template_path: Optional[str] = None):
+    """Write path (or path_part01.esp, ... when the plan is split). Returns list of files."""
+    import os
+    tpl = None
+    if template_path:
+        with open(template_path) as f:
+            tpl = json.load(f)
+    parts = plan.parts()
+    if len(parts) == 1:
+        with open(path, "w") as f:
+            json.dump(build_esp(plan, tpl, 0), f, separators=(",", ":"))
+        return [path]
+    base, ext = os.path.splitext(path)
+    out = []
+    for k in range(len(parts)):
+        p = f"{base}_part{k + 1:02d}{ext or '.esp'}"
+        with open(p, "w") as f:
+            json.dump(build_esp(plan, tpl, k), f, separators=(",", ":"))
+        out.append(p)
+    return out

cinematicearth/geo.py

@@ -0,0 +1,130 @@
+"""Geodesy helpers: spherical-earth great circles, ENU frames, LookAt <-> camera."""
+from __future__ import annotations
+
+import math
+from typing import Tuple
+
+R_E = 6_371_000.0
+rad, deg = math.radians, math.degrees
+
+
+def wrap180(a: float) -> float:
+    return (a + 180.0) % 360.0 - 180.0
+
+
+def unwrap_to(a: float, ref: float) -> float:
+    """Return angle equal to `a` (mod 360) closest to `ref` (continuous headings)."""
+    return ref + wrap180(a - ref)
+
+
+def haversine(lat1, lon1, lat2, lon2) -> float:
+    p1, p2 = rad(lat1), rad(lat2)
+    dp, dl = p2 - p1, rad(lon2 - lon1)
+    h = math.sin(dp / 2) ** 2 + math.cos(p1) * math.cos(p2) * math.sin(dl / 2) ** 2
+    return 2 * R_E * math.asin(min(1.0, math.sqrt(h)))
+
+
+def bearing(lat1, lon1, lat2, lon2) -> float:
+    p1, p2, dl = rad(lat1), rad(lat2), rad(lon2 - lon1)
+    y = math.sin(dl) * math.cos(p2)
+    x = math.cos(p1) * math.sin(p2) - math.sin(p1) * math.cos(p2) * math.cos(dl)
+    return deg(math.atan2(y, x)) % 360.0
+
+
+def destination(lat, lon, brg, dist) -> Tuple[float, float]:
+    p1, l1, b, d = rad(lat), rad(lon), rad(brg), dist / R_E
+    p2 = math.asin(math.sin(p1) * math.cos(d) + math.cos(p1) * math.sin(d) * math.cos(b))
+    l2 = l1 + math.atan2(math.sin(b) * math.sin(d) * math.cos(p1),
+                         math.cos(d) - math.sin(p1) * math.sin(p2))
+    return deg(p2), wrap180(deg(l2))
+
+
+def gc_interp(lat1, lon1, lat2, lon2, f) -> Tuple[float, float]:
+    """Point at fraction f along the great circle."""
+    p1, l1, p2, l2 = rad(lat1), rad(lon1), rad(lat2), rad(lon2)
+    d = haversine(lat1, lon1, lat2, lon2) / R_E
+    if d < 1e-12:
+        return lat1, lon1
+    a = math.sin((1 - f) * d) / math.sin(d)
+    b = math.sin(f * d) / math.sin(d)
+    x = a * math.cos(p1) * math.cos(l1) + b * math.cos(p2) * math.cos(l2)
+    y = a * math.cos(p1) * math.sin(l1) + b * math.cos(p2) * math.sin(l2)
+    z = a * math.sin(p1) + b * math.sin(p2)
+    return deg(math.atan2(z, math.hypot(x, y))), deg(math.atan2(y, x))
+
+
+def gc_crosses_antimeridian(lat1, lon1, lat2, lon2, n=64) -> bool:
+    prev = lon1
+    for k in range(1, n + 1):
+        _, lo = gc_interp(lat1, lon1, lat2, lon2, k / n)
+        if abs(lo - prev) > 180:
+            return True
+        prev = lo
+    return False
+
+
+# ---------- ECEF / ENU (spherical) ----------
+def ecef(lat, lon, alt):
+    r = R_E + alt
+    p, l = rad(lat), rad(lon)
+    return (r * math.cos(p) * math.cos(l), r * math.cos(p) * math.sin(l), r * math.sin(p))
+
+
+def enu_basis(lat, lon):
+    p, l = rad(lat), rad(lon)
+    e = (-math.sin(l), math.cos(l), 0.0)
+    n = (-math.sin(p) * math.cos(l), -math.sin(p) * math.sin(l), math.cos(p))
+    u = (math.cos(p) * math.cos(l), math.cos(p) * math.sin(l), math.sin(p))
+    return e, n, u
+
+
+def _dot(a, b):
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
+
+
+def look_rotation(cam_lat, cam_lon, cam_alt, tgt_lat, tgt_lon, tgt_alt) -> Tuple[float, float]:
+    """Exact (heading, tilt) for a camera at cam_* to centre the target point.
+
+    heading: compass degrees (0 = north, clockwise). tilt: 0 = straight down, 90 = horizon.
+    """
+    c = ecef(cam_lat, cam_lon, cam_alt)
+    t = ecef(tgt_lat, tgt_lon, tgt_alt)
+    v = (t[0] - c[0], t[1] - c[1], t[2] - c[2])
+    e, n, u = enu_basis(cam_lat, cam_lon)
+    ve, vn, vu = _dot(v, e), _dot(v, n), _dot(v, u)
+    horiz = math.hypot(ve, vn)
+    if horiz < 1e-4 * math.sqrt(ve * ve + vn * vn + vu * vu):   # looking straight down
+        return None, deg(math.atan2(horiz, -vu))
+    heading = deg(math.atan2(ve, vn)) % 360.0
+    tilt = deg(math.atan2(horiz, -vu))
+    return heading, tilt
+
+
+def lookat_to_camera(lat, lon, elev, rng, tilt, heading):
+    """LookAt (target + range/tilt/heading) -> camera lat, lon, alt (spherical earth).
+
+    Solves the triangle earth-centre / target / camera so it stays valid from
+    street level to orbit.
+    """
+    rt = R_E + elev
+    tr = rad(tilt)
+    # camera = target + rng * (sin(tilt) * back-horizontal + cos(tilt) * up), in target ENU
+    back = rad(heading + 180.0)
+    e, n, u = enu_basis(lat, lon)
+    t = ecef(lat, lon, elev)
+    h = rng * math.sin(tr)
+    vu = rng * math.cos(tr)
+    ve, vn = h * math.sin(back), h * math.cos(back)
+    c = tuple(t[i] + ve * e[i] + vn * n[i] + vu * u[i] for i in range(3))
+    r = math.sqrt(_dot(c, c))
+    clat = deg(math.asin(c[2] / r))
+    clon = deg(math.atan2(c[1], c[0]))
+    return clat, clon, r - R_E
+
+
+def enu_offset(lat, lon, de, dn):
+    """Small local offset (metres east/north) -> lat, lon."""
+    dist = math.hypot(de, dn)
+    if dist == 0:
+        return lat, lon
+    return destination(lat, lon, deg(math.atan2(de, dn)), dist)

cinematicearth/geocode.py

@@ -0,0 +1,82 @@
+"""Optional network helpers: place-name geocoding (Nominatim) and ground elevation
+(Open-Meteo). Standard library only; results cached in ~/.cache/cinematicearth."""
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.parse
+import urllib.request
+from typing import Optional, Tuple
+
+_CACHE = os.path.join(os.path.expanduser("~"), ".cache", "cinematicearth", "geo.json")
+_UA = "CinematicEarth (https://github.com/MayerT1/CinematicEarth)"
+
+
+def _load():
+    try:
+        with open(_CACHE) as f:
+            return json.load(f)
+    except Exception:
+        return {}
+
+
+def _save(c):
+    try:
+        os.makedirs(os.path.dirname(_CACHE), exist_ok=True)
+        with open(_CACHE, "w") as f:
+            json.dump(c, f)
+    except Exception:
+        pass
+
+
+def _get(url):
+    req = urllib.request.Request(url, headers={"User-Agent": _UA})
+    with urllib.request.urlopen(req, timeout=20) as r:
+        return json.loads(r.read().decode())
+
+
+def geocode(name: str) -> Optional[Tuple[float, float]]:
+    c = _load()
+    key = "g:" + name.lower().strip()
+    if key in c:
+        return tuple(c[key]) if c[key] else None
+    q = urllib.parse.urlencode({"q": name, "format": "json", "limit": 1})
+    res = _get(f"https://nominatim.openstreetmap.org/search?{q}")
+    time.sleep(1.0)    # Nominatim usage policy: max 1 request / second
+    val = (float(res[0]["lat"]), float(res[0]["lon"])) if res else None
+    c[key] = val
+    _save(c)
+    return val
+
+
+def elevation(lat: float, lon: float) -> Optional[float]:
+    c = _load()
+    key = f"e:{lat:.4f},{lon:.4f}"
+    if key in c:
+        return c[key]
+    try:
+        res = _get(f"https://api.open-meteo.com/v1/elevation?latitude={lat}&longitude={lon}")
+        val = float(res["elevation"][0])
+    except Exception:
+        return None
+    c[key] = val
+    _save(c)
+    return val
+
+
+def resolve(stops, need_coords=True, need_elev=True, verbose=True):
+    """Fill missing lat/lon (geocode) and elev (elevation API) in place."""
+    for s in stops:
+        if need_coords and (s.lat is None or s.lon is None):
+            r = geocode(s.name)
+            if r is None:
+                raise ValueError(f"could not geocode {s.name!r}; add lat/lon")
+            s.lat, s.lon = r
+            if verbose:
+                print(f"geocoded {s.name}: {s.lat:.4f}, {s.lon:.4f}")
+        if need_elev and s.elev is None:
+            s.elev = elevation(s.lat, s.lon)
+            if verbose and s.elev is not None:
+                print(f"elevation {s.name}: {s.elev:.0f} m")
+    return stops