Detect Meteors CLI

Automatically detect meteors in RAW astrophotography images using frame-to-frame difference analysis.

Motivation

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.

Features

• Fully automated: NPF Rule-based optimization analyzes EXIF metadata and scientifically tunes detection parameters
• Field-tested: 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

Requirements

• Python 3.12, 3.13
• macOS, Windows, or Linux
• Dependencies: numpy, opencv-python, rawpy, psutil, pillow, pydantic, pyyaml

Installation

See INSTALL.md for detailed installation instructions.

Quick Start

Step 1: Check EXIF Metadata

python detect_meteors_cli.py --show-exif

Verify focal length is detected. If missing, you'll need to specify it with --focal-length.

Step 2: Run Detection

# 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 --fisheye

Important

Detection is based on frame-to-frame differences.
If you provide N RAW files, the tool analyzes N−1 consecutive pairs (the first frame is used as the baseline and is not scored).
This is why “100 inputs → 99 processed” is expected—please review the first frame manually.

Step 3: Review Candidates

Check the candidates/ folder for detected meteor images.

Available Sensor Types

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

Inputs and Outputs

• Input: Directory of RAW images (default: rawfiles/)
• Output:
  • Candidate images in candidates/ (or custom -o path)
  • Optional debug masks with --debug-image and --debug-dir
  • progress.json for resumable processing

Configuration Files (YAML/JSON)

The CLI can load pipeline settings from a configuration file. The file must be a JSON or YAML object whose keys align with PipelineConfig.

Top-level keys

• target_folder, output_folder, debug_folder (required paths)
• params (detection parameters)
• num_workers, batch_size, auto_batch_size, enable_parallel
• progress_file, output_overwrite
• input_loader_name, input_loader_config
• detector_name, detector_config
• output_handler_name, output_handler_config

Example (YAML)

target_folder: ./rawfiles
output_folder: ./candidates
debug_folder: ./debug_masks
params:
  diff_threshold: 8
  min_area: 10
  min_aspect_ratio: 3.0
input_loader_name: raw
input_loader_config:
  binning: 1
  normalize: true
detector_name: hough
output_handler_name: file

Example file: config_examples/pipeline.yaml

Usage (CLI)

python detect_meteors_cli.py --config config_examples/pipeline.yaml

You can override plugin selections via CLI (e.g., --input-loader, --detector, --output-handler) and provide plugin configs as JSON/YAML strings or file paths. Legacy parameter flags (e.g., --diff-threshold) are still mapped into PipelineConfig.params but will be deprecated in favor of config files.

Usage (Python)

from meteor_core import MeteorDetectionPipeline, load_pipeline_config

config = load_pipeline_config("config_examples/pipeline.yaml")
pipeline = MeteorDetectionPipeline(config)
pipeline.run()

Resumable Processing

• Interrupt with Ctrl-C anytime
• Resume by running the same command again
• Use --no-resume for a fresh start

Documentation

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

What's New in v1.6.8 🌿

• Static type checking with ty: Integrated Astral's ty type checker for plugin development stability
  • Pre-commit hook integration for automatic type checking
  • Graduated rule enforcement (errors vs warnings)
• Plugin type safety: Resolved type-checking issues across all plugin registries
• Worker limit configuration: MAX_NUM_WORKERS constant with pipeline/CLI validation

For detailed migration information, see RELEASE_NOTES_1.6.md.

Previous Releases

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.

Roadmap

See ROADMAP.md for upcoming features.

Authors

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.

Contributing

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.

License

This project is licensed under the Apache License 2.0.