README.md

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