$ show agentmorris/MegaDetector
MegaDetector is a production-grade object detection pipeline specifically designed for camera trap images in wildlife conservation. It detects animals, people, and vehicles in images and videos, outputting bounding boxes with confidence scores in a standardized JSON format (MegaDetector output format). The system provides a comprehensive set of command-line tools for batch inference, post-processing (repeat detection elimination, classification smoothing, format conversion), and integration with platforms like Wildlife Insights and LILA. The architecture is a modular Python package with separate modules for detection (supporting PyTorch and TensorFlow backends), classification, data management, post-processing, visualization, and taxonomy mapping. Key entry points include `run_detector_batch.py` for batch inference, `run_detector.py` for single-image inference, `postprocess_batch_results.py` for generating HTML previews, and `separate_detections_into_folders.py` for organizing results. Data flows from raw images through the detector to JSON results, which are then post-processed (e.g., false positive reduction, confidence thresholding) and optionally converted to other formats (COCO, YOLO, Wildlife Insights). External dependencies include PyTorch, TensorFlow, ultralytics, OpenCV, PIL, and various utility libraries. The repository also includes a C# Windows GUI application for JSON subsetting and integration guides for Timelapse and digiKam.
The LLM identified 4 files worth highlighting for reuse:
Implements the Repeat Detection Elimination (RDE) algorithm to identify and remove likely false-positive detections (e.g., rocks, sticks) that recur at the same location across many images. Uses a quadtree (pyqtree) for efficient spatial overlap queries and sklearn clustering to group detections. Highly configurable via RepeatDetectionOptions, making it reusable for any object detection post-processing pipeline where static false positives are a concern.
Provides a robust batch inference pipeline for running MegaDetector on large image collections. Implements a producer-consumer pattern with multiprocessing for asynchronous image loading and GPU inference, built-in checkpoint/resume with backup file protection, and automatic GPU/CPU switching. The main function `load_and_run_detector_batch()` can be used programmatically or via CLI, making it a reusable framework for any batch object detection task.
A collection of highly reusable utility functions for JSON I/O (write_json with datetime handling), bounding box operations (convert_yolo_to_xywh, get_iou, rect_distance), list splitting, dictionary manipulation, and argument parsing. These functions are used across the entire codebase and can be extracted into any Python project needing similar helpers. Includes inline tests for validation.
Builds a directed acyclic graph (DAG) from a taxonomy CSV file, enabling hierarchical species lookups and validation. Handles special cases like multiple parents and cycles. The resulting graph can be used for taxonomic rollup, geofencing, and consistency checks. Reusable for any domain requiring taxonomy mapping from tabular data.