irsyadakbar01/revastco-facerecognizer

🎯 FaceMatch AI - Advanced Face Recognition System

    

An advanced facial recognition system powered by deep learning neural networks, designed for high-accuracy face matching in group photos and challenging conditions. Optimized for Hugging Face Spaces deployment.

🚀 Ready to Deploy? This app is ready for Hugging Face Spaces! Jump to Deployment Section for step-by-step guide.

✨ Features

🚀 5 Performance Tiers

• —⚡ Ultra Fast Mode (~0.5-1s) - Single model, quick results
• —⚡ Fast Mode (~1-2s) - Balanced speed and accuracy [RECOMMENDED]
• —🎯 Accurate Mode (~3-5s) - 3-model ensemble for high accuracy
• —🔥 HardMode (~10-20s) - 4-5 model ensemble for maximum accuracy
• —⚡🔥 Extreme Mode (~5-15s) - SUPERIOR: Multi-detector + 5+ models + FAISS [BEST]

🎨 Advanced Capabilities

• —✅ Multi-face detection - Detect and recognize multiple faces in a single photo
• —✅ Group photo support - Optimized for 21+ people in challenging conditions
• —✅ Multi-detector approach - RetinaFace, MTCNN, OpenCV for best detection
• —✅ Adaptive thresholding - Quality-based threshold adjustment per face
• —✅ Face enhancement - CLAHE, bilateral filtering, sharpening
• —✅ Second-pass matching - Automatic retry with enhancement for unmatched faces
• —✅ Cross-model verification - Reduces false positives significantly
• —✅ Persistent caching - Instant load times after initial setup
• —✅ Multi-user support - Concurrent access with session isolation
• —✅ Admin panel - Cache management and pre-warming tools

🧠 AI Models Used

• —Facenet512 - High-accuracy face embeddings (weighted 1.5x)
• —ArcFace - State-of-the-art face recognition (weighted 1.5x)
• —VGG-Face - Robust face representation
• —OpenFace - Lightweight and efficient
• —SFace - Additional verification layer
• —FAISS - Fast similarity search for large datasets

🎬 Quick Deployment Overview

For Hugging Face Spaces Users:

1. 1.Create Space → Choose Streamlit SDK
2. 2.Upload Files → All project files including persistent_cache/ (pre-warmed)
3. 3.Set Secrets → Admin credentials in Space settings
4. 4.Launch → Instant startup with pre-warmed cache!

Time to deploy: 5-10 minutes (with pre-warmed cache) | First load: < 10 seconds ⚡

📖 Full deployment guide below → Jump to Deployment

📋 Table of Contents

• —Installation
• —Quick Start
• —Usage
• —Admin Panel
• —Data Preparation
• —Configuration
• —🚀 Deployment to Hugging Face Spaces ⭐
• —Troubleshooting
• —Performance
• —Architecture
• —Contributing
• —Security
• —License

🛠️ Installation

Prerequisites

• —Python 3.8 or higher
• —4GB+ RAM (8GB recommended for Extreme Mode)
• —Windows, macOS, or Linux

Step 1: Clone the Repository

git clone <your-repo-url>
cd "FaceMatch Detector"

Step 2: Install Dependencies

pip install -r requirements.txt

Dependencies include:

• —Streamlit 1.32.2 - Web interface
• —DeepFace 0.0.91 - Face recognition library
• —TensorFlow 2.13.0 - Deep learning framework
• —OpenCV - Computer vision tools
• —FAISS - Fast similarity search
• —InsightFace - Additional face recognition models
• —And more... (see requirements.txt)

🚀 Quick Start

1️⃣ Prepare Your Dataset

Create a students_data.json file with your face database:

{
  "students": [
    {
      "nama": "John Doe",
      "nim": "123456",
      "foto": "foto rev/john.jpg",
      "kelas": "A"
    }
  ]
}

Place reference photos in the foto rev/ directory.

2️⃣ Run the Application

streamlit run app.py

The application will be available at: http://localhost:8501

3️⃣ Pre-warm Cache (Recommended)

For instant performance on subsequent runs:

Option A: Via Script (Fastest)

python prewarm_cache.py

Option B: Via Admin Panel

1. 1.Run admin panel: run_admin.bat (Windows) or ./run_admin.sh (Linux/Mac)
2. 2.Access at: http://localhost:7861
3. 3.Login with default credentials (username: admin, password: admin)
4. 4.Go to "🚀 Pre-warming" tab and click pre-warm for each mode

⏱️ First-time setup: 60-90 minutes ⚡ After pre-warming: Instant (< 1 second load time)

📖 Usage

Basic Recognition Flow

1. 1.Select Recognition Mode - Choose from 5 performance tiers based on your needs
2. 2.Upload Photo - Support for JPG, PNG, JPEG formats
3. 3.Adjust Threshold (Optional) - Fine-tune matching sensitivity (0.3-0.6)
4. 4.Detect Faces - AI processes the image and finds all faces
5. 5.View Results - See matched students with confidence scores and details

Recognition Modes Explained

Threshold Guidelines

• —0.30-0.35 - Very permissive (more matches, some false positives)
• —0.35-0.40 - Balanced (recommended)
• —0.40-0.50 - Strict (fewer matches, high confidence)
• —0.50-0.60 - Very strict (only very clear matches)

🔧 Admin Panel

Access the admin panel to manage cache and optimize performance.

Starting Admin Panel

Windows:

run_admin.bat

Linux/Mac:

chmod +x run_admin.sh
./run_admin.sh

Manual:

streamlit run admin_cache.py --server.port 7861

Access at: http://localhost:7861

Admin Features

📊 Cache Status Tab

• —View all cached modes
• —Monitor storage usage
• —Check cache validity
• —See creation timestamps

🚀 Pre-warming Tab

• —Pre-warm each mode individually
• —View progress in real-time
• —Verify successful caching

🔒 Security Settings

• —Change admin credentials
• —Secure your admin panel

⚠️ IMPORTANT: Change default credentials immediately!

python update_admin_password.py

📦 Data Preparation

Student Database Format

Create students_data.json:

{
  "students": [
    {
      "nama": "Student Name",
      "nim": "Student ID",
      "foto": "foto rev/student.jpg",
      "kelas": "Class Name",
      "jurusan": "Major (optional)",
      "angkatan": "Year (optional)"
    }
  ]
}

Photo Requirements

• —Format: JPG, PNG, JPEG
• —Quality: High resolution preferred (minimum 640x480)
• —Face visibility: Clear, front-facing photos work best
• —Lighting: Good lighting conditions
• —Location: Place in foto rev/ directory
• —Naming: Match the filename in students_data.json

Prepare Data Script

Use the included script to organize your data:

python prepare_data.py

⚙️ Configuration

Application Settings

Edit app.py to customize:

# Page configuration
st.set_page_config(
    page_title="FaceMatch AI - Recognition System",
    page_icon="🎯",
    layout="wide"
)

Cache Configuration

Cache is automatically managed by cache_manager.py:

• —Location: persistent_cache/ directory
• —Format: Pickle files with embeddings and metadata
• —Validation: Hash-based integrity checking
• —Modes: Separate cache for each recognition mode

Environment Variables

For deployment (e.g., Hugging Face Spaces):

ADMIN_USERNAME=your_username
ADMIN_PASSWORD=your_secure_password

🌐 Deployment to Hugging Face Spaces

🚀 Quick Deployment Guide

Step 1: Create Hugging Face Space

1. 1.Login to Hugging Face
2. 2.Click "New Space"
3. 3.Choose:
4. 4.SDK: Streamlit
5. 5.Space name: facematch-ai (or your preferred name)
6. 6.Visibility: Private (recommended) or Public
7. 7.Hardware: CPU Basic (Free) or upgrade for better performance

Step 2: Prepare Your Repository

Required files structure:

FaceMatch Detector/
├── app.py                      # Main application ✅
├── admin_cache.py              # Admin panel ✅
├── cache_manager.py            # Cache management ✅
├── requirements.txt            # Dependencies ✅
├── packages.txt                # System packages (empty is OK) ✅
├── students_data.json          # Your student database ✅
├── admin_config.json           # Admin credentials ✅
├── foto rev/                   # Reference photos ✅
├── persistent_cache/           # Pre-warmed cache (recommended) ✅
└── README.md                   # This file (with HF metadata) ✅

Step 3: Pre-warm Cache (HIGHLY RECOMMENDED)

⚠️ IMPORTANT: Pre-warming saves 25-35 minutes of wait time for first user!

Option A: Local Pre-warming (Recommended)

# Install dependencies locally
pip install -r requirements.txt

# Run pre-warming script
python prewarm_cache.py

# This creates persistent_cache/ folder with all embeddings
# Takes 60-90 minutes but only needs to be done ONCE

Option B: Use Admin Panel

# Run admin panel
run_admin.bat  # Windows
./run_admin.sh # Linux/Mac

# Access at http://localhost:7861
# Login and pre-warm each mode

Step 4: Upload to Hugging Face

Via Git (Recommended):

# Clone your space
git clone https://huggingface.co/spaces/YOUR_USERNAME/facematch-ai
cd facematch-ai

# Copy all files from your project
cp -r "path/to/FaceMatch Detector/"* .

# IMPORTANT: Ensure .gitignore allows persistent_cache/
# Check .gitignore doesn't have: persistent_cache/

# Add files
git add .

# Commit (may take time if including cache - ~1.2GB)
git commit -m "Initial deployment with pre-warmed cache"

# Push to Hugging Face
git push

Via Web UI:

1. 1.Go to your Space → Files
2. 2.Click "Add file" → "Upload files"
3. 3.Upload all files including persistent_cache/ folder
4. 4.Commit changes

Step 5: Configure Secrets (Security)

In your Space settings → Repository secrets, add:

ADMIN_USERNAME=your_secure_username
ADMIN_PASSWORD=your_secure_password

⚠️ Change default credentials immediately! Default is admin/admin

# Generate new password hash locally
python update_admin_password.py

Step 6: Verify Deployment

1. 1.Wait for build - Check "Building" status in Space
2. 2.Access app - Click "Open Space" when ready
3. 3.Test recognition - Upload a test photo
4. 4.Check cache - Should load instantly if pre-warmed
5. 5.Access admin - Run admin panel separately if needed

Your Space URL: https://huggingface.co/spaces/YOUR_USERNAME/facematch-ai

📊 Deployment Performance

Recommendation: Always pre-warm and commit cache!

🔐 Security Best Practices

1. 1.Change default credentials:

   python update_admin_password.py

1. 1.Use environment variables for sensitive data:
2. 2.Set in Space Settings → Repository secrets
3. 3.Don't commit credentials to Git

1. 1.Set visibility:
2. 2.Private: Only you can access
3. 3.Public: Anyone can use (be careful with personal data!)

1. 1.Monitor access:
2. 2.Check Space logs regularly
3. 3.Review admin panel access logs

⚙️ Advanced Configuration

Hardware Upgrades (Optional)

For better performance, upgrade Space hardware:

• —CPU Basic (Free) - Suitable for small datasets (<100 students)
• —CPU Upgrade ($9/month) - Better for medium datasets (100-500 students)
• —GPU ($60+/month) - Fastest for large datasets (500+ students)

Multi-Page App Setup

Access admin panel as a separate page:

# Create pages directory
mkdir pages

# Move admin to pages
mv admin_cache.py pages/1_🔧_Admin_Panel.py

Streamlit will auto-detect and show in sidebar!

Custom Domain (Optional)

1. 1.Upgrade to Hugging Face Pro
2. 2.Settings → Custom domain
3. 3.Follow DNS configuration steps

🐛 Troubleshooting Deployment

❌ Space stuck on "Building"

Solution: Check build logs for errors. Common issues:

• —Missing dependencies in requirements.txt
• —Python version mismatch
• —Large files timing out

❌ "Out of memory" error

Solution:

• —Use only Fast/Accurate modes (disable HardMode/Extreme)
• —Reduce cache size
• —Upgrade to better hardware

❌ Cache not loading

Solution:

• —Verify persistent_cache/ folder uploaded correctly
• —Check if files are Git LFS tracked (for large files)
• —Re-run pre-warming

❌ Slow performance

Solution:

• —Ensure cache is pre-warmed and committed
• —Upgrade hardware
• —Check Space isn't sleeping (Free tier sleeps after inactivity)

❌ Admin panel not accessible

Solution:

• —Set up as multi-page app (see Advanced Configuration)
• —Or run separately: streamlit run admin_cache.py --server.port 7861

📖 Additional Resources

• —📘 Detailed guide: See HUGGINGFACE_DEPLOYMENT.md
• —🚀 Quick start: See QUICKSTART.md
• —🔧 Admin guide: See ADMIN_ACCESS_GUIDE.md
• —🗄️ Cache system: See CACHE_SYSTEM_README.md

🎯 Deployment Checklist

Before going live, ensure:

• —✅ All files uploaded correctly
• —✅ Cache pre-warmed and committed
• —✅ Admin credentials changed
• —✅ Environment variables set
• —✅ Student data populated
• —✅ Reference photos uploaded
• —✅ App tested and working
• —✅ Admin panel accessible
• —✅ Performance acceptable
• —✅ Security configured

Ready to deploy? Follow the steps above! 🚀

🐛 Troubleshooting

Common Issues

❌ "Cache manager not available"

Solution: Ensure cache_manager.py exists in the project directory

❌ "Failed to load embeddings"

Solution: Run pre-warming script:

python prewarm_cache.py

❌ Slow first run

Expected: First run takes 5-20 minutes to compute embeddings. Use pre-warming to speed up!

❌ Low detection rate

Solution:

• —Try Extreme Mode for challenging photos
• —Adjust threshold (lower = more permissive)
• —Ensure reference photos are high quality
• —Check lighting and face visibility

❌ Memory errors

Solution:

• —Use lower modes (Ultra Fast or Fast)
• —Reduce image resolution
• —Add more RAM or use cloud deployment

❌ Admin panel won't start

Solution:

# Check if port is available
netstat -ano | findstr :7861

# Kill process if needed (Windows)
taskkill /PID <process_id> /F

# Restart admin panel
run_admin.bat

📊 Performance

Speed Benchmarks

Accuracy Comparison

Based on testing with 21-person group photo:

Storage Requirements

• —Application: ~50 MB
• —Dependencies: ~2 GB
• —Cache (all modes): ~1.2-1.5 GB
• —Total: ~3.5-4 GB

🏗️ Architecture

System Components

┌─────────────────────────────────────────────────┐
│              Web Interface (Streamlit)          │
└───────────────┬─────────────────────────────────┘
                │
┌───────────────▼─────────────────────────────────┐
│         Face Detection & Recognition            │
│  ┌─────────┬──────────┬──────────┬──────────┐  │
│  │RetinaFace│  MTCNN   │  OpenCV  │  SSD    │  │
│  └─────────┴──────────┴──────────┴──────────┘  │
└───────────────┬─────────────────────────────────┘
                │
┌───────────────▼─────────────────────────────────┐
│          Model Ensemble (DeepFace)              │
│  ┌─────────┬──────────┬──────────┬──────────┐  │
│  │Facenet512│ ArcFace │ VGG-Face │ OpenFace │  │
│  └─────────┴──────────┴──────────┴──────────┘  │
└───────────────┬─────────────────────────────────┘
                │
┌───────────────▼─────────────────────────────────┐
│           Cache Management System               │
│         (Persistent Embeddings Storage)         │
└───────────────┬─────────────────────────────────┘
                │
┌───────────────▼─────────────────────────────────┐
│        Student Database (JSON + Photos)         │
└─────────────────────────────────────────────────┘

Key Technologies

• —Frontend: Streamlit (Python web framework)
• —Backend: Python 3.8+
• —Face Detection: RetinaFace, MTCNN, OpenCV, SSD
• —Face Recognition: DeepFace (Facenet512, ArcFace, VGG-Face, OpenFace)
• —Deep Learning: TensorFlow, Keras
• —Similarity Search: FAISS (Facebook AI Similarity Search)
• —Image Processing: OpenCV, PIL, Albumentations
• —Caching: Pickle-based persistent storage

📝 Project Structure

FaceMatch Detector/
├── app.py                          # Main application
├── admin_cache.py                  # Admin panel
├── cache_manager.py                # Cache management system
├── prewarm_cache.py               # Cache pre-warming script
├── prepare_data.py                # Data preparation utility
├── update_admin_password.py       # Security utility
├── requirements.txt               # Python dependencies
├── packages.txt                   # System packages
├── students_data.json             # Student database
├── admin_config.json              # Admin credentials
├── foto rev/                      # Reference photos directory
├── persistent_cache/              # Cached embeddings
├── run_admin.bat                  # Windows admin launcher
├── run_admin.sh                   # Linux/Mac admin launcher
└── docs/                          # Documentation
    ├── QUICKSTART.md
    ├── ADMIN_ACCESS_GUIDE.md
    ├── CACHE_SYSTEM_README.md
    ├── DEPLOYMENT_SUMMARY.md
    ├── HUGGINGFACE_DEPLOYMENT.md
    └── ...

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. 1.Fork the repository
2. 2.Create a feature branch (git checkout -b feature/amazing-feature)
3. 3.Commit your changes (git commit -m 'Add amazing feature')
4. 4.Push to the branch (git push origin feature/amazing-feature)
5. 5.Open a Pull Request

Development Setup

# Clone repository
git clone <your-repo-url>
cd "FaceMatch Detector"

# Install dependencies
pip install -r requirements.txt

# Run in development mode
streamlit run app.py --server.runOnSave true

🔐 Security

Best Practices

1. 1.Change default admin credentials immediately:

   python update_admin_password.py

1. 1.Use environment variables for sensitive data:

   export ADMIN_USERNAME=your_username
   export ADMIN_PASSWORD=your_secure_password

1. 1.Secure admin panel access:
2. 2.Use strong passwords
3. 3.Limit network access
4. 4.Monitor access logs

1. 1.Protect student data:
2. 2.Don't commit students_data.json to public repos
3. 3.Use .gitignore for sensitive files
4. 4.Encrypt data at rest if needed

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• —DeepFace - Serengil et al. for the amazing face recognition library
• —Streamlit - For the intuitive web framework
• —TensorFlow - Google Brain team for the deep learning framework
• —FAISS - Facebook AI Research for fast similarity search
• —InsightFace - For state-of-the-art face recognition models
• —RetinaFace - For robust face detection

📞 Support

Need help? Here are your options:

1. 1.Documentation: Check the docs/ folder for detailed guides
2. 2.Issues: Open an issue on GitHub
3. 3.Discussions: Start a discussion for questions and ideas
4. 4.Email: Contact the maintainer

🗺️ Roadmap

Planned Features

• —[ ] Real-time video recognition
• —[ ] Mobile app support
• —[ ] REST API for integration
• —[ ] Batch processing for multiple images
• —[ ] Advanced analytics dashboard
• —[ ] Export to Excel/PDF reports
• —[ ] Multi-language support
• —[ ] Cloud storage integration (S3, Google Cloud Storage)
• —[ ] GPU acceleration for faster processing
• —[ ] Automated attendance system

📈 Changelog

Version 2.1 (Current)

• —✅ Added Extreme Mode with 90-95% accuracy
• —✅ Multi-detector support (RetinaFace, MTCNN, OpenCV)
• —✅ Multi-user concurrent access
• —✅ Persistent cache system
• —✅ Admin panel with cache management
• —✅ Second-pass matching with face enhancement
• —✅ Cross-model verification
• —✅ Adaptive thresholding

Version 2.0

• —✅ HardMode with 4-5 model ensemble
• —✅ Enhanced UI with modern design
• —✅ Improved accuracy algorithms
• —✅ Better error handling

Version 1.0

• —✅ Basic face recognition
• —✅ Multi-face detection
• —✅ Student database integration

💡 Tips & Best Practices

For Best Results

1. 1.Photo Quality Matters:
2. 2.Use high-resolution reference photos
3. 3.Ensure good lighting
4. 4.Front-facing photos work best

1. 1.Choose the Right Mode:
2. 2.Daily use → Fast Mode
3. 3.Important events → Accurate or HardMode
4. 4.Large groups/challenges → Extreme Mode

1. 1.Optimize Performance:
2. 2.Pre-warm cache before deployment
3. 3.Commit cache to avoid rebuild
4. 4.Use caching for faster subsequent runs

1. 1.Threshold Tuning:
2. 2.Start with default (0.35-0.40)
3. 3.Lower for more matches (risk false positives)
4. 4.Raise for stricter matching (risk false negatives)

1. 1.Database Management:
2. 2.Keep reference photos updated
3. 3.Remove duplicates
4. 4.Use consistent naming

<div align="center">

Built with ❤️ using DeepFace, TensorFlow, and Streamlit

⭐ Star this repository if you find it helpful!

</div>