Automatically detect meteors in RAW astrophotography images using frame-to-frame difference analysis.
Note: Detection compares consecutive RAW images. The first image is skipped—please check it manually.
During meteor shower events, manually reviewing thousands of RAW images to find meteors is tedious and time-consuming. This tool automates the initial detection process, allowing astrophotographers to quickly identify candidate images for further review.
📅 Planning your meteor photography? Check out the Meteor Showers Calendar for upcoming meteor shower dates and viewing tips.
- Fully automated: NPF Rule-based optimization analyzes EXIF metadata and scientifically tunes detection parameters
- Scientifically validated: 100% detection rate on real-world test dataset (OM Digital OM-1, 1000+ RAW images)
- RAW format support: Works with any format supported by
rawpy - Intelligent processing: ROI cropping, Hough transform line detection, resumable batch processing
- High performance: ~0.18 sec/image with multi-core parallel processing
- Python 3.12+
- macOS, Windows, or Linux
- Dependencies:
numpy,opencv-python,rawpy,psutil,pillow,pydantic,pyyaml
See INSTALL.md for detailed installation instructions.
python detect_meteors_cli.py --show-exifVerify focal length is detected. If missing, you'll need to specify it with --focal-length.
# Micro Four Thirds camera
python detect_meteors_cli.py --auto-params --sensor-type MFT
# APS-C camera (Sony/Nikon/Fuji)
python detect_meteors_cli.py --auto-params --sensor-type APS-C
# Full Frame camera
python detect_meteors_cli.py --auto-params --sensor-type FF
# With fisheye lens
python detect_meteors_cli.py --auto-params --sensor-type MFT --focal-length 16 --fisheyeCheck the candidates/ folder for detected meteor images.
| Sensor Type | Description |
|---|---|
1INCH |
1-inch sensor |
MFT |
Micro Four Thirds |
APS-C |
APS-C (Sony/Nikon/Fuji) |
APS-C_CANON |
APS-C (Canon) |
APS-H |
APS-H |
FF |
Full Frame 35mm |
MF44X33 |
Medium Format 44×33mm |
MF54X40 |
Medium Format 54×40mm |
List all presets: python detect_meteors_cli.py --list-sensor-types
- Input: Directory of RAW images (default:
rawfiles/) - Output:
- Candidate images in
candidates/(or custom-opath) - Optional debug masks with
--debug-dir progress.jsonfor resumable processing
- Candidate images in
- Interrupt with Ctrl-C anytime
- Resume by running the same command again
- Use
--no-resumefor a fresh start
| Document | Description |
|---|---|
| COMMAND_OPTIONS.md | Complete CLI options reference |
| NPF_RULE.md | NPF Rule and focal length handling |
| INSTALL.md | Installation guide |
| INSTALL_DEV.md | Developer setup |
| PLUGIN_AUTHOR_GUIDE.md | Plugin development |
| Wiki | Technical details |
- Schema versioning:
DetectionContextandDetectionResultnow includeschema_versionfor future migration support - Multi-framework images: New
ImageLiketype supports numpy, PyTorch tensors, and PIL images - Enhanced diagnostics:
DetectionResult.metricsfield for standardized detector diagnostics - ML-ready architecture: Foundation for PyTorch/TensorFlow-based detectors in v2.x
For detailed migration information, see RELEASE_NOTES_1.6.md.
| Version | Highlights | Details |
|---|---|---|
| v1.6.x | Schema versioning, ML-ready architecture, uv/Ruff toolchain | RELEASE_NOTES_1.6.md |
| v1.5.x | Plugin architecture, sensor presets, fisheye support | RELEASE_NOTES_1.5.md |
| v1.4.x | NPF Rule optimization, EXIF extraction | RELEASE_NOTES_1.4.md |
| v1.3.x | Auto-parameter estimation | RELEASE_NOTES_1.3.md |
| v1.2.x | Threshold estimation improvements | RELEASE_NOTES_1.2.md |
See CHANGELOG.md for complete release history.
See ROADMAP.md for upcoming features.
Detect Meteors CLI was created by Shinichi Morita (shin3tky).
The NPF Rule implementation is based on the formula developed by Frédéric Michaud of the Société Astronomique du Havre (SAH). See NOTICE for full attribution.
Issues and pull requests are welcome. Please open an issue to discuss substantial changes before submitting a PR.
For development setup, see INSTALL_DEV.md.
This project is licensed under the Apache License 2.0.