https://github.com/shin3tky/detect_meteors

Automatically detect meteors in RAW astrophotography images using frame-to-frame difference analysis.
https://github.com/shin3tky/detect_meteors

astrophotography camera image-processing meteor-detection meteorshower opencv opencv-python python

Last synced: 2 months ago
JSON representation

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

Host: GitHub
URL: https://github.com/shin3tky/detect_meteors
Owner: shin3tky
License: apache-2.0
Created: 2025-11-19T08:24:16.000Z (7 months ago)
Default Branch: main
Last Pushed: 2026-04-02T13:42:03.000Z (3 months ago)
Last Synced: 2026-04-03T02:34:12.542Z (3 months ago)
Topics: astrophotography, camera, image-processing, meteor-detection, meteorshower, opencv, opencv-python, python
Language: Python
Homepage:
Size: 22.9 MB
Stars: 1
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Roadmap: ROADMAP.md
- Notice: NOTICE

Awesome Lists containing this project

README

          # Detect Meteors CLI

![social_preview](social_preview.jpg)

[![tests](https://github.com/shin3tky/detect_meteors/actions/workflows/python-test.yml/badge.svg)](https://github.com/shin3tky/detect_meteors/actions/workflows/python-test.yml)

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.

![workflow](workflow.png)

📅 **Planning your meteor photography?** Check out the [Meteor Showers Calendar](https://github.com/shin3tky/detect_meteors/wiki/Meteor-Showers-Calendar) for upcoming meteor shower dates and viewing tips.

> [!TIP]

> 🌠 **Lyrids are coming — April 21-22, 2026!** The Lyrids meteor shower peaks on the night of April 21-22, 2026. Don't miss this opportunity to capture stunning meteors! See [April 2026 details](https://github.com/shin3tky/detect_meteors/wiki/Meteor-Showers-2026#april-2026) for viewing conditions and 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`](https://github.com/letmaik/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](INSTALL.md) for detailed installation instructions.

## Quick Start

### Step 1: Check EXIF Metadata

```bash

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

```bash

# 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)**

```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`](config_examples/pipeline.yaml)

**Usage (CLI)**

```bash

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)**

```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](COMMAND_OPTIONS.md) | Complete CLI options reference |

| [NPF_RULE.md](NPF_RULE.md) | NPF Rule and focal length handling |

| [INSTALL.md](INSTALL.md) | Installation guide |

| [INSTALL_DEV.md](INSTALL_DEV.md) | Developer setup |

| [PLUGIN_AUTHOR_GUIDE.md](PLUGIN_AUTHOR_GUIDE.md) | Plugin development |

| [Wiki](https://github.com/shin3tky/detect_meteors/wiki) | Technical details |

## What's New in v1.6.10

- **Sorted detection hooks**: New pipeline hooks for temporally-ordered detection analysis

  - `on_batch_results_sorted`: Per-batch hook with frame-order guarantee

  - `on_all_detections_sorted`: Post-pipeline hook for cross-frame analysis

- **SortedDetection dataclass**: Lightweight, memory-efficient container for sorted hooks

- **AircraftTrailHook improvements**: Enhanced robustness with error handling, logging, and 360° angle normalization

For detailed migration information, see [RELEASE_NOTES_1.6.md](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](RELEASE_NOTES_1.6.md) |

| v1.5.x | Plugin architecture, sensor presets, fisheye support | [RELEASE_NOTES_1.5.md](RELEASE_NOTES_1.5.md) |

| v1.4.x | NPF Rule optimization, EXIF extraction | [RELEASE_NOTES_1.4.md](RELEASE_NOTES_1.4.md) |

| v1.3.x | Auto-parameter estimation | [RELEASE_NOTES_1.3.md](RELEASE_NOTES_1.3.md) |

| v1.2.x | Threshold estimation improvements | [RELEASE_NOTES_1.2.md](RELEASE_NOTES_1.2.md) |

See [CHANGELOG.md](CHANGELOG.md) for complete release history.

## Roadmap

See [ROADMAP.md](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](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](INSTALL_DEV.md).

## License

This project is licensed under the [Apache License 2.0](LICENSE).

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/shin3tky/detect_meteors

Awesome Lists containing this project

README