Face Auth

A face authentication system built with Rust.

Overview

Face Auth is a modular face authentication system consisting of three main components:

1. App - A Rust-based face authentication engine that handles face embedding generation, storage, and user authentication
2. Camera Server - A Python FastAPI server that provides camera streaming capabilities with support for multiple camera sources
3. Workshop - Educational exercises for learning face recognition concepts and implementation techniques

Features

• 🎯 Real-time Face Authentication - Fast face recognition using ConvNeXt models
• 📹 Multiple Camera Sources - Support for OpenCV, libcamera, and custom video streams
• 💾 Local File Storage - Simple JSON-based storage for face embeddings
• 🌐 Web API - RESTful camera streaming API with dynamic camera switching
• 🔧 Easy Configuration - YAML-based configuration for all components
• 🚀 Cross-platform - Works on Windows, Linux, and Raspberry Pi
• 📚 Educational Workshop - Step-by-step exercises for learning face recognition

Architecture

┌─────────────────┐    HTTP Stream    ┌──────────────────┐
│   Camera Server │ ◄─────────────── │   Face Auth App  │
│   (Python)      │                  │   (Rust)         │
│                 │                  │                  │
│ • FastAPI       │                  │ 
│ • OpenCV        │                  │ • Embedding Gen  │
│ • libcamera     │                  │ • Authentication │
└─────────────────┘                  └──────────────────┘
         │                                      │
         ▼                                      ▼
┌─────────────────┐                  ┌──────────────────┐
│   USB Camera    │                  │   Local Storage  │
│   Raspberry Pi  │                  │ • JSON Files     │
│   Webcam        │                  │ • Face Embeddings│
└─────────────────┘                  └──────────────────┘

Quick Start

git clone https://github.com/Wyliodrin/edge-ai-face-auth.git
cd face-auth
cd workshop
cargo build

1. Setup Camera Server

cd ~/WORKSHOP/camera_server
source venv/bin/activate

# Start the camera server
uvicorn camera_stream_api:app --host 0.0.0.0 --port 8000

2. Setup Face Auth App

cd app

# Build the application
cargo build

# Run the application
cargo run

3. Usage

1. Register a new user:

   • Run the app and type register
   • Enter a username
   • Look at the camera while the system captures face samples

2. Authenticate:

   • Type login
   • Enter your username
   • Look at the camera for authentication

Components

Face Auth App (Rust)

The core authentication engine built with Rust for performance and safety.

Key Features:

• ConvNeXt-based face embedding generation
• Local file storage for face embeddings
• Real-time face capture and processing
• High-performance face matching algorithms

Dependencies:

• candle-core & candle-nn - Neural network framework
• reqwest - HTTP client for video streaming
• image & minifb - Image processing and display

Configuration:

# config.yaml
storage:
  type: "local_file"
  local_file:
    path: "embeddings.json"

stream:
  url: "http://localhost:8000/video_feed"
  num_images: 5
  interval_millis: 10

model:
  name: "timm/convnext_atto.d2_in1k"

Camera Server (Python)

A FastAPI-based streaming server that provides camera access with multiple source support.

Key Features:

• FastAPI web server with real-time streaming
• OpenCV and libcamera support
• Dynamic camera source switching
• Comprehensive error handling and logging
• Health check and diagnostic endpoints

Dependencies:

• fastapi & uvicorn - Web framework and server
• opencv-python - Computer vision library
• picamera2 - Raspberry Pi camera support (optional)

API Endpoints:

• GET / - Server status and camera info
• GET /health - Health check
• GET /video_feed - Video stream
• GET /camera_info - Detailed camera configuration
• GET /switch_camera?source={opencv|libcamera} - Switch camera source

Workshop

A collection of progressive exercises designed to teach face recognition concepts and implementation.

Exercises:

• Exercise 01 - Image Processing - Loading and normalizing images for neural networks
• Exercise 02 - Embeddings - Computing face embeddings using ConvNeXt models
• Exercise 03 - Similarity - Implementing cosine similarity for face matching
• Exercise 04 - Storage - Building local file storage for face embeddings
• Exercise 05 - Retrieval - Implementing k-nearest neighbor search

Structure:

• Each exercise includes skeleton code with TODO comments
• Solutions provided for reference and verification
• Documentation and explanations
• Progressive difficulty building core concepts

Running tests

cd ex0x..
cargo test

Storage

Face embeddings are stored locally in JSON format (embeddings.json by default).

Benefits:

• Simple setup with no external dependencies
• Works offline and is easy to backup
• Human-readable format for debugging
• Suitable for development, testing, and small-scale deployments

Project Structure

Face Auth/
├── app/                    # Rust face authentication engine
│   ├── src/
│   │   ├── main.rs        # Application entry point
│   │   ├── config.rs      # Configuration management
│   │   ├── embeddings/    # Face embedding generation
│   │   ├── storage/       # Storage implementations
│   │   └── image_utils/   # Image processing utilities
│   ├── config.yaml        # App configuration
│   └── Cargo.toml         # Rust dependencies
├── camera_server/          # Python camera streaming server
│   ├── camera_stream_api.py # FastAPI application
│   ├── requirements.txt    # Python dependencies
│   └── config.env         # Environment configuration
└── workshop/              # Workshop exercises
    ├── ex01_image_processing/ # Exercise 1: Image loading and normalization
    ├── ex02_embeddings/       # Exercise 2: Face embedding generation
    ├── ex03_similarity/       # Exercise 3: Cosine similarity computation
    ├── ex04_storage_local/    # Exercise 4: Local file storage implementation
    ├── ex05_retrieval/        # Exercise 5: k-NN search and retrieval
    └── solution/              # Reference solutions for all exercises

Authentication Issues

1. Poor recognition accuracy:

   • Ensure good lighting conditions
   • Capture multiple face samples during registration
   • Keep face centered and looking at camera

2. Video stream errors:

   • Verify camera server is running on correct port
   • Check network connectivity between components

Performance Optimization

1. Faster inference:

   • Use release build: cargo run --release
   • Adjust capture interval in config

2. Memory usage:

   • Limit number of face samples during capture

License

This project is licensed under the MIT License - see the individual component READMEs for details.

Acknowledgments

• Uses Candle framework for neural network inference
• Camera streaming powered by FastAPI
• Image processing with OpenCV and Rust image crate

Support

For issues and questions:

• Check the Troubleshooting section
• Review component-specific READMEs in app/ and camera_server/
• Open an issue in the repository

---

Face Auth - Secure, fast, and reliable face authentication for modern applications.