Skip to content

Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)

Show a bounded real Livermore flyover run

Cinna Davisba094d1ac750
diff --git a/README.md b/README.md
index 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
+
+![Spectrogram and scored search grid for a real Livermore aircraft flyover](assets/livermore-real-demo.png)
+
+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.md
index 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.png
rsvg-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.png
new file mode 100644
index 0000000..dde7712
Binary files /dev/null and b/assets/livermore-real-demo.png differ
diff --git a/docs/LIVERMORE_DEMO.md b/docs/LIVERMORE_DEMO.md
new file mode 100644
index 0000000..8debaa3
--- /dev/null
+++ b/docs/LIVERMORE_DEMO.md
@@ -0,0 +1,77 @@
+# A bounded real-audio demonstration: Livermore
+
+![Real Livermore flyover spectrogram and constrained search scores](../assets/livermore-real-demo.png)
+
+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.py
new file mode 100644
index 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.py
new file mode 100644
index 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()