Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Python acoustic-geolocationads-baircraft-trackingairplaneaudio-forensicsdoppler-effectdoppler-shiftgeolocationosintsignal-processing
Feature automatic MP3 search beside configured example (#255)
Cinna Davis494b874a42d8
diff --git a/README.md b/README.mdindex 97f50da..cac3739 100644--- a/README.md+++ b/README.md@@ -4,6 +4,10 @@DOPPLERGEIST investigates **where an audio recording was made** by comparing the Doppler patterns of passing aircraft with historical flight trajectories. It combines acoustic measurements, aircraft motion, sound travel time and terrain to rank possible recording locations.+++<sub>From a real MP3, DOPPLERGEIST automatically detected a flyover and searched tracks from 466 aircraft. Its top candidate landed **476 m from an inferred reference**, using a city-sized search area and an approximately 10-second time window; [see the full results and limitations](docs/LIVERMORE_DEMO.md#all-aircraft-archive-mp3-ranking).</sub>+<sub>From a real aircraft flyover, DOPPLERGEIST’s highest-scoring point landed **481 m from a reference derived from other flight tracks**. This demonstration uses the known aircraft and a bounded time and area; [see the full results and limitations](docs/LIVERMORE_DEMO.md).</sub>diff --git a/assets/README.md b/assets/README.mdindex 02831b1..7913534 100644--- a/assets/README.md+++ b/assets/README.md@@ -66,3 +66,8 @@ published flight data. It uses USGS / USDA NAIP imagery and data from PraveenPathak'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.++`livermore-automatic-mp3.png` depicts the separate automatic MP3 upload and+its retained aircraft-search scores, using the same USGS / USDA NAIP imagery.+The [all-aircraft case study](../docs/LIVERMORE_DEMO.md#all-aircraft-archive-mp3-ranking)+describes the selected map points, inferred reference, and run limitations.diff --git a/assets/livermore-automatic-mp3.png b/assets/livermore-automatic-mp3.pngnew file mode 100644index 0000000..5e67d29Binary files /dev/null and b/assets/livermore-automatic-mp3.png differdiff --git a/docs/LIVERMORE_DEMO.md b/docs/LIVERMORE_DEMO.mdindex 7b4c559..9f92b23 100644--- a/docs/LIVERMORE_DEMO.md+++ b/docs/LIVERMORE_DEMO.md@@ -123,7 +123,10 @@ not to surveyed microphone truth.| 48 | 37.661666 | -121.787273 | 0.901372 | 506 m |The [complete 105-candidate ranking](../benchmarks/livermore-all-aircraft-ranking-20261103.json)-is retained in original order. Scores are fit measures, not probabilities.+is retained in original order. The README figure plots the highest retained+score per receiver point from the saved search tiles and highlights ranks 1 and+10; it is a cropped map, not a plot of every searched point. Scores are fit+measures, not probabilities.Despite full declared archive coverage, the result remains **inconclusive**:187 CPA track evaluations exceeded the supported trajectory model. The scoreralso recorded 725,947 unknown clock trials across 40,531 candidate envelopes,@@ -172,6 +175,15 @@ PYTHONPATH=src python scripts/render_livermore_demo.py \results/livermore-run results/livermore-naip.jpg results/livermore-demo.png```+To reproduce the automatic MP3 figure from its saved job directory, the same+NAIP image, and the flight index used by that job:++```bash+PYTHONPATH=src python scripts/render_livermore_automatic.py \+ path/to/automatic-upload-job path/to/all-aircraft-index.sqlite \+ results/livermore-naip.jpg results/livermore-automatic.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 ofthe related dataset's reconstructed reference and other real-data work.diff --git a/scripts/render_livermore_automatic.py b/scripts/render_livermore_automatic.pynew file mode 100644index 0000000..e26be37--- /dev/null+++ b/scripts/render_livermore_automatic.py@@ -0,0 +1,114 @@+#!/usr/bin/env python3+"""Render the saved real MP3 upload's spectrogram and retained search scores."""+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.audio import spectrogram+from dopplergeist.data_access import FlightIndex+from dopplergeist.geometry import ecef+from dopplergeist.matching import predict_fitted_ridge++# Extent of the documented USGS image request, WGS84.+BBOX = (-121.82, 37.642, -121.74, 37.687)+REFERENCE = (37.66321511833046, -121.78187655936314)+++def main():+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument('job', type=Path, help='Completed local MP3 upload job directory')+ parser.add_argument('flight_index', type=Path, help='Flight index used by the job')+ parser.add_argument('imagery', type=Path, help='USGS NAIP image for the documented extent')+ parser.add_argument('output', type=Path)+ args = parser.parse_args()++ result = json.loads((args.job / 'result.json').read_text())+ refined = json.loads((args.job / 'refined-candidates.json').read_text())['ranked']+ discovery = json.loads((args.job / 'discovery/discovery.json').read_text())+ recording = json.loads((args.job / 'intake/recording.json').read_text())+ best = refined[0]+ if (best['lat'], best['lon'], best['score']) != tuple(result['candidates'][0][k] for k in ('lat', 'lon', 'score')):+ raise ValueError('Refined winner and API ranking do not match')+ geod = Geod(ellps='WGS84')+ alternative = next(row for row in result['candidates'][1:]+ if geod.inv(best['lon'], best['lat'], row['lon'], row['lat'])[2] >= 250)+ distances = [geod.inv(REFERENCE[1], REFERENCE[0], row['lon'], row['lat'])[2]+ for row in (best, alternative)]++ event = next(item for item in discovery['events'] if item['event_id'] == best['event_ids'][0])+ sample_rate = recording['sample_rate_hz']+ samples = np.memmap(args.job / 'intake/recording.f32', dtype='<f4', mode='r')+ spec = spectrogram(np.asarray(samples), sample_rate, event['band_hz'])+ tracks = list(FlightIndex(args.flight_index).lookup(best['flight_ids']))+ by_id = {track.id: track for track in tracks}+ track = by_id[best['flight_ids'][0]]+ diagnostic = dict(best['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'] + spec.time, diagnostic)++ # Each tile retained its highest-scoring hypotheses. Plot the best retained+ # score per receiver point; absent points are not interpolated or scored here.+ points = {}+ for tile in sorted((args.job / 'search').glob('tile-*.json')):+ for row in json.loads(tile.read_text())['payload']['ranked']:+ key = (row['lat'], row['lon'])+ points[key] = max(points.get(key, float('-inf')), row['score'])+ if not points:+ raise ValueError('No retained tile scores found')+ coords = np.array(list(points))+ scores = np.array(list(points.values()))+ order = np.argsort(scores)++ 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=.18, top=.86, wspace=.16)+ ax = fig.add_subplot(gs[0, 0])+ ax.pcolormesh(spec.time, spec.frequency, spec.contrast, shading='auto', cmap='Blues',+ vmin=0, vmax=5, rasterized=True)+ ax.plot(spec.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)))+ 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)+ dots = ax.scatter(coords[order, 1], coords[order, 0], 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(alternative['lon'], alternative['lat'], s=95, marker='D', facecolor='#69d5c8',+ edgecolor='#17242c', linewidth=1, zorder=6)+ ax.scatter(best['lon'], best['lat'], s=145, marker='*', facecolor='#f5d55c',+ edgecolor='#17242c', linewidth=1, zorder=7)+ ax.set(xlim=(west, east), ylim=(south, north)); ax.set_xticks([]); ax.set_yticks([])+ ax.set_title('The search, up close', fontsize=20, fontweight='normal', pad=15)+ scale_lon = geod.fwd(west + .005, south + .005, 90, 1000)[0]+ ax.plot([west + .005, scale_lon], [south + .005, south + .005], color='white', lw=5, zorder=8)+ ax.plot([west + .005, scale_lon], [south + .005, south + .005], color='#17242c', lw=2, zorder=9)+ ax.text(west + .005, south + .0075, '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('Retained fit score · higher is better', fontsize=9)+ cb.ax.tick_params(labelsize=8)+ fig.text(.5, .078, f'★ Highest score ({distances[0]:.0f} m) ◆ Alternative ({distances[1]:.0f} m)'+ ' ● Inferred reference — Aircraft track', ha='center', fontsize=10, color='#334451')+ fig.text(.065, .035, '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}: {len(points)} retained points; {distances[0]:.1f} m and {distances[1]:.1f} m from inferred reference')+++if __name__ == '__main__':+ main()