TIF_E41253336/facerecognition_presensi/README.md

367 lines
15 KiB
Markdown
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<div align="center">
# 🎯 Sistem Presensi Cerdas Berbasis Pengenalan Wajah & Geofencing
### *AI-Powered Face Biometric & Geolocation Attendance System*
[![Python](https://img.shields.io/badge/Python-3.11-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-009688?style=for-the-badge&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com)
[![MySQL](https://img.shields.io/badge/MySQL-8.0-4479A1?style=for-the-badge&logo=mysql&logoColor=white)](https://www.mysql.com)
[![React](https://img.shields.io/badge/React-19.0-61DAFB?style=for-the-badge&logo=react&logoColor=black)](https://react.dev)
[![Vite](https://img.shields.io/badge/Vite-7.0-646CFF?style=for-the-badge&logo=vite&logoColor=white)](https://vitejs.dev)
[![Expo](https://img.shields.io/badge/Expo-SDK_54-000020?style=for-the-badge&logo=expo&logoColor=white)](https://expo.dev)
[![React Native](https://img.shields.io/badge/React_Native-0.81-61DAFB?style=for-the-badge&logo=react&logoColor=black)](https://reactnative.dev)
[![PyTorch](https://img.shields.io/badge/PyTorch-Anti_Spoofing-EE4C2C?style=for-the-badge&logo=pytorch&logoColor=white)](https://pytorch.org)
<p align="center">
<b>Solusi absensi modern, presisi, dan aman yang mengintegrasikan Computer Vision, Deep Learning, deteksi anti-spoofing wajah secara real-time, dan validasi radius lokasi GPS (Geofencing).</b>
</p>
[Fitur Utama](#-fitur-utama) •
[Arsitektur AI](#-arsitektur--pipeline-biometrik) •
[Struktur Proyek](#-struktur-repositori) •
[Panduan Instalasi](#-panduan-instalasi--instalasi-cepat) •
[Dokumentasi API](#-dokumentasi-api) •
[Keamanan & Privasi](#-keamanan--privasi-data)
---
</div>
## 📖 Tentang Proyek
Sistem Presensi Pengenalan Wajah ini dirancang untuk mengatasi kecurangan absensi (*titip absen*, spoofing foto/layar digital) dan mempermudah rekapitulasi data kehadiran akademik secara *real-time*.
Platform ini mengadopsi arsitektur multi-klien:
1. **Backend API (`FastAPI`)**: Mesin backend asinkron berperforma tinggi yang menangani pipeline Machine Learning, manajemen database, dan otentikasi JWT.
2. **Web Dashboard (`React 19 + Vite`)**: Panel admin dan dosen untuk manajemen master data akademik, penjadwalan kelas, konfigurasi zona geofencing, hingga rekapitulasi dan ekspor laporan presensi.
3. **Aplikasi Mobile (`Expo / React Native`)**: Aplikasi mahasiswa untuk melakukan presensi mandiri dengan kamera live dan validasi koordinat GPS di area kelas.
---
## ✨ Fitur Utama
- 👤 **Pipeline Biometrik Wajah Multi-Tahap**:
- **Deteksi Wajah**: Menggunakan **YuNet** (ONNX runtime) yang ringan dan sangat akurat menangani berbagai sudut dan pencahayaan.
- **Anti-Spoofing (Liveness Detection)**: Menggunakan model **Silent-Face-Anti-Spoofing** (PyTorch) untuk mencegah penipuan presensi menggunakan foto cetak, replika, atau layar gawai.
- **Ekstraksi Fitur**: Menggunakan **MobileFaceNet** untuk mengekstrak vektor embedding biometrik berdimensi tinggi.
- **Pencarian Cepat & Fusi Skor**: Menggunakan **FAISS Indexing** dan tekstur **LBPH** dengan *Adaptive Score Fusion* untuk verifikasi identitas mahasiswa dalam hitungan milidetik.
- 📍 **Geofencing & Validasi Lokasi Presisi**:
- Penentuan titik lokasi kelas berbasis radius lingkaran atau poligon interaktif menggunakan Leaflet / OpenStreetMap.
- Pengecekan koordinat GPS mahasiswa secara *real-time* via Expo Location untuk memastikan mahasiswa berada di ruangan kelas saat presensi dibuka.
- 🔐 **Autentikasi & Keamanan Ketat**:
- Menggunakan JSON Web Token (JWT) berbasis OAuth2 Password Bearer.
- Role-based Access Control (Admin, Dosen, Mahasiswa).
- 📊 **Manajemen Akademik Komprehensif**:
- Pengelolaan Program Studi, Angkatan, Golongan, Kelas, Mata Kuliah, Dosen, dan Mahasiswa.
- Penjadwalan pertemuan terstruktur, log riwayat deteksi wajah, dan ekspor data presensi ke format Excel (`.xlsx`).
---
## 🧠 Arsitektur & Pipeline Biometrik
```mermaid
flowchart TD
subgraph Client ["📱 Klien (Mobile / Web)"]
Cam["📸 Live Camera Feed"]
GPS["📍 Real-Time GPS Coordinate"]
end
subgraph BackendGateway ["🛡️ Backend Gateway (FastAPI)"]
Auth["OAuth2 / JWT Verification"]
GeoCheck{"Validasi Radius Geofencing?"}
end
subgraph AIPipeline ["🧠 AI Pipeline (ModelBaru)"]
Det["Face Detection\n(YuNet ONNX)"]
AntiSpoof{"Anti-Spoofing Check\n(SilentFace PyTorch)"}
Embed["Feature Extraction\n(MobileFaceNet 512-d)"]
Match["Vector Similarity Search\n(FAISS + LBPH Score Fusion)"]
end
subgraph Database ["🗄️ Database & Storage"]
MySQL[("MySQL 8.0\n20 Tables")]
FAISScache[("Vector Cache & Index")]
end
Cam --> Auth
GPS --> Auth
Auth --> GeoCheck
GeoCheck -- "❌ Di luar radius" --> RejectGeo["Tolak: Lokasi di luar batas"]
GeoCheck -- "✅ Valid" --> Det
Det --> AntiSpoof
AntiSpoof -- "❌ Spoofing Terdeteksi" --> RejectSpoof["Tolak: Wajah Tidak Hidup / Fake"]
AntiSpoof -- "✅ Real Human" --> Embed
Embed --> Match
Match <--> FAISScache
Match -- "✅ Kecocokan Terpenuhi" --> Record["Simpan Status Hadir"]
Record --> MySQL
```
---
## 🛠️ Tech Stack
| Layer | Teknologi | Deskripsi |
| :--- | :--- | :--- |
| **Backend** | Python 3.11, FastAPI, SQLAlchemy, Uvicorn | RESTful API berkecepatan tinggi, ORM terstruktur, OpenAPI auto-docs |
| **Database** | MySQL 8.0 | Penyimpanan relasional terindeks untuk data akademik dan transaksi presensi |
| **AI / Computer Vision** | OpenCV, ONNX Runtime, PyTorch, FAISS | YuNet (Detection), MobileFaceNet (Embedding), SilentFaceAntiSpoofing (Liveness) |
| **Web Dashboard** | React 19, Vite, Tailwind CSS, React-Leaflet | Antarmuka web responsif dengan visualisasi peta geofencing dan tabel interaktif |
| **Aplikasi Mobile** | React Native, Expo SDK 54, Expo Router, Expo Camera | Aplikasi mobile Android dengan akses kamera native dan sensor GPS berakurasi tinggi |
---
## 📂 Struktur Repositori
```text
facerecognition_presensi/
├── backend/ # REST API FastAPI & Manajemen Database
│ ├── app/
│ │ ├── config/ # Konfigurasi aplikasi & database
│ │ ├── controllers/ # Logika bisnis dan handler
│ │ ├── models/ # Definisi model tabel SQLAlchemy (20 tabel)
│ │ ├── routes/ # Router endpoint modular (auth, presensi, dll.)
│ │ ├── schemas/ # Skema validasi Pydantic
│ │ └── services/ # Layanan biometrik, geolokasi, & token
│ ├── init_db.py # Inisialisasi skema tabel database
│ ├── seed.py # Pembuatan akun Super Admin interaktif
│ ├── requirements.txt # Dependensi pustaka Python
│ └── .env.example # Contoh variabel lingkungan backend
├── ModelBaru/ # Core AI Pipeline (YuNet, MobileFaceNet, FAISS)
│ ├── models/ # Model bobot ONNX (YuNet, MobileFaceNet)
│ ├── resources/ # Model bobot PyTorch Anti-Spoofing
│ ├── enhanced_system.py # Koordinator sistem biometrik terpadu
│ ├── anti_spoof_manager.py # Modul deteksi liveness / anti-spoof
│ └── faiss_gallery.py # Pengindeksan & pencarian vektor embedding
├── SilentFaceAntiSpoofing/ # Pustaka pendukung deteksi anti-spoofing
├── Website/ # Web Dashboard Admin & Dosen
│ ├── src/ # Komponen UI, Halaman, dan Konfigurasi Route
│ ├── package.json # Dependensi frontend React 19 & Tailwind
│ └── .env.example # Contoh variabel lingkungan frontend
└── AndroidFolder/ # Aplikasi Mobile Mahasiswa
├── app/ # Routing navigasi (Expo Router)
├── package.json # Dependensi Expo SDK 54 & React Native
└── .env.example # Contoh konfigurasi URL API mobile
```
---
## 🚀 Panduan Instalasi & Menjalankan Sistem
### 📋 Prasyarat Sistem
Pastikan perangkat Anda telah terpasang:
- **Python**: Versi `3.10` atau `3.11` *(Disarankan 3.11 untuk kompatibilitas ONNX/TensorFlow)*
- **Node.js**: Versi `20.19+` atau `22.12+` dan npm
- **Database**: MySQL Server 8.x aktif
- **Mobile Development**: Expo Go pada perangkat Android fisik atau Android Studio Emulator
---
### 1️⃣ Konfigurasi Database (MySQL)
Buka MySQL Client / phpMyAdmin / DBeaver, lalu buat database dan pengguna khusus:
```sql
CREATE DATABASE skripsi_presensi CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'presensi_app'@'localhost' IDENTIFIED BY 'PasswordKuatAnda123!';
GRANT ALL PRIVILEGES ON skripsi_presensi.* TO 'presensi_app'@'localhost';
FLUSH PRIVILEGES;
```
---
### 2️⃣ Konfigurasi & Menjalankan Backend
Buka terminal PowerShell pada direktori root proyek:
```powershell
# 1. Masuk ke folder backend
cd backend
# 2. Buat virtual environment Python 3.11
py -3.11 -m venv venv
.\venv\Scripts\Activate.ps1
# 3. Perbarui pip dan pasang pustaka
python -m pip install --upgrade pip
pip install -r requirements.txt
# 4. Buat file .env dari template
Copy-Item .env.example .env
```
Buka dan sesuaikan file `backend/.env`:
```env
DB_HOST=localhost
DB_PORT=3306
DB_USER=presensi_app
DB_PASSWORD=PasswordKuatAnda123!
DB_NAME=skripsi_presensi
# Generate secret key dengan: python -c "import secrets; print(secrets.token_hex(32))"
SECRET_KEY=masukkan_secret_key_acak_minimal_32_karakter_disini
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=60
DEBUG=false
FACE_MODEL_TYPE=enhanced
PRELOAD_ML_MODEL=false
UPLOAD_DIR=uploads
DATASET_DIR=datasets
```
Inisialisasi tabel database dan buat akun Admin pertama:
```powershell
# Inisialisasi 20 tabel database otomatis
python init_db.py
# Buat akun Admin utama secara interaktif
python seed.py
# Jalankan server FastAPI
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```
> 🌐 **Backend aktif di**: `http://localhost:8000`
> 📑 **Dokumentasi Swagger API**: `http://localhost:8000/api/docs`
> 💓 **Health Check**: `http://localhost:8000/api/health`
---
### 3️⃣ Menjalankan Web Dashboard (React + Vite)
Buka terminal baru dari root direktori proyek:
```powershell
cd Website
# Pasang dependensi
npm ci
# Siapkan file environment
Copy-Item .env.example .env
```
Pastikan isi `Website/.env` mengarah ke backend Anda:
```env
VITE_API_BASE_URL=http://localhost:8000/api/v1
```
Jalankan server pengembangan:
```powershell
npm run dev
```
> 💻 Akses dashboard melalui browser pada tautan lokal yang ditampilkan Vite (biasanya `http://localhost:5173`).
---
### 4️⃣ Menjalankan Aplikasi Mobile (Expo / Android)
Buka terminal baru dari root direktori proyek:
```powershell
cd AndroidFolder
# Pasang dependensi
npm ci
# Siapkan file environment
Copy-Item .env.example .env
```
Edit file `AndroidFolder/.env`:
- **Jika menggunakan Android Emulator**:
```env
EXPO_PUBLIC_API_URL=http://10.0.2.2:8000
```
- **Jika menggunakan Perangkat HP Fisik (Expo Go)**:
```env
EXPO_PUBLIC_API_URL=http://192.168.x.x:8000
```
*(Ganti `192.168.x.x` dengan alamat IPv4 LAN komputer Anda yang satu jaringan Wi-Fi dengan HP)*.
Mulai aplikasi Expo:
```powershell
npm start
```
Scan QR code yang muncul di terminal menggunakan aplikasi **Expo Go** pada smartphone Android Anda.
---
## 🧭 Alur Kerja Penggunaan Pertama Kali
```text
1. Login Admin di Web Dashboard
└── Buat data master: Program Studi, Angkatan, Golongan, Kelas, Dosen, Mahasiswa.
│
2. Pendaftaran Wajah (Enrollment)
└── Ambil/unggah foto wajah mahasiswa berwenang untuk membentuk template embedding biometrik.
│
3. Konfigurasi Jadwal & Pertemuan
└── Tentukan lokasi kelas (titik koordinat & radius geofence) dan buka sesi pertemuan.
│
4. Presensi Mandiri Mahasiswa (Mobile)
└── Mahasiswa membuka aplikasi -> Verifikasi lokasi GPS -> Pindai wajah (Liveness + Face Match).
│
5. Rekapitulasi & Monitoring
└── Admin/Dosen memantau data kehadiran live dan dapat mengunduh rekapitulasi nilai presensi ke Excel.
```
---
## 📡 Ringkasan Endpoint API
Dokumentasi lengkap dan interaktif dapat diuji langsung melalui Swagger UI di `http://localhost:8000/api/docs`.
| Modul | Method | Endpoint | Deskripsi |
| :--- | :---: | :--- | :--- |
| **Auth** | `POST` | `/api/v1/auth/login` | Otentikasi pengguna & generate JWT bearer token |
| **Akademik** | `GET/POST` | `/api/v1/mahasiswa/` | Manajemen data mahasiswa |
| | `GET/POST` | `/api/v1/dosen/` | Manajemen data dosen |
| | `GET/POST` | `/api/v1/jadwal/` | Penjadwalan mata kuliah & kelas |
| **Geolokasi** | `GET/POST` | `/api/v1/geolokasi/` | Konfigurasi koordinat dan radius geofencing |
| **Biometrik** | `POST` | `/api/v1/enhanced-recognition/recognize` | Presensi wajah dengan YuNet + Anti-Spoofing + FAISS |
| | `POST` | `/api/v1/arcface-enrollment/enroll` | Pendaftaran sampel wajah mahasiswa baru |
| **Presensi** | `POST` | `/api/v1/presensi/` | Pencatatan transaksi presensi mahasiswa |
| | `GET` | `/api/v1/history-presensi/` | Riwayat dan log deteksi presensi |
---
## 🗄️ Skema Database
Skrip `init_db.py` secara otomatis menginisialisasi 20 tabel relasional yang saling terhubung:
| Kategori | Tabel-tabel Terkait |
| :--- | :--- |
| **Otentikasi & Akun** | `users` |
| **Struktur Akademik** | `prodi`, `angkatan`, `golongan`, `kelas`, `matakuliah` |
| **Sivitas Akademika** | `dosen`, `mahasiswa` |
| **Kurikulum & Kelas** | `penawaran_matakuliah`, `penawaran_kelas`, `pengajar` |
| **Perkuliahan & Jadwal** | `geolokasi`, `jadwal`, `pertemuan`, `pengajar_pertemuan` |
| **Biometrik Wajah** | `dataset_wajah`, `registrasi_wajah`, `log_deteksi` |
| **Presensi & Rekap** | `presensi`, `history_presensi` |
---
## 🔒 Keamanan & Privasi Data
- 🛑 **Jangan Unggah Data Pribadi**: File foto wajah mahasiswa, database dump produksi, dan file cache embedding (`face_metadata.pkl`, `face_mahasiswa/`, `uploads/`, `datasets/`) sudah masuk ke dalam `.gitignore`.
- 🔑 **Kerahasiaan Kunci (.env)**: Selalu gunakan nilai acak `SECRET_KEY` yang unik pada setiap instalasi server. Jangan pernah commit file `.env`.
- 🛡️ **Proteksi Liveness**: Algoritma anti-spoofing aktif secara otomatis menolak masukan gambar dari layar smartphone, tablet, atau kertas foto cetak untuk mencegah kecurangan absensi.
---
## 📄 Lisensi & Kredit
Proyek ini dikembangkan untuk kebutuhan riset dan sistem presensi akademik.
- **Deteksi Wajah**: [OpenCV Zoo YuNet](https://github.com/opencv/opencv_zoo/tree/master/models/face_detection_yunet)
- **Anti-Spoofing**: [Silent-Face-Anti-Spoofing](https://github.com/minivision-ai/Silent-Face-Anti-Spoofing)
- **Pengenalan Wajah**: [MobileFaceNet](https://github.com/sirius-ai/MobileFaceNet_TF)
- **Vector Search**: [FAISS - Meta Research](https://github.com/facebookresearch/faiss)
---
<div align="center">
<sub>Dikembangkan dengan dedikasi untuk integritas presensi akademik berbasis Artificial Intelligence.</sub>
</div>