Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,188 @@
+---
+language:
+  - km
+  - en
+tags:
+  - object-detection
+  - text-detection
+  - yolo
+  - yolo11
+  - khmer
+  - ultralytics
+  - pytorch
+license: mit
+---
+
+# mini-text-detection — Khmer & English Text Detection
+
+A **YOLO11n**-based text detection model fine-tuned to locate and classify text regions in images containing **Khmer and English** content.  
+It detects 3 types of text blocks and can be used as the first stage before passing crops to an OCR model (e.g. [phonsobon/mini-ocr](https://huggingface.co/phonsobon/mini-ocr)).
+
+---
+
+## Model Details
+
+| Property | Value |
+|----------|-------|
+| Architecture | YOLO11n (nano) |
+| Task | Object Detection — 3 classes |
+| Weights file | `khmer-text-detection-mini.pt` |
+| Framework | Ultralytics / PyTorch |
+| Input | RGB image, any size (auto-resized internally) |
+
+---
+
+## Classes
+
+| ID | Name | Description |
+|----|------|-------------|
+| `0` | `subject` | Title or heading text |
+| `1` | `reference` | Reference, label, or metadata text |
+| `2` | `content` | Main body / paragraph text |
+
+---
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `khmer-text-detection-mini.pt` | Full Ultralytics YOLO model (weights + config) |
+
+---
+
+## Quick Start
+
+### Install dependencies
+
+```bash
+pip install ultralytics huggingface_hub
+```
+
+### Run inference
+
+```python
+from ultralytics import YOLO
+from huggingface_hub import hf_hub_download
+
+# ── Download model ────────────────────────────────────────────────────────────
+model_path = hf_hub_download(
+    repo_id="phonsobon/mini-text-detection",
+    filename="khmer-text-detection-mini.pt",
+)
+
+# ── Class names ───────────────────────────────────────────────────────────────
+CLASS_NAMES = {0: "subject", 1: "reference", 2: "content"}
+
+# ── Load & predict ────────────────────────────────────────────────────────────
+model = YOLO(model_path)
+
+results = model.predict(
+    source="your_image.jpg",   # path, URL, or numpy array
+    conf=0.25,                 # confidence threshold
+    iou=0.45,                  # NMS IoU threshold
+    imgsz=640,
+)
+
+# ── Print results ─────────────────────────────────────────────────────────────
+for r in results:
+    r.show()                                        # display with bounding boxes
+    for box in r.boxes:
+        cls_id = int(box.cls)
+        label  = CLASS_NAMES[cls_id]
+        conf   = float(box.conf)
+        x1, y1, x2, y2 = box.xyxy[0].tolist()
+        print(f"[{label}] conf={conf:.2f}  box=({x1:.0f},{y1:.0f},{x2:.0f},{y2:.0f})")
+```
+
+### Filter by class
+
+```python
+# Get only subject (heading) boxes
+subject_boxes = [b for b in results[0].boxes if int(b.cls) == 0]
+
+# Get only content (body) boxes
+content_boxes = [b for b in results[0].boxes if int(b.cls) == 2]
+```
+
+### Save annotated images
+
+```python
+results = model.predict(source="your_image.jpg", save=True, project="runs/detect")
+# Saved to runs/detect/predict/
+```
+
+### Batch inference on a folder
+
+```python
+results = model.predict(source="path/to/images/", conf=0.25, imgsz=640)
+for r in results:
+    counts = {name: 0 for name in CLASS_NAMES.values()}
+    for box in r.boxes:
+        counts[CLASS_NAMES[int(box.cls)]] += 1
+    print(r.path, "→", counts)
+```
+
+---
+
+## Crop + OCR Pipeline
+
+Combine this model with [phonsobon/mini-ocr](https://huggingface.co/phonsobon/mini-ocr) for full end-to-end document reading, with each region labelled by type:
+
+```python
+from ultralytics import YOLO
+from huggingface_hub import hf_hub_download
+from PIL import Image
+
+CLASS_NAMES = {0: "subject", 1: "reference", 2: "content"}
+
+# ── Load detection model ──────────────────────────────────────────────────────
+det_path = hf_hub_download("phonsobon/mini-text-detection", "khmer-text-detection-mini.pt")
+detector = YOLO(det_path)
+
+# ── Detect text regions ───────────────────────────────────────────────────────
+image_path = "your_image.jpg"
+results = detector.predict(source=image_path, conf=0.25, imgsz=640)
+
+img = Image.open(image_path).convert("RGB")
+
+# ── Crop each region sorted by class ─────────────────────────────────────────
+for i, box in enumerate(results[0].boxes):
+    cls_id        = int(box.cls)
+    label         = CLASS_NAMES[cls_id]
+    x1,y1,x2,y2  = map(int, box.xyxy[0].tolist())
+
+    crop = img.crop((x1, y1, x2, y2))
+    crop.save(f"crop_{i}_{label}.png")
+    print(f"Saved crop {i} → class: {label}")
+    # → feed each crop to phonsobon/mini-ocr for text recognition
+```
+
+---
+
+## Input Tips
+
+- Works on **any image size** — YOLO resizes internally to 640 px by default.
+- Best results on **document photos, screenshots, and scanned pages**.
+- Adjust `conf` (0.1 – 0.5) to trade recall vs. precision depending on your use case.
+
+---
+
+## Limitations
+
+- May miss very small text (< ~8 px height in the original image).
+- Not designed for handwritten or heavily stylised/artistic fonts.
+- Performance is best on document-style layouts similar to training data.
+
+---
+
+## Related Model
+
+| Model | Task |
+|-------|------|
+| [phonsobon/mini-ocr](https://huggingface.co/phonsobon/mini-ocr) | Text recognition (CRNN + CTC) for Khmer & English |
+
+---
+
+## License
+
+MIT