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.
- meteorlens-0.0.0/LICENSE +21 -0
- meteorlens-0.0.0/NOTICE +10 -0
- meteorlens-0.0.0/PKG-INFO +283 -0
- meteorlens-0.0.0/README.md +252 -0
- meteorlens-0.0.0/pyproject.toml +62 -0
- meteorlens-0.0.0/setup.cfg +4 -0
- meteorlens-0.0.0/src/meteorlens/__init__.py +4 -0
- meteorlens-0.0.0/src/meteorlens/__main__.py +4 -0
- meteorlens-0.0.0/src/meteorlens/astrometry.py +398 -0
- meteorlens-0.0.0/src/meteorlens/calibrate.py +797 -0
- meteorlens-0.0.0/src/meteorlens/capture.py +225 -0
- meteorlens-0.0.0/src/meteorlens/cli.py +103 -0
- meteorlens-0.0.0/src/meteorlens/config.py +504 -0
- meteorlens-0.0.0/src/meteorlens/control.py +154 -0
- meteorlens-0.0.0/src/meteorlens/data/config.example.ini +125 -0
- meteorlens-0.0.0/src/meteorlens/data/mask.example.png +0 -0
- meteorlens-0.0.0/src/meteorlens/data/showers.csv +112 -0
- meteorlens-0.0.0/src/meteorlens/data/star_names.csv +36 -0
- meteorlens-0.0.0/src/meteorlens/data/stars_hip.csv +2817 -0
- meteorlens-0.0.0/src/meteorlens/detect.py +377 -0
- meteorlens-0.0.0/src/meteorlens/filters.py +4 -0
- meteorlens-0.0.0/src/meteorlens/media.py +120 -0
- meteorlens-0.0.0/src/meteorlens/metrics.py +96 -0
- meteorlens-0.0.0/src/meteorlens/outputs.py +126 -0
- meteorlens-0.0.0/src/meteorlens/runner.py +404 -0
- meteorlens-0.0.0/src/meteorlens/showers.py +129 -0
- meteorlens-0.0.0/src/meteorlens/store.py +705 -0
- meteorlens-0.0.0/src/meteorlens/synth.py +87 -0
- meteorlens-0.0.0/src/meteorlens/thumbs.py +113 -0
- meteorlens-0.0.0/src/meteorlens/video.py +106 -0
- meteorlens-0.0.0/src/meteorlens/web/__init__.py +4 -0
- meteorlens-0.0.0/src/meteorlens/web/app.py +96 -0
- meteorlens-0.0.0/src/meteorlens/web/formatting.py +91 -0
- meteorlens-0.0.0/src/meteorlens/web/labels.py +44 -0
- meteorlens-0.0.0/src/meteorlens/web/live.py +35 -0
- meteorlens-0.0.0/src/meteorlens/web/routes/__init__.py +7 -0
- meteorlens-0.0.0/src/meteorlens/web/routes/api.py +155 -0
- meteorlens-0.0.0/src/meteorlens/web/routes/control.py +22 -0
- meteorlens-0.0.0/src/meteorlens/web/routes/media.py +65 -0
- meteorlens-0.0.0/src/meteorlens/web/routes/pages.py +105 -0
- meteorlens-0.0.0/src/meteorlens/web/setup.py +325 -0
- meteorlens-0.0.0/src/meteorlens/web/skymap.py +180 -0
- meteorlens-0.0.0/src/meteorlens/web/static/app.css +171 -0
- meteorlens-0.0.0/src/meteorlens/web/static/js/dashboard.js +380 -0
- meteorlens-0.0.0/src/meteorlens/web/static/js/gallery.js +84 -0
- meteorlens-0.0.0/src/meteorlens/web/static/js/header.js +26 -0
- meteorlens-0.0.0/src/meteorlens/web/static/js/settings.js +54 -0
- meteorlens-0.0.0/src/meteorlens/web/static/js/setup.js +519 -0
- meteorlens-0.0.0/src/meteorlens/web/static/setup.css +114 -0
- meteorlens-0.0.0/src/meteorlens/web/templates/_macros.html +71 -0
- meteorlens-0.0.0/src/meteorlens/web/templates/_nav.html +7 -0
- meteorlens-0.0.0/src/meteorlens/web/templates/base.html +30 -0
- meteorlens-0.0.0/src/meteorlens/web/templates/dashboard.html +94 -0
- meteorlens-0.0.0/src/meteorlens/web/templates/gallery.html +33 -0
- meteorlens-0.0.0/src/meteorlens/web/templates/settings.html +27 -0
- meteorlens-0.0.0/src/meteorlens/web/templates/setup.html +290 -0
- meteorlens-0.0.0/src/meteorlens.egg-info/PKG-INFO +283 -0
- meteorlens-0.0.0/src/meteorlens.egg-info/SOURCES.txt +81 -0
- meteorlens-0.0.0/src/meteorlens.egg-info/dependency_links.txt +1 -0
- meteorlens-0.0.0/src/meteorlens.egg-info/entry_points.txt +3 -0
- meteorlens-0.0.0/src/meteorlens.egg-info/requires.txt +10 -0
- meteorlens-0.0.0/src/meteorlens.egg-info/top_level.txt +1 -0
- meteorlens-0.0.0/tests/test_astrometry.py +281 -0
- meteorlens-0.0.0/tests/test_control.py +110 -0
- meteorlens-0.0.0/tests/test_csv.py +41 -0
- meteorlens-0.0.0/tests/test_detect_synthetic.py +62 -0
- meteorlens-0.0.0/tests/test_e2e.py +113 -0
- meteorlens-0.0.0/tests/test_features.py +96 -0
- meteorlens-0.0.0/tests/test_media.py +98 -0
- meteorlens-0.0.0/tests/test_metrics.py +105 -0
- meteorlens-0.0.0/tests/test_purge.py +130 -0
- meteorlens-0.0.0/tests/test_record.py +92 -0
- meteorlens-0.0.0/tests/test_reference_clip.py +46 -0
- meteorlens-0.0.0/tests/test_regression.py +64 -0
- meteorlens-0.0.0/tests/test_runner.py +133 -0
- meteorlens-0.0.0/tests/test_settings.py +159 -0
- meteorlens-0.0.0/tests/test_setup.py +309 -0
- meteorlens-0.0.0/tests/test_showers.py +74 -0
- meteorlens-0.0.0/tests/test_store.py +486 -0
- meteorlens-0.0.0/tests/test_thumbs.py +71 -0
- meteorlens-0.0.0/tests/test_tuning_tools.py +130 -0
- meteorlens-0.0.0/tests/test_video.py +59 -0
- meteorlens-0.0.0/tests/test_web.py +179 -0
meteorlens-0.0.0/LICENSE
ADDED
|
@@ -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.
|
meteorlens-0.0.0/NOTICE
ADDED
|
@@ -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"]
|