A real-time attendance tracking system that uses facial recognition technology to automatically identify and record attendance. The system consists of a Python FastAPI backend with face recognition capabilities and an Angular frontend for user interaction.
- Real-time Face Recognition: Uses OpenCV and face_recognition library for accurate face detection and identification
- Live Video Streaming: Real-time webcam feed with face detection overlay
- Web-based Interface: Modern Angular frontend with Material Design components
- RESTful API: FastAPI backend for handling video streams and face recognition processing
- Automatic Attendance: Seamless attendance tracking through facial recognition
- Known Face Management: System to encode and store known faces for recognition
The system provides an intuitive interface for registering new faces. Users can upload a clear photo along with their name to register for attendance tracking.
The main attendance interface features a live video feed with real-time face recognition capabilities, plus manual attendance options as a fallback.
View and manage attendance history with a clean, organized interface showing timestamps and recent attendance activities.
- FastAPI: Modern Python web framework for building APIs
- OpenCV: Computer vision library for image processing
- face_recognition: Face recognition library built on dlib
- Uvicorn: ASGI server for running the FastAPI application
- Angular 16: Modern web application framework
- Angular Material: Material Design components for Angular
- Bootstrap: CSS framework for responsive design
- TypeScript: Typed superset of JavaScript
- Python 3.7+
- OpenCV (
cv2) - face_recognition
- FastAPI
- Uvicorn
- NumPy
- Node.js 16+
- Angular CLI
- npm or yarn
We provide automated setup scripts that use uv for fast and reliable Python dependency management:
# Clone the repository
git clone https://github.com/jasonjiang8866/attendance.git
cd attendance
# Run the automated setup script (Python)
python setup.py
# Or use the shell script alternative
chmod +x setup.sh
./setup.shThe setup script will:
- Install uv package manager if not already installed
- Create a virtual environment and install all Python dependencies
- Install face recognition models
- Create the required 'faces' directory
git clone https://github.com/jasonjiang8866/attendance.git
cd attendance# Install Python dependencies manually
pip install fastapi uvicorn opencv-python face-recognition numpy jinja2
# Create a 'faces' directory and add known face images
mkdir faces
# Add images of known people to the faces directory (format: name.jpg)# Navigate to the Angular application
cd UI/i-attendance
# Install dependencies
npm install
# Build the application
npm run buildIf you used the automated setup (recommended):
# From the repository root
uv run python main.pyIf you used manual installation:
# From the repository root
python main.pyThe FastAPI server will start on http://127.0.0.1:8000
# Navigate to the Angular application
cd UI/i-attendance
# Start the development server
npm startThe Angular application will be available on http://localhost:4200
GET /: Main interface with live video streamGET /video_feed: Video streaming endpoint for face recognition
attendance/
├── README.md # This file
├── main.py # FastAPI backend application
├── face_recognizor.py # Face recognition logic and processing
├── setup.py # Automated Python setup script for developers
├── setup.sh # Automated shell setup script for developers
├── pyproject.toml # Python project configuration and dependencies
├── .python-version # Python version specification for uv
├── templates/ # HTML templates for the web interface
│ └── index.html # Main template for video streaming
├── UI/ # Frontend application
│ └── i-attendance/ # Angular application
│ ├── src/ # Angular source code
│ ├── package.json # Node.js dependencies
│ └── README.md # Angular-specific README
├── faces/ # Directory for known face images (created by setup)
├── .gitignore # Git ignore rules
└── known_face_*.dat # Generated face encoding files
- Face Encoding: The system scans the
faces/directory and creates encodings for all known faces - Real-time Detection: Uses webcam feed to detect faces in real-time
- Recognition: Compares detected faces with known face encodings
- Confidence Scoring: Provides confidence percentage for face matches
- Visual Feedback: Displays bounding boxes and names on the video feed
- Add high-quality images of people to the
faces/directory - Name the files with the person's name (e.g.,
john_doe.jpg) - Restart the application to update the face encodings
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is open source and available under the MIT License.
- Ensure good lighting conditions for optimal face recognition accuracy
- The system requires camera permissions to function properly
- Face recognition accuracy depends on the quality of images in the
faces/directory - For production use, consider implementing additional security measures and data protection
- Camera not detected: Ensure your webcam is connected and not being used by other applications
- Face recognition not working: Check if the
faces/directory contains images and face encodings are generated - Performance issues: Reduce video frame size or adjust processing frequency in the code
If you encounter issues installing face_recognition:
# On Ubuntu/Debian
sudo apt-get install cmake libopenblas-dev liblapack-dev libx11-dev libgtk-3-dev
# On macOS
brew install cmakeFor support and questions, please open an issue in the GitHub repository.