{"id":34617891,"url":"https://github.com/shin3tky/detect_meteors","last_synced_at":"2026-04-20T20:36:25.395Z","repository":{"id":325192787,"uuid":"1099621388","full_name":"shin3tky/detect_meteors","owner":"shin3tky","description":"Automatically detect meteors in RAW astrophotography images using frame-to-frame difference analysis.","archived":false,"fork":false,"pushed_at":"2026-04-02T13:42:03.000Z","size":24053,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T02:34:12.542Z","etag":null,"topics":["astrophotography","camera","image-processing","meteor-detection","meteorshower","opencv","opencv-python","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shin3tky.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-19T08:24:16.000Z","updated_at":"2026-04-02T13:42:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shin3tky/detect_meteors","commit_stats":null,"previous_names":["shin3tky/detect_meteors"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/shin3tky/detect_meteors","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shin3tky%2Fdetect_meteors","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shin3tky%2Fdetect_meteors/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shin3tky%2Fdetect_meteors/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shin3tky%2Fdetect_meteors/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shin3tky","download_url":"https://codeload.github.com/shin3tky/detect_meteors/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shin3tky%2Fdetect_meteors/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32065137,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T11:35:06.609Z","status":"ssl_error","status_checked_at":"2026-04-20T11:34:48.899Z","response_time":94,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astrophotography","camera","image-processing","meteor-detection","meteorshower","opencv","opencv-python","python"],"created_at":"2025-12-24T14:53:14.799Z","updated_at":"2026-04-20T20:36:25.388Z","avatar_url":"https://github.com/shin3tky.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Detect Meteors CLI\n\n![social_preview](social_preview.jpg)\n\n[![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)\n\nAutomatically detect meteors in RAW astrophotography images using frame-to-frame difference analysis.\n\n## Motivation\n\nDuring 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.\n\n![workflow](workflow.png)\n\n📅 **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.\n\n\u003e [!TIP]\n\u003e 🌠 **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.\n\n## Features\n\n- **Fully automated**: NPF Rule-based optimization analyzes EXIF metadata and scientifically tunes detection parameters\n- **Field-tested**: 100% detection rate on real-world test dataset (OM Digital OM-1, 1000+ RAW images)\n- **RAW format support**: Works with any format supported by [`rawpy`](https://github.com/letmaik/rawpy)\n- **Intelligent processing**: ROI cropping, Hough transform line detection, resumable batch processing\n- **High performance**: ~0.18 sec/image with multi-core parallel processing\n\n## Requirements\n\n- Python 3.12, 3.13\n- macOS, Windows, or Linux\n- Dependencies: `numpy`, `opencv-python`, `rawpy`, `psutil`, `pillow`, `pydantic`, `pyyaml`\n\n## Installation\n\nSee [INSTALL.md](INSTALL.md) for detailed installation instructions.\n\n## Quick Start\n\n### Step 1: Check EXIF Metadata\n\n```bash\npython detect_meteors_cli.py --show-exif\n```\n\nVerify focal length is detected. If missing, you'll need to specify it with `--focal-length`.\n\n### Step 2: Run Detection\n\n```bash\n# Micro Four Thirds camera\npython detect_meteors_cli.py --auto-params --sensor-type MFT\n\n# APS-C camera (Sony/Nikon/Fuji)\npython detect_meteors_cli.py --auto-params --sensor-type APS-C\n\n# Full Frame camera\npython detect_meteors_cli.py --auto-params --sensor-type FF\n\n# With fisheye lens\npython detect_meteors_cli.py --auto-params --sensor-type MFT --focal-length 16 --fisheye\n```\n\n\u003e [!IMPORTANT]\n\u003e Detection is based on frame-to-frame differences.  \n\u003e 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).  \n\u003e This is why “100 inputs → 99 processed” is expected—please review the first frame manually.\n\n### Step 3: Review Candidates\n\nCheck the `candidates/` folder for detected meteor images.\n\n## Available Sensor Types\n\n| Sensor Type | Description |\n|-------------|-------------|\n| `1INCH` | 1-inch sensor |\n| `MFT` | Micro Four Thirds |\n| `APS-C` | APS-C (Sony/Nikon/Fuji) |\n| `APS-C_CANON` | APS-C (Canon) |\n| `APS-H` | APS-H |\n| `FF` | Full Frame 35mm |\n| `MF44X33` | Medium Format 44×33mm |\n| `MF54X40` | Medium Format 54×40mm |\n\nList all presets: `python detect_meteors_cli.py --list-sensor-types`\n\n## Inputs and Outputs\n\n- **Input**: Directory of RAW images (default: `rawfiles/`)\n- **Output**: \n  - Candidate images in `candidates/` (or custom `-o` path)\n  - Optional debug masks with `--debug-image` and `--debug-dir`\n  - `progress.json` for resumable processing\n\n## Configuration Files (YAML/JSON)\n\nThe CLI can load pipeline settings from a configuration file. The file must be a\nJSON or YAML object whose keys align with `PipelineConfig`.\n\n**Top-level keys**\n\n- `target_folder`, `output_folder`, `debug_folder` (required paths)\n- `params` (detection parameters)\n- `num_workers`, `batch_size`, `auto_batch_size`, `enable_parallel`\n- `progress_file`, `output_overwrite`\n- `input_loader_name`, `input_loader_config`\n- `detector_name`, `detector_config`\n- `output_handler_name`, `output_handler_config`\n\n**Example (YAML)**\n\n```yaml\ntarget_folder: ./rawfiles\noutput_folder: ./candidates\ndebug_folder: ./debug_masks\nparams:\n  diff_threshold: 8\n  min_area: 10\n  min_aspect_ratio: 3.0\ninput_loader_name: raw\ninput_loader_config:\n  binning: 1\n  normalize: true\ndetector_name: hough\noutput_handler_name: file\n```\n\n**Example file**: [`config_examples/pipeline.yaml`](config_examples/pipeline.yaml)\n\n**Usage (CLI)**\n\n```bash\npython detect_meteors_cli.py --config config_examples/pipeline.yaml\n```\n\nYou can override plugin selections via CLI (e.g., `--input-loader`, `--detector`,\n`--output-handler`) and provide plugin configs as JSON/YAML strings or file paths.\nLegacy parameter flags (e.g., `--diff-threshold`) are still mapped into\n`PipelineConfig.params` but will be deprecated in favor of config files.\n\n**Usage (Python)**\n\n```python\nfrom meteor_core import MeteorDetectionPipeline, load_pipeline_config\n\nconfig = load_pipeline_config(\"config_examples/pipeline.yaml\")\npipeline = MeteorDetectionPipeline(config)\npipeline.run()\n```\n\n## Resumable Processing\n\n- Interrupt with Ctrl-C anytime\n- Resume by running the same command again\n- Use `--no-resume` for a fresh start\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [COMMAND_OPTIONS.md](COMMAND_OPTIONS.md) | Complete CLI options reference |\n| [NPF_RULE.md](NPF_RULE.md) | NPF Rule and focal length handling |\n| [INSTALL.md](INSTALL.md) | Installation guide |\n| [INSTALL_DEV.md](INSTALL_DEV.md) | Developer setup |\n| [PLUGIN_AUTHOR_GUIDE.md](PLUGIN_AUTHOR_GUIDE.md) | Plugin development |\n| [Wiki](https://github.com/shin3tky/detect_meteors/wiki) | Technical details |\n\n## What's New in v1.6.10\n\n- **Sorted detection hooks**: New pipeline hooks for temporally-ordered detection analysis\n  - `on_batch_results_sorted`: Per-batch hook with frame-order guarantee\n  - `on_all_detections_sorted`: Post-pipeline hook for cross-frame analysis\n- **SortedDetection dataclass**: Lightweight, memory-efficient container for sorted hooks\n- **AircraftTrailHook improvements**: Enhanced robustness with error handling, logging, and 360° angle normalization\n\nFor detailed migration information, see [RELEASE_NOTES_1.6.md](RELEASE_NOTES_1.6.md).\n\n### Previous Releases\n\n| Version | Highlights | Details |\n|---------|------------|---------|\n| v1.6.x | Schema versioning, ML-ready architecture, uv/Ruff toolchain | [RELEASE_NOTES_1.6.md](RELEASE_NOTES_1.6.md) |\n| v1.5.x | Plugin architecture, sensor presets, fisheye support | [RELEASE_NOTES_1.5.md](RELEASE_NOTES_1.5.md) |\n| v1.4.x | NPF Rule optimization, EXIF extraction | [RELEASE_NOTES_1.4.md](RELEASE_NOTES_1.4.md) |\n| v1.3.x | Auto-parameter estimation | [RELEASE_NOTES_1.3.md](RELEASE_NOTES_1.3.md) |\n| v1.2.x | Threshold estimation improvements | [RELEASE_NOTES_1.2.md](RELEASE_NOTES_1.2.md) |\n\nSee [CHANGELOG.md](CHANGELOG.md) for complete release history.\n\n## Roadmap\n\nSee [ROADMAP.md](ROADMAP.md) for upcoming features.\n\n## Authors\n\nDetect Meteors CLI was created by Shinichi Morita (shin3tky).\n\nThe 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.\n\n## Contributing\n\nIssues and pull requests are welcome. Please open an issue to discuss substantial changes before submitting a PR.\n\nFor development setup, see [INSTALL_DEV.md](INSTALL_DEV.md).\n\n## License\n\nThis project is licensed under the [Apache License 2.0](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshin3tky%2Fdetect_meteors","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshin3tky%2Fdetect_meteors","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshin3tky%2Fdetect_meteors/lists"}