meteorlens 0.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. meteorlens-0.0.0/LICENSE +21 -0
  2. meteorlens-0.0.0/NOTICE +10 -0
  3. meteorlens-0.0.0/PKG-INFO +283 -0
  4. meteorlens-0.0.0/README.md +252 -0
  5. meteorlens-0.0.0/pyproject.toml +62 -0
  6. meteorlens-0.0.0/setup.cfg +4 -0
  7. meteorlens-0.0.0/src/meteorlens/__init__.py +4 -0
  8. meteorlens-0.0.0/src/meteorlens/__main__.py +4 -0
  9. meteorlens-0.0.0/src/meteorlens/astrometry.py +398 -0
  10. meteorlens-0.0.0/src/meteorlens/calibrate.py +797 -0
  11. meteorlens-0.0.0/src/meteorlens/capture.py +225 -0
  12. meteorlens-0.0.0/src/meteorlens/cli.py +103 -0
  13. meteorlens-0.0.0/src/meteorlens/config.py +504 -0
  14. meteorlens-0.0.0/src/meteorlens/control.py +154 -0
  15. meteorlens-0.0.0/src/meteorlens/data/config.example.ini +125 -0
  16. meteorlens-0.0.0/src/meteorlens/data/mask.example.png +0 -0
  17. meteorlens-0.0.0/src/meteorlens/data/showers.csv +112 -0
  18. meteorlens-0.0.0/src/meteorlens/data/star_names.csv +36 -0
  19. meteorlens-0.0.0/src/meteorlens/data/stars_hip.csv +2817 -0
  20. meteorlens-0.0.0/src/meteorlens/detect.py +377 -0
  21. meteorlens-0.0.0/src/meteorlens/filters.py +4 -0
  22. meteorlens-0.0.0/src/meteorlens/media.py +120 -0
  23. meteorlens-0.0.0/src/meteorlens/metrics.py +96 -0
  24. meteorlens-0.0.0/src/meteorlens/outputs.py +126 -0
  25. meteorlens-0.0.0/src/meteorlens/runner.py +404 -0
  26. meteorlens-0.0.0/src/meteorlens/showers.py +129 -0
  27. meteorlens-0.0.0/src/meteorlens/store.py +705 -0
  28. meteorlens-0.0.0/src/meteorlens/synth.py +87 -0
  29. meteorlens-0.0.0/src/meteorlens/thumbs.py +113 -0
  30. meteorlens-0.0.0/src/meteorlens/video.py +106 -0
  31. meteorlens-0.0.0/src/meteorlens/web/__init__.py +4 -0
  32. meteorlens-0.0.0/src/meteorlens/web/app.py +96 -0
  33. meteorlens-0.0.0/src/meteorlens/web/formatting.py +91 -0
  34. meteorlens-0.0.0/src/meteorlens/web/labels.py +44 -0
  35. meteorlens-0.0.0/src/meteorlens/web/live.py +35 -0
  36. meteorlens-0.0.0/src/meteorlens/web/routes/__init__.py +7 -0
  37. meteorlens-0.0.0/src/meteorlens/web/routes/api.py +155 -0
  38. meteorlens-0.0.0/src/meteorlens/web/routes/control.py +22 -0
  39. meteorlens-0.0.0/src/meteorlens/web/routes/media.py +65 -0
  40. meteorlens-0.0.0/src/meteorlens/web/routes/pages.py +105 -0
  41. meteorlens-0.0.0/src/meteorlens/web/setup.py +325 -0
  42. meteorlens-0.0.0/src/meteorlens/web/skymap.py +180 -0
  43. meteorlens-0.0.0/src/meteorlens/web/static/app.css +171 -0
  44. meteorlens-0.0.0/src/meteorlens/web/static/js/dashboard.js +380 -0
  45. meteorlens-0.0.0/src/meteorlens/web/static/js/gallery.js +84 -0
  46. meteorlens-0.0.0/src/meteorlens/web/static/js/header.js +26 -0
  47. meteorlens-0.0.0/src/meteorlens/web/static/js/settings.js +54 -0
  48. meteorlens-0.0.0/src/meteorlens/web/static/js/setup.js +519 -0
  49. meteorlens-0.0.0/src/meteorlens/web/static/setup.css +114 -0
  50. meteorlens-0.0.0/src/meteorlens/web/templates/_macros.html +71 -0
  51. meteorlens-0.0.0/src/meteorlens/web/templates/_nav.html +7 -0
  52. meteorlens-0.0.0/src/meteorlens/web/templates/base.html +30 -0
  53. meteorlens-0.0.0/src/meteorlens/web/templates/dashboard.html +94 -0
  54. meteorlens-0.0.0/src/meteorlens/web/templates/gallery.html +33 -0
  55. meteorlens-0.0.0/src/meteorlens/web/templates/settings.html +27 -0
  56. meteorlens-0.0.0/src/meteorlens/web/templates/setup.html +290 -0
  57. meteorlens-0.0.0/src/meteorlens.egg-info/PKG-INFO +283 -0
  58. meteorlens-0.0.0/src/meteorlens.egg-info/SOURCES.txt +81 -0
  59. meteorlens-0.0.0/src/meteorlens.egg-info/dependency_links.txt +1 -0
  60. meteorlens-0.0.0/src/meteorlens.egg-info/entry_points.txt +3 -0
  61. meteorlens-0.0.0/src/meteorlens.egg-info/requires.txt +10 -0
  62. meteorlens-0.0.0/src/meteorlens.egg-info/top_level.txt +1 -0
  63. meteorlens-0.0.0/tests/test_astrometry.py +281 -0
  64. meteorlens-0.0.0/tests/test_control.py +110 -0
  65. meteorlens-0.0.0/tests/test_csv.py +41 -0
  66. meteorlens-0.0.0/tests/test_detect_synthetic.py +62 -0
  67. meteorlens-0.0.0/tests/test_e2e.py +113 -0
  68. meteorlens-0.0.0/tests/test_features.py +96 -0
  69. meteorlens-0.0.0/tests/test_media.py +98 -0
  70. meteorlens-0.0.0/tests/test_metrics.py +105 -0
  71. meteorlens-0.0.0/tests/test_purge.py +130 -0
  72. meteorlens-0.0.0/tests/test_record.py +92 -0
  73. meteorlens-0.0.0/tests/test_reference_clip.py +46 -0
  74. meteorlens-0.0.0/tests/test_regression.py +64 -0
  75. meteorlens-0.0.0/tests/test_runner.py +133 -0
  76. meteorlens-0.0.0/tests/test_settings.py +159 -0
  77. meteorlens-0.0.0/tests/test_setup.py +309 -0
  78. meteorlens-0.0.0/tests/test_showers.py +74 -0
  79. meteorlens-0.0.0/tests/test_store.py +486 -0
  80. meteorlens-0.0.0/tests/test_thumbs.py +71 -0
  81. meteorlens-0.0.0/tests/test_tuning_tools.py +130 -0
  82. meteorlens-0.0.0/tests/test_video.py +59 -0
  83. meteorlens-0.0.0/tests/test_web.py +179 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 MeteorLens contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,10 @@
1
+ MeteorLens bundles the following data files:
2
+
3
+ - `showers.csv` - meteor shower catalog derived from the IAU Meteor Data Center.
4
+ See https://www.iaa.csic.es/IAU_MDC/ for the original catalog and citation
5
+ requirements.
6
+ - `stars_hip.csv` - bright-star subset of the Hipparcos catalogue (ESA, 1997).
7
+ - `star_names.csv` - common star names used for optional labels.
8
+
9
+ These files are data, not code, and remain subject to their upstream terms.
10
+ If you redistribute MeteorLens, keep this notice together with the data.
@@ -0,0 +1,283 @@
1
+ Metadata-Version: 2.4
2
+ Name: meteorlens
3
+ Version: 0.0.0
4
+ Summary: Local-first meteor detection from IP cameras
5
+ Author: MeteorLens contributors
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/svatec/meteorlens
8
+ Keywords: meteor,astronomy,opencv,rtsp,camera,detection
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Environment :: Console
11
+ Classifier: Intended Audience :: Science/Research
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Topic :: Scientific/Engineering :: Astronomy
18
+ Requires-Python: >=3.11
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ License-File: NOTICE
22
+ Requires-Dist: numpy>=1.26
23
+ Requires-Dist: opencv-python-headless>=4.9
24
+ Requires-Dist: flask>=3.0
25
+ Provides-Extra: calibrate
26
+ Requires-Dist: scipy>=1.11; extra == "calibrate"
27
+ Provides-Extra: dev
28
+ Requires-Dist: pytest>=8; extra == "dev"
29
+ Requires-Dist: ruff>=0.6; extra == "dev"
30
+ Dynamic: license-file
31
+
32
+ # MeteorLens
33
+
34
+ Local-first meteor detection from IP cameras. MeteorLens records RTSP segments,
35
+ detects meteors with OpenCV, stores events in SQLite, and serves a dashboard,
36
+ a detections gallery, and a small control/settings page.
37
+
38
+ The project is an early community edition (v0.1.0, alpha). The detection core is
39
+ shared with a private production deployment; the community edition deliberately
40
+ drops publishing features (Instagram Reels, stories, timelapse) and keeps the
41
+ pipeline easy to run and extend.
42
+
43
+ ## Requirements
44
+
45
+ - Python 3.11 or newer
46
+ - `ffmpeg` and `ffprobe` on `PATH`
47
+ - An RTSP camera (tested with Tapo C325WB; any camera that exposes H.264 over RTSP
48
+ should work, but thresholds and masks are scene-specific), or a folder with
49
+ existing MKV segments for analysis-only use
50
+
51
+ ## Quick start
52
+
53
+ ```bash
54
+ git clone https://github.com/svatec/meteorlens.git
55
+ cd meteorlens
56
+ python3 -m venv .venv
57
+ . .venv/bin/activate
58
+ pip install -e ".[dev]"
59
+
60
+ meteorlens serve
61
+ ```
62
+
63
+ Open <http://127.0.0.1:8765>. On a fresh home MeteorLens starts the setup wizard
64
+ instead of the dashboard:
65
+
66
+ 1. choose an RTSP camera or a folder with existing MKV segments,
67
+ 2. set the observing location,
68
+ 3. test the camera stream (codec, resolution, frame rate, bitrate),
69
+ 4. pick storage and recording defaults,
70
+ 5. choose a detection profile.
71
+
72
+ The wizard writes `config.ini` atomically with mode `0600` and creates the data
73
+ directories. An existing file is backed up to `config.ini.bak`; the camera URL is
74
+ never shown again. Re-run the wizard from Settings or `/setup`.
75
+ [Setup wizard screenshot](docs/screenshots/setup.png).
76
+
77
+ To configure manually instead:
78
+
79
+ ```bash
80
+ cp config.example.ini config.ini
81
+ # edit camera.rtsp_url, location.latitude and location.longitude
82
+ meteorlens serve
83
+ ```
84
+
85
+ The dashboard and gallery are read-only until you start recording or analysis
86
+ from the control page.
87
+
88
+ Run the recorder and the analyzer as separate long-lived processes:
89
+
90
+ ```bash
91
+ meteorlens record # capture RTSP segments while it is dark
92
+ meteorlens run # analyse new segments (cron/systemd timer or manually)
93
+ ```
94
+
95
+ `meteorlens serve` is a local tool: it binds to `127.0.0.1` by default, has no
96
+ authentication and must not be exposed to the internet without a reverse proxy
97
+ and access control.
98
+
99
+ ## Demo data and screenshots
100
+
101
+ You do not need a camera to explore the UI. The demo builder creates three
102
+ deterministic synthetic clips, runs the real analyser, labels two meteors and
103
+ one aircraft candidate, and exports the demo home:
104
+
105
+ ```bash
106
+ python docs/demo/make_demo.py --home /tmp/meteorlens-demo
107
+ METEORLENS_HOME=/tmp/meteorlens-demo meteorlens serve
108
+ ```
109
+
110
+ The demo home contains no personal data; delete it when done. Screenshots from
111
+ this demo: [Dashboard](docs/screenshots/dashboard.png),
112
+ [Detections](docs/screenshots/detections.png),
113
+ [Settings](docs/screenshots/settings.png). The live panel shows "Camera
114
+ unavailable" because the demo has no RTSP camera, and the sky map falls back to
115
+ the camera axis because the demo has no calibration.
116
+
117
+ ## Configuration
118
+
119
+ MeteorLens reads `config.ini` from `METEORLENS_HOME` (default: the current
120
+ directory). Relative paths in `[paths]` are resolved against the same directory.
121
+
122
+ - `[camera]` is never shown in the UI and never written by the settings page.
123
+ The first-run wizard is the only web path that writes it; the file is mode `0600`.
124
+ - `[detect]` contains the detection thresholds. Change them only together with
125
+ the regression tests; the project treats threshold changes as behaviour changes.
126
+ - `[calibration]` is optional. Without it, events have no azimuth/altitude angles
127
+ and the sky map falls back to the camera axis.
128
+ - `[showers]` enables meteor-shower association from the bundled IAU-derived
129
+ catalogue.
130
+
131
+ Runtime layout:
132
+
133
+ ```
134
+ config.ini
135
+ data/
136
+ recordings/active/ # segment being written
137
+ recordings/ready/ # finished MKV segments (UTC names)
138
+ detections/ # clips, thumbnails, events.csv, tracks.csv
139
+ state/ # SQLite database, logs, locks, control state
140
+ ```
141
+
142
+ ## Commands
143
+
144
+ | Command | Description |
145
+ |---|---|
146
+ | `meteorlens record` | Record RTSP segments while the Sun is below the configured altitude. |
147
+ | `meteorlens run` | Analyse new segments. `--reprocess`, `--before`, `--after` control the range. |
148
+ | `meteorlens file FILE` | Analyse one file; `-v` prints rejected tracks, `--dry` writes nothing. |
149
+ | `meteorlens snapshot [FILE]` | Save a frame as `mask_template.png` for drawing a sky mask. |
150
+ | `meteorlens serve` | Start the local web UI; an incomplete config opens the setup wizard. |
151
+ | `meteorlens index` | Rebuild the static `detections/index.html` page. |
152
+ | `meteorlens export` | Export the SQLite database to CSV/JSON. |
153
+ | `meteorlens purge [--dry]` | Delete events labelled as insect/aircraft/cloud/satellite. |
154
+ | `meteorlens bench FILE` | Measure analysis speed and suggest worker settings. |
155
+ | `meteorlens-calibrate` | Solve the camera model from stars (requires `pip install -e ".[calibrate]"`). |
156
+
157
+ ## Calibration and masks
158
+
159
+ The bundled mask is only an example. For your own camera:
160
+
161
+ ```bash
162
+ meteorlens snapshot data/recordings/ready/YYYYMMDD_HHMMSS.mkv
163
+ # paint everything except the sky black, save as mask.png, then set in config.ini:
164
+ # [detect] mask = mask.png
165
+ ```
166
+
167
+ Camera calibration (focal length, orientation) is optional and uses `scipy`:
168
+
169
+ ```bash
170
+ pip install -e ".[calibrate]"
171
+ meteorlens-calibrate solve --video FILE --at 60 --lat 48.0 --lon 17.0 \
172
+ --az 270 --alt 35 --out calibration.json
173
+ # then set [calibration] file = calibration.json
174
+ ```
175
+
176
+ ## Architecture
177
+
178
+ ```
179
+ camera --RTSP--> meteorlens record --> data/recordings/ready/*.mkv
180
+ |
181
+ v
182
+ meteorlens run (multiprocessing)
183
+ |
184
+ SQLite + clips/thumbnails + CSV exports
185
+ |
186
+ v
187
+ meteorlens serve (Flask, localhost)
188
+ ```
189
+
190
+ - `capture.py` - ffmpeg segment recorder and disk guard.
191
+ - `detect.py` - frame differencing, blob tracking, track classification.
192
+ - `astrometry.py`, `showers.py` - angles, radiant and shower association.
193
+ - `store.py` - SQLite schema, migrations, queries and exports.
194
+ - `runner.py` - parallel segment processing, clip cutting, retention/purge.
195
+ - `web/` - Flask app factory, first-run setup wizard, `routes/` blueprints (pages,
196
+ API, control, media), Jinja templates and static CSS/JS assets.
197
+ - `control.py` - starts/stops recorder and analyzer subprocesses.
198
+
199
+ Long-running work stays in subprocesses so ffmpeg and OpenCV cannot block the
200
+ web UI. The web process only reads the database and file outputs.
201
+
202
+ ## Development
203
+
204
+ ```bash
205
+ pip install -e ".[dev]"
206
+ pytest
207
+ ruff check .
208
+ ```
209
+
210
+ The regression suite uses synthetic meteors inserted into a noisy background,
211
+ so it runs without a camera. `pytest tests/test_e2e.py` exercises the real CLI
212
+ (`file`, `run`, `snapshot`, `index`, `export`, `purge --dry`) in a temporary
213
+ `METEORLENS_HOME`; recorder startup is covered with a mock ffmpeg process. A
214
+ real reference clip can be provided out of band:
215
+
216
+ ```bash
217
+ METEORLENS_REF_CLIP=/path/to/reference.mkv pytest tests/test_reference_clip.py
218
+ ```
219
+
220
+ Detection thresholds are scene-specific, so tune them by measuring instead of
221
+ guessing. The development tools in `tools/` are not part of the package:
222
+
223
+ ```bash
224
+ # one row per clip with the current config (no database writes)
225
+ python -m tools.sweep --clips data/recordings/ready --out /tmp/tune/baseline.csv
226
+
227
+ # grid over two thresholds; score the result against known counts
228
+ python -m tools.sweep --clips tests/clips --grid diff_threshold=14,18,22 \
229
+ --grid min_speed=100,120 --out /tmp/tune/grid.csv --detail /tmp/tune/events.csv
230
+ python -m tools.score --sweep /tmp/tune/grid.csv --expect tests/clips/expected.json
231
+ ```
232
+
233
+ `--detail` writes one row per accepted and rejected track (span, speed, peak,
234
+ duration, reason), which is usually enough to see whether a false positive comes
235
+ from noise, a cloud edge, or the track-linking limits. A combination that scores
236
+ well belongs in `tests/clips/expected.json`; the clips themselves stay local
237
+ (`*.mkv`, `*.mp4` are ignored by git).
238
+
239
+ Do not commit camera recordings, `config.ini`, the database, or generated clips.
240
+
241
+ ## Troubleshooting
242
+
243
+ **`Missing configuration`** - `meteorlens run/file/record` read `config.ini` from
244
+ `METEORLENS_HOME` (default: current directory). Run `meteorlens serve` once:
245
+ without a complete config it opens the setup wizard at `/setup`, which writes
246
+ the file and creates the data directories. For analysis-only setups choose
247
+ "Existing recordings" and point the wizard at the MKV folder.
248
+
249
+ **`ffmpeg` or `ffprobe` not found** - install both and make sure they are on
250
+ `PATH`. Use `meteorlens bench FILE` to compare decoders and estimate worker
251
+ counts.
252
+
253
+ **The camera is unavailable** - test the stream outside MeteorLens
254
+ (`ffprobe -rtsp_transport tcp rtsp_url`). Try switching `camera.rtsp_transport`
255
+ between `udp` and `tcp`; UDP is usually better on lossy Wi-Fi, TCP on stable
256
+ networks. Credentials stay in `config.ini` and are never shown in the UI.
257
+
258
+ **No detections** - check focus, exposure and that the sky is dark; inspect
259
+ `meteorlens file CLIP -v` for rejected tracks. A scene mask and calibration
260
+ usually improve results. Detection thresholds are scene-specific; do not tune
261
+ them without running the regression suite.
262
+
263
+ **Sky map says calibration or location is missing** - the map needs
264
+ `[calibration] file` and `[location] latitude/longitude`. Without calibration,
265
+ events have no angles and the map falls back to the camera axis.
266
+
267
+ **Calibration fails with a scipy error** - install the optional extra:
268
+ `pip install -e ".[calibrate]"`.
269
+
270
+ **The web page has no styling or JavaScript** - the templates and static assets
271
+ must be installed with the package; reinstall with `pip install -e .` (or a
272
+ wheel built from this repository). Check `/static/app.css` returns 200.
273
+
274
+ **Port 8765 is already in use** - start with another port, for example
275
+ `meteorlens serve --port 8766`.
276
+
277
+ **`purge` refuses to run** - analysis or another purge holds `run.lock`; wait
278
+ for it to finish. Use `purge --dry` to see what would be deleted.
279
+
280
+ ## Data and licence
281
+
282
+ Code is released under the MIT licence (see `LICENSE`). Bundled catalogues are
283
+ described in `NOTICE`; keep that notice when redistributing.
@@ -0,0 +1,252 @@
1
+ # MeteorLens
2
+
3
+ Local-first meteor detection from IP cameras. MeteorLens records RTSP segments,
4
+ detects meteors with OpenCV, stores events in SQLite, and serves a dashboard,
5
+ a detections gallery, and a small control/settings page.
6
+
7
+ The project is an early community edition (v0.1.0, alpha). The detection core is
8
+ shared with a private production deployment; the community edition deliberately
9
+ drops publishing features (Instagram Reels, stories, timelapse) and keeps the
10
+ pipeline easy to run and extend.
11
+
12
+ ## Requirements
13
+
14
+ - Python 3.11 or newer
15
+ - `ffmpeg` and `ffprobe` on `PATH`
16
+ - An RTSP camera (tested with Tapo C325WB; any camera that exposes H.264 over RTSP
17
+ should work, but thresholds and masks are scene-specific), or a folder with
18
+ existing MKV segments for analysis-only use
19
+
20
+ ## Quick start
21
+
22
+ ```bash
23
+ git clone https://github.com/svatec/meteorlens.git
24
+ cd meteorlens
25
+ python3 -m venv .venv
26
+ . .venv/bin/activate
27
+ pip install -e ".[dev]"
28
+
29
+ meteorlens serve
30
+ ```
31
+
32
+ Open <http://127.0.0.1:8765>. On a fresh home MeteorLens starts the setup wizard
33
+ instead of the dashboard:
34
+
35
+ 1. choose an RTSP camera or a folder with existing MKV segments,
36
+ 2. set the observing location,
37
+ 3. test the camera stream (codec, resolution, frame rate, bitrate),
38
+ 4. pick storage and recording defaults,
39
+ 5. choose a detection profile.
40
+
41
+ The wizard writes `config.ini` atomically with mode `0600` and creates the data
42
+ directories. An existing file is backed up to `config.ini.bak`; the camera URL is
43
+ never shown again. Re-run the wizard from Settings or `/setup`.
44
+ [Setup wizard screenshot](docs/screenshots/setup.png).
45
+
46
+ To configure manually instead:
47
+
48
+ ```bash
49
+ cp config.example.ini config.ini
50
+ # edit camera.rtsp_url, location.latitude and location.longitude
51
+ meteorlens serve
52
+ ```
53
+
54
+ The dashboard and gallery are read-only until you start recording or analysis
55
+ from the control page.
56
+
57
+ Run the recorder and the analyzer as separate long-lived processes:
58
+
59
+ ```bash
60
+ meteorlens record # capture RTSP segments while it is dark
61
+ meteorlens run # analyse new segments (cron/systemd timer or manually)
62
+ ```
63
+
64
+ `meteorlens serve` is a local tool: it binds to `127.0.0.1` by default, has no
65
+ authentication and must not be exposed to the internet without a reverse proxy
66
+ and access control.
67
+
68
+ ## Demo data and screenshots
69
+
70
+ You do not need a camera to explore the UI. The demo builder creates three
71
+ deterministic synthetic clips, runs the real analyser, labels two meteors and
72
+ one aircraft candidate, and exports the demo home:
73
+
74
+ ```bash
75
+ python docs/demo/make_demo.py --home /tmp/meteorlens-demo
76
+ METEORLENS_HOME=/tmp/meteorlens-demo meteorlens serve
77
+ ```
78
+
79
+ The demo home contains no personal data; delete it when done. Screenshots from
80
+ this demo: [Dashboard](docs/screenshots/dashboard.png),
81
+ [Detections](docs/screenshots/detections.png),
82
+ [Settings](docs/screenshots/settings.png). The live panel shows "Camera
83
+ unavailable" because the demo has no RTSP camera, and the sky map falls back to
84
+ the camera axis because the demo has no calibration.
85
+
86
+ ## Configuration
87
+
88
+ MeteorLens reads `config.ini` from `METEORLENS_HOME` (default: the current
89
+ directory). Relative paths in `[paths]` are resolved against the same directory.
90
+
91
+ - `[camera]` is never shown in the UI and never written by the settings page.
92
+ The first-run wizard is the only web path that writes it; the file is mode `0600`.
93
+ - `[detect]` contains the detection thresholds. Change them only together with
94
+ the regression tests; the project treats threshold changes as behaviour changes.
95
+ - `[calibration]` is optional. Without it, events have no azimuth/altitude angles
96
+ and the sky map falls back to the camera axis.
97
+ - `[showers]` enables meteor-shower association from the bundled IAU-derived
98
+ catalogue.
99
+
100
+ Runtime layout:
101
+
102
+ ```
103
+ config.ini
104
+ data/
105
+ recordings/active/ # segment being written
106
+ recordings/ready/ # finished MKV segments (UTC names)
107
+ detections/ # clips, thumbnails, events.csv, tracks.csv
108
+ state/ # SQLite database, logs, locks, control state
109
+ ```
110
+
111
+ ## Commands
112
+
113
+ | Command | Description |
114
+ |---|---|
115
+ | `meteorlens record` | Record RTSP segments while the Sun is below the configured altitude. |
116
+ | `meteorlens run` | Analyse new segments. `--reprocess`, `--before`, `--after` control the range. |
117
+ | `meteorlens file FILE` | Analyse one file; `-v` prints rejected tracks, `--dry` writes nothing. |
118
+ | `meteorlens snapshot [FILE]` | Save a frame as `mask_template.png` for drawing a sky mask. |
119
+ | `meteorlens serve` | Start the local web UI; an incomplete config opens the setup wizard. |
120
+ | `meteorlens index` | Rebuild the static `detections/index.html` page. |
121
+ | `meteorlens export` | Export the SQLite database to CSV/JSON. |
122
+ | `meteorlens purge [--dry]` | Delete events labelled as insect/aircraft/cloud/satellite. |
123
+ | `meteorlens bench FILE` | Measure analysis speed and suggest worker settings. |
124
+ | `meteorlens-calibrate` | Solve the camera model from stars (requires `pip install -e ".[calibrate]"`). |
125
+
126
+ ## Calibration and masks
127
+
128
+ The bundled mask is only an example. For your own camera:
129
+
130
+ ```bash
131
+ meteorlens snapshot data/recordings/ready/YYYYMMDD_HHMMSS.mkv
132
+ # paint everything except the sky black, save as mask.png, then set in config.ini:
133
+ # [detect] mask = mask.png
134
+ ```
135
+
136
+ Camera calibration (focal length, orientation) is optional and uses `scipy`:
137
+
138
+ ```bash
139
+ pip install -e ".[calibrate]"
140
+ meteorlens-calibrate solve --video FILE --at 60 --lat 48.0 --lon 17.0 \
141
+ --az 270 --alt 35 --out calibration.json
142
+ # then set [calibration] file = calibration.json
143
+ ```
144
+
145
+ ## Architecture
146
+
147
+ ```
148
+ camera --RTSP--> meteorlens record --> data/recordings/ready/*.mkv
149
+ |
150
+ v
151
+ meteorlens run (multiprocessing)
152
+ |
153
+ SQLite + clips/thumbnails + CSV exports
154
+ |
155
+ v
156
+ meteorlens serve (Flask, localhost)
157
+ ```
158
+
159
+ - `capture.py` - ffmpeg segment recorder and disk guard.
160
+ - `detect.py` - frame differencing, blob tracking, track classification.
161
+ - `astrometry.py`, `showers.py` - angles, radiant and shower association.
162
+ - `store.py` - SQLite schema, migrations, queries and exports.
163
+ - `runner.py` - parallel segment processing, clip cutting, retention/purge.
164
+ - `web/` - Flask app factory, first-run setup wizard, `routes/` blueprints (pages,
165
+ API, control, media), Jinja templates and static CSS/JS assets.
166
+ - `control.py` - starts/stops recorder and analyzer subprocesses.
167
+
168
+ Long-running work stays in subprocesses so ffmpeg and OpenCV cannot block the
169
+ web UI. The web process only reads the database and file outputs.
170
+
171
+ ## Development
172
+
173
+ ```bash
174
+ pip install -e ".[dev]"
175
+ pytest
176
+ ruff check .
177
+ ```
178
+
179
+ The regression suite uses synthetic meteors inserted into a noisy background,
180
+ so it runs without a camera. `pytest tests/test_e2e.py` exercises the real CLI
181
+ (`file`, `run`, `snapshot`, `index`, `export`, `purge --dry`) in a temporary
182
+ `METEORLENS_HOME`; recorder startup is covered with a mock ffmpeg process. A
183
+ real reference clip can be provided out of band:
184
+
185
+ ```bash
186
+ METEORLENS_REF_CLIP=/path/to/reference.mkv pytest tests/test_reference_clip.py
187
+ ```
188
+
189
+ Detection thresholds are scene-specific, so tune them by measuring instead of
190
+ guessing. The development tools in `tools/` are not part of the package:
191
+
192
+ ```bash
193
+ # one row per clip with the current config (no database writes)
194
+ python -m tools.sweep --clips data/recordings/ready --out /tmp/tune/baseline.csv
195
+
196
+ # grid over two thresholds; score the result against known counts
197
+ python -m tools.sweep --clips tests/clips --grid diff_threshold=14,18,22 \
198
+ --grid min_speed=100,120 --out /tmp/tune/grid.csv --detail /tmp/tune/events.csv
199
+ python -m tools.score --sweep /tmp/tune/grid.csv --expect tests/clips/expected.json
200
+ ```
201
+
202
+ `--detail` writes one row per accepted and rejected track (span, speed, peak,
203
+ duration, reason), which is usually enough to see whether a false positive comes
204
+ from noise, a cloud edge, or the track-linking limits. A combination that scores
205
+ well belongs in `tests/clips/expected.json`; the clips themselves stay local
206
+ (`*.mkv`, `*.mp4` are ignored by git).
207
+
208
+ Do not commit camera recordings, `config.ini`, the database, or generated clips.
209
+
210
+ ## Troubleshooting
211
+
212
+ **`Missing configuration`** - `meteorlens run/file/record` read `config.ini` from
213
+ `METEORLENS_HOME` (default: current directory). Run `meteorlens serve` once:
214
+ without a complete config it opens the setup wizard at `/setup`, which writes
215
+ the file and creates the data directories. For analysis-only setups choose
216
+ "Existing recordings" and point the wizard at the MKV folder.
217
+
218
+ **`ffmpeg` or `ffprobe` not found** - install both and make sure they are on
219
+ `PATH`. Use `meteorlens bench FILE` to compare decoders and estimate worker
220
+ counts.
221
+
222
+ **The camera is unavailable** - test the stream outside MeteorLens
223
+ (`ffprobe -rtsp_transport tcp rtsp_url`). Try switching `camera.rtsp_transport`
224
+ between `udp` and `tcp`; UDP is usually better on lossy Wi-Fi, TCP on stable
225
+ networks. Credentials stay in `config.ini` and are never shown in the UI.
226
+
227
+ **No detections** - check focus, exposure and that the sky is dark; inspect
228
+ `meteorlens file CLIP -v` for rejected tracks. A scene mask and calibration
229
+ usually improve results. Detection thresholds are scene-specific; do not tune
230
+ them without running the regression suite.
231
+
232
+ **Sky map says calibration or location is missing** - the map needs
233
+ `[calibration] file` and `[location] latitude/longitude`. Without calibration,
234
+ events have no angles and the map falls back to the camera axis.
235
+
236
+ **Calibration fails with a scipy error** - install the optional extra:
237
+ `pip install -e ".[calibrate]"`.
238
+
239
+ **The web page has no styling or JavaScript** - the templates and static assets
240
+ must be installed with the package; reinstall with `pip install -e .` (or a
241
+ wheel built from this repository). Check `/static/app.css` returns 200.
242
+
243
+ **Port 8765 is already in use** - start with another port, for example
244
+ `meteorlens serve --port 8766`.
245
+
246
+ **`purge` refuses to run** - analysis or another purge holds `run.lock`; wait
247
+ for it to finish. Use `purge --dry` to see what would be deleted.
248
+
249
+ ## Data and licence
250
+
251
+ Code is released under the MIT licence (see `LICENSE`). Bundled catalogues are
252
+ described in `NOTICE`; keep that notice when redistributing.
@@ -0,0 +1,62 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "meteorlens"
7
+ version = "0.0.0"
8
+ description = "Local-first meteor detection from IP cameras"
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = {text = "MIT"}
12
+ authors = [{name = "MeteorLens contributors"}]
13
+ keywords = ["meteor", "astronomy", "opencv", "rtsp", "camera", "detection"]
14
+ classifiers = [
15
+ "Development Status :: 3 - Alpha",
16
+ "Environment :: Console",
17
+ "Intended Audience :: Science/Research",
18
+ "License :: OSI Approved :: MIT License",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3.11",
21
+ "Programming Language :: Python :: 3.12",
22
+ "Programming Language :: Python :: 3.13",
23
+ "Topic :: Scientific/Engineering :: Astronomy",
24
+ ]
25
+ dependencies = [
26
+ "numpy>=1.26",
27
+ "opencv-python-headless>=4.9",
28
+ "flask>=3.0",
29
+ ]
30
+
31
+ [project.optional-dependencies]
32
+ calibrate = ["scipy>=1.11"]
33
+ dev = ["pytest>=8", "ruff>=0.6"]
34
+
35
+ [project.scripts]
36
+ meteorlens = "meteorlens.cli:main"
37
+ meteorlens-calibrate = "meteorlens.calibrate:main"
38
+
39
+ [project.urls]
40
+ Homepage = "https://github.com/svatec/meteorlens"
41
+
42
+ [tool.setuptools]
43
+ package-dir = {"" = "src"}
44
+
45
+ [tool.setuptools.packages.find]
46
+ where = ["src"]
47
+
48
+ [tool.setuptools.package-data]
49
+ meteorlens = ["data/*.csv", "data/*.png", "data/*.ini"]
50
+ "meteorlens.web" = ["templates/*.html", "static/*.css", "static/js/*.js"]
51
+
52
+ [tool.pytest.ini_options]
53
+ testpaths = ["tests"]
54
+ addopts = "-q"
55
+
56
+ [tool.ruff]
57
+ line-length = 110
58
+ target-version = "py311"
59
+
60
+ [tool.ruff.lint]
61
+ select = ["E", "F", "W", "I"]
62
+ ignore = ["E501"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,4 @@
1
+ """MeteorLens - local-first meteor detection from IP cameras."""
2
+
3
+ __version__ = "0.1.0"
4
+ VERSION = __version__
@@ -0,0 +1,4 @@
1
+ from .cli import main
2
+
3
+ if __name__ == "__main__":
4
+ raise SystemExit(main())