Installation

This guide covers everything you need to install and configure EmoChat on your system.

System Requirements

Operating System

Linux (Ubuntu 20.04+)
macOS (10.15+)
Windows 10/11

Python

Python 3.8 or higher
pip package manager
Virtual environment (recommended)

Hardware

Webcam (for real-time detection)
4GB RAM minimum
1GB free disk space

Browser

Chrome 80+
Firefox 75+
Safari 13+
Edge 80+

Python Environment Setup

Linux/macOS
Windows

Create and activate a virtual environment:

# Create virtual environment
python3 -m venv emochat-env

# Activate environment
source emochat-env/bin/activate

# Verify Python version
python --version

You should see Python 3.8 or higher. If not, install a newer version using your package manager.

Create and activate a virtual environment:

# Create virtual environment
python -m venv emochat-env

# Activate environment
.\emochat-env\Scripts\activate

# Verify Python version
python --version

On Windows, you may need to enable script execution:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Install Dependencies

Core Requirements

Install all required packages from requirements.txt:

pip install -r requirements.txt

Key Dependencies

The requirements.txt file includes:

Web Framework (Flask 3.1.3)

Flask powers the web server and API endpoints:

Flask==3.1.3 - Core framework
Werkzeug==3.1.6 - WSGI utilities
Jinja2==3.1.6 - Template engine
click==8.3.1 - CLI utilities

Computer Vision (OpenCV 4.13.0.92)

OpenCV handles all image processing and facial detection:

opencv-contrib-python==4.13.0.92 - Required for cv2.face module
opencv-python==4.13.0.92 - Core OpenCV functionality

Critical: You must use opencv-contrib-python, not just opencv-python. The contrib version includes the cv2.face module required for facial landmark detection.

Machine Learning (scikit-learn 1.8.0)

Scikit-learn provides the classification algorithms:

scikit-learn==1.8.0 - Random Forest classifier
numpy==2.4.2 - Numerical arrays
scipy==1.17.1 - Scientific computing
joblib==1.5.3 - Model serialization

Google Gemini AI (Optional)

For AI-powered emotional analysis:

google-genai==1.66.0 - Gemini API client
google-auth==2.48.0 - Authentication
httpx==0.28.1 - HTTP client

This is optional. Real-time emotion detection works without Gemini. Only session analysis requires it.

Visualization (matplotlib 3.10.8)

For data visualization during model training:

matplotlib==3.10.8 - Plotting library
Pillow==12.1.1 - Image processing

OpenCV Installation

Why opencv-contrib-python?

EmoChat uses the LBF (Local Binary Features) facial landmark model, which is part of OpenCV’s cv2.face module. This module is only available in opencv-contrib-python.

Verify Installation

Check if cv2.face module is available:

import cv2

if hasattr(cv2, 'face'):
    print("✓ opencv-contrib-python is correctly installed")
else:
    print("✗ Missing cv2.face module - install opencv-contrib-python")

Fix Missing cv2.face Module

If you get an error about cv2.face not existing:

Solution 1: Reinstall
Solution 2: Build from Source

# Remove standard OpenCV
pip uninstall opencv-python opencv-python-headless

# Install contrib version
pip install opencv-contrib-python==4.13.0.92

If pip installation fails, build from source:

# Install build dependencies (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install build-essential cmake git
sudo apt-get install libgtk-3-dev libavcodec-dev libavformat-dev libswscale-dev

# Clone OpenCV repos
git clone https://github.com/opencv/opencv.git
git clone https://github.com/opencv/opencv_contrib.git

# Build with contrib modules
cd opencv
mkdir build && cd build
cmake -DOPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules ..
make -j4
sudo make install

Building from source can take 30-60 minutes depending on your system.

Google Gemini API Setup (Optional)

Get API Key

Visit Google AI Studio
Sign in with your Google account
Click “Create API Key”
Copy your API key

Configure Environment Variable

Linux/macOS
Windows

Add to your ~/.bashrc or ~/.zshrc:

export GEMINI_API_KEY="your-api-key-here"

Then reload:

source ~/.bashrc  # or ~/.zshrc

Set environment variable:

# Temporary (current session)
$env:GEMINI_API_KEY = "your-api-key-here"

# Permanent (system-wide)
[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'your-api-key-here', 'User')

Alternative: Hardcode in app.py

Edit app.py at line 74:

client = genai.Client(api_key="your-api-key-here")

Don’t commit your API key to version control. Add app.py to .gitignore or use environment variables.

Model Files Download

EmoChat automatically downloads required model files on first run:

Haar Cascade Classifier

File: haarcascade_frontalface_default.xmlSource: OpenCV GitHub repositoryPurpose: Detects faces in imagesSize: ~900 KB

LBF Landmark Model

File: lbfmodel.yamlSource: GSOC2017 GitHub repositoryPurpose: Extracts 68 facial landmarksSize: ~50 MB

These models are downloaded automatically by utils.py when you first run prepare_data.py, train_model.py, or app.py. No manual download required.

Manual Download (Optional)

If automatic download fails, download manually:

# Haar Cascade
wget https://raw.githubusercontent.com/opencv/opencv/master/data/haarcascades/haarcascade_frontalface_default.xml

# LBF Model
wget https://raw.githubusercontent.com/kurnianggoro/GSOC2017/master/data/lbfmodel.yaml

Verify Installation

Run this verification script:

verify_install.py

import sys

def check_installation():
    checks = []
    
    # Python version
    py_version = sys.version_info
    checks.append((
        "Python 3.8+",
        py_version.major == 3 and py_version.minor >= 8,
        f"Python {py_version.major}.{py_version.minor}.{py_version.micro}"
    ))
    
    # Flask
    try:
        import flask
        checks.append(("Flask", True, f"v{flask.__version__}"))
    except ImportError:
        checks.append(("Flask", False, "Not installed"))
    
    # OpenCV
    try:
        import cv2
        has_face = hasattr(cv2, 'face')
        checks.append((
            "opencv-contrib-python",
            has_face,
            f"v{cv2.__version__} {'(with cv2.face)' if has_face else '(missing cv2.face!)'}"
        ))
    except ImportError:
        checks.append(("opencv-contrib-python", False, "Not installed"))
    
    # NumPy
    try:
        import numpy
        checks.append(("numpy", True, f"v{numpy.__version__}"))
    except ImportError:
        checks.append(("numpy", False, "Not installed"))
    
    # scikit-learn
    try:
        import sklearn
        checks.append(("scikit-learn", True, f"v{sklearn.__version__}"))
    except ImportError:
        checks.append(("scikit-learn", False, "Not installed"))
    
    # Google GenAI (optional)
    try:
        import google.genai
        checks.append(("google-genai (optional)", True, "Installed"))
    except ImportError:
        checks.append(("google-genai (optional)", True, "Not installed (optional)"))
    
    # Print results
    print("\n=== EmoChat Installation Verification ===")
    all_passed = True
    for name, passed, info in checks:
        status = "✓" if passed else "✗"
        print(f"{status} {name}: {info}")
        if not passed and "optional" not in name.lower():
            all_passed = False
    
    print("\n" + ("All checks passed!" if all_passed else "Some required packages missing."))
    return all_passed

if __name__ == "__main__":
    check_installation()

Run it:

python verify_install.py

Troubleshooting

Common Issues

ImportError: No module named 'cv2'

OpenCV is not installed:

pip install opencv-contrib-python==4.13.0.92

AttributeError: module 'cv2' has no attribute 'face'

You have opencv-python instead of opencv-contrib-python:

pip uninstall opencv-python
pip install opencv-contrib-python==4.13.0.92

ModuleNotFoundError: No module named 'flask'

Flask is not installed:

pip install Flask==3.1.3

FileNotFoundError: No se encontró el modelo entrenado

The model hasn’t been trained yet:

python prepare_data.py
python train_model.py

SSL/TLS Certificate Errors on Windows

Windows may have certificate issues when downloading models:

pip install --upgrade certifi

Or download models manually (see “Model Files Download” section).

Permission Denied on Linux/macOS

Use pip install --user or activate virtual environment:

python3 -m venv env
source env/bin/activate
pip install -r requirements.txt

Port 5000 Already in Use

Change the port in app.py:96:

app.run(debug=True, port=5001)  # Use different port

Platform-Specific Issues

macOS
Linux
Windows

Webcam PermissionGrant Terminal/IDE camera access in System Preferences:

System Preferences → Security & Privacy → Privacy → Camera

M1/M2 ARM IssuesIf you encounter architecture errors:

# Use Rosetta Python
arch -x86_64 python3 -m pip install -r requirements.txt

Video Device AccessAdd your user to the video group:

sudo usermod -a -G video $USER
# Log out and back in

Missing Build ToolsInstall development headers:

# Ubuntu/Debian
sudo apt-get install python3-dev libopencv-dev

# Fedora/RHEL
sudo dnf install python3-devel opencv-devel

Visual C++ Build ToolsSome packages require compilation. Install:

Microsoft C++ Build Tools

Long Path SupportEnable long paths in Windows 10/11:

# Run as Administrator
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Next Steps

Once installation is complete:

Quickstart Guide

Follow the quickstart to train your model and launch EmoChat

Model Training

Learn how to prepare data and train the emotion classifier

API Reference

Explore Flask API endpoints and integration options

Core Concepts

Understand the system architecture and how components work together

Get Started

Core Concepts

Training Guide

Web Application

System Requirements

Operating System

Python

Hardware

Browser

Python Environment Setup

Install Dependencies

Core Requirements

Key Dependencies

OpenCV Installation

Why opencv-contrib-python?

Verify Installation

Fix Missing cv2.face Module

Google Gemini API Setup (Optional)

Model Files Download

Haar Cascade Classifier

LBF Landmark Model

Manual Download (Optional)

Verify Installation

Troubleshooting

Common Issues

Platform-Specific Issues

Next Steps

Quickstart Guide

Model Training

API Reference

Core Concepts

Build docs developers (and LLMs) love

Get Started

Core Concepts

Training Guide

Web Application

​System Requirements

Operating System

Python

Hardware

Browser

​Python Environment Setup

​Install Dependencies

​Core Requirements

​Key Dependencies

​OpenCV Installation

​Why opencv-contrib-python?

​Verify Installation

​Fix Missing cv2.face Module

​Google Gemini API Setup (Optional)

​Model Files Download

Haar Cascade Classifier

LBF Landmark Model

​Manual Download (Optional)

​Verify Installation

​Troubleshooting

​Common Issues

​Platform-Specific Issues

​Next Steps

Quickstart Guide

Model Training

API Reference

Core Concepts

Build docs developers (and LLMs) love

System Requirements

Python Environment Setup

Install Dependencies

Core Requirements

Key Dependencies

OpenCV Installation

Why opencv-contrib-python?

Verify Installation

Fix Missing cv2.face Module

Google Gemini API Setup (Optional)

Model Files Download

Manual Download (Optional)

Verify Installation

Troubleshooting

Common Issues

Platform-Specific Issues

Next Steps