| --- |
| 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) |
|
|
