367 lines
15 KiB
Markdown
367 lines
15 KiB
Markdown
<div align="center">
|
||
|
||
# 🎯 Sistem Presensi Cerdas Berbasis Pengenalan Wajah & Geofencing
|
||
### *AI-Powered Face Biometric & Geolocation Attendance System*
|
||
|
||
[](https://python.org)
|
||
[](https://fastapi.tiangolo.com)
|
||
[](https://www.mysql.com)
|
||
[](https://react.dev)
|
||
[](https://vitejs.dev)
|
||
[](https://expo.dev)
|
||
[](https://reactnative.dev)
|
||
[](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>
|