README.md

metadata

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.

✨ 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

git clone <repository-url>
cd smartAttandence

Step 2: Install Dependencies

Windows (Recommended Method)

# 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:

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

python init_db.py

This creates:

• SQLite database with all tables
• Sample UTM classrooms (N28, V01, C22)
• Test student account

Step 4: Run Application

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:

# 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