Deploy YOLOv8 attendance validator app

.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+.Python
+.pytest_cache/
+.mypy_cache/
+
+# Virtual environment
+.venv/
+venv/
+env/
+
+# Gradio / local app cache
+.gradio/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Notebook / misc
+.ipynb_checkpoints/
+
+# OS/editor
+.DS_Store
+Thumbs.db
+.vscode/
+
+# Optional model/log artifacts
+*.pt
+*.pth
+!best.pt
+logs/

README.md

@@ -1,12 +1,90 @@
 ---
-title: KLP2
-emoji: 🏃
-colorFrom: red
+title: Validasi Kehadiran Mahasiswa YOLOv8
+emoji: 🎓
+colorFrom: blue
 colorTo: green
 sdk: gradio
-sdk_version: 6.12.0
+python_version: 3.10
 app_file: app.py
-pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Implementasi Klasifikasi Kehadiran Mahasiswa Berbasis YOLOv8
+
+Proyek ini menyiapkan demo riset untuk validasi kehadiran mahasiswa di dalam ruang kelas menggunakan deteksi objek YOLOv8 dan OpenCV.
+
+## Tujuan Proyek
+
+Membangun aplikasi yang dapat:
+- menerima input gambar kelas (upload atau webcam),
+- mendeteksi objek kelas `person`,
+- menghitung jumlah mahasiswa terdeteksi,
+- membandingkan hasil deteksi dengan jumlah presensi,
+- menampilkan status validasi:
+  - `Sesuai` jika jumlah deteksi sama dengan presensi,
+  - `Tidak sesuai` jika berbeda.
+
+## Cara Kerja Validasi Presensi
+
+1. Model YOLOv8 dimuat dari `best.pt` (lokal), atau dari Hugging Face Hub (opsional).
+2. Gambar diproses untuk deteksi objek.
+3. Sistem menghitung jumlah objek `person`.
+4. Jumlah deteksi dibandingkan dengan jumlah presensi dari pengguna.
+5. Aplikasi menampilkan:
+   - gambar teranotasi bounding box,
+   - ringkasan jumlah terdeteksi,
+   - jumlah presensi,
+   - status validasi.
+
+## Evaluasi Manual (Confusion Matrix)
+
+Aplikasi menyediakan panel evaluasi manual:
+- setelah inferensi, pilih label aktual (`Sesuai` / `Tidak sesuai`),
+- klik **Update Confusion Matrix**,
+- panel akan menampilkan nilai `TP`, `FP`, `FN`, `TN`,
+- metrik `Accuracy`, `Precision`, `Recall`, dan `F1-Score` dihitung langsung dengan rumus.
+
+## Struktur File yang Diharapkan
+
+- `app.py` - aplikasi Gradio untuk Spaces
+- `requirements.txt` - dependensi Python
+- `.gitignore` - aturan ignore
+- `best.pt` - model YOLOv8 hasil training (disarankan diletakkan di root project)
+
+Opsional environment variable:
+- `MODEL_PATH` : path model lokal custom
+- `HF_MODEL_REPO` : repo model Hugging Face Hub (misalnya `username/repo-model`)
+- `HF_MODEL_FILE` : nama file model di repo Hub (default `best.pt`)
+
+## Menjalankan Secara Lokal
+
+```bash
+python -m venv .venv
+# Windows
+.venv\Scripts\activate
+# Linux/macOS
+# source .venv/bin/activate
+
+pip install -r requirements.txt
+python app.py
+```
+
+Buka URL lokal yang muncul di terminal (default Gradio).
+
+## Deploy ke Hugging Face Spaces
+
+1. Buat Space baru dengan SDK **Gradio**.
+2. Upload file:
+   - `app.py`
+   - `requirements.txt`
+   - `README.md`
+   - `.gitignore`
+   - `best.pt` (atau gunakan env Hub fallback)
+3. Jika model dari Hub, atur Secrets/Variables:
+   - `HF_MODEL_REPO`
+   - `HF_MODEL_FILE` (opsional)
+4. Space akan build otomatis dan menjalankan `app.py`.
+
+## Catatan
+
+- Fitur utama saat ini fokus pada inferensi gambar.
+- Kerangka ekstensi video sudah disiapkan sebagai stub, tetapi pipeline video penuh belum diimplementasikan.

app.py

@@ -0,0 +1,296 @@
+import os
+from functools import lru_cache
+from typing import Any, Dict, Tuple
+
+import cv2
+import gradio as gr
+import numpy as np
+from huggingface_hub import hf_hub_download
+from ultralytics import YOLO
+
+
+CM_INIT = {"tp": 0, "fp": 0, "fn": 0, "tn": 0}
+
+
+def resolve_model_path() -> str:
+    """Resolve YOLO model path from local file or Hugging Face Hub."""
+    model_env = os.getenv("MODEL_PATH", "").strip()
+    candidate_path = model_env or os.path.join(os.path.dirname(__file__), "best.pt")
+
+    if os.path.exists(candidate_path):
+        return candidate_path
+
+    hf_repo = os.getenv("HF_MODEL_REPO", "").strip()
+    hf_file = os.getenv("HF_MODEL_FILE", "best.pt").strip()
+    if hf_repo:
+        return hf_hub_download(repo_id=hf_repo, filename=hf_file)
+
+    raise FileNotFoundError(
+        "Model tidak ditemukan. Simpan file 'best.pt' di root project "
+        "atau set environment MODEL_PATH. "
+        "Opsional fallback Hugging Face Hub: set HF_MODEL_REPO dan HF_MODEL_FILE."
+    )
+
+
+@lru_cache(maxsize=1)
+def load_model() -> YOLO:
+    model_path = resolve_model_path()
+    return YOLO(model_path)
+
+
+def format_summary(detected_count: int, attendance_count: int, status: str) -> str:
+    return (
+        f"Jumlah terdeteksi: {detected_count}\n"
+        f"Jumlah presensi: {attendance_count}\n"
+        f"Status validasi: {status}"
+    )
+
+
+def _safe_div(num: float, den: float) -> float:
+    return 0.0 if den == 0 else num / den
+
+
+def compute_metrics(tp: int, fp: int, fn: int, tn: int) -> Dict[str, float]:
+    total = tp + fp + fn + tn
+    accuracy = _safe_div(tp + tn, total)
+    precision = _safe_div(tp, tp + fp)
+    recall = _safe_div(tp, tp + fn)
+    f1 = _safe_div(2 * precision * recall, precision + recall)
+    return {
+        "accuracy": accuracy,
+        "precision": precision,
+        "recall": recall,
+        "f1": f1,
+    }
+
+
+def render_evaluation_panel(cm_state: Dict[str, int]) -> str:
+    tp = int(cm_state.get("tp", 0))
+    fp = int(cm_state.get("fp", 0))
+    fn = int(cm_state.get("fn", 0))
+    tn = int(cm_state.get("tn", 0))
+    m = compute_metrics(tp, fp, fn, tn)
+
+    return f"""
+    <div class="eval-grid">
+      <div class="card">
+        <h3>Confusion Matrix</h3>
+        <table class="cm-table">
+          <thead>
+            <tr>
+              <th></th>
+              <th>Prediksi Sesuai</th>
+              <th>Prediksi Tidak sesuai</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <th>Aktual Sesuai</th>
+              <td>TP = {tp}</td>
+              <td>FN = {fn}</td>
+            </tr>
+            <tr>
+              <th>Aktual Tidak sesuai</th>
+              <td>FP = {fp}</td>
+              <td>TN = {tn}</td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+      <div class="card">
+        <h3>Perhitungan Rumus</h3>
+        <p><b>Accuracy</b> = (TP + TN) / (TP + FP + FN + TN)<br>
+           = ({tp} + {tn}) / ({tp + fp + fn + tn}) = <b>{m["accuracy"]:.4f}</b></p>
+        <p><b>Precision</b> = TP / (TP + FP)<br>
+           = {tp} / ({tp + fp}) = <b>{m["precision"]:.4f}</b></p>
+        <p><b>Recall</b> = TP / (TP + FN)<br>
+           = {tp} / ({tp + fn}) = <b>{m["recall"]:.4f}</b></p>
+        <p><b>F1-Score</b> = 2 * (Precision * Recall) / (Precision + Recall)<br>
+           = <b>{m["f1"]:.4f}</b></p>
+      </div>
+    </div>
+    """
+
+
+def _resolve_person_class_id(result: Any) -> int:
+    names = getattr(result, "names", {})
+    if isinstance(names, dict):
+        for idx, name in names.items():
+            if str(name).lower() == "person":
+                return int(idx)
+    if isinstance(names, list):
+        for idx, name in enumerate(names):
+            if str(name).lower() == "person":
+                return idx
+    return 0
+
+
+def run_attendance_validation(
+    image: np.ndarray, attendance_count: float, conf_threshold: float
+) -> Tuple[np.ndarray, str, str]:
+    if image is None:
+        raise ValueError("Silakan unggah gambar atau gunakan kamera terlebih dahulu.")
+
+    try:
+        target_attendance = int(attendance_count)
+    except (TypeError, ValueError):
+        target_attendance = 0
+
+    model = load_model()
+    image_bgr = cv2.cvtColor(image, cv2.COLOR_RGB2BGR)
+    results = model.predict(source=image_bgr, conf=conf_threshold, verbose=False)
+    result = results[0]
+
+    person_class_id = _resolve_person_class_id(result)
+    classes = result.boxes.cls.cpu().numpy() if result.boxes is not None else np.array([])
+    detected_count = int(np.sum(classes == person_class_id))
+
+    annotated_bgr = result.plot()
+    annotated_rgb = cv2.cvtColor(annotated_bgr, cv2.COLOR_BGR2RGB)
+
+    status = "Sesuai" if detected_count == target_attendance else "Tidak sesuai"
+    summary = format_summary(detected_count, target_attendance, status)
+    return annotated_rgb, summary, status
+
+
+def update_confusion_matrix(
+    cm_state: Dict[str, int], predicted_label: str, actual_label: str
+) -> Tuple[Dict[str, int], str, str]:
+    state = dict(cm_state or CM_INIT)
+
+    if predicted_label not in ("Sesuai", "Tidak sesuai"):
+        panel = render_evaluation_panel(state)
+        return state, panel, "Lakukan validasi gambar terlebih dahulu sebelum update confusion matrix."
+
+    if actual_label == "Sesuai" and predicted_label == "Sesuai":
+        state["tp"] += 1
+    elif actual_label == "Sesuai" and predicted_label == "Tidak sesuai":
+        state["fn"] += 1
+    elif actual_label == "Tidak sesuai" and predicted_label == "Sesuai":
+        state["fp"] += 1
+    else:
+        state["tn"] += 1
+
+    panel = render_evaluation_panel(state)
+    return state, panel, "Confusion matrix berhasil diperbarui."
+
+
+def reset_confusion_matrix() -> Tuple[Dict[str, int], str, str]:
+    state = dict(CM_INIT)
+    panel = render_evaluation_panel(state)
+    return state, panel, "Confusion matrix direset ke nol."
+
+
+def run_inference_ui(
+    image: np.ndarray, attendance_count: float, conf_threshold: float
+) -> Tuple[np.ndarray, str, str]:
+    try:
+        return run_attendance_validation(image, attendance_count, conf_threshold)
+    except Exception as err:
+        summary = (
+            "Proses gagal.\n"
+            f"Detail: {err}\n\n"
+            "Tips:\n"
+            "1) Pastikan file model tersedia (best.pt atau MODEL_PATH).\n"
+            "2) Jika menggunakan Hugging Face Hub, set HF_MODEL_REPO dan HF_MODEL_FILE."
+        )
+        return image, summary, ""
+
+
+def run_video_validation_stub(video_path: str) -> None:
+    """
+    Extension point for future video attendance pipeline.
+    This project intentionally keeps image inference as the primary feature.
+    """
+    raise NotImplementedError(
+        f"Video pipeline belum diimplementasikan. Input diterima: {video_path}"
+    )
+
+
+CUSTOM_CSS = """
+.container {max-width: 1200px !important; margin: auto;}
+.app-title {text-align: center; margin-bottom: 6px;}
+.app-subtitle {text-align: center; color: #4a5568; margin-top: 0;}
+.eval-grid {display: grid; grid-template-columns: 1fr; gap: 12px;}
+.card {border: 1px solid #e2e8f0; border-radius: 10px; padding: 12px; background: #ffffff;}
+.cm-table {width: 100%; border-collapse: collapse;}
+.cm-table th, .cm-table td {border: 1px solid #cbd5e1; padding: 8px; text-align: center;}
+@media (min-width: 980px) {.eval-grid {grid-template-columns: 1fr 1fr;}}
+"""
+
+
+with gr.Blocks(css=CUSTOM_CSS, title="Validasi Kehadiran Mahasiswa - YOLOv8") as demo:
+    gr.HTML(
+        """
+        <h1 class="app-title">Validasi Kehadiran Mahasiswa Berbasis YOLOv8</h1>
+        <p class="app-subtitle">
+            Implementasi klasifikasi kehadiran dalam ruang kelas berbasis citra secara real-time (demo riset).
+        </p>
+        """
+    )
+
+    cm_state = gr.State(dict(CM_INIT))
+    predicted_label_state = gr.State("")
+
+    with gr.Row():
+        with gr.Column(scale=2):
+            image_input = gr.Image(
+                label="Input Gambar Kelas",
+                type="numpy",
+                sources=["upload", "webcam"],
+            )
+            attendance_input = gr.Number(
+                label="Jumlah Presensi",
+                value=0,
+                precision=0,
+                minimum=0,
+            )
+            conf_input = gr.Slider(
+                minimum=0.1,
+                maximum=1.0,
+                value=0.25,
+                step=0.05,
+                label="Confidence Threshold",
+            )
+            run_btn = gr.Button("Proses Validasi", variant="primary")
+
+            output_image = gr.Image(label="Hasil Deteksi (Bounding Box)", type="numpy")
+            output_summary = gr.Textbox(
+                label="Ringkasan Validasi",
+                lines=5,
+                interactive=False,
+            )
+
+        with gr.Column(scale=1):
+            gr.Markdown("### Evaluasi Manual")
+            actual_label_input = gr.Radio(
+                choices=["Sesuai", "Tidak sesuai"],
+                value="Sesuai",
+                label="Label Aktual Sampel",
+            )
+            update_cm_btn = gr.Button("Update Confusion Matrix")
+            reset_cm_btn = gr.Button("Reset Confusion Matrix")
+            eval_status = gr.Markdown("Silakan proses gambar terlebih dahulu.")
+            cm_panel = gr.HTML(render_evaluation_panel(CM_INIT))
+
+    run_btn.click(
+        fn=run_inference_ui,
+        inputs=[image_input, attendance_input, conf_input],
+        outputs=[output_image, output_summary, predicted_label_state],
+    )
+
+    update_cm_btn.click(
+        fn=update_confusion_matrix,
+        inputs=[cm_state, predicted_label_state, actual_label_input],
+        outputs=[cm_state, cm_panel, eval_status],
+    )
+
+    reset_cm_btn.click(
+        fn=reset_confusion_matrix,
+        inputs=[],
+        outputs=[cm_state, cm_panel, eval_status],
+    )
+
+
+if __name__ == "__main__":
+    demo.launch()

requirements.txt

@@ -0,0 +1,5 @@
+gradio>=4.44.1
+ultralytics>=8.2.0
+opencv-python-headless>=4.10.0.84
+huggingface_hub>=0.23.0
+numpy>=1.26.0