File size: 4,836 Bytes
038ca9f 55e3afe 038ca9f 55e3afe | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 | ---
license: mit
library_name: transformers
tags:
- object-detection
- vision
- conservation
- aerial-imagery
- drones
- pytorch
---
# DroneMegaDetector (Transformers Version)
This repository hosts the Hugging Face `transformers`-compatible version of **DroneMegaDetector**, an object detection model optimized for conservation drone imagery. The model has been converted from its original format to seamlessly integrate with the Hugging Face ecosystem, allowing for easy loading, inference, and deployment using standard `AutoImageProcessor` and `AutoModelForObjectDetection` classes.
**Original GitHub Repository:** [ConservationDronesAI/DroneMegaDetector](https://github.com/ConservationDronesAI/DroneMegaDetector?tab=readme-ov-file)
## Intended Use
* **Primary Use Case:** Detecting objects of interest (e.g., wildlife, humans, vehicles) in aerial imagery captured by drones for conservation, ecology, and anti-poaching efforts.
* **Input:** High-resolution RGB images.
* **Output:** Bounding boxes, confidence scores, and class labels for detected objects.
## Installation
Ensure you have the required dependencies installed to run the model. You can install the exact environment tested for this model using the repository's `requirements.txt`:
```bash
pip install torch==2.14.0 torchvision==0.29.0 transformers==5.18.0 Pillow==12.3.0
```
## Quickstart & Inference
You can run inference using the standard Hugging Face pipeline.
The following example code demonstrates how to load the model, process a source image, filter for detections with a confidence score of `>= 0.3`, and save an annotated output image with bounding boxes.
```python
import os
import sys
import torch
from PIL import Image, ImageDraw, ImageFont
from transformers import AutoImageProcessor, AutoModelForObjectDetection
# Hugging Face repository
repo_id = "ConservationDrones/DroneMegaDetector"
# Load the demo image (defaults to "example.png" if no argument is provided)
image_path = sys.argv[1] if len(sys.argv) > 1 else "example.png"
image = Image.open(image_path).convert("RGB")
# Load the processor and model from Hugging Face
processor = AutoImageProcessor.from_pretrained(repo_id)
model = AutoModelForObjectDetection.from_pretrained(repo_id).eval()
# Optimize CPU threading for local inference
torch.set_num_threads(4)
# Preprocess the image and run inference
encoded = processor(images=image, return_tensors="pt")
with torch.inference_mode():
outputs = model(**encoded)
# Keep scores above 0.3 and map boxes back to the original image dimensions
results = processor.post_process_object_detection(
outputs,
threshold=0.3,
target_sizes=[(image.height, image.width)],
)[0]
# Print detection results
print(f"{image_path}: {len(results['scores'])} detections (score >= 0.3)")
for score, label, box in zip(results["scores"], results["labels"], results["boxes"]):
print(
model.config.id2label[label.item()],
f"{score.item():.3f}",
[round(v, 1) for v in box.tolist()],
)
# Draw the detections on the original image
draw = ImageDraw.Draw(image)
font = ImageFont.load_default(size=18)
for score, label, box in zip(results["scores"], results["labels"], results["boxes"]):
bounds = box.tolist()
text = f"{model.config.id2label[label.item()]} {score.item():.2f}"
# Draw bounding box
draw.rectangle(bounds, outline="red", width=3)
# Position and draw text label
text_x = min(max(2, bounds[0]), image.width - draw.textlength(text, font=font) - 2)
draw.text(
(text_x, max(0, bounds[1] - 20)),
text,
font=font,
fill="white",
stroke_width=2,
stroke_fill="black",
)
# Save the annotated image
output_path = "example_annotated.jpg"
image.save(output_path, quality=95)
print(f"Saved {output_path}")
```
## Limitations & Best Practices
* **Confidence Thresholding:** The default demonstration filters out predictions below a `0.3` confidence score. You may need to tune this threshold up or down based on your specific drone altitude, camera resolution, and environment.
* **Inference Speed:** For optimal performance on large batches of aerial images, running inference on a CUDA-enabled GPU is highly recommended, though CPU inference is supported (and configured to use 4 threads in the demo script).
* **Image Dimensions:** The `AutoImageProcessor` handles automatic resizing and normalization. However, for extremely high-resolution drone panoramas, consider splitting the image into tiles before passing them to the model to avoid missing small objects (like distant animals).
## Citation
If you use this model in your research or conservation project, please consider linking back to the original GitHub repository:
> `https://github.com/ConservationDronesAI/DroneMegaDetector`
```
``` |