Setting up LibreFace Environment

This comprehensive tutorial will guide you through setting up LibreFace for facial recognition and emotion detection projects.

Prerequisites

Before starting, ensure you have:

• Python 3.8 or higher installed
• pip package manager
• A working camera (webcam or external)
• At least 4GB RAM (8GB recommended)
• Good internet connection for downloading models

Step 1: Environment Setup

Create an isolated Python environment for your project:

# Create virtual environment
python -m venv libreface_env

# Activate environment
# On Windows:
libreface_env\Scripts\activate
# On macOS/Linux:
source libreface_env/bin/activate

# Upgrade pip
python -m pip install --upgrade pip

Step 2: Install Core Dependencies

Install the required packages in the correct order:

# Install OpenCV first
pip install opencv-python>=4.5.0

# Install NumPy and basic dependencies
pip install numpy>=1.21.0 pillow>=8.0.0

# Install MediaPipe for face mesh analysis
pip install mediapipe>=0.8.0

# Install LibreFace (note: this might be a custom installation)
pip install libreface

# Install additional utilities
pip install pandas matplotlib seaborn

Step 3: Verify Installation

Test that all packages are working correctly:

import cv2
import numpy as np
import mediapipe as mp
try:
    import libreface
    print("All packages installed successfully!")
    print(f"OpenCV version: {cv2.__version__}")
    print(f"NumPy version: {np.__version__}")
    print(f"MediaPipe version: {mp.__version__}")
except ImportError as e:
    print(f"Error importing packages: {e}")

Step 4: Configure Camera Access

Test camera functionality:

import cv2

def test_camera():
    """Test camera access and display video feed"""
    cap = cv2.VideoCapture(0)  # Try camera index 0
    
    if not cap.isOpened():
        print("Error: Cannot access camera")
        return False
    
    print("Camera test successful! Press 'q' to quit.")
    
    while True:
        ret, frame = cap.read()
        if not ret:
            break
            
        cv2.imshow('Camera Test', frame)
        
        if cv2.waitKey(1) & 0xFF == ord('q'):
            break
    
    cap.release()
    cv2.destroyAllWindows()
    return True

# Run the test
test_camera()

Step 5: Basic Face Detection Setup

Implement a simple face detection system:

import cv2
import mediapipe as mp

class FaceDetector:
    def __init__(self):
        self.mp_face_detection = mp.solutions.face_detection
        self.mp_drawing = mp.solutions.drawing_utils
        self.face_detection = self.mp_face_detection.FaceDetection(
            model_selection=0, 
            min_detection_confidence=0.5
        )
    
    def detect_faces(self, image):
        """Detect faces in image"""
        rgb_image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
        results = self.face_detection.process(rgb_image)
        
        if results.detections:
            for detection in results.detections:
                self.mp_drawing.draw_detection(image, detection)
        
        return image, results.detections
    
    def run_realtime(self):
        """Run real-time face detection"""
        cap = cv2.VideoCapture(0)
        
        while cap.isOpened():
            success, image = cap.read()
            if not success:
                continue
            
            image, detections = self.detect_faces(image)
            
            # Display face count
            face_count = len(detections) if detections else 0
            cv2.putText(image, f'Faces: {face_count}', (10, 30), 
                       cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
            
            cv2.imshow('Face Detection', image)
            
            if cv2.waitKey(5) & 0xFF == 27:  # ESC key
                break
        
        cap.release()
        cv2.destroyAllWindows()

# Use the detector
detector = FaceDetector()
detector.run_realtime()

Step 6: Advanced Configuration

Configure LibreFace for emotion detection:

class EmotionDetector(FaceDetector):
    def __init__(self):
        super().__init__()
        # Initialize LibreFace emotion models
        # (This depends on your specific LibreFace installation)
        self.emotion_model = None  # Initialize your emotion model here
        
    def detect_emotions(self, face_region):
        """Detect emotions in face region"""
        # Implement emotion detection logic
        # This will depend on your specific LibreFace setup
        emotions = {
            'angry': 0.1,
            'disgust': 0.0,
            'fear': 0.0,
            'happy': 0.7,
            'sad': 0.1,
            'surprise': 0.05,
            'neutral': 0.05
        }
        return emotions
    
    def calculate_stress_level(self, emotions):
        """Calculate stress level from emotions"""
        stress_indicators = ['angry', 'fear', 'sad']
        stress_level = sum(emotions.get(emotion, 0) for emotion in stress_indicators)
        return min(stress_level, 1.0)  # Normalize to 0-1

Step 7: Performance Optimization

Optimize for real-time processing:

import time
from collections import deque

class OptimizedDetector:
    def __init__(self):
        self.face_detector = FaceDetector()
        self.fps_counter = deque(maxlen=30)  # Track FPS
        self.skip_frames = 2  # Process every nth frame
        self.frame_count = 0
        
    def process_frame(self, image):
        """Process frame with optimization"""
        self.frame_count += 1
        
        # Skip frames for performance
        if self.frame_count % self.skip_frames != 0:
            return image
            
        start_time = time.time()
        
        # Resize for faster processing
        height, width = image.shape[:2]
        if width > 640:
            scale = 640 / width
            new_width = int(width * scale)
            new_height = int(height * scale)
            image = cv2.resize(image, (new_width, new_height))
        
        # Process image
        processed_image, detections = self.face_detector.detect_faces(image)
        
        # Calculate FPS
        process_time = time.time() - start_time
        fps = 1.0 / process_time if process_time > 0 else 0
        self.fps_counter.append(fps)
        
        # Display performance info
        avg_fps = sum(self.fps_counter) / len(self.fps_counter)
        cv2.putText(processed_image, f'FPS: {avg_fps:.1f}', 
                   (10, 60), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (255, 0, 0), 2)
        
        return processed_image

Step 8: Error Handling and Debugging

Implement robust error handling:

import logging

# Set up logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('libreface_debug.log'),
        logging.StreamHandler()
    ]
)

class RobustFaceDetector:
    def __init__(self):
        self.logger = logging.getLogger(__name__)
        try:
            self.face_detector = FaceDetector()
            self.logger.info("Face detector initialized successfully")
        except Exception as e:
            self.logger.error(f"Failed to initialize face detector: {e}")
            raise
    
    def safe_process(self, image):
        """Process image with error handling"""
        try:
            return self.face_detector.detect_faces(image)
        except Exception as e:
            self.logger.error(f"Error processing frame: {e}")
            return image, None
    
    def run_with_error_handling(self):
        """Run detector with comprehensive error handling"""
        cap = cv2.VideoCapture(0)
        
        if not cap.isOpened():
            self.logger.error("Cannot open camera")
            return
        
        retry_count = 0
        max_retries = 5
        
        while retry_count < max_retries:
            try:
                success, image = cap.read()
                if not success:
                    self.logger.warning("Failed to read from camera")
                    retry_count += 1
                    continue
                
                processed_image, detections = self.safe_process(image)
                cv2.imshow('Robust Face Detection', processed_image)
                
                if cv2.waitKey(1) & 0xFF == 27:  # ESC key
                    break
                    
                retry_count = 0  # Reset on success
                
            except Exception as e:
                self.logger.error(f"Unexpected error: {e}")
                retry_count += 1
                time.sleep(1)  # Wait before retry
        
        cap.release()
        cv2.destroyAllWindows()
        self.logger.info("Detection session ended")

Step 9: Configuration File Setup

Create a configuration file for easy parameter adjustment:

# config.py
class Config:
    # Camera settings
    CAMERA_INDEX = 0
    FRAME_WIDTH = 640
    FRAME_HEIGHT = 480
    
    # Detection settings
    MIN_DETECTION_CONFIDENCE = 0.5
    MODEL_SELECTION = 0  # 0 for short-range, 1 for full-range
    
    # Performance settings
    SKIP_FRAMES = 2
    MAX_FPS = 30
    
    # Emotion detection settings
    EMOTION_THRESHOLD = 0.3
    STRESS_CALCULATION_METHOD = 'weighted_sum'
    
    # Logging settings
    LOG_LEVEL = 'INFO'
    LOG_FILE = 'libreface.log'
    
    # Output settings
    SAVE_DETECTIONS = True
    OUTPUT_DIRECTORY = './outputs'

Troubleshooting Common Issues

Installation Problems

• LibreFace not found: Check if the package is available in your region
• OpenCV issues: Try installing opencv-python-headless for server environments
• MediaPipe errors: Ensure you have the correct Python version (3.7-3.9 recommended)

Runtime Issues

• Low FPS: Reduce frame size or increase skip_frames value
• Memory leaks: Ensure proper cleanup of OpenCV windows and camera resources
• Accuracy problems: Adjust detection confidence and lighting conditions

Next Steps

Once you have LibreFace working, you can:

1. Implement custom emotion detection algorithms
2. Add data logging and analysis features
3. Integrate with databases for storing results
4. Build web interfaces for remote monitoring
5. Explore advanced features like age and gender detection