feat: add model card — 6-class metrics, usage, download instructions

README.md

@@ -1,3 +1,117 @@
 ---
 license: mit
+language:
+- en
+tags:
+- object-detection
+- solar-panel
+- yolo
+- computer-vision
+- onnx
+- defect-detection
+library_name: ultralytics
+pipeline_tag: object-detection
 ---
+
+# Solar Panel Defect Detection
+
+YOLOv11-based object detection model for solar panel surface anomaly detection. Identifies 6 defect categories in RGB images. Trained on a custom labeled dataset using both RGB and thermal modalities; this repo contains the RGB variant.
+
+**GitHub:** [4keles/Solar-Panel-AI-Analysis](https://github.com/4keles/Solar-Panel-AI-Analysis)
+
+---
+
+## Classes
+
+| Class | Description |
+|-------|-------------|
+| `bird_drop` | Bird dropping contamination |
+| `bird_feather` | Feather debris on panel surface |
+| `physical_damage` | Cracks, chips, physical panel damage |
+| `dust_partical` | Dust and particle contamination |
+| `leaf` | Leaf debris |
+| `snow` | Snow coverage |
+
+---
+
+## Performance — v1.2.1 (test split)
+
+| Metric | Value |
+|--------|-------|
+| mAP@50 | **0.546** |
+| mAP@50-95 | 0.241 |
+| Precision | 0.569 |
+| Recall | 0.582 |
+| F1 | 0.575 |
+
+### Per-Class Breakdown
+
+| Class | mAP@50 | Precision | Recall |
+|-------|--------|-----------|--------|
+| bird_feather | **0.995** | 0.832 | 1.000 |
+| leaf | 0.752 | 0.668 | 0.813 |
+| physical_damage | 0.552 | 0.543 | 0.565 |
+| snow | 0.467 | 0.567 | 0.494 |
+| dust_partical | 0.408 | 0.590 | 0.373 |
+| bird_drop | 0.100 | 0.214 | 0.246 |
+
+> `bird_drop` performance is low due to limited labeled samples in the dataset — planned improvement in v1.3.
+
+---
+
+## Model Versions
+
+| Version | Format | Size | Notes |
+|---------|--------|------|-------|
+| `v1.2.1/best.onnx` | ONNX | 37.9 MB | **Recommended** — CPU/GPU portable |
+| `v1.2.1/best.pt` | PyTorch | 6 MB | Fine-tuning / training |
+| `thermal-v1.0.4/best.onnx` | ONNX | 37.9 MB | Thermal camera variant |
+
+---
+
+## Usage
+
+### Download (Python)
+
+```python
+from huggingface_hub import hf_hub_download
+
+model_path = hf_hub_download(
+    repo_id="4keles/solar-panel-od",
+    filename="v1.2.1/best.onnx"
+)
+```
+
+Or use the project download script:
+
+```bash
+python scripts/download_model.py --version v1.2.1
+```
+
+### Inference
+
+```python
+from ultralytics import YOLO
+
+model = YOLO("best.onnx", task="detect")
+results = model.predict("solar_panel.jpg", conf=0.25)
+results[0].show()
+```
+
+### Class names (ordered)
+
+```python
+CLASSES = ["bird_drop", "bird_feather", "physical_damage", "dust_partical", "leaf", "snow"]
+```
+
+---
+
+## Hardware
+
+Trained on NVIDIA GeForce RTX 3050 Laptop GPU (4 GB VRAM). ONNX export runs on CPU or any CUDA device without recompilation.
+
+---
+
+## License
+
+MIT