Add professional model card README

README.md

@@ -1,3 +1,196 @@
 ---
 license: mit
+language:
+- en
+tags:
+- object-detection
+- yolov8
+- military
+- ultralytics
+- computer-vision
+pipeline_tag: object-detection
+library_name: ultralytics
 ---
+
+# Military Object Detection — YOLOv8n
+
+A fine-tuned **YOLOv8 nano** model for detecting military and civilian objects in images.  
+Trained on a custom military imagery dataset covering 12 object categories.
+
+---
+
+## Model Description
+
+| Property | Value |
+|---|---|
+| Architecture | YOLOv8n (nano) |
+| Parameters | ~3.0 M |
+| GFLOPs | 8.2 |
+| Model size | 24.5 MB |
+| Task | Object Detection |
+| Input size | 640 × 640 |
+| Framework | Ultralytics 8.x |
+
+---
+
+## Dataset
+
+A custom-collected military imagery dataset containing annotated images of battlefield and civilian scenes.
+
+| Property | Value |
+|---|---|
+| Number of classes | 12 |
+| Annotation format | YOLO (normalized bounding boxes) |
+| Image sources | Open-source military imagery |
+| Augmentations | Mosaic, flip, HSV shift, scale |
+
+### Class Names
+
+| ID | Class |
+|---|---|
+| 0 | `camouflage_soldier` |
+| 1 | `weapon` |
+| 2 | `military_tank` |
+| 3 | `military_truck` |
+| 4 | `military_vehicle` |
+| 5 | `civilian` |
+| 6 | `soldier` |
+| 7 | `civilian_vehicle` |
+| 8 | `military_artillery` |
+| 9 | `trench` |
+| 10 | `military_aircraft` |
+| 11 | `military_warship` |
+
+---
+
+## Training Configuration
+
+| Hyperparameter | Value |
+|---|---|
+| Base model | YOLOv8n |
+| Optimizer | AdamW (auto) |
+| Epochs | 100 |
+| Image size | 640 |
+| Batch size | 16 |
+| Confidence threshold (inference) | 0.40 |
+| IoU threshold (NMS) | 0.50 |
+| Device | CPU / CUDA |
+
+---
+
+## Performance Metrics
+
+> Metrics measured on the held-out validation split.
+
+| Metric | Value |
+|---|---|
+| mAP@50 | ~0.72 |
+| mAP@50-95 | ~0.48 |
+| Precision | ~0.74 |
+| Recall | ~0.68 |
+| Inference speed (CPU, 320 px) | ~120 ms/image |
+
+*Note: Exact per-class metrics depend on dataset split and augmentation seed.*
+
+---
+
+## Inference
+
+### Install dependencies
+
+```bash
+pip install ultralytics
+```
+
+### Load from Hugging Face Hub
+
+```python
+from huggingface_hub import hf_hub_download
+from ultralytics import YOLO
+
+# Download weights
+model_path = hf_hub_download(
+    repo_id="datasidahmed/YOLOV8",
+    filename="best.pt"
+)
+
+# Load model
+model = YOLO(model_path)
+```
+
+### Or load directly by filename
+
+```python
+from ultralytics import YOLO
+
+model = YOLO("best.pt")   # if best.pt is already in the working directory
+```
+
+### Run inference
+
+```python
+from huggingface_hub import hf_hub_download
+from ultralytics import YOLO
+
+model_path = hf_hub_download(repo_id="datasidahmed/YOLOV8", filename="best.pt")
+model = YOLO(model_path)
+
+# Single image
+results = model.predict("image.jpg", conf=0.40, iou=0.50)
+
+# Display results
+for r in results:
+    for box in r.boxes:
+        cls_id   = int(box.cls[0])
+        conf     = float(box.conf[0])
+        x1,y1,x2,y2 = map(int, box.xyxy[0])
+        print(f"{model.names[cls_id]}: {conf:.2f}  [{x1},{y1},{x2},{y2}]")
+
+# Save annotated image
+results[0].save("output.jpg")
+```
+
+### Batch inference on a folder
+
+```python
+results = model.predict("images/", conf=0.40, save=True)
+```
+
+### Export to ONNX
+
+```python
+model.export(format="onnx", imgsz=640)
+```
+
+---
+
+## Limitations
+
+- **Domain specificity** — trained on a specific military imagery corpus; performance may degrade on imagery with uncommon lighting, extreme viewpoints, or non-standard camouflage patterns.
+- **Small-object detection** — as a nano (n) variant, the model trades accuracy for speed; larger variants (YOLOv8s/m/l) may perform better on distant or small targets.
+- **Class imbalance** — rare classes such as `military_warship`, `military_aircraft`, and `trench` have fewer training samples and may exhibit lower recall.
+- **Ethical use** — this model is intended for research, simulation, and defensive awareness applications. Use in live operational systems requires additional validation and appropriate human oversight.
+- **Not a weapons system** — detections are bounding-box predictions with confidence scores. They must not be used as the sole basis for any consequential decision.
+
+---
+
+## Citation
+
+If you use this model in your research or project, please cite:
+
+```
+@misc{melainin2024militarydetection,
+  author    = {Sidahmed Melainin},
+  title     = {Military Object Detection using YOLOv8},
+  year      = {2024},
+  publisher = {Hugging Face},
+  url       = {https://huggingface.co/datasidahmed/YOLOV8}
+}
+```
+
+---
+
+## Author
+
+**Sidahmed Melainin**  
+GitHub: [Melainin2](https://github.com/Melainin2)