Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Python acoustic-geolocationads-baircraft-trackingairplaneaudio-forensicsdoppler-effectdoppler-shiftgeolocationosintsignal-processing
Show a bounded real Livermore flyover run
Cinna Davisba094d1ac750
diff --git a/README.md b/README.mdindex 9044f21..cb22f6f 100644--- a/README.md+++ b/README.md@@ -98,6 +98,12 @@ Remaining reliability work includes [unsupported trajectory motion and coverage## Experimental results+### A real flyover, with bounded priors++++This configured run combines a real recording with its supplied aircraft track, a narrow time window and a regional search area. Its highest-scoring point is **481 m from a dataset-derived reference**, not surveyed microphone ground truth. The result is inconclusive: model assessment is incomplete and the fitted clock is at the search boundary. [Setup, limitations and reproduction](docs/LIVERMORE_DEMO.md).+The published project artifacts preserve both successful fits and cases where the system could not justify a location. The following are **historical configured replays**, with their original settings and thresholds:| Experiment | Reported finding | Important qualification |diff --git a/assets/README.md b/assets/README.mdindex c190194..02831b1 100644--- a/assets/README.md+++ b/assets/README.md@@ -58,3 +58,11 @@ rsvg-convert assets/dopplergeist-banner.svg \-o assets/dopplergeist-banner-preview.pngrsvg-convert -w 600 assets/dopplergeist-banner.svg -o /tmp/dopplergeist-banner-600.png```++## Livermore demonstration++`livermore-real-demo.png` shows a real recording and a configured search over+published flight data. It uses USGS / USDA NAIP imagery and data from Praveen+Pathak's [Zenodo dataset](https://doi.org/10.5281/zenodo.23424278) (CC BY 4.0).+[Setup, limitations and rendering instructions](../docs/LIVERMORE_DEMO.md)+explain the inferred reference and the incomplete model assessment.diff --git a/assets/livermore-real-demo.png b/assets/livermore-real-demo.pngnew file mode 100644index 0000000..dde7712Binary files /dev/null and b/assets/livermore-real-demo.png differdiff --git a/docs/LIVERMORE_DEMO.md b/docs/LIVERMORE_DEMO.mdnew file mode 100644index 0000000..8debaa3--- /dev/null+++ b/docs/LIVERMORE_DEMO.md@@ -0,0 +1,77 @@+# A bounded real-audio demonstration: Livermore++++This is a configured research run on **N784MB_R04**, a smartphone recording and+an accompanying aircraft track from [Praveen Pathak's Livermore dataset](https://doi.org/10.5281/zenodo.23424278)+(CC BY 4.0). We ran DOPPLERGEIST at `8c19362` on the original WAV and the+published KML track. The plot overlays the best physical model on the recording+and shows scored grid points for its selected track segment. Colors are raw fit+scores, not probabilities; locations with no plotted point were not assigned a+score in this visualization.++The highest-scoring point is **481 m from an inferred reference**, not surveyed+microphone ground truth. That reference was reconstructed from published flight+tracks and reported closest-track offsets across the same dataset; the dataset+does not publish an exact microphone coordinate. The search region was chosen+with that inferred site in mind, so this separation is **not an independent+measurement of location accuracy**. The candidate is within 500 m and 1,000 m+of the inferred reference, but not 100 m; the unknown reference error prevents+those figures from establishing those accuracy thresholds.++The configured run supplied one aircraft's track, the recording's full 0–85 s+window and the 99–164 Hz band, a roughly 10-second start-time interval derived+from the published UTC ridge and WAV duration, and a regional search box. The+published ridge constrains sample zero only if the entire annotated passage is+within this audio file; it is not an independently measured recording clock.+The midpoint was `2026-05-14T17:41:32.238656Z`, with a ±5.01 s scoring sweep+in 0.5 s steps. The winner lies at the early edge of that sweep, 0.01 s earlier+than the estimated lower bound; its clock is therefore particularly sensitive to+the imposed boundary. Terrain was held at 150 m above mean sea level with an+EGM96 geoid conversion. The run scored 358 grid points and retained 407 rows+including refinements. Its model assessment is incomplete: one track segment was+unsupported at each of three CPA stages, and all 407 scored candidate clock+envelopes were unclassified by the legacy brightness scorer. The program marked+`accepted_location: false`. One pass also permits competing geometries; the+plot does not rule them out.++A separate fresh configured two-flyover replay on the same code placed its+leading candidate 43.86 m from an approximate public reference, also with+incomplete model support. Both are development examples, not automatic or+independent real-world acceptance. The Livermore run took 20.7 seconds on the+local machine; runtime depends on hardware and load.++## Reproduce++Install the project as described in the [README](../README.md). Download+`Raw data_V_constant_H_constant.zip` from the dataset page, verify its published+MD5 `d34b32ae57477074d6e8563300a7fc19`, and extract the `N784MB_R04` folder.+Obtain an EGM96 geoid raster compatible with DOPPLERGEIST, for example+`data/terrain/us_nga_egm96_15.tif` from the project checkpoint's `data-terrain`+bundle. Use new output directories:++```bash+PYTHONPATH=src python scripts/prepare_livermore_demo.py \+ path/to/V_constant_H_constant/N784MB_R04 \+ data/terrain/us_nga_egm96_15.tif results/livermore-prepared+PYTHONPATH=src python -m dopplergeist.cli run \+ results/livermore-prepared/config.json --output results/livermore-run+```++The imagery in the figure comes from [USGS The National Map / USDA NAIP](https://imagery.nationalmap.gov/arcgis/rest/services/USGSNAIPImagery/ImageServer).+To reproduce the graphic, download the public-domain USGS image for the fixed+extent and pass it to the renderer:++```bash+curl -G 'https://imagery.nationalmap.gov/arcgis/rest/services/USGSNAIPImagery/ImageServer/exportImage' \+ --data-urlencode 'bbox=-121.82,37.642,-121.74,37.687' \+ --data-urlencode 'bboxSR=4326' --data-urlencode 'imageSR=4326' \+ --data-urlencode 'size=1600,900' --data-urlencode 'format=jpg' \+ --data-urlencode 'f=image' -o results/livermore-naip.jpg+PYTHONPATH=src python scripts/render_livermore_demo.py \+ results/livermore-run results/livermore-naip.jpg results/livermore-demo.png+```++The live imagery service may serve a newer aerial image in the future. See+[Dopplerprint comparison](DOPPLERPRINT_REVIEW_2026-11-03.md) for the limits of+the related dataset's reconstructed reference and other real-data work.diff --git a/scripts/prepare_livermore_demo.py b/scripts/prepare_livermore_demo.pynew file mode 100644index 0000000..b287168--- /dev/null+++ b/scripts/prepare_livermore_demo.py@@ -0,0 +1,41 @@+#!/usr/bin/env python3+"""Prepare the explicitly prior-constrained Livermore demonstration inputs."""+import argparse+import json+from pathlib import Path++from dopplergeist.terrain import Terrain+from dopplergeist.tracks import read_kml+++def main():+ parser = argparse.ArgumentParser()+ parser.add_argument('case', type=Path, help='Extracted N784MB_R04 directory from Zenodo 23424278')+ parser.add_argument('geoid', type=Path, help='EGM96 geoid raster')+ parser.add_argument('output', type=Path, help='New preparation directory')+ args = parser.parse_args()+ case, geoid, output = args.case.resolve(), args.geoid.resolve(), args.output.resolve()+ output.mkdir(parents=True, exist_ok=False)+ frame = read_kml(case / 'N784MB-track-EGM96.kml')+ frame['alt_m'] += Terrain([geoid]).sample(frame.lat.to_numpy(), frame.lon.to_numpy())+ frame['altitude_basis'] = 'ellipsoidal_from_egm96_msl'+ track = output / 'track-ellipsoid.csv'+ frame.to_csv(track, index=False)+ config = {+ 'audio': str(case / 'audio.wav'), 'tracks': [str(track)],+ 'terrain': {'constant_m': 150, 'geoid_raster': str(geoid)},+ 'grid': {'bounds': [-121.84, 37.65, -121.70, 37.73], 'spacing_m': 300,+ 'scoring_spacing_m': 150, 'refine_spacing_m': 50, 'refine_pairs': 1},+ 'recording_start_utc': '2026-05-14T17:41:32.238656Z',+ 'filters': {'known_time_tolerance_s': 10},+ 'scoring': {'mode': 'brightness', 'time_sweep_s': 5.01, 'time_step_s': .5},+ 'events': [{'start_s': 0, 'end_s': 85., 'band_hz': [99, 164],+ 'max_slope_hz_s': 4, 'max_up_slope_hz_s': 1}],+ 'scoring_workers': 2,+ }+ (output / 'config.json').write_text(json.dumps(config, indent=2) + '\n')+ print(output / 'config.json')+++if __name__ == '__main__':+ main()diff --git a/scripts/render_livermore_demo.py b/scripts/render_livermore_demo.pynew file mode 100644index 0000000..1d5fca9--- /dev/null+++ b/scripts/render_livermore_demo.py@@ -0,0 +1,93 @@+#!/usr/bin/env python3+"""Render the real, constrained Livermore N784MB_R04 demonstration."""+import argparse+import json+from pathlib import Path++import matplotlib+matplotlib.use('Agg')+import matplotlib.pyplot as plt+from matplotlib.colors import Normalize+import numpy as np+from pyproj import Geod++from dopplergeist.geometry import ecef+from dopplergeist.matching import predict_fitted_ridge+from dopplergeist.tracks import load_tracks++# Image extent for the documented USGS NAIP request, WGS84.+BBOX = (-121.82, 37.642, -121.74, 37.687)+# Inferred from the dataset's reported track offsets; not measured microphone GPS.+REFERENCE = (37.6632161, -121.7818757)+++def main():+ parser = argparse.ArgumentParser()+ parser.add_argument('run', type=Path)+ parser.add_argument('imagery', type=Path)+ parser.add_argument('output', type=Path)+ args = parser.parse_args()+ report = json.loads((args.run / 'report.json').read_text())+ ranked = json.loads((args.run / 'ranked-grid.json').read_text())+ best, cfg = report['best'], report['config']+ rows = [r for r in ranked if r['flight_ids'] == best['flight_ids']]+ if not rows:+ raise ValueError('No grid scores for winning flight combination')+ tracks, _ = load_tracks(report['imports'][0]['path'], max_gap_s=cfg.get('max_track_gap_s', 30))+ track = {t.id: t for t in tracks}[best['flight_ids'][0]]+ spec = np.load(args.run / 'event-1.npz')+ time, freq = spec['time'], spec['frequency']+ diag = dict(best.get('event_diagnostics', [{}])[0], f0_hz=best['f0_hz'][0])+ model = predict_fitted_ridge(track, ecef(best['lat'], best['lon'], best['elev_m']),+ best['recording_start_time_s'] + time, diag,+ cfg.get('sound_speed_mps', 343.0))+ distance = Geod(ellps='WGS84').inv(best['lon'], best['lat'], REFERENCE[1], REFERENCE[0])[2]++ plt.rcParams.update({'font.family':'DejaVu Sans', 'font.size':11, 'text.color':'#202d38',+ 'axes.labelcolor':'#5b6875','xtick.color':'#687581','ytick.color':'#687581'})+ fig = plt.figure(figsize=(14.5, 7.1), facecolor='#fbfaf7')+ gs = fig.add_gridspec(1, 2, left=.065, right=.97, bottom=.20, top=.86, wspace=.16)+ ax = fig.add_subplot(gs[0,0])+ ax.pcolormesh(time, freq, spec['contrast'], shading='auto', cmap='Blues',+ vmin=0, vmax=5, rasterized=True)+ ax.plot(time, model, color='#e76b45', lw=2.6, label='Fitted aircraft model')+ ax.set(title='The recorded flyover', xlabel='Time in recording (s)', ylabel='Frequency (Hz)')+ ax.title.set_fontsize(20); ax.title.set_fontweight('normal'); ax.title.set_position((.5,1.03))+ ax.spines[['top','right']].set_visible(False)+ ax.legend(loc='upper right', frameon=True, framealpha=.9, fontsize=10)++ ax = fig.add_subplot(gs[0,1]); west,south,east,north = BBOX+ ax.imshow(plt.imread(args.imagery), extent=[west,east,south,north], origin='upper', aspect=1/np.cos(np.deg2rad(37.665)))+ # A line connects actual samples from the selected track segment; clipping is visual only.+ ax.plot(track.lon, track.lat, color='#17242c', lw=4, alpha=.8, zorder=1)+ ax.plot(track.lon, track.lat, color='white', lw=2, alpha=.9, zorder=2)+ scores = np.array([r['score'] for r in rows]); order = np.argsort(scores)+ dots = ax.scatter(np.array([r['lon'] for r in rows])[order],+ np.array([r['lat'] for r in rows])[order], c=scores[order], s=29,+ cmap='magma', norm=Normalize(vmin=scores.min(), vmax=scores.max()),+ edgecolor='none', alpha=.88, zorder=3)+ ax.scatter(REFERENCE[1], REFERENCE[0], s=130, facecolor='white', edgecolor='#17242c', linewidth=2, zorder=5)+ ax.scatter(best['lon'], best['lat'], s=145, marker='*', facecolor='#f5d55c', edgecolor='#17242c', linewidth=1, zorder=6)+ ax.set(xlim=(west,east),ylim=(south,north)); ax.set_xticks([]); ax.set_yticks([])+ ax.set_title('The bounded search', fontsize=20, fontweight='normal', pad=15)+ # Longitude of a 1 km eastward geodesic at the latitude of the scale.+ scale_lon = Geod(ellps='WGS84').fwd(west+.003, south+.003, 90, 1000)[0]+ ax.plot([west+.003,scale_lon],[south+.003,south+.003], color='white',lw=5,zorder=8)+ ax.plot([west+.003,scale_lon],[south+.003,south+.003], color='#17242c',lw=2,zorder=9)+ ax.text(west+.003,south+.0042,'1 km',color='white',fontsize=10,weight='bold',zorder=9)+ cb=fig.colorbar(dots, ax=ax, orientation='horizontal', fraction=.038, pad=.025)+ cb.set_label('Fit score · higher is better · not a probability',fontsize=9)+ cb.ax.tick_params(labelsize=8)+ fig.text(.065,.115, f'★ Highest score ● Inferred reference — Aircraft track {distance:.0f} m between points',+ fontsize=10, color='#334451')+ fig.text(.065,.075, 'Real recording · supplied aircraft, approximate area and time · reference inferred from track data',+ fontsize=9, color='#5b6875')+ fig.text(.065,.047, 'Research ranking; incomplete model assessment. USGS / USDA NAIP imagery.', fontsize=9, color='#5b6875')+ args.output.parent.mkdir(parents=True, exist_ok=True)+ fig.savefig(args.output, dpi=180, facecolor=fig.get_facecolor())+ plt.close(fig)+ print(f'{args.output}: {distance:.1f} m from inferred reference; {len(rows)} scored grid points')+++if __name__ == '__main__':+ main()