dopplertrack 0.1.0__py3-none-any.whl

dopplertrack/__init__.py

@@ -0,0 +1,2 @@
+def hello() -> str:
+    return "Hello from dopplertrack!"

dopplertrack/adsb.py

@@ -0,0 +1,161 @@
+"""Read adsb.lol / readsb `globe_history` daily archives and classify aircraft."""
+from __future__ import annotations
+
+import csv
+import gzip
+import io
+import json
+import os
+from concurrent.futures import ProcessPoolExecutor
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import requests
+
+from .geo import lla_to_enu
+
+FT = 0.3048
+KT = 0.514444
+_DOC8643_URL = "https://opensky-network.org/datasets/metadata/doc8643AircraftTypes.csv"
+
+
+def _cache_dir() -> Path:
+    p = Path(os.environ.get("DOPPLERTRACK_CACHE", Path.home() / ".cache" / "dopplertrack"))
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+class AircraftTypes:
+    """ICAO Doc 8643 designator -> engine class ('Piston', 'Turboprop', 'Jet', ...)."""
+
+    def __init__(self, path: str | Path | None = None):
+        p = Path(path) if path else _cache_dir() / "doc8643AircraftTypes.csv"
+        if not p.exists():
+            p.write_bytes(requests.get(_DOC8643_URL, timeout=120).content)
+        self.types: dict[str, dict] = {}
+        with open(p, newline="", encoding="utf-8") as fh:
+            for row in csv.DictReader(fh):
+                self.types.setdefault(row["Designator"], row)
+
+    def engine(self, designator: str | None) -> str | None:
+        r = self.types.get(designator or "")
+        return r["EngineType"] if r else None
+
+    def is_prop(self, designator: str | None, unknown_ok: bool = True) -> bool:
+        e = self.engine(designator)
+        if e is None:
+            return unknown_ok
+        return any(k in e for k in ("Piston", "Turboprop", "Electric"))
+
+
+@dataclass
+class Trace:
+    icao: str
+    reg: str | None
+    typ: str | None
+    desc: str | None
+    t: np.ndarray        # unix seconds
+    lat: np.ndarray
+    lon: np.ndarray
+    alt: np.ndarray      # metres MSL (geometric when available, else barometric)
+    gs: np.ndarray       # m/s (nan if missing)
+    on_ground: np.ndarray
+
+    def __len__(self):
+        return len(self.t)
+
+    def segments(self, max_gap_s: float = 90.0) -> list[slice]:
+        """Index slices of contiguous airborne data."""
+        out = []
+        if len(self.t) == 0:
+            return out
+        brk = np.where((np.diff(self.t) > max_gap_s) | (self.on_ground[1:] != self.on_ground[:-1]))[0] + 1
+        starts = np.r_[0, brk]; ends = np.r_[brk, len(self.t)]
+        for s, e in zip(starts, ends):
+            if e - s >= 2 and not self.on_ground[s]:
+                out.append(slice(s, e))
+        return out
+
+    def resample(self, sl: slice, dt: float = 1.0):
+        """Uniformly resampled (t, lat, lon, alt) over one segment."""
+        t = self.t[sl]
+        tq = np.arange(t[0], t[-1], dt)
+        return (tq, np.interp(tq, t, self.lat[sl]), np.interp(tq, t, self.lon[sl]), np.interp(tq, t, self.alt[sl]))
+
+    def enu(self, sl: slice, lat0: float, lon0: float, dt: float = 1.0):
+        tq, la, lo, al = self.resample(sl, dt)
+        return tq, lla_to_enu(la, lo, al, lat0, lon0)
+
+
+def parse_trace_file(path: str | Path) -> Trace | None:
+    raw = Path(path).read_bytes()
+    if raw[:2] == b"\x1f\x8b":
+        raw = gzip.decompress(raw)
+    d = json.loads(raw)
+    base = float(d.get("timestamp", 0.0))
+    rows = d.get("trace") or []
+    t, lat, lon, alt, gs, grd = [], [], [], [], [], []
+    for r in rows:
+        if r[1] is None or r[2] is None:
+            continue
+        a = r[3]
+        on_ground = a == "ground"
+        geom = r[10] if len(r) > 10 else None
+        if isinstance(geom, (int, float)):
+            am = geom * FT
+        elif isinstance(a, (int, float)):
+            am = a * FT
+        elif on_ground:
+            am = np.nan
+        else:
+            continue
+        t.append(base + r[0]); lat.append(r[1]); lon.append(r[2]); alt.append(am)
+        gs.append(r[4] * KT if isinstance(r[4], (int, float)) else np.nan); grd.append(on_ground)
+    if not t:
+        return None
+    return Trace(d.get("icao", Path(path).stem.split("_")[-1]), d.get("r"), d.get("t"), d.get("desc"),
+                 np.array(t), np.array(lat), np.array(lon), np.array(alt), np.array(gs), np.array(grd))
+
+
+def _scan_one(args):
+    path, bbox = args
+    try:
+        tr = parse_trace_file(path)
+    except Exception:
+        return None
+    if tr is None:
+        return None
+    lat0, lat1, lon0, lon1 = bbox
+    m = (tr.lat >= lat0) & (tr.lat <= lat1) & (tr.lon >= lon0) & (tr.lon <= lon1)
+    if not m.any():
+        return None
+    return tr
+
+
+def load_region(archive_dir: str | Path, bbox: tuple[float, float, float, float],
+                workers: int | None = None) -> list[Trace]:
+    """All traces with at least one point inside bbox=(lat_min, lat_max, lon_min, lon_max)."""
+    files = sorted(Path(archive_dir).glob("traces/*/trace_full_*.json"))
+    out = []
+    with ProcessPoolExecutor(workers or os.cpu_count()) as ex:
+        for tr in ex.map(_scan_one, ((str(f), bbox) for f in files), chunksize=256):
+            if tr is not None:
+                out.append(tr)
+    return out
+
+
+def save_traces(traces: list[Trace], path: str | Path):
+    np.savez_compressed(path, n=len(traces),
+                        meta=np.array([json.dumps([t.icao, t.reg, t.typ, t.desc]) for t in traces]),
+                        **{f"a{i}": np.stack([t.t, t.lat, t.lon, t.alt, t.gs, t.on_ground.astype(float)]) for i, t in enumerate(traces)})
+
+
+def load_traces(path: str | Path) -> list[Trace]:
+    z = np.load(path, allow_pickle=False)
+    out = []
+    for i in range(int(z["n"])):
+        icao, reg, typ, desc = json.loads(str(z["meta"][i]))
+        a = z[f"a{i}"]
+        out.append(Trace(icao, reg, typ, desc, a[0], a[1], a[2], a[3], a[4], a[5].astype(bool)))
+    return out

dopplertrack/audio.py

@@ -0,0 +1,101 @@
+"""Audio decoding and whitened low-band spectrograms."""
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import scipy.signal as ss
+
+
+def load_audio(path: str | Path, sr: int = 4000) -> tuple[np.ndarray, int]:
+    """Decode any ffmpeg-readable file to mono float32 at `sr` Hz."""
+    cmd = ["ffmpeg", "-v", "error", "-i", str(path), "-ac", "1", "-ar", str(sr),
+           "-f", "f32le", "-acodec", "pcm_f32le", "-"]
+    raw = subprocess.run(cmd, check=True, capture_output=True).stdout
+    return np.frombuffer(raw, dtype=np.float32).copy(), sr
+
+
+@dataclass
+class Spectrogram:
+    t: np.ndarray      # (T,) centre time of each frame, s
+    f: np.ndarray      # (F,) bin frequencies, Hz
+    S: np.ndarray      # (F, T) whitened power, dB above per-bin median
+
+    @property
+    def dt(self) -> float:
+        return float(self.t[1] - self.t[0])
+
+    @property
+    def df(self) -> float:
+        return float(self.f[1] - self.f[0])
+
+    def sample(self, t, f, fill=0.0):
+        """Bilinear sample at (t, f) pairs (arrays); outside the grid -> fill."""
+        t = np.asarray(t, float); f = np.asarray(f, float)
+        ti = (t - self.t[0]) / self.dt
+        fi = (f - self.f[0]) / self.df
+        ok = (ti >= 0) & (ti <= len(self.t) - 1) & (fi >= 0) & (fi <= len(self.f) - 1) & np.isfinite(ti) & np.isfinite(fi)
+        out = np.full(t.shape, fill, float)
+        ti = ti[ok]; fi = fi[ok]
+        i0 = np.floor(ti).astype(int); j0 = np.floor(fi).astype(int)
+        i1 = np.minimum(i0 + 1, len(self.t) - 1); j1 = np.minimum(j0 + 1, len(self.f) - 1)
+        wt = ti - i0; wf = fi - j0
+        v = (self.S[j0, i0] * (1 - wt) * (1 - wf) + self.S[j0, i1] * wt * (1 - wf)
+             + self.S[j1, i0] * (1 - wt) * wf + self.S[j1, i1] * wt * wf)
+        out[ok] = v
+        return out
+
+    def crop(self, t0, t1, f0=None, f1=None) -> "Spectrogram":
+        m = (self.t >= t0) & (self.t <= t1)
+        fm = np.ones_like(self.f, bool)
+        if f0 is not None: fm &= self.f >= f0
+        if f1 is not None: fm &= self.f <= f1
+        return Spectrogram(self.t[m], self.f[fm], self.S[np.ix_(fm, m)])
+
+    def save(self, path):
+        np.savez_compressed(path, t=self.t, f=self.f, S=self.S.astype(np.float32))
+
+    @classmethod
+    def load(cls, path) -> "Spectrogram":
+        z = np.load(path)
+        return cls(z["t"], z["f"], z["S"])
+
+
+def compute_spectrogram(x: np.ndarray, sr: int, nperseg: int = 8192, hop_s: float = 0.25,
+                        fmin: float = 40.0, fmax: float = 450.0,
+                        whiten_window_s: float | None = 600.0) -> Spectrogram:
+    """High-resolution STFT in the low band, converted to dB and whitened.
+
+    Whitening subtracts, per frequency bin, the running median over
+    `whiten_window_s` (or the global median if None). This flattens mains
+    hum and stationary machinery so only *changing* tones stand out.
+    """
+    hop = max(1, int(round(hop_s * sr)))
+    f, t, Z = ss.stft(x, sr, nperseg=nperseg, noverlap=nperseg - hop, window="hann",
+                      boundary=None, padded=False)
+    band = (f >= fmin) & (f <= fmax)
+    L = 10 * np.log10(np.abs(Z[band]) ** 2 + 1e-20)
+    f = f[band]
+    if whiten_window_s is None:
+        L = L - np.median(L, axis=1, keepdims=True)
+    else:
+        w = int(whiten_window_s / (hop / sr))
+        if w >= L.shape[1]:
+            L = L - np.median(L, axis=1, keepdims=True)
+        else:
+            # block-wise running median (cheap, adequate for slow drifts)
+            nb = int(np.ceil(L.shape[1] / w))
+            med = np.zeros_like(L)
+            centers = []
+            for b in range(nb):
+                sl = slice(b * w, min((b + 1) * w, L.shape[1]))
+                med[:, sl] = np.median(L[:, sl], axis=1, keepdims=True)
+                centers.append((sl.start + sl.stop) / 2)
+            # linearly blend block medians to avoid seams
+            cm = np.array([np.median(L[:, b * w:min((b + 1) * w, L.shape[1])], axis=1) for b in range(nb)])  # (nb, F)
+            idx = np.arange(L.shape[1])
+            med = np.stack([np.interp(idx, centers, cm[:, k]) for k in range(L.shape[0])])
+            L = L - med
+    return Spectrogram(t, f, L.astype(np.float32))

dopplertrack/cli.py

@@ -0,0 +1,99 @@
+"""dopplertrack command line."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+import numpy as np
+
+from . import pipeline
+from .adsb import load_traces
+from .audio import Spectrogram
+from .search import Grid
+from .terrain import Terrain
+from .tracks import EventFit
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="dopplertrack")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("spectrogram", help="audio/video file -> whitened low-band spectrogram (.npz)")
+    s.add_argument("audio"); s.add_argument("out"); s.add_argument("--hop", type=float, default=0.25)
+    s.add_argument("--fmin", type=float, default=40); s.add_argument("--fmax", type=float, default=450)
+
+    f = sub.add_parser("fit", help="fit an ideal Doppler curve inside a time/frequency window")
+    f.add_argument("spec"); f.add_argument("--window", nargs=2, type=float, required=True, metavar=("T0", "T1"))
+    f.add_argument("--band", nargs=2, type=float, required=True, metavar=("FLO", "FHI"))
+    f.add_argument("--harmonics", type=int, default=1); f.add_argument("--out")
+
+    e = sub.add_parser("extract-region", help="pull traces touching a bbox out of an adsb.lol day archive")
+    e.add_argument("archive_dir"); e.add_argument("out")
+    e.add_argument("--bbox", nargs=4, type=float, required=True, metavar=("LATMIN", "LATMAX", "LONMIN", "LONMAX"))
+    e.add_argument("--keep-jets", action="store_true")
+
+    r = sub.add_parser("search", help="rank candidate locations for a two-event recording")
+    r.add_argument("spec"); r.add_argument("--events", nargs=2, required=True, metavar=("EV1_JSON", "EV2_JSON"))
+    r.add_argument("--traces", required=True); r.add_argument("--out", required=True)
+    r.add_argument("--bbox", nargs=4, type=float, metavar=("LATMIN", "LATMAX", "LONMIN", "LONMAX"))
+    r.add_argument("--point", nargs=2, type=float, metavar=("LAT", "LON"), help="score a single known point instead of a grid")
+    r.add_argument("--spacing", type=float, default=200.0); r.add_argument("--harmonics", nargs=2, type=int, default=(1, 1))
+    r.add_argument("--no-dem", action="store_true"); r.add_argument("--no-silence", action="store_true")
+    r.add_argument("--tol", type=float, default=6.0)
+
+    g = sub.add_parser("search-single", help="rank locations for ONE event whose absolute time is known")
+    g.add_argument("spec"); g.add_argument("--event", required=True); g.add_argument("--traces", required=True)
+    g.add_argument("--utc", required=True, help="heard CPA time of the event, unix seconds or ISO-8601 UTC")
+    g.add_argument("--tol", type=float, default=30.0); g.add_argument("--out", required=True)
+    g.add_argument("--bbox", nargs=4, type=float, required=True, metavar=("LATMIN", "LATMAX", "LONMIN", "LONMAX"))
+    g.add_argument("--spacing", type=float, default=200.0); g.add_argument("--harmonics", type=int, default=1)
+    g.add_argument("--no-dem", action="store_true")
+
+    a = ap.parse_args(argv)
+    if a.cmd == "spectrogram":
+        sp = pipeline.make_spectrogram(a.audio, a.out, hop_s=a.hop, fmin=a.fmin, fmax=a.fmax)
+        print(f"wrote {a.out}: {sp.S.shape[0]} bins x {sp.S.shape[1]} frames")
+    elif a.cmd == "fit":
+        sp = Spectrogram.load(a.spec)
+        ef = pipeline.fit_event(sp, a.window[0], a.window[1], a.band[0], a.band[1], harmonics=a.harmonics)
+        js = json.dumps(ef.to_dict(), indent=1)
+        print(js)
+        if a.out:
+            open(a.out, "w").write(js)
+    elif a.cmd == "extract-region":
+        pipeline.extract_region(a.archive_dir, tuple(a.bbox), a.out, prop_only=not a.keep_jets)
+    elif a.cmd == "search":
+        sp = Spectrogram.load(a.spec)
+        ev1, ev2 = (EventFit(**json.load(open(p))) for p in a.events)
+        traces = load_traces(a.traces)
+        elev = None if a.no_dem else Terrain().elevation
+        if a.point:
+            el = elev(np.array([a.point[0]]), np.array([a.point[1]])) if elev else np.zeros(1)
+            grid = Grid.points([a.point[0]], [a.point[1]], el)
+        else:
+            grid = Grid.make(*a.bbox, a.spacing, elev)
+        res, segs = pipeline.run_search(sp, ev1, ev2, traces, grid, harmonics=tuple(a.harmonics),
+                                        silence_d_m=None if a.no_silence else 6000.0, tol_s=a.tol)
+        res["lat0"] = grid.lat0; res["lon0"] = grid.lon0
+        res.to_csv(a.out, index=False)
+        print(res.head(20).to_string())
+    elif a.cmd == "search-single":
+        from datetime import datetime, timezone
+        sp = Spectrogram.load(a.spec)
+        ev = EventFit(**json.load(open(a.event)))
+        traces = load_traces(a.traces)
+        try:
+            t_unix = float(a.utc)
+        except ValueError:
+            t_unix = datetime.fromisoformat(a.utc.replace("Z", "+00:00")).astimezone(timezone.utc).timestamp()
+        elev = None if a.no_dem else Terrain().elevation
+        grid = Grid.make(*a.bbox, a.spacing, elev)
+        res, segs = pipeline.run_single_search(sp, ev, traces, grid, t_unix, tol_s=a.tol, harmonics=a.harmonics)
+        res["lat0"] = grid.lat0; res["lon0"] = grid.lon0
+        res.to_csv(a.out, index=False)
+        print(res.head(20).to_string())
+
+
+if __name__ == "__main__":
+    main()

dopplertrack/doppler.py

@@ -0,0 +1,72 @@
+"""Doppler curve physics.
+
+All functions use *emission-time* kinematics: the frequency heard at
+observation time t_obs was produced at emission time t_e where
+t_obs = t_e + r(t_e)/c, and the shift is set by the range rate at t_e.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+def speed_of_sound(temp_c: float = 15.0) -> float:
+    return 331.3 * np.sqrt(1.0 + temp_c / 273.15)
+
+
+def observed_frequency(f0, range_rate, c):
+    """Frequency heard for a source of rest frequency f0 with range rate dr/dt
+    (positive = receding)."""
+    return f0 * c / (c + range_rate)
+
+
+def ideal_curve(t_obs, f0, v, d_cpa, t_cpa, c=None, span=600.0, n=4001):
+    """Frequency heard at times t_obs for a straight, constant-speed pass.
+
+    v: speed (m/s); d_cpa: slant distance at closest approach (m);
+    t_cpa: *emission* time of closest approach.
+    """
+    c = speed_of_sound() if c is None else c
+    te = t_cpa + np.linspace(-span, span, n)
+    r = np.sqrt(d_cpa**2 + (v * (te - t_cpa)) ** 2)
+    rr = v * v * (te - t_cpa) / r
+    f = observed_frequency(f0, rr, c)
+    tobs = te + r / c
+    return np.interp(np.asarray(t_obs, float), tobs, f, left=np.nan, right=np.nan)
+
+
+def ideal_curve_params_from_endpoints(f_pre, f_post, c=None):
+    """Recover (f0, v) from the approach and recede asymptote frequencies."""
+    c = speed_of_sound() if c is None else c
+    # f_pre = f0 c/(c-v), f_post = f0 c/(c+v)
+    v = c * (f_pre - f_post) / (f_pre + f_post)
+    f0 = f_pre * (c - v) / c
+    return f0, v
+
+
+def curve_from_trajectory(t_e, pos_enu, obs_enu, f0=1.0, c=None):
+    """Doppler curve a stationary observer hears from a sampled trajectory.
+
+    t_e: (N,) emission times (s); pos_enu: (N,3) source positions (m);
+    obs_enu: (3,) observer position (m). Returns (t_obs, f, r) with f for
+    rest frequency f0 (use f0=1 to get the ratio).
+    """
+    c = speed_of_sound() if c is None else c
+    t_e = np.asarray(t_e, float)
+    d = np.asarray(pos_enu, float) - np.asarray(obs_enu, float)
+    r = np.linalg.norm(d, axis=-1)
+    rr = np.gradient(r, t_e)
+    f = observed_frequency(f0, rr, c)
+    t_obs = t_e + r / c
+    return t_obs, f, r
+
+
+def cpa_from_trajectory(t_e, pos_enu, obs_enu, c=None):
+    """Closest point of approach: (t_cpa_emission, t_cpa_heard, slant_m, speed_mps)."""
+    c = speed_of_sound() if c is None else c
+    t_e = np.asarray(t_e, float)
+    d = np.asarray(pos_enu, float) - np.asarray(obs_enu, float)
+    r = np.linalg.norm(d, axis=-1)
+    i = int(np.argmin(r))
+    vel = np.gradient(np.asarray(pos_enu, float), t_e, axis=0)
+    speed = float(np.linalg.norm(vel[i]))
+    return float(t_e[i]), float(t_e[i] + r[i] / c), float(r[i]), speed

dopplertrack/geo.py

@@ -0,0 +1,59 @@
+"""Geodesy helpers: WGS-84 <-> ECEF <-> local East-North-Up (ENU)."""
+from __future__ import annotations
+
+import numpy as np
+
+_A = 6378137.0
+_F = 1 / 298.257223563
+_E2 = _F * (2 - _F)
+
+
+def lla_to_ecef(lat_deg, lon_deg, alt_m):
+    lat = np.radians(lat_deg)
+    lon = np.radians(lon_deg)
+    s, c = np.sin(lat), np.cos(lat)
+    n = _A / np.sqrt(1 - _E2 * s * s)
+    x = (n + alt_m) * c * np.cos(lon)
+    y = (n + alt_m) * c * np.sin(lon)
+    z = (n * (1 - _E2) + alt_m) * s
+    return np.stack([x, y, z], axis=-1)
+
+
+def enu_rotation(lat0_deg, lon0_deg):
+    lat, lon = np.radians(lat0_deg), np.radians(lon0_deg)
+    sl, cl = np.sin(lat), np.cos(lat)
+    so, co = np.sin(lon), np.cos(lon)
+    return np.array([
+        [-so, co, 0.0],
+        [-sl * co, -sl * so, cl],
+        [cl * co, cl * so, sl],
+    ])
+
+
+def lla_to_enu(lat_deg, lon_deg, alt_m, lat0_deg, lon0_deg, alt0_m=0.0):
+    """Convert points to ENU metres relative to the origin. Broadcasts."""
+    p = lla_to_ecef(np.asarray(lat_deg, float), np.asarray(lon_deg, float), np.asarray(alt_m, float))
+    o = lla_to_ecef(lat0_deg, lon0_deg, alt0_m)
+    return (p - o) @ enu_rotation(lat0_deg, lon0_deg).T
+
+
+def enu_to_lla(e, n, u, lat0_deg, lon0_deg, alt0_m=0.0):
+    r = enu_rotation(lat0_deg, lon0_deg)
+    o = lla_to_ecef(lat0_deg, lon0_deg, alt0_m)
+    xyz = np.stack([np.asarray(e, float), np.asarray(n, float), np.asarray(u, float)], -1) @ r + o
+    x, y, z = xyz[..., 0], xyz[..., 1], xyz[..., 2]
+    lon = np.arctan2(y, x)
+    p = np.hypot(x, y)
+    lat = np.arctan2(z, p * (1 - _E2))
+    for _ in range(5):
+        s = np.sin(lat)
+        nn = _A / np.sqrt(1 - _E2 * s * s)
+        alt = p / np.cos(lat) - nn
+        lat = np.arctan2(z, p * (1 - _E2 * nn / (nn + alt)))
+    return np.degrees(lat), np.degrees(lon), alt
+
+
+def haversine_m(lat1, lon1, lat2, lon2):
+    lat1, lon1, lat2, lon2 = map(np.radians, (lat1, lon1, lat2, lon2))
+    a = np.sin((lat2 - lat1) / 2) ** 2 + np.cos(lat1) * np.cos(lat2) * np.sin((lon2 - lon1) / 2) ** 2
+    return 2 * 6371000.0 * np.arcsin(np.sqrt(a))

dopplertrack/pipeline.py

@@ -0,0 +1,114 @@
+"""High-level pipeline steps that the CLI and notebooks share."""
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from .adsb import AircraftTypes, Trace, load_region, load_traces, save_traces
+from .audio import Spectrogram, compute_spectrogram, load_audio
+from .doppler import speed_of_sound
+from .score import EventWindow, locked_score
+from .search import Grid, Segment, build_segments, cpa_table, pair_candidates
+from .terrain import Terrain
+from .tracks import EventFit, fit_event
+
+
+def log(msg):
+    print(f"[{time.strftime('%H:%M:%S')}] {msg}", flush=True)
+
+
+def make_spectrogram(audio_path, out_path, hop_s=0.25, fmin=40, fmax=450, nperseg=8192, whiten_window_s=600):
+    x, sr = load_audio(audio_path)
+    sp = compute_spectrogram(x, sr, nperseg=nperseg, hop_s=hop_s, fmin=fmin, fmax=fmax, whiten_window_s=whiten_window_s)
+    sp.save(out_path)
+    return sp
+
+
+def extract_region(archive_dir, bbox, out_path, prop_only=True, workers=None) -> list[Trace]:
+    log(f"scanning {archive_dir} for traces in {bbox}")
+    traces = load_region(archive_dir, bbox, workers=workers)
+    log(f"{len(traces)} traces touch the region")
+    if prop_only:
+        types = AircraftTypes()
+        traces = [t for t in traces if types.is_prop(t.typ)]
+        log(f"{len(traces)} after dropping known jets")
+    save_traces(traces, out_path)
+    return traces
+
+
+def run_search(sp: Spectrogram, ev1: EventFit, ev2: EventFit, traces: list[Trace], grid: Grid,
+               harmonics=(1, 1), tol_s=6.0, v_tol=0.35, d_tol=(0.4, 2.5), silence_d_m=6000.0,
+               max_range_m=12000.0, c=None, top_pairs=None, progress=True) -> tuple[pd.DataFrame, list[Segment]]:
+    c = speed_of_sound() if c is None else c
+    e0, e1 = grid.enu[:, 0].min() - max_range_m, grid.enu[:, 0].max() + max_range_m
+    n0, n1 = grid.enu[:, 1].min() - max_range_m, grid.enu[:, 1].max() + max_range_m
+    segs = build_segments(traces, grid.lat0, grid.lon0, clip_enu=(e0, e1, n0, n1))
+    log(f"{len(segs)} airborne segments; grid of {len(grid)} points")
+    cpa = cpa_table(grid, segs, max_range_m=max_range_m, c=c)
+    log(f"{len(cpa)} (point, flight) CPA records")
+    dt = ev2.t_cpa - ev1.t_cpa
+    pairs = pair_candidates(cpa, dt, tol_s=tol_s,
+                            v1=(ev1.v * (1 - v_tol), ev1.v * (1 + v_tol)), d1=(ev1.d * d_tol[0], ev1.d * d_tol[1]),
+                            v2=(ev2.v * (1 - v_tol), ev2.v * (1 + v_tol)), d2=(ev2.d * d_tol[0], ev2.d * d_tol[1]),
+                            silence_d_m=silence_d_m)
+    log(f"{len(pairs)} candidate (point, flight1, flight2) triples after offset + silence filters")
+    w1 = EventWindow.from_fit(sp, ev1, harmonics[0]); w2 = EventWindow.from_fit(sp, ev2, harmonics[1])
+    out = []
+    t0 = time.time()
+    for k, p in enumerate(pairs.itertuples()):
+        tot, s1, s2, sh = locked_score(w1, w2, segs[p.seg1], segs[p.seg2], grid.enu[p.gidx], float(p.t_heard1), c=c)
+        out.append((p.gidx, grid.lat[p.gidx], grid.lon[p.gidx], p.seg1, p.seg2, p.icao1, p.icao2, p.t_heard1, p.d1, p.v1, p.d2, p.v2, tot, s1, s2, sh))
+        if progress and (k + 1) % 500 == 0:
+            log(f"scored {k + 1}/{len(pairs)} ({(time.time() - t0) / (k + 1) * 1000:.0f} ms each)")
+    cols = ["gidx", "lat", "lon", "seg1", "seg2", "icao1", "icao2", "t_heard1", "d1", "v1", "d2", "v2", "score", "s1", "s2", "shift"]
+    res = pd.DataFrame(out, columns=cols).sort_values("score", ascending=False).reset_index(drop=True)
+    return res, segs
+
+
+def refine(sp, ev1, ev2, segs, res_row, spacing_m=50.0, half_m=400.0, harmonics=(1, 1), elevation=None, c=None):
+    """Fine grid around one result row for one flight pair."""
+    c = speed_of_sound() if c is None else c
+    lat, lon = float(res_row.lat), float(res_row.lon)
+    dlat = half_m / 111320.0; dlon = half_m / (111320.0 * np.cos(np.radians(lat)))
+    g = Grid.make(lat - dlat, lat + dlat, lon - dlon, lon + dlon, spacing_m, elevation)
+    # re-express grid in the segments' ENU frame (segments were built on the search grid origin)
+    from .geo import lla_to_enu
+    seg1, seg2 = segs[int(res_row.seg1)], segs[int(res_row.seg2)]
+    w1 = EventWindow.from_fit(sp, ev1, harmonics[0]); w2 = EventWindow.from_fit(sp, ev2, harmonics[1])
+    rows = []
+    for i in range(len(g)):
+        obs = lla_to_enu(g.lat[i], g.lon[i], g.elev[i], res_row.lat0, res_row.lon0)
+        d = np.linalg.norm(seg1.enu - obs, axis=1); j = int(np.argmin(d)); t_heard1 = seg1.t[j] + d[j] / c
+        tot, s1, s2, sh = locked_score(w1, w2, seg1, seg2, obs, float(t_heard1), c=c)
+        rows.append((g.lat[i], g.lon[i], tot, s1, s2, sh))
+    return pd.DataFrame(rows, columns=["lat", "lon", "score", "s1", "s2", "shift"]).sort_values("score", ascending=False).reset_index(drop=True)
+
+
+def run_single_search(sp: Spectrogram, ev: EventFit, traces: list[Trace], grid: Grid, t_cpa_unix: float,
+                      tol_s: float = 30.0, harmonics: int = 1, v_tol=0.35, d_tol=(0.4, 2.5),
+                      max_range_m=12000.0, c=None) -> tuple[pd.DataFrame, list[Segment]]:
+    """One event whose absolute time is known (±tol_s): rank grid points by how well the
+    curve they would hear from each nearby flight matches the spectrogram."""
+    from .score import single_score
+    c = speed_of_sound() if c is None else c
+    e0, e1 = grid.enu[:, 0].min() - max_range_m, grid.enu[:, 0].max() + max_range_m
+    n0, n1 = grid.enu[:, 1].min() - max_range_m, grid.enu[:, 1].max() + max_range_m
+    segs = build_segments(traces, grid.lat0, grid.lon0, clip_enu=(e0, e1, n0, n1))
+    # only segments alive around the event time
+    keep = [s for s in segs if s.t[0] - 300 <= t_cpa_unix <= s.t[-1] + 300]
+    log(f"{len(keep)} of {len(segs)} segments overlap the event time")
+    cpa = cpa_table(grid, keep, max_range_m=max_range_m, c=c)
+    m = cpa[(cpa.t_heard - t_cpa_unix).abs() <= tol_s]
+    m = m[m.v.between(ev.v * (1 - v_tol), ev.v * (1 + v_tol)) & m.d.between(ev.d * d_tol[0], ev.d * d_tol[1])]
+    log(f"{len(m)} candidate (point, flight) pairs")
+    w = EventWindow.from_fit(sp, ev, harmonics)
+    out = []
+    for p in m.itertuples():
+        s = single_score(w, keep[p.seg], grid.enu[p.gidx], float(p.t_heard), c=c)
+        out.append((p.gidx, grid.lat[p.gidx], grid.lon[p.gidx], p.seg, p.icao, p.t_heard, p.d, p.v, s))
+    res = pd.DataFrame(out, columns=["gidx", "lat", "lon", "seg", "icao", "t_heard", "d", "v", "score"]).sort_values("score", ascending=False).reset_index(drop=True)
+    return res, keep

dopplertrack/plots.py

@@ -0,0 +1,61 @@
+"""Diagnostic figures: event fits, modelled curves over the spectrogram, score maps."""
+from __future__ import annotations
+
+import numpy as np
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
+from .audio import Spectrogram
+from .doppler import ideal_curve, speed_of_sound
+from .score import modelled_curve
+from .tracks import EventFit, local_whiten
+
+
+def _show(ax, sp: Spectrogram, vmax=10):
+    ax.imshow(sp.S, origin="lower", aspect="auto", extent=[sp.t[0], sp.t[-1], sp.f[0], sp.f[-1]],
+              vmin=0, vmax=vmax, cmap="magma")
+    ax.set_ylabel("Hz")
+
+
+def plot_event_fit(sp: Spectrogram, fit: EventFit, harmonics=1, pad=30, fmax=None, ax=None):
+    ax = ax or plt.gca()
+    w = local_whiten(sp.crop(fit.t_start - pad, fit.t_end + pad, fit.f_post * 0.7, fmax or fit.f_pre * 1.3 * harmonics))
+    _show(ax, w)
+    tt = np.linspace(w.t[0], w.t[-1], 600)
+    for h in range(1, harmonics + 1):
+        ax.plot(tt, h * ideal_curve(tt, fit.f0, fit.v, fit.d, fit.t_cpa_emit), "c-", lw=0.8)
+    ax.set_title(f"ideal fit: f0={fit.f0:.1f} Hz  v={fit.v:.0f} m/s  d={fit.d:.0f} m  t_cpa={fit.t_cpa:.1f} s")
+    return ax
+
+
+def plot_modelled(sp: Spectrogram, fit: EventFit, seg, obs_enu, t_audio_offset, f0_scale=1.0, harmonics=1,
+                  pad=30, ax=None, c=None, label=None):
+    """Overlay the curve a candidate observer would hear from `seg`. t_audio_offset maps
+    unix time to recording time (t_audio = t_unix + offset)."""
+    c = speed_of_sound() if c is None else c
+    ax = ax or plt.gca()
+    w = local_whiten(sp.crop(fit.t_start - pad, fit.t_end + pad, fit.f_post * 0.7, fit.f_pre * 1.3 * harmonics))
+    _show(ax, w)
+    to, ratio = modelled_curve(seg, obs_enu, c)
+    ta = to + t_audio_offset
+    for h in range(1, harmonics + 1):
+        ax.plot(ta, h * fit.f0 * f0_scale * ratio, "c-", lw=0.9)
+    ax.set_xlim(w.t[0], w.t[-1]); ax.set_ylim(w.f[0], w.f[-1])
+    if label:
+        ax.set_title(label)
+    return ax
+
+
+def plot_score_map(res, truth=None, ax=None, top=None, s=6):
+    """Scatter of candidate scores (best per grid point)."""
+    ax = ax or plt.gca()
+    best = res.sort_values("score", ascending=False).drop_duplicates("gidx")
+    if top:
+        best = best.head(top)
+    sc = ax.scatter(best.lon, best.lat, c=best.score, s=s, cmap="viridis")
+    plt.colorbar(sc, ax=ax, label="combined score")
+    if truth is not None:
+        ax.plot(truth[1], truth[0], "r+", ms=14, mew=2, label="truth"); ax.legend()
+    ax.set_xlabel("lon"); ax.set_ylabel("lat"); ax.set_aspect(1 / np.cos(np.radians(best.lat.mean())))
+    return ax

dopplertrack/score.py

@@ -0,0 +1,89 @@
+"""Score candidate observers by modelling the exact Doppler curve they would hear."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from .audio import Spectrogram
+from .doppler import curve_from_trajectory, speed_of_sound
+from .search import Segment
+from .tracks import EventFit, local_whiten
+
+
+@dataclass
+class EventWindow:
+    """Whitened spectrogram crop for one event plus its measured parameters."""
+    fit: EventFit
+    sp: Spectrogram
+    harmonics: int = 1
+
+    @classmethod
+    def from_fit(cls, sp: Spectrogram, fit: EventFit, harmonics: int = 1, pad_s: float = 40.0):
+        w = sp.crop(fit.t_start - pad_s, fit.t_end + pad_s, max(fit.f_post * 0.8, sp.f[0]),
+                    min(fit.f_pre * 1.25 * harmonics, sp.f[-1]))
+        return cls(fit, local_whiten(w), harmonics)
+
+    def curve_score(self, t_audio, ratio, f0_scale=1.0) -> float:
+        """Mean brightness under the curve, within the event's fit window."""
+        m = (t_audio >= self.fit.t_start) & (t_audio <= self.fit.t_end) & np.isfinite(ratio)
+        if m.sum() < 10:
+            return 0.0
+        s = 0.0
+        for h in range(1, self.harmonics + 1):
+            s += float(np.mean(self.sp.sample(t_audio[m], h * self.fit.f0 * f0_scale * ratio[m])))
+        return s / self.harmonics
+
+    def sweep_scores(self, t_audio, ratio, shifts, f0_scales, n=160) -> np.ndarray:
+        """Scores for every (shift, f0_scale) combination in one vectorised pass.
+        The curve is resampled onto n points of the fit window for each shift."""
+        tq = np.linspace(self.fit.t_start, self.fit.t_end, n)
+        rel = tq[None, :] - np.asarray(shifts)[:, None]                       # (S, n) un-shifted audio time
+        ok = np.isfinite(ratio)
+        rat = np.interp(rel, t_audio[ok], ratio[ok], left=np.nan, right=np.nan)  # (S, n)
+        valid = np.isfinite(rat).sum(1) >= 10                                  # (S,)
+        total = np.zeros((len(shifts), len(f0_scales)))
+        for h in range(1, self.harmonics + 1):
+            F = h * self.fit.f0 * np.asarray(f0_scales)[None, :, None] * rat[:, None, :]   # (S, K, n)
+            T = np.broadcast_to(tq[None, None, :], F.shape)
+            v = self.sp.sample(T.ravel(), np.nan_to_num(F.ravel(), nan=-1.0)).reshape(F.shape)
+            v = np.where(np.isfinite(F), v, np.nan)
+            total += np.nanmean(v, axis=2)
+        total[~valid] = 0.0
+        return np.nan_to_num(total / self.harmonics, nan=0.0)
+
+
+def modelled_curve(seg: Segment, obs_enu, c):
+    """(t_obs unix, ratio f/f0) the observer at obs_enu hears from this segment."""
+    t_obs, ratio, r = curve_from_trajectory(seg.t, seg.enu, obs_enu, f0=1.0, c=c)
+    return t_obs, ratio
+
+
+def locked_score(ev1: EventWindow, ev2: EventWindow, seg1: Segment, seg2: Segment, obs_enu,
+                 t_heard1: float, c: float | None = None,
+                 shifts=np.arange(-8, 8.01, 0.5), f0_scales=np.arange(0.95, 1.0501, 0.005)):
+    """Two-event locked scoring.
+
+    Event 1's placement is swept over small time shifts and f0 scales (both are
+    measurements). Event 2 is placed with the *same* time shift, so its timing
+    relative to event 1 is fixed purely by flight geometry.
+    Returns (total, s1, s2, best_shift).
+    """
+    c = speed_of_sound() if c is None else c
+    # map unix time -> audio time so that the modelled heard-CPA of event 1 lands on the measured one
+    t0_map = ev1.fit.t_cpa - t_heard1
+    to1, r1 = modelled_curve(seg1, obs_enu, c)
+    to2, r2 = modelled_curve(seg2, obs_enu, c)
+    sc1 = ev1.sweep_scores(to1 + t0_map, r1, shifts, f0_scales)
+    i, j = np.unravel_index(np.argmax(sc1), sc1.shape)
+    s1, sh = float(sc1[i, j]), float(shifts[i])
+    s2 = float(ev2.sweep_scores(to2 + t0_map, r2, [sh], f0_scales).max())
+    return s1 + s2, s1, s2, sh
+
+
+def single_score(ev: EventWindow, seg: Segment, obs_enu, t_heard: float, c=None,
+                 shifts=np.arange(-8, 8.01, 0.5), f0_scales=np.arange(0.95, 1.0501, 0.005)):
+    c = speed_of_sound() if c is None else c
+    to, r = modelled_curve(seg, obs_enu, c)
+    t0_map = ev.fit.t_cpa - t_heard
+    return float(ev.sweep_scores(to + t0_map, r, shifts, f0_scales).max())

dopplertrack/search.py

@@ -0,0 +1,137 @@
+"""Candidate observer generation: who could have heard which flight, when, how far."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+from scipy.spatial import cKDTree
+
+from .adsb import Trace
+from .doppler import speed_of_sound
+from .geo import lla_to_enu, enu_to_lla
+
+
+@dataclass
+class Grid:
+    lat: np.ndarray
+    lon: np.ndarray
+    elev: np.ndarray
+    enu: np.ndarray        # (G,3) relative to (lat0, lon0, 0)
+    lat0: float
+    lon0: float
+
+    @classmethod
+    def make(cls, lat_min, lat_max, lon_min, lon_max, spacing_m, elevation_fn=None):
+        lat0, lon0 = (lat_min + lat_max) / 2, (lon_min + lon_max) / 2
+        dlat = spacing_m / 111320.0
+        dlon = spacing_m / (111320.0 * np.cos(np.radians(lat0)))
+        la, lo = np.meshgrid(np.arange(lat_min, lat_max, dlat), np.arange(lon_min, lon_max, dlon), indexing="ij")
+        la, lo = la.ravel(), lo.ravel()
+        el = elevation_fn(la, lo) if elevation_fn else np.zeros_like(la)
+        el = np.maximum(el, 0.0)
+        return cls(la, lo, el, lla_to_enu(la, lo, el, lat0, lon0), lat0, lon0)
+
+    @classmethod
+    def points(cls, lat, lon, elev, lat0=None, lon0=None):
+        lat = np.atleast_1d(np.asarray(lat, float)); lon = np.atleast_1d(np.asarray(lon, float)); elev = np.atleast_1d(np.asarray(elev, float))
+        lat0 = float(lat.mean()) if lat0 is None else lat0; lon0 = float(lon.mean()) if lon0 is None else lon0
+        return cls(lat, lon, elev, lla_to_enu(lat, lon, elev, lat0, lon0), lat0, lon0)
+
+    def __len__(self):
+        return len(self.lat)
+
+
+@dataclass
+class Segment:
+    trace_idx: int
+    icao: str
+    t: np.ndarray       # emission times (unix s), 1 Hz
+    enu: np.ndarray     # (N,3)
+    speed: np.ndarray   # (N,) m/s
+
+
+def build_segments(traces: list[Trace], lat0: float, lon0: float, dt: float = 1.0, min_len: int = 20,
+                   clip_enu: tuple[float, float, float, float] | None = None) -> list[Segment]:
+    """1 Hz ENU segments. clip_enu=(e_min, e_max, n_min, n_max) keeps only the parts of a
+    track inside that box (split where it leaves), which bounds memory in cpa_table."""
+    segs = []
+    for i, tr in enumerate(traces):
+        for sl in tr.segments():
+            t, enu = tr.enu(sl, lat0, lon0, dt)
+            if len(t) < min_len or not np.all(np.isfinite(enu)):
+                continue
+            vel = np.gradient(enu, t, axis=0)
+            spd = np.linalg.norm(vel, axis=1)
+            if clip_enu is None:
+                segs.append(Segment(i, tr.icao, t, enu, spd))
+                continue
+            inside = (enu[:, 0] >= clip_enu[0]) & (enu[:, 0] <= clip_enu[1]) & (enu[:, 1] >= clip_enu[2]) & (enu[:, 1] <= clip_enu[3])
+            if not inside.any():
+                continue
+            edges = np.flatnonzero(np.diff(inside.astype(int))) + 1
+            for a, b in zip(np.r_[0, edges], np.r_[edges, len(t)]):
+                if inside[a] and b - a >= min_len:
+                    segs.append(Segment(i, tr.icao, t[a:b], enu[a:b], spd[a:b]))
+    return segs
+
+
+def cpa_table(grid: Grid, segs: list[Segment], max_range_m: float = 10000.0, c: float | None = None,
+              chunk: int = 20000) -> pd.DataFrame:
+    """For every (grid point, segment) within max_range: CPA emission time, heard time,
+    slant distance and ground-track speed at CPA."""
+    c = speed_of_sound() if c is None else c
+    rows = []
+    tree = cKDTree(grid.enu[:, :2])
+    for si, s in enumerate(segs):
+        # grid points within max_range (horizontally) of the track polyline, via a KD-tree
+        # on track samples spaced <= max_range/4 apart (so the union of balls covers the corridor)
+        step = max(1, int(max_range_m / 4 / max(np.median(s.speed), 1.0)))
+        probes = s.enu[::step, :2]
+        hits = tree.query_ball_point(probes, r=max_range_m * 1.05)
+        m = np.unique(np.concatenate([np.asarray(h, int) for h in hits])) if len(hits) else np.array([], int)
+        if len(m) == 0:
+            continue
+        for k in range(0, len(m), chunk):
+            idx = m[k:k + chunk]
+            g = grid.enu[idx].astype(np.float32)                      # (G,3)
+            nstep = max(1, int(2e7 // max(len(idx), 1)))
+            best = np.full(len(idx), np.inf); j = np.zeros(len(idx), int)
+            for n0 in range(0, len(s.t), nstep):
+                d2 = ((g[:, None, :] - s.enu[None, n0:n0 + nstep, :].astype(np.float32)) ** 2).sum(-1)    # (G,n)
+                jj = np.argmin(d2, axis=1)
+                dd = d2[np.arange(len(idx)), jj]
+                upd = dd < best
+                best[upd] = dd[upd]; j[upd] = jj[upd] + n0
+            r = np.sqrt(best)
+            ok = (r <= max_range_m) & (j > 0) & (j < len(s.t) - 1)     # interior CPA only
+            if not ok.any():
+                continue
+            rows.append(pd.DataFrame({
+                "gidx": idx[ok], "seg": si, "trace": s.trace_idx, "icao": s.icao,
+                "t_emit": s.t[j[ok]], "t_heard": s.t[j[ok]] + r[ok] / c,
+                "d": r[ok], "v": s.speed[j[ok]],
+            }))
+    if not rows:
+        return pd.DataFrame(columns=["gidx", "seg", "trace", "icao", "t_emit", "t_heard", "d", "v"])
+    return pd.concat(rows, ignore_index=True)
+
+
+def pair_candidates(cpa: pd.DataFrame, dt_offset: float, tol_s: float = 6.0,
+                    v1=(0, 1e9), d1=(0, 1e9), v2=(0, 1e9), d2=(0, 1e9),
+                    silence_d_m: float | None = 6000.0, silence_margin_s: float = 40.0) -> pd.DataFrame:
+    """Grid points that hear an event-1-like CPA then, dt_offset later, an event-2-like CPA."""
+    a = cpa[(cpa.v.between(*v1)) & (cpa.d.between(*d1))]
+    b = cpa[(cpa.v.between(*v2)) & (cpa.d.between(*d2))]
+    m = a.merge(b, on="gidx", suffixes=("1", "2"))
+    m = m[(m.seg1 != m.seg2) & ((m.t_heard2 - m.t_heard1 - dt_offset).abs() <= tol_s)].copy()
+    if silence_d_m is not None and len(m):
+        near = cpa[cpa.d <= silence_d_m][["gidx", "seg", "t_heard"]]
+        x = m[["gidx", "seg1", "seg2", "t_heard1", "t_heard2"]].reset_index().merge(near, on="gidx")
+        bad = x[(x.seg != x.seg1) & (x.seg != x.seg2) & (x.t_heard > x.t_heard1 + silence_margin_s) & (x.t_heard < x.t_heard2 - silence_margin_s)]
+        m = m.drop(index=bad["index"].unique())
+    return m.reset_index(drop=True)
+
+
+def grid_lla(grid: Grid, gidx):
+    return grid.lat[gidx], grid.lon[gidx], grid.elev[gidx]

dopplertrack/terrain.py

@@ -0,0 +1,49 @@
+"""Ground elevation from AWS Terrain Tiles (Terrarium encoding), cached on disk."""
+from __future__ import annotations
+
+import io
+import os
+from pathlib import Path
+
+import numpy as np
+import requests
+from PIL import Image
+
+_URL = "https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png"
+
+
+class Terrain:
+    def __init__(self, zoom: int = 12, cache_dir: str | Path | None = None):
+        self.z = zoom
+        self.cache = Path(cache_dir or os.environ.get("DOPPLERTRACK_CACHE", Path.home() / ".cache" / "dopplertrack")) / "terrarium" / str(zoom)
+        self.cache.mkdir(parents=True, exist_ok=True)
+        self._mem: dict[tuple[int, int], np.ndarray] = {}
+
+    def _tile(self, x: int, y: int) -> np.ndarray:
+        k = (x, y)
+        if k in self._mem:
+            return self._mem[k]
+        p = self.cache / f"{x}_{y}.png"
+        if not p.exists():
+            r = requests.get(_URL.format(z=self.z, x=x, y=y), timeout=60)
+            r.raise_for_status()
+            p.write_bytes(r.content)
+        img = np.asarray(Image.open(p).convert("RGB"), dtype=np.float64)
+        elev = img[..., 0] * 256 + img[..., 1] + img[..., 2] / 256 - 32768
+        self._mem[k] = elev
+        return elev
+
+    def elevation(self, lat, lon) -> np.ndarray:
+        """Elevation in metres (MSL) for arrays of lat/lon. Nearest pixel."""
+        lat = np.atleast_1d(np.asarray(lat, float)); lon = np.atleast_1d(np.asarray(lon, float))
+        n = 2 ** self.z
+        xf = (lon + 180.0) / 360.0 * n
+        latr = np.radians(lat)
+        yf = (1 - np.log(np.tan(latr) + 1 / np.cos(latr)) / np.pi) / 2 * n
+        xt = np.floor(xf).astype(int); yt = np.floor(yf).astype(int)
+        px = np.clip(((xf - xt) * 256).astype(int), 0, 255); py = np.clip(((yf - yt) * 256).astype(int), 0, 255)
+        out = np.zeros(lat.shape)
+        for (tx, ty) in set(zip(xt.tolist(), yt.tolist())):
+            m = (xt == tx) & (yt == ty)
+            out[m] = self._tile(tx, ty)[py[m], px[m]]
+        return out

dopplertrack/tracks.py

@@ -0,0 +1,127 @@
+"""Extract a Doppler event from a spectrogram window and fit the ideal model."""
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+
+import numpy as np
+from scipy.optimize import minimize
+
+from .audio import Spectrogram
+from .doppler import ideal_curve, speed_of_sound
+
+
+@dataclass
+class EventFit:
+    t_cpa: float        # heard CPA time in the recording, s (observation time of the f0 crossing)
+    t_cpa_emit: float   # emission-time CPA (t_cpa - d/c)
+    f0: float           # rest fundamental, Hz
+    v: float            # speed, m/s
+    d: float            # CPA slant distance, m
+    t_start: float
+    t_end: float
+    score: float        # mean whitened dB along the fitted curve
+    f_pre: float
+    f_post: float
+
+    def to_dict(self):
+        return asdict(self)
+
+
+def local_whiten(sp: Spectrogram, floor: float = 0.0) -> Spectrogram:
+    """Remove tones that are stationary over this window (per-bin median), clip at floor."""
+    S = sp.S - np.median(sp.S, axis=1, keepdims=True)
+    return Spectrogram(sp.t, sp.f, np.maximum(S, floor).astype(np.float32))
+
+
+def ridge(sp: Spectrogram, max_step_bins: int = 3, smooth: float = 1.5) -> np.ndarray:
+    """Viterbi ridge through S (F,T): maximise sum(S) - smooth*|Δbin|. Returns freq per frame."""
+    S = sp.S
+    F, T = S.shape
+    cost = np.full((T, F), -np.inf)
+    back = np.zeros((T, F), np.int16)
+    cost[0] = S[:, 0]
+    offs = np.arange(-max_step_bins, max_step_bins + 1)
+    pen = smooth * np.abs(offs)
+    for t in range(1, T):
+        prev = cost[t - 1]
+        cand = np.full((len(offs), F), -np.inf)
+        for k, o in enumerate(offs):
+            if o >= 0:
+                cand[k, o:] = prev[: F - o] - pen[k]
+            else:
+                cand[k, :o] = prev[-o:] - pen[k]
+        kbest = np.argmax(cand, axis=0)
+        cost[t] = cand[kbest, np.arange(F)] + S[:, t]
+        back[t] = offs[kbest]
+    path = np.zeros(T, int)
+    path[-1] = int(np.argmax(cost[-1]))
+    for t in range(T - 1, 0, -1):
+        path[t - 1] = path[t] - back[t, path[t]]
+    return sp.f[path]
+
+
+def _shape(v, d, c, span=400.0, n=161):
+    """Observation-time offsets and frequency ratios for a straight pass, relative to
+    emission-time CPA (tau=0)."""
+    tau = np.linspace(-span, span, n)
+    r = np.sqrt(d * d + (v * tau) ** 2)
+    rr = v * v * tau / r
+    return tau + r / c, c / (c + rr)
+
+
+def grid_search(sp: Spectrogram, t_start, t_end, f_lo, f_hi, c, harmonics=1,
+                v_grid=None, d_grid=None, f0_step=1.0, t0_step=1.0, n_curve=120):
+    """Coarse maximisation of brightness under ideal curves. Returns (score, f0, v, d, t0_emit)."""
+    v_grid = np.arange(30, 170, 10.0) if v_grid is None else v_grid
+    d_grid = np.geomspace(300, 9000, 14) if d_grid is None else d_grid
+    f0s = np.arange(f_lo * 1.15, f_hi * 0.85, f0_step)
+    t0s = np.arange(t_start, t_end, t0_step)
+    tq = np.linspace(t_start, t_end, n_curve)
+    best = (-np.inf, None)
+    for v in v_grid:
+        for d in d_grid:
+            dto, ratio = _shape(v, d, c)
+            # for each t0: curve observation times = t0 + dto; frequencies = f0*ratio
+            # sample at tq by interpolating ratio onto tq - t0
+            rel = tq[None, :] - t0s[:, None]                         # (T0, N)
+            rat = np.interp(rel, dto, ratio, left=np.nan, right=np.nan)  # (T0, N)
+            total = np.zeros((len(t0s), len(f0s)))
+            for h in range(1, harmonics + 1):
+                F = h * f0s[None, None, :] * rat[:, :, None]           # (T0, N, F0)
+                T = np.broadcast_to(tq[None, :, None], F.shape)
+                vals = sp.sample(T.ravel(), F.ravel()).reshape(F.shape)
+                total += np.nanmean(vals, axis=1)
+            i, j = np.unravel_index(np.argmax(total), total.shape)
+            if total[i, j] > best[0]:
+                best = (float(total[i, j] / harmonics), (float(f0s[j]), float(v), float(d), float(t0s[i])))
+    return best
+
+
+def fit_event(sp: Spectrogram, t_start: float, t_end: float, f_lo: float, f_hi: float,
+              c: float | None = None, harmonics: int = 1, whiten: bool = True) -> EventFit:
+    """Fit (f0, v, d, t_cpa) to the brightest Doppler-shaped curve in a window."""
+    c = speed_of_sound() if c is None else c
+    pad = 0.3 * (f_hi - f_lo)
+    win = sp.crop(t_start - 30, t_end + 30, max(f_lo - pad, sp.f[0]), min(f_hi * harmonics + pad, sp.f[-1]))
+    if whiten:
+        win = local_whiten(win)
+    score0, (f0, v, d, t0) = grid_search(win, t_start, t_end, f_lo, f_hi, c, harmonics)
+    tt = np.linspace(t_start, t_end, 400)
+
+    def neg(p):
+        f0_, v_, d_, t0_ = p
+        if not (10 < v_ < 300 and 100 < d_ < 30000):
+            return 1e3
+        s = 0.0
+        for h in range(1, harmonics + 1):
+            s += float(np.nanmean(win.sample(tt, ideal_curve(tt, h * f0_, v_, d_, t0_, c=c))))
+        return -s / harmonics
+
+    best = minimize(neg, [f0, v, d, t0], method="Nelder-Mead",
+                    options={"xatol": 1e-2, "fatol": 1e-4, "maxiter": 4000,
+                             "initial_simplex": np.array([[f0, v, d, t0], [f0 + 2, v, d, t0], [f0, v + 10, d, t0],
+                                                          [f0, v, d * 1.3, t0], [f0, v, d, t0 + 2]])})
+    f0, v, d, t0 = best.x
+    return EventFit(t_cpa=float(t0 + d / c), t_cpa_emit=float(t0), f0=float(f0), v=float(v), d=float(d),
+                    t_start=t_start, t_end=t_end, score=float(-best.fun),
+                    f_pre=float(f0 * c / (c - v)), f_post=float(f0 * c / (c + v)))

dopplertrack-0.1.0.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: dopplertrack
+Version: 0.1.0
+Summary: Acoustic geolocation from inaudible aircraft Doppler curves matched against ADS-B flight tracks
+Keywords: doppler,ads-b,geolocation,acoustics,osint,spectrogram
+Author: MacCallister Higgins
+Author-email: MacCallister Higgins <maccallister.higgins@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: matplotlib>=3.11.2
+Requires-Dist: numpy>=2.5.4
+Requires-Dist: pandas>=3.1.0
+Requires-Dist: pillow>=13.0.0
+Requires-Dist: requests>=2.34.2
+Requires-Dist: scipy>=1.18.1
+Requires-Dist: soundfile>=0.14.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/mjshiggins/dopplertrack
+Project-URL: Issues, https://github.com/mjshiggins/dopplertrack/issues
+Description-Content-Type: text/markdown
+
+# dopplertrack
+
+Acoustic geolocation from the Doppler curves of propeller aircraft.
+
+Any outdoor (and many indoor) recordings contain faint, usually inaudible
+tones from aircraft flying over: the propeller blade-pass fundamental and its
+harmonics, between roughly 60 and 400 Hz. As the aircraft passes, the tone
+sweeps down in frequency. The exact shape of that sweep depends on where the
+listener was relative to the aircraft's real trajectory. With historical
+ADS-B data for every flight that day, each candidate location on the ground
+predicts a different curve, and the recording picks out the one that matches.
+
+This is a reimplementation of the technique shown in colsto's video
+["I discovered a sound that leaks your exact location"](https://www.youtube.com/watch?v=UytYrhYLOKI).
+No code was released with that video; this project is an open, automatic
+version of the method. See `docs/superpowers/specs/` for the design.
+
+## Status
+
+Proof of concept. Validated against the author's reference recording
+(known answer: Oyster Bay, NY, 2026-09-08). See the results section below.
+
+## Pipeline
+
+1. `spectrogram` — decode any audio/video with ffmpeg, high-resolution STFT of
+   the 40–450 Hz band, whitened per frequency bin so only *changing* tones stand out.
+2. `fit` — fit an ideal straight-pass Doppler curve (f0, speed, CPA slant
+   distance, CPA time) to a time/frequency window. The fit seeds a search
+   with coarse parameter ranges.
+3. `extract-region` — pull every flight that touched a bounding box out of an
+   [adsb.lol](https://github.com/adsblol/globe_history_2026) daily archive and
+   drop known jets using ICAO Doc 8643 engine classes.
+4. `search` — for every grid point (200 m) and every flight, compute the
+   closest point of approach (CPA), its slant distance (using a DEM for the
+   observer's elevation) and the *heard* CPA time (propagation delay). Keep
+   points that hear an event-1-like pass, then exactly Δt later an
+   event-2-like pass, with no other prop flight in between. Model the exact
+   Doppler curve each survivor would hear from the real trajectory
+   (emission-time radial velocity) and score it against the spectrogram.
+   Event 1's placement absorbs measurement error; event 2's placement is
+   locked to the flight geometry.
+
+## Usage
+
+```bash
+uv sync
+uv run dopplertrack spectrogram recording.mp4 rec.npz
+uv run dopplertrack fit rec.npz --window 2090 2200 --band 95 200 --harmonics 2 --out ev1.json
+uv run dopplertrack fit rec.npz --window 3020 3130 --band 95 195 --out ev2.json
+uv run dopplertrack extract-region /path/to/adsb-day --bbox 40.4 41.3 -74.4 -72.6 traces_ny.npz
+uv run dopplertrack search rec.npz --events ev1.json ev2.json --traces traces_ny.npz \
+    --bbox 40.4 41.3 -74.4 -72.6 --spacing 200 --out results.csv
+```
+
+`search --point LAT LON` scores a single known location instead of a grid,
+which is the quickest way to validate the data and physics on a recording
+whose location you already know.
+
+## Changes from the method in the video
+
+The physics and the search strategy are the author's. What differs:
+
+- **Automatic curve measurement.** The video measures each Doppler curve by
+  hand, sliding f0 / speed / distance / CPA-time until the overlay looks
+  right, then choosing "generous ranges" by eye. `fit` does this without a
+  person: the window is whitened per frequency bin so stationary tones
+  (mains hum, machinery) vanish, a vectorised grid search over all four
+  parameters maximises spectrogram brightness under the curve, and a
+  Nelder-Mead pass refines it. The ideal-curve fit still only seeds coarse
+  filters; final ranking uses real trajectories.
+- **Harmonic-aware fitting and scoring.** When a flyover shows a second
+  harmonic, fundamental and harmonic are scored together, which constrains
+  the curve more tightly than one line.
+- **Open, documented data path.** The video used a paid/scraped ADS-B feed
+  and did not release code. Here every input is a public dataset with a
+  loader: adsb.lol daily archives, ICAO Doc 8643 engine classes, AWS
+  terrain tiles.
+- **Search engineering.** A KD-tree corridor around each flight path limits
+  CPA computation to grid points that could possibly hear it; distance math
+  is chunked so multi-hour tracks do not exhaust memory; the time-shift and
+  f0 sweeps of the locked scorer run as one array operation per candidate.
+- **Single-event, known-time mode as a first-class command.** The video
+  demonstrates locating from one faint one-minute curve when the recording
+  time is known; `search-single` exposes that directly.
+
+Kept unchanged on purpose: emission-time radial velocity (not
+observation-time), propagation-delayed CPA times, slant distance with a DEM,
+the inter-event offset filter, the silence filter, and locked two-event
+scoring where event 1 absorbs measurement error and event 2 is placed purely
+by flight geometry.
+
+## Data sources (all free)
+
+| Need | Source |
+|---|---|
+| Historical ADS-B | adsb.lol `globe_history_YYYY` GitHub releases (~4 GB/day) |
+| Aircraft engine class | OpenSky mirror of ICAO Doc 8643 |
+| Elevation | AWS Terrain Tiles (Terrarium) |
+
+## Development
+
+```bash
+uv run pytest
+```
+
+## Releasing
+
+Releases are driven by git tags. Pushing a tag `vX.Y.Z` that matches the
+version in `pyproject.toml` runs `.github/workflows/release.yml`, which runs
+the tests, builds the sdist and wheel, attaches them to a GitHub Release with
+generated notes, and publishes to PyPI through trusted publishing (no API
+token stored anywhere).
+
+```bash
+uv version 0.2.0            # bump pyproject.toml
+git commit -am "Release 0.2.0"
+git tag v0.2.0 && git push && git push --tags
+```
+
+One-time setup for PyPI: on pypi.org, add a *pending publisher* for project
+`dopplertrack` with owner `mjshiggins`, repository `dopplertrack`, workflow
+`release.yml`, environment `pypi`, and create a `pypi` environment in the
+GitHub repository settings. Until that exists the `pypi` job fails and the
+GitHub Release still succeeds.

dopplertrack-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+dopplertrack/__init__.py,sha256=adQDvyRTcwnIYAkk1RW-3DWa50_jxjeHc0C3je-JYtE,58
+dopplertrack/adsb.py,sha256=Z7l5ydWRE1TYYSCmENVWMQd-UbgJfu8wlgwSH2i-Al0,5658
+dopplertrack/audio.py,sha256=TMdnX_VOm1mOdm8RxvzJG5RF4bMrWf8OrT-QISKnY08,4254
+dopplertrack/cli.py,sha256=ba9-9rVHrzo03k0UUwCLs6SyILAuarzz0O0FFQ1Dq9A,5218
+dopplertrack/doppler.py,sha256=T5Pkt_WfNAj9olOLsjDCIgIy69rI0JLgO1exmtYAt98,2668
+dopplertrack/geo.py,sha256=xKwgXrj-5uZjOocm1nX64h7l2MsJ23SbjfBIvGHrLcY,2051
+dopplertrack/pipeline.py,sha256=KYon4w9Cz8hMPF404YEk0aJM2oZz4TruIA76X3P_7Rk,6529
+dopplertrack/plots.py,sha256=5nWj7WSZ1ZCCaBv-bHTZBVD9gXXaSbssfpa-ZffwVEw,2582
+dopplertrack/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dopplertrack/score.py,sha256=zMTph87GiLaxN9Q4C41wSVXuCqL_xa34990_7ww3TJk,4202
+dopplertrack/search.py,sha256=oIRGlwkF5XdwAJ6dM0cVvypO8GLVfROUGNBicWalYY4,6392
+dopplertrack/terrain.py,sha256=8JdxYh095bcIR4jyMf06epyb4SoXaLImfDFayDfVlq8,1997
+dopplertrack/tracks.py,sha256=nZylbmojHqlXEebi_MQx9LRpScOOwB8AMS27FkKo3so,5526
+dopplertrack-0.1.0.dist-info/licenses/LICENSE,sha256=XT1Wkw8MQ_neNrlQzFNUgmK09_zMGI7QENUyqaUwu1w,1077
+dopplertrack-0.1.0.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+dopplertrack-0.1.0.dist-info/entry_points.txt,sha256=Xl1GMJAzPVkwf2h4qKQ-vVYEXHsB4T9IZl6ob0jefNg,56
+dopplertrack-0.1.0.dist-info/METADATA,sha256=hMLA7bz0IhwwauVKYTJRsEPnqq3eoDWF8VJmu3nkdxA,6951
+dopplertrack-0.1.0.dist-info/RECORD,,

dopplertrack-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.24
+Root-Is-Purelib: true
+Tag: py3-none-any

dopplertrack-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+dopplertrack = dopplertrack.cli:main
+

dopplertrack-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MacCallister Higgins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.