README.md

metadata

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

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:

install_windows.bat

Atau dari 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:

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:

gradio
ultralytics
opencv-python-headless
huggingface_hub
numpy
matplotlib
seaborn

Alur kerja setelah edit:

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)