Update README.md

README.md

@@ -1,338 +1,380 @@
-# Attendr - Smart Attendance System 🎓
-
-An AI-powered smart attendance system for Universiti Teknologi Malaysia (UTM) that combines **facial recognition**, **geolocation verification**, and **auto-refresh attendance codes** to eliminate proxy attendance and streamline the attendance process.
-
-![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)
-![Flask](https://img.shields.io/badge/Flask-3.0-green.svg)
-![License](https://img.shields.io/badge/License-MIT-yellow.svg)
-
-## ✨ Features
-
-### For Students
-- 🎭 **Biometric Face Recognition** - Secure identity verification using AI
-- 📍 **GPS Location Validation** - Confirms physical presence in classroom
-- 🔐 **Auto-Refresh Codes** - Time-limited codes prevent sharing
-- ⚡ **Real-time Feedback** - Instant attendance confirmation
-- 📱 **Mobile Friendly** - Works on smartphones and tablets
-
-### For Lecturers
-- 🎯 **One-Click Session Creation** - Quick setup for any class
-- 🔄 **Auto-Refreshing Codes** - New code every 2 minutes
-- 📊 **Real-time Monitoring** - Live attendance updates
-- 📥 **Export Reports** - Download CSV for record-keeping
-- 📈 **Attendance Analytics** - View statistics at a glance
-
-### Security Features
-- ✅ Prevents proxy attendance through face + location verification
-- ✅ Time-limited codes expire automatically
-- ✅ All verifications logged with timestamps
-- ✅ Distance tracking from classroom center
-
-## 🧠 AI Logic & Knowledge Representation
-
-Attendr implements **5 Knowledge Representation (KR) rules** using First-Order Logic:
-
-1. **Face Recognition**: `∀x ((CapturedFace(x) ∧ MatchStored(x)) → FaceMatch(x))`
-2. **Location Verification**: `∀x[(Student(x) ∧ IsWithinAllowedArea(x)) → VerifiedLocation(x)]`
-3. **Device Readiness**: `∀d ((CameraOn(d) ∧ GPSOn(d)) → StartVerification(d))`
-4. **Attendance Validation**: `∀x ((FaceMatch(x) ∧ LocationValid(x)) → GrantCodeAccess(x))`
-5. **Code Confirmation**: `∀x ((ValidCodeEntry(User,x) ∧ WithinCycle(Code,x)) → MarkPresent(System,x))`
-
-## 🚀 Installation
-
-### Prerequisites
-- Python 3.8 or higher
-- Webcam for face capture
-- GPS-enabled device (or browser location services)
-
-### Step 1: Clone Repository
-```bash
-git clone <repository-url>
-cd smartAttandence
-```
-
-### Step 2: Install Dependencies
-
-#### Windows (Recommended Method)
-```powershell
-# Install Visual C++ Build Tools first (required for dlib)
-# Download from: https://visualstudio.microsoft.com/visual-cpp-build-tools/
-
-# Create virtual environment
-python -m venv venv
-venv\Scripts\activate
-
-# Install dependencies
-pip install -r requirements.txt
-```
-
-#### Alternative: Use Pre-compiled Wheels
-If you encounter issues installing `face_recognition`, use pre-compiled wheels:
-```powershell
-pip install https://github.com/jloh02/dlib/releases/download/v19.22/dlib-19.22.99-cp38-cp38-win_amd64.whl
-pip install face_recognition
-```
-
-### Step 3: Initialize Database
-```bash
-python init_db.py
-```
-
-This creates:
-- SQLite database with all tables
-- Sample UTM classrooms (N28, V01, C22)
-- Test student account
-
-### Step 4: Run Application
-```bash
-python app.py
-```
-
-The application will be available at: **http://localhost:5000**
-
-## 📖 Usage Guide
-
-### For Students
-
-1. **Register Your Face**
-   - Visit `/register`
-   - Enter Student ID and Name
-   - Capture your face using webcam
-   - System stores your biometric encoding
-
-2. **Mark Attendance**
-   - Visit `/student`
-   - Enter Student ID and select active session
-   - Enable camera and GPS permissions
-   - System verifies your face and location
-   - Enter attendance code displayed by lecturer
-   - Attendance marked instantly!
-
-### For Lecturers
-
-1. **Create Session**
-   - Visit `/lecturer`
-   - Enter course name and your name
-   - Select classroom location
-   - Click "Create Session"
-
-2. **Display Code**
-   - Large attendance code appears on screen
-   - Code auto-refreshes every 2 minutes
-   - Show this code to students in class
-
-3. **Monitor Attendance**
-   - View real-time attendance list
-   - See verification details (distance, time)
-   - Export CSV report when done
-
-## 🗂️ Project Structure
-
-```
-smartAttandence/
-├── app.py                          # Main Flask application
-├── config.py                       # Configuration settings
-├── models.py                       # Database models
-├── init_db.py                      # Database initialization
-├── requirements.txt                # Python dependencies
-│
-├── face_recognition_module.py      # Face recognition logic (KR Rule #1)
-├── geolocation_module.py           # GPS verification (KR Rule #2)
-├── attendance_code_module.py       # Auto-refresh codes (KR Rule #5)
-├── utils.py                        # Helper functions
-│
-├── static/
-│   ├── css/
-│   │   └── style.css              # Premium design system
-│   └── js/
-│       ├── student.js             # Student portal logic
-│       └── lecturer.js            # Lecturer dashboard logic
-│
-└── templates/
-    ├── index.html                 # Landing page
-    ├── student.html               # Student portal
-    ├── lecturer.html              # Lecturer dashboard
-    └── register.html              # Face registration
-```
-
-## 🔧 Configuration
-
-Edit `config.py` to customize:
-
-```python
-# Face recognition settings
-FACE_RECOGNITION_TOLERANCE = 0.6    # Lower = more strict (0.4-0.6 recommended)
-
-# Geolocation settings
-GEOLOCATION_RADIUS_METERS = 50      # Classroom detection radius
-
-# Attendance code settings
-CODE_REFRESH_INTERVAL_SECONDS = 120 # Code refresh interval (2 minutes)
-CODE_LENGTH = 6                     # Length of attendance code
-```
-
-## 🌐 API Endpoints
-
-### Student Endpoints
-- `POST /api/register_face` - Register student face encoding
-- `POST /api/verify_face` - Verify face against stored encoding
-- `POST /api/verify_location` - Validate GPS location
-- `POST /api/mark_attendance` - Mark attendance with code
-
-### Lecturer Endpoints
-- `POST /api/create_session` - Create attendance session
-- `GET /api/get_session/<id>` - Get session details with current code
-- `GET /api/get_attendance/<id>` - Get attendance records
-- `POST /api/end_session/<id>` - End session
-
-### General Endpoints
-- `GET /api/get_active_sessions` - List all active sessions
-- `GET /api/classrooms` - Get all classrooms
-
-## 🧪 Testing
-
-### Manual Testing Checklist
-
-**Face Recognition:**
-- [ ] Register new student face
-- [ ] Verify with same person (should succeed)
-- [ ] Verify with different person (should fail)
-- [ ] Test with poor lighting
-- [ ] Test with glasses/mask
-
-**Geolocation:**
-- [ ] Mark attendance from inside classroom (should succeed)
-- [ ] Mark attendance from outside radius (should fail)
-- [ ] Verify distance calculation accuracy
-
-**Auto-Refresh Codes:**
-- [ ] Code refreshes every 2 minutes
-- [ ] Expired code rejected
-- [ ] Valid code accepted
-- [ ] Code sharing prevented
-
-**End-to-End Flow:**
-- [ ] Complete student registration
-- [ ] Lecturer creates session
-- [ ] Student marks attendance successfully
-- [ ] Attendance appears in real-time
-- [ ] Export CSV works
-
-## 🐛 Troubleshooting
-
-### Face Recognition Issues
-
-**Problem:** `dlib` installation fails on Windows
-**Solution:** 
-1. Install Visual C++ Build Tools
-2. Or use pre-compiled wheel: `pip install dlib-19.22.99-cp38-cp38-win_amd64.whl`
-
-**Problem:** "No face detected"
-**Solution:**
-- Ensure good lighting
-- Face camera directly
-- Remove glasses/mask if possible
-- Move closer to camera
-
-### GPS Issues
-
-**Problem:** Location permission denied
-**Solution:**
-- Enable location services in browser settings
-- Use HTTPS (required for geolocation API)
-- Check device GPS is enabled
-
-**Problem:** "Location unavailable"
-**Solution:**
-- Ensure GPS is enabled on device
-- Try outdoors for better signal
-- Check browser location permissions
-
-### Code Validation Issues
-
-**Problem:** "Code has expired"
-**Solution:**
-- Enter code within 2-minute window
-- Check lecturer's displayed code
-- Ensure system clocks are synchronized
-
-## 📊 Database Schema
-
-### Students Table
-- `id` - Primary key
-- `student_id` - Unique student identifier
-- `name` - Student name
-- `email` - Email address
-- `face_encoding` - Biometric data (JSON)
-- `registered_at` - Registration timestamp
-
-### Classrooms Table
-- `id` - Primary key
-- `name` - Classroom name (e.g., N28-01-01)
-- `building` - Building name
-- `latitude` - GPS latitude
-- `longitude` - GPS longitude
-- `radius_meters` - Geofencing radius
-
-### AttendanceSessions Table
-- `id` - Primary key
-- `course_name` - Course name
-- `lecturer_name` - Lecturer name
-- `classroom_id` - Foreign key to Classrooms
-- `current_code` - Active attendance code
-- `code_generated_at` - Code generation time
-- `is_active` - Session status
-
-### AttendanceRecords Table
-- `id` - Primary key
-- `session_id` - Foreign key to AttendanceSessions
-- `student_id` - Foreign key to Students
-- `marked_at` - Attendance timestamp
-- `face_verified` - Face verification status
-- `location_verified` - Location verification status
-- `code_verified` - Code verification status
-- `distance_from_classroom` - Distance in meters
-
-## 🎨 Design Philosophy
-
-Attendr features a **premium dark mode design** with:
-- 🌈 Vibrant gradient accents
-- ✨ Glassmorphism effects
-- 🎭 Smooth micro-animations
-- 📱 Fully responsive layout
-- 🎯 Modern typography (Inter + Outfit fonts)
-
-## 🤝 Contributing
-
-Contributions are welcome! Please follow these steps:
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Test thoroughly
-5. Submit a pull request
-
-## 📄 License
-
-This project is licensed under the MIT License.
-
-## 👥 Authors
-
-Developed for Universiti Teknologi Malaysia (UTM) as part of an AI Smart Attendance System project.
-
-## 🙏 Acknowledgments
-
-- **OpenCV** - Computer vision library
-- **face_recognition** - Face recognition library by Adam Geitgey
-- **Flask** - Web framework
-- **UTM** - Project inspiration and requirements
-
-## 📞 Support
-
-For issues or questions:
-1. Check the Troubleshooting section
-2. Review API documentation
-3. Open an issue on GitHub
-
----
-
-**Made with ❤️ for UTM Students and Lecturers**
+---
+title: Attendr UTM Smart Attendance
+emoji: 🎓
+colorFrom: red
+colorTo: yellow
+sdk: docker
+pinned: false
+---
+
+# Attendr - Smart Attendance System 🎓
+
+An AI-powered smart attendance system for Universiti Teknologi Malaysia (UTM) that combines **facial recognition**, **geolocation verification**, and **auto-refresh attendance codes** to eliminate proxy attendance and streamline the attendance process.
+
+![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)
+![Flask](https://img.shields.io/badge/Flask-3.0-green.svg)
+![License](https://img.shields.io/badge/License-MIT-yellow.svg)
+
+## ✨ Features
+
+### For Students
+
+- 🎭 **Biometric Face Recognition** - Secure identity verification using AI
+- 📍 **GPS Location Validation** - Confirms physical presence in classroom
+- 🔐 **Auto-Refresh Codes** - Time-limited codes prevent sharing
+- ⚡ **Real-time Feedback** - Instant attendance confirmation
+- 📱 **Mobile Friendly** - Works on smartphones and tablets
+
+### For Lecturers
+
+- 🎯 **One-Click Session Creation** - Quick setup for any class
+- 🔄 **Auto-Refreshing Codes** - New code every 2 minutes
+- 📊 **Real-time Monitoring** - Live attendance updates
+- 📥 **Export Reports** - Download CSV for record-keeping
+- 📈 **Attendance Analytics** - View statistics at a glance
+
+### Security Features
+
+- ✅ Prevents proxy attendance through face + location verification
+- ✅ Time-limited codes expire automatically
+- ✅ All verifications logged with timestamps
+- ✅ Distance tracking from classroom center
+
+## 🧠 AI Logic & Knowledge Representation
+
+Attendr implements **5 Knowledge Representation (KR) rules** using First-Order Logic:
+
+1. **Face Recognition**: `∀x ((CapturedFace(x) ∧ MatchStored(x)) → FaceMatch(x))`
+2. **Location Verification**: `∀x[(Student(x) ∧ IsWithinAllowedArea(x)) → VerifiedLocation(x)]`
+3. **Device Readiness**: `∀d ((CameraOn(d) ∧ GPSOn(d)) → StartVerification(d))`
+4. **Attendance Validation**: `∀x ((FaceMatch(x) ∧ LocationValid(x)) → GrantCodeAccess(x))`
+5. **Code Confirmation**: `∀x ((ValidCodeEntry(User,x) ∧ WithinCycle(Code,x)) → MarkPresent(System,x))`
+
+## 🚀 Installation
+
+### Prerequisites
+
+- Python 3.8 or higher
+- Webcam for face capture
+- GPS-enabled device (or browser location services)
+
+### Step 1: Clone Repository
+
+```bash
+git clone <repository-url>
+cd smartAttandence
+```
+
+### Step 2: Install Dependencies
+
+#### Windows (Recommended Method)
+
+```powershell
+# Install Visual C++ Build Tools first (required for dlib)
+# Download from: https://visualstudio.microsoft.com/visual-cpp-build-tools/
+
+# Create virtual environment
+python -m venv venv
+venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+#### Alternative: Use Pre-compiled Wheels
+
+If you encounter issues installing `face_recognition`, use pre-compiled wheels:
+
+```powershell
+pip install https://github.com/jloh02/dlib/releases/download/v19.22/dlib-19.22.99-cp38-cp38-win_amd64.whl
+pip install face_recognition
+```
+
+### Step 3: Initialize Database
+
+```bash
+python init_db.py
+```
+
+This creates:
+
+- SQLite database with all tables
+- Sample UTM classrooms (N28, V01, C22)
+- Test student account
+
+### Step 4: Run Application
+
+```bash
+python app.py
+```
+
+The application will be available at: **http://localhost:5000**
+
+## 📖 Usage Guide
+
+### For Students
+
+1. **Register Your Face**
+
+   - Visit `/register`
+   - Enter Student ID and Name
+   - Capture your face using webcam
+   - System stores your biometric encoding
+
+2. **Mark Attendance**
+   - Visit `/student`
+   - Enter Student ID and select active session
+   - Enable camera and GPS permissions
+   - System verifies your face and location
+   - Enter attendance code displayed by lecturer
+   - Attendance marked instantly!
+
+### For Lecturers
+
+1. **Create Session**
+
+   - Visit `/lecturer`
+   - Enter course name and your name
+   - Select classroom location
+   - Click "Create Session"
+
+2. **Display Code**
+
+   - Large attendance code appears on screen
+   - Code auto-refreshes every 2 minutes
+   - Show this code to students in class
+
+3. **Monitor Attendance**
+   - View real-time attendance list
+   - See verification details (distance, time)
+   - Export CSV report when done
+
+## 🗂️ Project Structure
+
+```
+smartAttandence/
+├��─ app.py                          # Main Flask application
+├── config.py                       # Configuration settings
+├── models.py                       # Database models
+├── init_db.py                      # Database initialization
+├── requirements.txt                # Python dependencies
+│
+├── face_recognition_module.py      # Face recognition logic (KR Rule #1)
+├── geolocation_module.py           # GPS verification (KR Rule #2)
+├── attendance_code_module.py       # Auto-refresh codes (KR Rule #5)
+├── utils.py                        # Helper functions
+│
+├── static/
+│   ├── css/
+│   │   └── style.css              # Premium design system
+│   └── js/
+│       ├── student.js             # Student portal logic
+│       └── lecturer.js            # Lecturer dashboard logic
+│
+└── templates/
+    ├── index.html                 # Landing page
+    ├── student.html               # Student portal
+    ├── lecturer.html              # Lecturer dashboard
+    └── register.html              # Face registration
+```
+
+## 🔧 Configuration
+
+Edit `config.py` to customize:
+
+```python
+# Face recognition settings
+FACE_RECOGNITION_TOLERANCE = 0.6    # Lower = more strict (0.4-0.6 recommended)
+
+# Geolocation settings
+GEOLOCATION_RADIUS_METERS = 50      # Classroom detection radius
+
+# Attendance code settings
+CODE_REFRESH_INTERVAL_SECONDS = 120 # Code refresh interval (2 minutes)
+CODE_LENGTH = 6                     # Length of attendance code
+```
+
+## 🌐 API Endpoints
+
+### Student Endpoints
+
+- `POST /api/register_face` - Register student face encoding
+- `POST /api/verify_face` - Verify face against stored encoding
+- `POST /api/verify_location` - Validate GPS location
+- `POST /api/mark_attendance` - Mark attendance with code
+
+### Lecturer Endpoints
+
+- `POST /api/create_session` - Create attendance session
+- `GET /api/get_session/<id>` - Get session details with current code
+- `GET /api/get_attendance/<id>` - Get attendance records
+- `POST /api/end_session/<id>` - End session
+
+### General Endpoints
+
+- `GET /api/get_active_sessions` - List all active sessions
+- `GET /api/classrooms` - Get all classrooms
+
+## 🧪 Testing
+
+### Manual Testing Checklist
+
+**Face Recognition:**
+
+- [ ] Register new student face
+- [ ] Verify with same person (should succeed)
+- [ ] Verify with different person (should fail)
+- [ ] Test with poor lighting
+- [ ] Test with glasses/mask
+
+**Geolocation:**
+
+- [ ] Mark attendance from inside classroom (should succeed)
+- [ ] Mark attendance from outside radius (should fail)
+- [ ] Verify distance calculation accuracy
+
+**Auto-Refresh Codes:**
+
+- [ ] Code refreshes every 2 minutes
+- [ ] Expired code rejected
+- [ ] Valid code accepted
+- [ ] Code sharing prevented
+
+**End-to-End Flow:**
+
+- [ ] Complete student registration
+- [ ] Lecturer creates session
+- [ ] Student marks attendance successfully
+- [ ] Attendance appears in real-time
+- [ ] Export CSV works
+
+## 🐛 Troubleshooting
+
+### Face Recognition Issues
+
+**Problem:** `dlib` installation fails on Windows
+**Solution:**
+
+1. Install Visual C++ Build Tools
+2. Or use pre-compiled wheel: `pip install dlib-19.22.99-cp38-cp38-win_amd64.whl`
+
+**Problem:** "No face detected"
+**Solution:**
+
+- Ensure good lighting
+- Face camera directly
+- Remove glasses/mask if possible
+- Move closer to camera
+
+### GPS Issues
+
+**Problem:** Location permission denied
+**Solution:**
+
+- Enable location services in browser settings
+- Use HTTPS (required for geolocation API)
+- Check device GPS is enabled
+
+**Problem:** "Location unavailable"
+**Solution:**
+
+- Ensure GPS is enabled on device
+- Try outdoors for better signal
+- Check browser location permissions
+
+### Code Validation Issues
+
+**Problem:** "Code has expired"
+**Solution:**
+
+- Enter code within 2-minute window
+- Check lecturer's displayed code
+- Ensure system clocks are synchronized
+
+## 📊 Database Schema
+
+### Students Table
+
+- `id` - Primary key
+- `student_id` - Unique student identifier
+- `name` - Student name
+- `email` - Email address
+- `face_encoding` - Biometric data (JSON)
+- `registered_at` - Registration timestamp
+
+### Classrooms Table
+
+- `id` - Primary key
+- `name` - Classroom name (e.g., N28-01-01)
+- `building` - Building name
+- `latitude` - GPS latitude
+- `longitude` - GPS longitude
+- `radius_meters` - Geofencing radius
+
+### AttendanceSessions Table
+
+- `id` - Primary key
+- `course_name` - Course name
+- `lecturer_name` - Lecturer name
+- `classroom_id` - Foreign key to Classrooms
+- `current_code` - Active attendance code
+- `code_generated_at` - Code generation time
+- `is_active` - Session status
+
+### AttendanceRecords Table
+
+- `id` - Primary key
+- `session_id` - Foreign key to AttendanceSessions
+- `student_id` - Foreign key to Students
+- `marked_at` - Attendance timestamp
+- `face_verified` - Face verification status
+- `location_verified` - Location verification status
+- `code_verified` - Code verification status
+- `distance_from_classroom` - Distance in meters
+
+## 🎨 Design Philosophy
+
+Attendr features a **premium dark mode design** with:
+
+- 🌈 Vibrant gradient accents
+- ✨ Glassmorphism effects
+- 🎭 Smooth micro-animations
+- 📱 Fully responsive layout
+- 🎯 Modern typography (Inter + Outfit fonts)
+
+## 🤝 Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Test thoroughly
+5. Submit a pull request
+
+## 📄 License
+
+This project is licensed under the MIT License.
+
+## 👥 Authors
+
+Developed for Universiti Teknologi Malaysia (UTM) as part of an AI Smart Attendance System project.
+
+## 🙏 Acknowledgments
+
+- **OpenCV** - Computer vision library
+- **face_recognition** - Face recognition library by Adam Geitgey
+- **Flask** - Web framework
+- **UTM** - Project inspiration and requirements
+
+## 📞 Support
+
+For issues or questions:
+
+1. Check the Troubleshooting section
+2. Review API documentation
+3. Open an issue on GitHub
+
+---
+
+**Made with ❤️ for UTM Students and Lecturers**