Blame for README.md

---
title: Klasifikasi Kehadiran Mahasiswa YOLOv8
emoji: 🎓
colorFrom: blue
colorTo: green
sdk: gradio
python_version: "3.10"
app_file: app.py
---

# Pengecekan dan Klasifikasi Person Berbasis YOLOv8

Versi ini difokuskan untuk tahap awal:
- pengecekan gambar kelas,
- deteksi objek `person`,
- klasifikasi sederhana `person` vs `not person/background`.

## Tujuan Fitur Saat Ini

1. Upload gambar atau ambil dari kamera.
2. Jalankan deteksi `person` dengan YOLOv8.
3. Tampilkan hasil:
   - gambar teranotasi bounding box,
   - jumlah person terdeteksi,
   - kelas prediksi evaluasi `Person` / `Not Person/Background`,
   - confusion matrix dan rumus evaluasi,
   - arsip evaluasi lokal (gambar hasil + CSV),
   - grafik hasil pengecekan.
4. Setelah proses cek, confusion matrix dan rumus evaluasi diperbarui otomatis tanpa input manual tambahan.

## Struktur UI

- **Tahap 1 - Pilih Model**
  - mode inferensi
  - pilihan model `YOLOv8n` atau `Best.pt`
  - confidence threshold
  - advanced options:
    - gaya anotasi `Border + Label` atau `Label saja`
- **Tahap 2 - Training dan Evaluasi Model**
  - membaca dataset dari `dataset/train` dan `dataset/test`
  - pilihan model awal training: `YOLOv8n` atau `Best.pt`
  - jika label `.txt` YOLO belum ada, bisa aktifkan pseudo-label
  - training dijalankan di background process (server-side)
  - progres bisa dipantau kembali setelah reconnect (status + log + grafik)
  - terminal training live untuk progres epoch
  - grafik training otomatis (loss, precision, recall, mAP per epoch)
  - confusion matrix training dari hasil validasi YOLO
  - ringkasan precision, recall, mAP50, dan mAP50-95
  - output model terbaik selalu di-overwrite ke `best.pt` setiap training selesai
  - file `results.csv` training tersedia sebagai arsip metrik lokal
  - file `training.log`, `training_curve_latest.png`, dan `confusion_matrix_latest.png` juga disimpan lokal
  - jika env Hugging Face diisi, `best.pt` dan artefak training otomatis di-sync ke repo HF
  - grafik training disimpan permanen sebagai gambar PNG di `training_outputs/training_curve_latest.png` dan `space_training_archive/<run>/training_curve.png`
  - persiapan dataset dan pseudo-label berjalan di background worker, sehingga training tidak berhenti hanya karena koneksi browser terputus
- **Tahap 3 - Input Gambar**
  - input gambar (upload/webcam)
  - tombol proses
- **Tahap 4 - Grafik Hasil Deteksi**
  - grafik count `Person` dan `Not Person/Background`
- **Tahap 5 - Evaluasi Foto Uji**
  - confusion matrix berbasis count objek `Person` dan `Not Person/Background`
  - rumus Accuracy, Precision, Recall, dan F1 dengan substitusi angka
- **Tahap 6 - Hasil Gambar**
  - hasil gambar deteksi
  - ringkasan klasifikasi `person` vs `not person/background`
  - file gambar evaluasi dan file CSV evaluasi lokal

Catatan:
- evaluasi dilakukan pada kelas `Person` dan `Not Person/Background` berbasis count objek.
- panel evaluasi diperbarui otomatis setelah inferensi.
- hasil confidence rendah/tinggi dapat diamati melalui slider confidence dan arsip CSV evaluasi.
- UI otomatis menyesuaikan mode gelap perangkat (dark mode).
- output gambar dapat diperbesar melalui file hasil evaluasi yang tersimpan.
- `Best.pt` mengikuti kelas yang memang tersedia pada model hasil training.
- Jika `best.pt` belum tersedia, opsi `Best.pt` tetap muncul di UI, tetapi proses akan menampilkan pesan bahwa model sedang belum tersedia dan perlu training terlebih dahulu.
- `YOLOv8n.pt` dipakai sebagai model default yang masih mendeteksi semua objek umum.
- `Best.pt` dipakai sebagai model hasil training yang difokuskan ke `Person` saja.

## File Penting

- `app.py` - aplikasi Gradio
- `requirements.txt` - dependensi
- `yolov8n.pt` - model default
- `.gitignore` - aturan ignore
- `CHANGELOG.md` - riwayat update (termasuk nomor update)
- `skills/update-tracking/SKILL.md` - panduan konsistensi versi & format update
- `evaluation_outputs/` - arsip hasil deteksi untuk evaluasi artikel
- `runs_train/` - hasil training dan grafik/metrik YOLO
- `training_outputs/` - arsip lokal grafik PNG dan summary training terbaru

## Tracking Versi

- UI menampilkan versi kecil di bagian atas dan bawah halaman.
- Konfigurasi versi ada di `app.py`:
  - `APP_VERSION`
  - `APP_MINOR_UPDATE`
- Setiap perubahan sebaiknya menambah entri `CHANGELOG.md`.

Opsional environment variable:
- `MODEL_PATH` - path model lokal custom
- `HF_MODEL_REPO` - repo target Hugging Face (contoh: `KLP2-PCD/KLP2`)
- `HF_MODEL_FILE` - nama file model di Hub (disarankan: `best.pt`)
- `HF_MODEL_REPO_TYPE` - tipe repo HF: `space` (default), `model`, atau `dataset`
- `HF_TOKEN` - token untuk upload otomatis saat training selesai
- `HF_DETECTION_DIR` - folder khusus di repo HF untuk auto-save hasil deteksi (default: `space_detection_archive`)
- `HF_TRAINING_DIR` - folder khusus di repo HF untuk auto-save artefak training (default: `space_training_archive`)
- `HF_ARTIFACT_REPO` - repo dataset/model terpisah untuk menyimpan dan menampilkan ulang artefak training terakhir (contoh: `KLP2-PCD/KLP2-training-artifacts`)
- `HF_ARTIFACT_REPO_TYPE` - tipe repo artefak, default `dataset`
- `HF_AUTOSYNC_ENABLED` - aktif/nonaktif auto-sync file repo (`true/false`)
- `HF_AUTOSYNC_LOCAL_ONLY` - default `true`, artinya autosync hanya jalan dari lokal
- `HF_AUTOSYNC_REALTIME` - default `false`; jika `true` baru watcher realtime aktif
- `HF_AUTOSYNC_REPO_ID` - repo target auto-sync (fallback ke `HF_MODEL_REPO`)
- `HF_AUTOSYNC_REPO_TYPE` - tipe repo target auto-sync (default `space`)
- `HF_AUTOSYNC_TOKEN` - token auto-sync (fallback ke `HF_TOKEN`)
- `HF_AUTOSYNC_INTERVAL_SEC` - interval cek perubahan file (default `3` detik)
- `HF_AUTOSYNC_DEBOUNCE_SEC` - jeda batch commit agar tidak commit tiap perubahan kecil (default `8` detik)
- `HF_AUTOSYNC_INCLUDE_GLOBS` - pola file yang ingin disync (default `*.py,*.md,requirements.txt,.gitignore`)
- `HF_AUTOSYNC_MAX_FILE_MB` - batas ukuran file yang di-sync (default `200` MB)
- `HF_AUTOSYNC_IGNORE_GLOBS` - daftar pola file/folder yang diabaikan (dipisah koma)
- `HF_ALLOW_SPACE_RUNTIME_COMMITS` - default `false`; aktifkan hanya jika benar-benar ingin app melakukan commit ke repo Space yang sedang berjalan

Catatan sync otomatis setelah training:
- Jika `HF_MODEL_REPO` terisi, aplikasi akan upload `best.pt` ke `HF_MODEL_FILE`.
- Jika tidak terisi, training tetap jalan normal dan hanya menyimpan `best.pt` lokal.
- Jika `HF_MODEL_REPO` menunjuk ke Space yang sama, upload runtime dinonaktifkan secara default agar Space tidak rebuild sendiri dan memunculkan 503.

Catatan auto-save hasil deteksi:
- Setelah inferensi sukses, aplikasi menyimpan gambar anotasi ke `evaluation_outputs/` lokal.
- Jika `HF_MODEL_REPO` terisi, gambar hasil deteksi dan `detection_log.csv` juga otomatis di-upload ke folder repo `HF_DETECTION_DIR`.

Catatan auto-save hasil training:
- Setelah training selesai, grafik training, confusion matrix training, `results.csv`, `training.log`, dan summary JSON disimpan ke folder repo `HF_TRAINING_DIR`.
- File grafik terbaru juga disalin ke `training_outputs/training_curve_latest.png` agar tetap bisa ditampilkan ulang setelah Space rebuild.
- Proses training juga langsung menyalin grafik YOLO `results.png` menjadi PNG permanen saat training selesai, sehingga tidak bergantung pada refresh browser.
- Jika koneksi browser terputus saat training, artefak tetap aman setelah proses training selesai dan sync ke repo berhasil. Jika container berhenti sebelum training selesai, artefak final memang belum sempat dibuat.
- Pseudo-label dari dataset tanpa label `.txt` dapat memakan waktu di CPU Space karena semua gambar harus diproses YOLOv8n sebelum epoch dimulai.
- Panel training akan mengambil ulang data terakhir dari `HF_ARTIFACT_REPO` saat Space rebuild, sehingga metrik dan grafik terakhir tetap tampil di UI.

Catatan auto-sync update file repo:
- Default `HF_AUTOSYNC_ENABLED=false`, jadi tidak ada sync repo saat startup/runtime.
- Jika ingin sync repo otomatis, aktifkan manual: `HF_AUTOSYNC_ENABLED=true`.
- Untuk mode realtime, tambahkan `HF_AUTOSYNC_REALTIME=true`.
- Disarankan tetap fokus ke sync model `best.pt` setelah training (lebih ringan dan stabil).

## Menjalankan Lokal

```bash
python -m venv .venv
# Windows
.venv\Scripts\activate

pip install -r requirements.txt
python app.py
```

## Setup Kontributor Windows/VS Code

### Opsi A - Installer Otomatis

Jika laptop teman belum punya Git, Python, atau VS Code, jalankan:

```cmd
install_windows.bat
```

Atau dari PowerShell:

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install_windows.ps1
```

Installer ini memakai `winget` untuk menyiapkan:
- Git for Windows,
- Python 3.10,
- Visual Studio Code.

Setelah aplikasi dasar siap, installer otomatis lanjut menjalankan `setup_contributor.ps1`.

Catatan:
- `winget` biasanya tersedia di Windows 10/11 melalui App Installer.
- Jika `winget` tidak ada, install **App Installer** dari Microsoft Store.
- Beberapa laptop mungkin meminta izin administrator saat install aplikasi.

### Opsi B - Setup Project Saja

Pastikan teman kelompok sudah:
- menjadi member organization `KLP2-PCD` dengan akses write,
- punya Git for Windows,
- punya Python 3.10+,
- punya token Hugging Face dengan permission write ke `KLP2-PCD/KLP2`.

Jalankan dari PowerShell:

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\setup_contributor.ps1
```

Script akan:
- clone repo `KLP2-PCD/KLP2`,
- membuat `.venv`,
- upgrade `pip`, `setuptools`, dan `wheel`,
- install dependency dari `requirements.txt`,
- menjalankan `pip check`,
- menyiapkan ekstensi VS Code: Python, Pylance, dan Jupyter,
- memakai konfigurasi workspace dari `.vscode/settings.json`,
- validasi `app.py`,
- set remote agar bisa `git push`,
- membuka folder di VS Code jika command `code` tersedia.

Package Python yang dipasang:

```text
gradio
ultralytics
opencv-python-headless
huggingface_hub
numpy
matplotlib
seaborn
```

Alur kerja setelah edit:

```powershell
git status
git add app.py README.md CHANGELOG.md requirements.txt
git commit -m "update fitur"
git push origin main
```

## Deploy ke Hugging Face Spaces

Upload:
- `app.py`
- `requirements.txt`
- `README.md`
- `.gitignore`
- `yolov8n.pt` (atau gunakan env Hub fallback)