Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Python acoustic-geolocationads-baircraft-trackingairplaneaudio-forensicsdoppler-effectdoppler-shiftgeolocationosintsignal-processing
chore: declutter repository root and repair documentation links (#408)
Cinna Davis322ee1cac854
diff --git a/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.mdsimilarity index 100%rename from CODE_OF_CONDUCT.mdrename to .github/CODE_OF_CONDUCT.mddiff --git a/CONTRIBUTING.md b/.github/CONTRIBUTING.mdsimilarity index 80%rename from CONTRIBUTING.mdrename to .github/CONTRIBUTING.mdindex 70a30c5..d315bf5 100644--- a/CONTRIBUTING.md+++ b/.github/CONTRIBUTING.md@@ -9,10 +9,10 @@ real-recording evaluation, and reproducibility are welcome. Please follow the- Search the [issues](https://github.com/1337isnot1337/DOPPLERGEIST/issues) and[discussions](https://github.com/1337isnot1337/DOPPLERGEIST/discussions) forrelated work. Open an issue to discuss substantial changes or a new approach.-- Read the [README](README.md) for current capabilities and limitations. For- data and research changes, see [data sources](docs/DATA_SOURCES.md),- [data and search](docs/DATA_AND_SCALE.md), and the relevant documentation.-- Project agents should also follow [AGENTS.md](AGENTS.md), including its+- Read the [README](../README.md) for current capabilities and limitations. For+ data and research changes, see [data sources](../docs/DATA_SOURCES.md),+ [data and search](../docs/DATA_AND_SCALE.md), and the relevant documentation.+- Project agents should also follow [AGENTS.md](../AGENTS.md), including itscoordination and real-world-data rules.## Development@@ -27,7 +27,7 @@ python -m venv .venvMake a focused change and run checks relevant to it. The standard CI workflowchecks installation, compilation, CLI help, packaged assets and selected-real-input behavior; see [.github/workflows/tests.yml](.github/workflows/tests.yml).+real-input behavior; see [.github/workflows/tests.yml](workflows/tests.yml).Do not run the entire pytest suite indiscriminately: it includes synthetic-datatests. The project currently requires real recordings and real-world observationsfor empirical evaluation and prohibits new synthetic-data suites or generated@@ -40,7 +40,7 @@ all outcomes, including failures and inconclusive results. Distinguish regional,selected, or assisted experiments from independent end-to-end validation; do notuse evaluation truth as an input to an automatic search. Do not publish recordings,coordinates, credentials, or other sensitive material without permission. Follow-[artifact guidance](docs/ARTIFACTS.md) and source-specific terms.+[artifact guidance](../docs/ARTIFACTS.md) and source-specific terms.## Pull requests@@ -48,7 +48,7 @@ Open a pull request describing the problem, the change, and the checks performedlink the relevant issue when there is one. Explain limitations and any changes tointerfaces, data, or dependencies. Keep unrelated work separate and respond toreview feedback. Contributions are subject to the repository's-[license](LICENSE); the [legacy notice](licenses/MIT-legacy.txt) preserves+[license](../LICENSE); the [legacy notice](../licenses/MIT-legacy.txt) preservespreviously granted MIT rights, and third-party materials may have separate terms.For vulnerabilities, use the private process in [SECURITY.md](SECURITY.md), notdiff --git a/SECURITY.md b/.github/SECURITY.mdsimilarity index 100%rename from SECURITY.mdrename to .github/SECURITY.mddiff --git a/README.md b/README.mdindex 4b95efe..bf4bd73 100644--- a/README.md+++ b/README.md@@ -2,7 +2,7 @@<h1 align="center">DOPPLERGEIST</h1><p align="center">Aircraft Doppler Audio Geolocation</p><p align="center">- <img src="assets/dopplergeist-banner.svg" alt="DOPPLERGEIST — Acoustic geolocation through Doppler analysis" width="100%">+ <img src="docs/assets/dopplergeist-banner.svg" alt="DOPPLERGEIST — Acoustic geolocation through Doppler analysis" width="100%"></p><p align="center">@@ -17,7 +17,7 @@<h3 align="center">Example: automatic MP3 analysis</h3>-+<sub>Automatic MP3 analysis selected 466 aircraft and ranked 105 candidate locations. The first candidate was **476 m from an inferred reference** in a constrained geographic search and approximately 10-second clock window. The reference was not surveyed, and the result was inconclusive. [Experiment and ranking](docs/LIVERMORE_DEMO.md#all-aircraft-archive-mp3-ranking).</sub>@@ -151,7 +151,7 @@ In a constrained real-MP3 demonstration, the highest-ranked location was **476 m### Is DOPPLERGEIST free and open source?-DOPPLERGEIST is **source-available, not OSI-approved open source**. It is licensed under [PolyForm Noncommercial 1.0.0](LICENSE), which permits use, modification, and distribution for permitted noncommercial purposes, subject to its terms. Commercial use outside those permissions requires separate authorization; see [Commercial licensing](COMMERCIAL-LICENSING.md).+DOPPLERGEIST is **source-available, not OSI-approved open source**. It is licensed under [PolyForm Noncommercial 1.0.0](LICENSE), which permits use, modification, and distribution for permitted noncommercial purposes, subject to its terms. Commercial use outside those permissions requires separate authorization; see [Commercial licensing](docs/COMMERCIAL-LICENSING.md).## Validation and results@@ -186,13 +186,13 @@ Optional native backends, reuse of acoustic calculations, and checkpointed searc## License-DOPPLERGEIST is distributed under the **[PolyForm Noncommercial License 1.0.0](LICENSE)** (`PolyForm-Noncommercial-1.0.0`). It is **source-available, not OSI-approved open-source software**. Noncommercial uses, modification, and distribution are permitted subject to the license. Commercial use not otherwise permitted requires authorization from the relevant rights holders. See [Commercial licensing](COMMERCIAL-LICENSING.md).+DOPPLERGEIST is distributed under the **[PolyForm Noncommercial License 1.0.0](LICENSE)** (`PolyForm-Noncommercial-1.0.0`). It is **source-available, not OSI-approved open-source software**. Noncommercial uses, modification, and distribution are permitted subject to the license. Commercial use not otherwise permitted requires authorization from the relevant rights holders. See [Commercial licensing](docs/COMMERCIAL-LICENSING.md).Recordings, aircraft archives, terrain datasets, and other third-party materials retain their own licenses, rights, and attribution requirements.## Contributing and development-Contributions, reproducible test recordings with appropriate permissions, documentation improvements, and independently verifiable evaluations are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md), the [issue tracker](https://github.com/1337isnot1337/DOPPLERGEIST/issues), and the [development discussion](https://github.com/1337isnot1337/DOPPLERGEIST/discussions/39).+Contributions, reproducible test recordings with appropriate permissions, documentation improvements, and independently verifiable evaluations are welcome. See [CONTRIBUTING.md](.github/CONTRIBUTING.md), the [issue tracker](https://github.com/1337isnot1337/DOPPLERGEIST/issues), and the [development discussion](https://github.com/1337isnot1337/DOPPLERGEIST/discussions/39).Created by **Cinna Davis** with extensive AI-assisted development. Thanks to @henriklied, @EirikAskheim, @kleindotc, and other contributors. Follow updates on [X](https://x.com/1337isnot1337) or [LinkedIn](https://www.linkedin.com/in/cinna-davis/).diff --git a/COMMERCIAL-LICENSING.md b/docs/COMMERCIAL-LICENSING.mdsimilarity index 88%rename from COMMERCIAL-LICENSING.mdrename to docs/COMMERCIAL-LICENSING.mdindex ae91e3d..53a5d62 100644--- a/COMMERCIAL-LICENSING.md+++ b/docs/COMMERCIAL-LICENSING.md@@ -1,7 +1,7 @@# Commercial licensing and license historyDOPPLERGEIST's current source distribution is offered under the-[PolyForm Noncommercial License 1.0.0](LICENSE). This permits use, modification,+[PolyForm Noncommercial License 1.0.0](../LICENSE). This permits use, modification,and redistribution for noncommercial purposes as defined by that license.Commercial uses that are not otherwise authorized require a separate licensefrom the appropriate copyright holders. To discuss a commercial license, contact@@ -15,7 +15,7 @@ granted for those versions or for previously MIT-licensed code. Copies legitimatobtained under MIT may continue to be used under those MIT permissions.The earlier MIT permission and copyright notice are preserved in-[`licenses/MIT-legacy.txt`](licenses/MIT-legacy.txt), including for compliance+[`licenses/MIT-legacy.txt`](../licenses/MIT-legacy.txt), including for compliancewith existing notice obligations. Its presence is not intended to describenew contributions after this license change as MIT-licensed, but it does notlimit rights already granted under MIT.diff --git a/docs/LIVERMORE_DEMO.md b/docs/LIVERMORE_DEMO.mdindex 9f92b23..1f91c03 100644--- a/docs/LIVERMORE_DEMO.md+++ b/docs/LIVERMORE_DEMO.md@@ -1,6 +1,6 @@# A bounded real-audio demonstration: Livermore-+This is a configured research run on **N784MB_R04**, a smartphone recording andan accompanying aircraft track from [Praveen Pathak's Livermore dataset](https://doi.org/10.5281/zenodo.23424278)diff --git a/docs/PYPI.md b/docs/PYPI.mdindex f335f42..6293cd4 100644--- a/docs/PYPI.md+++ b/docs/PYPI.md@@ -50,4 +50,4 @@ PyPI does not allow replacement of an uploaded distribution file. If a release i- `ffmpeg` and `ffprobe` are system dependencies. The PyPI wheel does not contain them.- Optional native C accelerators use platform-specific wheels. The source archive supports builds with a suitable compiler.- Distribution files include the browser application's assets and the PolyForm Noncommercial and MIT-legacy notices.-- PyPI publication does not grant commercial-use rights. See [commercial licensing](../COMMERCIAL-LICENSING.md).+- PyPI publication does not grant commercial-use rights. See [commercial licensing](COMMERCIAL-LICENSING.md).diff --git a/docs/PYPI_README.md b/docs/PYPI_README.mdindex 623f19b..9cc8173 100644--- a/docs/PYPI_README.md+++ b/docs/PYPI_README.md@@ -1,10 +1,10 @@# DOPPLERGEIST-+**DOPPLERGEIST** is a Python CLI and local web application for aircraft Doppler audio geolocation. It detects candidate flyover signals in recordings, retrieves historical ADS-B flight tracks, models acoustic propagation, and ranks possible recording locations.-+The illustrated real-recording experiment ranked a location 476 m from an *inferred* reference within a constrained search. The reference was not surveyed ground truth; independent blind geolocation accuracy has not been established. [Read the experiment](https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/LIVERMORE_DEMO.md).@@ -61,4 +61,4 @@ dopplergeist analyze recording.mp3 --jobs jobs \## License-**PolyForm Noncommercial License 1.0.0.** Noncommercial uses are permitted under the terms of that license; commercial uses that are not otherwise authorized need a separate agreement with the applicable copyright holders. Earlier MIT-licensed releases retain the permissions originally granted for those versions. [Commercial licensing details](https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/COMMERCIAL-LICENSING.md).+**PolyForm Noncommercial License 1.0.0.** Noncommercial uses are permitted under the terms of that license; commercial uses that are not otherwise authorized need a separate agreement with the applicable copyright holders. Earlier MIT-licensed releases retain the permissions originally granted for those versions. [Commercial licensing details](https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/COMMERCIAL-LICENSING.md).diff --git a/assets/README.md b/docs/assets/README.mdsimilarity index 85%rename from assets/README.mdrename to docs/assets/README.mdindex 8f1515c..8582fde 100644--- a/assets/README.md+++ b/docs/assets/README.md@@ -28,9 +28,9 @@ wide after any edit.Render previews with librsvg:```bash-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+rsvg-convert docs/assets/dopplergeist-banner.svg \+ -o docs/assets/dopplergeist-banner-preview.png+rsvg-convert -w 600 docs/assets/dopplergeist-banner.svg -o /tmp/dopplergeist-banner-600.png```## Livermore demonstration@@ -38,10 +38,10 @@ rsvg-convert -w 600 assets/dopplergeist-banner.svg -o /tmp/dopplergeist-banner-6`livermore-real-demo.png` shows a real recording and a configured search overpublished 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)+[Setup, limitations and rendering instructions](../LIVERMORE_DEMO.md)explain the inferred reference and the incomplete model assessment.`livermore-automatic-mp3.png` depicts the separate automatic MP3 upload andits 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)+The [all-aircraft case study](../LIVERMORE_DEMO.md#all-aircraft-archive-mp3-ranking)describes the selected map points, inferred reference, and run limitations.diff --git a/assets/dopplergeist-banner-preview.png b/docs/assets/dopplergeist-banner-preview.pngsimilarity index 100%rename from assets/dopplergeist-banner-preview.pngrename to docs/assets/dopplergeist-banner-preview.pngdiff --git a/assets/dopplergeist-banner.svg b/docs/assets/dopplergeist-banner.svgsimilarity index 100%rename from assets/dopplergeist-banner.svgrename to docs/assets/dopplergeist-banner.svgdiff --git a/assets/livermore-automatic-mp3.png b/docs/assets/livermore-automatic-mp3.pngsimilarity index 100%rename from assets/livermore-automatic-mp3.pngrename to docs/assets/livermore-automatic-mp3.pngdiff --git a/assets/livermore-real-demo.png b/docs/assets/livermore-real-demo.pngsimilarity index 100%rename from assets/livermore-real-demo.pngrename to docs/assets/livermore-real-demo.pngdiff --git a/docs/examples.html b/docs/examples.htmlindex a6caad7..828b6aa 100644--- a/docs/examples.html+++ b/docs/examples.html@@ -62,7 +62,7 @@</main><footer class="wrap"><a class="brand" href="./">DOPPLERGEIST</a>-<nav aria-label="Footer navigation"><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/SETUP.md">Documentation</a><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/LICENSE">License</a><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/COMMERCIAL-LICENSING.md">Commercial use</a></nav>+<nav aria-label="Footer navigation"><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/SETUP.md">Documentation</a><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/LICENSE">License</a><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/COMMERCIAL-LICENSING.md">Commercial use</a></nav></footer></body></html>diff --git a/docs/how-it-works.html b/docs/how-it-works.htmlindex f28e616..4d7f0a6 100644--- a/docs/how-it-works.html+++ b/docs/how-it-works.html@@ -80,7 +80,7 @@ python -m venv .venv</main><footer class="wrap"><a class="brand" href="./">DOPPLERGEIST</a>-<nav aria-label="Footer navigation"><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/SETUP.md">Documentation</a><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/LICENSE">License</a><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/COMMERCIAL-LICENSING.md">Commercial use</a></nav>+<nav aria-label="Footer navigation"><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/SETUP.md">Documentation</a><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/LICENSE">License</a><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/COMMERCIAL-LICENSING.md">Commercial use</a></nav></footer></body></html>diff --git a/docs/index.html b/docs/index.htmlindex 5f5efea..6a31d1b 100644--- a/docs/index.html+++ b/docs/index.html@@ -80,7 +80,7 @@</main><footer class="wrap"><a class="brand" href="./">DOPPLERGEIST</a>-<nav aria-label="Footer navigation"><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/SETUP.md">Documentation</a><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/LICENSE">License</a><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/COMMERCIAL-LICENSING.md">Commercial use</a></nav>+<nav aria-label="Footer navigation"><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/SETUP.md">Documentation</a><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/LICENSE">License</a><a href="https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/COMMERCIAL-LICENSING.md">Commercial use</a></nav></footer></body></html>