Update README.md

README.md

@@ -1,3 +1,134 @@
----
-license: apache-2.0
----
+---
+license: apache-2.0
+---
+# GolfCart YOLO11s — Model Card
+
+**Model name:** `golfcart-yolo11s`
+
+**One-line summary**
+A compact YOLO11s detection model fine-tuned to identify golf carts in aerial and ground-level images. Optimized for fast inference on edge devices while maintaining strong precision across varying lighting and backgrounds.
+
+---
+
+## Model description
+
+This model is a lightweight YOLO11s variant trained to **detect golf carts** in diverse environments — fairways, parking lots, garages, and drone captures. It balances speed and accuracy for real-time applications like fleet monitoring, course management, safety analytics, and automated observation systems.
+
+* **Architecture:** YOLO11s (small) — one-stage single-shot detector optimized for real-time inference.
+* **Input size:** variable; recommended 640×640 or 512×512.
+* **Output:** detection mask and confidence score for the class `golf_cart`.
+
+---
+
+## Visual examples
+
+Below are example inputs and model outputs (replace with your own hosted images):
+
+![Golf cart — example 1 (ground)](images/golfcart_ground_01.jpg)
+*Detected golf cart in ground-level image.*
+
+![Golf cart — example 2 (drone)](images/golfcart_drone_01.jpg)
+*Detected golf cart in aerial view.*
+
+![Predictions collage](images/golfcart_collage_predictions.jpg)
+*Model predictions with confidence overlays.*
+
+---
+
+## Intended uses
+
+**Primary (appropriate):**
+
+* Monitoring golf cart activity on courses.
+* Fleet usage and movement tracking.
+* Safety or proximity alerts on maintenance vehicles.
+* Drone-based detection of golf carts in aerial surveys.
+
+**Out-of-scope:**
+
+* Identifying individuals or non-cart objects.
+* Use in safety-critical or privacy-sensitive contexts without human oversight.
+
+---
+
+## Training data
+
+* **Total images:** 624
+* **Content:** golf carts and mixed scenes (including negative examples with no carts)
+* **Augmentations:** horizontal flip, brightness/contrast variation, mosaic augmentation, scaling, rotation.
+* **Annotation style:** detection labels (not bounding boxes)
+
+---
+
+## Evaluation
+
+* **Validation/Evaluation set:** 68 images (balanced with and without golf carts)
+* **Results:**
+
+  * **mAP@50:** 0.93
+  * **mAP@50–95:** 0.649
+  * **Precision:** 0.978
+  * **Recall:** 0.853
+
+These results indicate strong performance even with a relatively small dataset, especially in high-confidence detection of golf carts across mixed environments.
+
+---
+
+## How to use
+
+**Install:**
+
+```bash
+pip install ultralytics
+```
+
+**Inference example:**
+
+```python
+from ultralytics import YOLO
+
+model = YOLO('best-3.pt')
+results = model('test_images/golfcart_drone_01.jpg', imgsz=640)
+
+results[0].show()  # or results[0].save()
+```
+
+Supports ONNX, TorchScript, and TensorRT conversion for deployment.
+
+---
+
+## Limitations and failure modes
+
+* Misses can occur when golf carts are small, heavily occluded, or extremely far away in aerial imagery.
+* Performance may vary for uncommon cart shapes or regions not represented in the training set.
+
+---
+
+## Biases
+
+The dataset contains mostly North American golf cart models and course designs. Accuracy may dip in unfamiliar regional styles or environments.
+
+---
+
+## Ethical considerations
+
+* Avoid using this model for surveillance involving people.
+* Respect local drone and privacy regulations.
+
+---
+
+## Model parameters
+
+* **Weights:** `best-3.pt`
+* **Training date:** 2025-10-03 (replace with actual)
+---
+
+## How to cite
+
+If you use this model, please cite with the model name and link to its Hugging Face card.
+
+---
+
+## Contact
+
+Maintainer: Ryan Witzman — `ryan@rwitz.com`