Web based Liveness Detection

Face Liveness Detection Application using DeepFace and FastAPI

Features

• ✅ Real-time face liveness detection using DeepFace
• ✅ Camera view with responsive circular frame
• ✅ Color border indicators (green = success, red = failed, orange = scanning)
• ✅ Face quality analysis with improvement recommendations
• ✅ Automatic photo saving to storage/liveness/
• ✅ Real-time notifications without popups
• ✅ "Next Process" button after successful detection
• ✅ Responsive design with Bootstrap 5

Tech Stack

• Backend: FastAPI with Python 3.12+
• Frontend: HTML5, CSS3, Bootstrap 5, jQuery
• Liveness Detection: DeepFace with TensorFlow/Keras
• Computer Vision: OpenCV
• Package Manager: UV

Installation

Prerequisites

• Python 3.12 or higher
• UV package manager (https://docs.astral.sh/uv/)
• Web/USB camera

Setup

1. Clone this repository:

git clone <repository-url>
cd poc-liveness

2. Install dependencies with UV:

uv sync --python 3.12

3. Activate virtual environment:

source .venv/bin/activate  # For Linux/Mac
# or
.venv\Scripts\activate     # For Windows

Running the Application

Development Mode

uv run python -m app.main

The application will run at http://localhost:8002

Production Mode

uvicorn app.main:app --host 0.0.0.0 --port 8002 --workers 4

Deploying with Docker

You can easily run this application using Docker.

1. Build the Docker image

In the root directory of the project, run:

docker build -t web-liveness-app:1.0.0 -f Dockerfile .

2. Start the container with Docker Compose

To start the application (and optional dependencies such as Redis), use:

docker compose up -d

This will build and start all services defined in docker-compose.yml.
The application will be available at http://localhost:8002.

Note:

• Ensure ports and volumes specified in docker-compose.yml are available on your system.
• The app’s persistent data (such as liveness images) is stored in the storage directory, mapped as a Docker volume.

API Endpoints

• GET / - Main application page (http://localhost:8002)
• GET /api/health - Health check
• POST /api/liveness/check - Check liveness from base64 image
• POST /api/liveness/capture - Save successful liveness photo
• POST /api/liveness/quality - Analyze face quality

Project Structure

poc-liveness/
├── app/
│   ├── __init__.py
│   ├── main.py              # Main FastAPI application
│   ├── api/
│   │   ├── __init__.py
│   │   └── routes.py        # API endpoints
│   ├── core/
│   │   ├── __init__.py
│   │   └── config.py        # Configuration settings
│   ├── services/
│   │   ├── __init__.py
│   │   └── liveness_service.py  # Liveness detection logic
│   └── utils/
│       └── __init__.py
├── static/
│   ├── css/
│   │   └── style.css        # Custom styles
│   └── js/
│       └── main.js          # JavaScript functionality
├── templates/
│   └── index.html           # Main HTML page
├── storage/
│   └── liveness/            # Saved liveness images
├── pyproject.toml           # Project configuration
└── README.md               # This file

How to Use

1. Open browser and access http://localhost:8002
2. Grant camera permission when prompted
3. Position your face within the available circle
4. System will automatically detect liveness every 2 seconds
5. Follow recommendations if face quality is poor
6. If liveness is successfully detected:
   • Circle border will turn green
   • Success notification will appear
   • Photo will be saved automatically
   • "Next Process" button will appear

Configuration

Configuration can be changed in app/core/config.py:

• LIVENESS_CONFIDENCE_THRESHOLD: Confidence threshold for liveness detection (default: 0.90)
• LIVENESS_MODEL: Model used for detection (default: "VGG-Face")
• LIVENESS_DETECTOR_BACKEND: Backend for face detection (default: "opencv")
• STORAGE_PATH: Path for file storage
• LIVENESS_STORAGE_PATH: Specific path for liveness photos

Troubleshooting

Common Issues

1. Cannot access camera

   • Ensure browser has camera permission
   • Check if other applications are using the camera
   • Use HTTPS in production environment

2. Import error with tf-keras

   uv sync --python 3.12

   Ensure tf-keras is properly installed

3. Port already in use

   • Change port in app/main.py or kill process using port 8002

4. DeepFace model download slow

   • Ensure stable internet connection
   • Models will be downloaded on first run and saved in ~/.deepface/weights/

Dependencies Check

uv tree  # To see dependency tree
uv sync  # To reinstall dependencies

Development

Adding Dependencies

uv add <package-name>

Testing

# Test health endpoint
curl http://localhost:8002/api/health

# Test main page
curl http://localhost:8002/

Security Notes

• Ensure HTTPS is used in production environment
• Validate and sanitize all received input
• Rate limiting for API endpoints
• Secure file upload handling

License

[Add your license information here]

Support

For questions or issues, please contact the development team.