Initial commit for EmotionMirror finalproject

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,47 @@
+# Ignorar modelos grandes
+*.pt
+
+# Entornos virtuales
+venv/
+.venv/
+ENV/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Archivos de caché y bytecode
+.cache/
+.pytest_cache/
+
+# Archivos de distribución
+dist/
+build/
+*.egg-info/
+
+# Archivos de registro y bases de datos
+*.log
+*.db
+*.sqlite
+*.sqlite3
+
+# Archivos de imagen y uploads (se deben crear en tiempo de ejecución)
+/static/uploads/*
+/static/results/*
+!/static/uploads/.gitkeep
+!/static/results/.gitkeep
+
+# Directorios de modelos (muy pesados para git)
+/models/*
+!/models/.gitkeep
+
+# Archivos de configuración locales
+.env
+.env.local
+
+# Archivos del sistema operativo
+.DS_Store
+Thumbs.db

.streamlit/config.toml

@@ -0,0 +1,17 @@
+[theme]
+primaryColor = "#FF4B4B"
+backgroundColor = "#0E1117"
+secondaryBackgroundColor = "#262730"
+textColor = "#FAFAFA"
+font = "sans serif"
+
+[server]
+port = 8501
+headless = true
+enableCORS = false
+enableXsrfProtection = false
+maxUploadSize = 10
+
+[browser]
+serverAddress = "0.0.0.0"
+gatherUsageStats = false

Dockerfile

@@ -0,0 +1,36 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# Instalar dependencias esenciales del sistema para OpenCV
+RUN apt-get update && apt-get install -y \
+    libgl1-mesa-glx \
+    libglib2.0-0 \
+    libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Configurar variables de entorno para Matplotlib y Ultralytics
+ENV MPLCONFIGDIR=/tmp/matplotlib
+ENV YOLO_CONFIG_DIR=/tmp/ultralytics
+
+# Crear directorios necesarios
+RUN mkdir -p /app/static /app/models /app/database
+
+# Copiar requirements.txt primero para aprovechar caché de Docker
+COPY requirements.txt .
+
+# Instalar dependencias
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copiar el resto de archivos
+COPY . .
+
+# Crear directorios necesarios para la aplicación
+RUN mkdir -p /app/static/uploads /app/static/images /app/database \
+    && chmod -R 777 /app /tmp
+
+# Exponer el puerto que utiliza Streamlit por defecto
+EXPOSE 8501
+
+# Comando para ejecutar la aplicación
+CMD ["streamlit", "run", "app.py", "--server.headless", "true", "--server.port=8501", "--server.address=0.0.0.0"]

README-HF.md

@@ -0,0 +1,173 @@
+# EmotionMirror - Facial Emotion Analysis with Computer Vision
+
+EmotionMirror is an emotional analysis application based on computer vision that uses artificial intelligence models to detect and analyze emotions from facial expressions.
+
+## Key Features
+
+- **Facial Analysis**: Detection of faces and recognition of basic emotions
+- **Results Visualization**: Clear presentation of data with numbered and sequential text
+- **Intuitive Interface**: Minimalist design with well-defined sections
+- **Group Analysis**: Process group photos with up to 5 people
+- **Mandatory Labeling**: All faces in group photos must be labeled with names
+- **Comprehensive History**: View both group analyses and individual analyses from group photos
+- **Enhanced Visualization**: View individual analyses with highlighted faces in their original group context
+- **Detailed Facial Metrics**: Shows brightness, contrast, and symmetry metrics for each face
+- **Demographic Analysis**: Includes age and gender estimation for each individual
+- **Precise Emotion Values**: Displays numerical confidence values for all detected emotions
+
+## Technical Architecture
+
+EmotionMirror uses a modular architecture to improve maintainability and separation of concerns:
+
+### Module Structure
+
+```
+EmotionMirror/
+├── app.py                    # Streamlined main application entry point
+├── controllers/              # UI and business logic controllers
+│   ├── group_analysis_controller.py
+│   ├── ui_controller.py      # Main UI controller
+├── services/                 # Specialized service modules
+│   ├── history_service.py    # History management
+│   ├── history_display_service.py # History visualization
+│   ├── visual_analysis_service.py # Analysis visualization
+│   ├── emotion_service.py
+│   ├── group_analysis_service.py
+│   └── ...
+```
+
+### Implementation Principles
+
+The application follows these key principles:
+
+- **Modular Services**: Each service focuses on one specific functionality
+- **Separation of Concerns**: Clear separation between UI, business logic, and data management
+- **Error Isolation**: Errors in one module don't affect others
+- **Code Reusability**: Common functions are centralized in appropriate service modules
+
+## Recent Enhancements (April 2025)
+
+### 1. Code Architecture Modularization
+
+The application has been refactored into a modular architecture:
+
+- **Modular Services Architecture**: Implementation split into specialized service modules
+- **Organized Hierarchy**: Clear structure with controllers and services
+- **Enhanced Maintainability**: Smaller, focused files instead of one large application file
+- **Easier Debugging**: Isolated components simplify troubleshooting
+
+### 2. UI Improvements and Error Fixes
+
+- **Nested Columns Error Fix**: Resolved StreamlitAPIException by flattening UI components
+- **Group Analysis Improvements**:
+  - Added summary section showing overall group emotion distribution
+  - Improved visual separation between individual analyses
+  - Smaller, more compact face images for better overview
+  - Added handling for false positives and untagged faces
+- **Sequential Layout**: Hierarchical display with clearly marked sections
+
+### 3. History Visualization Enhancements
+
+- **Individual Face Extracts**: Each person's face is now extracted and displayed with their analysis
+- **Two-Column Layout**: Images and analysis data clearly separated
+- **Visual Separators**: Clear dividers between different people in group analyses
+- **Group Summaries**: Added group-level emotion distribution charts
+
+### 4. Visual Analysis Improvements
+
+- **Equivalent Visualization**: Visual Analysis shows exactly the same level of detail as History
+- **Structured Analysis Display**: Clearly numbered sections (1. Facial Metrics, 2. Emotion Confidence, 3. Analysis Features)
+- **Detailed Metrics**: Enhanced display of brightness, contrast, symmetry, age, and gender
+- **Emotion Values**: Precise numerical confidence values for all emotions
+
+### 5. Bug Fixes & Technical Improvements
+
+- **AttributeError Fix**: Resolved 'ContextMember' object has no attribute 'face_data' error
+- **Error Handling**: Added graceful fallbacks when face extraction fails
+- **Data Handling**: Enhanced robustness when handling various data formats
+
+## Technologies
+
+- Streamlit for the user interface
+- YOLOv8 for facial detection and pose analysis
+- Custom agent framework for analysis coordination
+- DeepFace for advanced emotion detection (when enabled)
+- OpenCV for image visualization and face highlighting
+
+## Usage
+
+1. Navigate to the "Visual Analysis" page
+2. Upload an image containing faces
+3. Click on "Detect Faces in Image"
+4. For single face images:
+   - Enter the person's name
+   - Click "Analyze Individual"
+5. For group images (2-5 faces):
+   - Select which faces to analyze using the checkboxes
+   - Provide names for each selected face (mandatory)
+   - Enter a group name
+   - Click "Save Group Analysis"
+6. View analysis results in the History page, which includes:
+   - Individual analyses (both from single photos and group photos)
+   - Individual analyses from groups show the full image with the specific person highlighted
+   - Group analyses with aggregate statistics
+   - Detailed facial metrics, demographic information, and emotion confidence values for each analysis
+
+## Advanced Features
+
+### Context-Aware History Display
+
+When viewing individual analyses that originated from group photos:
+- The original group image is shown with the specific person highlighted
+- A green bounding box marks the analyzed individual
+- The person's name appears as a label over their face
+- A caption indicates which group the analysis belongs to
+
+### Enhanced Group Analysis Visualization
+
+When viewing group analyses in the History section:
+- Each person's face is extracted and displayed in its own section
+- A two-column layout separates face images from analysis data
+- Clear visual separators distinguish between different people
+- Each analysis includes detailed metrics and emotion values in a consistent format
+
+### Comprehensive Analysis Metrics
+
+Each analysis (both individual and group) now includes:
+
+1. **Facial Metrics**:
+   - Brightness: Average brightness level of the facial region
+   - Contrast: Contrast level of the facial area
+   - Symmetry: Score (0-1) indicating facial symmetry
+
+2. **Demographic Estimation**:
+   - Age: Approximate age of the detected individual
+   - Gender: Estimated gender of the detected person
+
+3. **Detailed Emotion Breakdown**:
+   - Bar chart visualization showing all emotion confidence levels
+   - Precise numerical values for each emotion (anger, disgust, fear, joy, neutral, sadness, surprise)
+   - Grid layout for easy comparison between emotions
+
+4. **Structured Analysis Display**:
+   - Clearly numbered sections for easy navigation
+   - Consistent formatting across both individual and group analyses
+   - Tab-based interface for group analyses to easily view each individual
+
+## Version Notes
+
+Current version: 0.1.3 (Phase 1.3 - April 2025)
+- Basic facial detection implementation
+- Functional Streamlit user interface
+- Basic emotion classification
+- Group analysis with up to 5 people
+- Mandatory face labeling system
+- Improved history display showing both group and individual analyses
+- Enhanced visualization showing highlighted individuals in original group photos
+- Added detailed facial metrics (brightness, contrast, symmetry)
+- Implemented demographic analysis (age, gender)
+- Added precise numerical emotion confidence values
+- Ensured consistent UI formatting with clearly numbered sections
+- All text elements standardized in English for international accessibility
+- Improved group analysis visualization with individual face images
+- Fixed AttributeError in ContextMember object handling

README-PREPROCESSING.md

@@ -0,0 +1,58 @@
+# Image Preprocessing Module (Step 4)
+
+## Overview
+The image preprocessing module enhances facial detection and emotion analysis by improving image quality before processing. This feature allows users to:
+
+1. View a side-by-side comparison of original vs. processed images
+2. Choose whether to use the original or improved image for analysis
+3. Understand the technical benefits of preprocessing for facial analysis
+
+## Key Components
+
+### 1. Image Service (`services/image_service.py`)
+The core preprocessing functionality is implemented in the ImageService class:
+
+- **`preprocess_image()`**: Applies multiple image enhancements and returns both original and processed images
+- **`resize_image()`**: Resizes images to optimal dimensions while maintaining aspect ratio
+- **`adjust_brightness()`**: Increases or decreases image brightness based on analysis
+- **`adjust_contrast()`**: Adapts image contrast for better facial feature visibility
+- **`save_processed_image()`**: Saves processed images to temporary storage
+
+### 2. Preprocessing UI (`utils/preprocessing_ui.py`)
+A modular UI component that handles the preprocessing interface:
+
+- **`display_preprocessing_comparison()`**: Shows side-by-side comparison of original vs. processed images
+- **`setup_preprocessing_controls()`**: Provides buttons for selecting which image to use
+- **`display_processing_status()`**: Shows status indicators for the current image selection
+- **`get_processing_image()`**: Retrieves the appropriate image based on user selection
+
+### 3. Visual Agent Integration (`agent_framework/visual_agent.py`)
+The VisualAgent has been extended to support preprocessed images:
+
+- Updated `process()` method to handle preprocessed image paths
+- Added support for switching between original and processed images
+
+## Technical Benefits for Facial Analysis
+
+The preprocessing steps provide several benefits for facial detection and emotion analysis:
+
+1. **Balanced contrast**: Enhances visibility of facial features while reducing shadows and highlights
+2. **Optimal brightness**: Ensures facial features are clearly distinguishable without over-exposure
+3. **Proper sizing**: Maintains ideal dimensions for detection algorithms to recognize facial landmarks
+
+These improvements result in:
+- More accurate emotion classification
+- Better feature extraction (eyes, mouth, eyebrows)
+- Reduced noise and artifacts
+- More consistent performance across different lighting conditions
+
+## Usage Flow
+
+1. User uploads an image
+2. System analyzes and applies appropriate preprocessing
+3. User is shown a comparison of original vs. improved images
+4. User selects which image to use for analysis
+5. Analysis proceeds with the selected image
+6. Status indicators keep the user informed about which image is being used
+
+The preprocessing is adaptive, applying only the enhancements needed for each specific image.

README.md

@@ -0,0 +1,222 @@
+---
+title: EmotionMirror
+emoji: 📊
+colorFrom: indigo
+colorTo: purple
+sdk: streamlit
+sdk_version: 1.26.0
+app_file: app.py
+pinned: false
+---
+
+# EmotionMirror
+
+EmotionMirror is an emotional analysis application that uses computer vision and AI to analyze facial expressions and body language.
+
+## Features
+
+- **Visual Analysis**: Detect faces and analyze expressions
+- **Emotion Tracking**: Track emotions over time (coming soon)
+- **Multi-Agent System**: Coordinated analysis with specialized agents
+- **Group Analysis**: Process images with multiple faces (up to 5), with mandatory face labeling
+- **Comprehensive History**: View both group analyses and individual analyses from group photos
+- **Hugging Face Integration**: Designed for deployment on Hugging Face Spaces
+
+## Project Structure
+
+```
+EmotionMirror/
+├── app.py                     # Main Streamlit application
+├── config/                    # Configuration
+│   ├── __init__.py
+│   └── settings.py            # Centralized settings
+├── agent_framework/           # Agent implementation
+│   ├── __init__.py
+│   ├── base_agent.py          # Base agent class
+│   ├── visual_agent.py        # Visual processing agent
+│   └── agent_manager.py       # Agent coordinator
+├── services/                  # Modular services
+│   ├── __init__.py
+│   └── model_service.py       # Model management service
+├── utils/                     # Utilities
+│   ├── __init__.py
+│   └── file_utils.py          # File handling utilities
+├── models/                    # Pre-trained models
+└── static/                    # Static assets
+    ├── uploads/               # Uploaded images
+    └── results/               # Processing results
+```
+
+## Requirements
+
+- Python 3.9+
+- Streamlit
+- Ultralytics YOLO
+- OpenCV
+- Torch
+- See requirements.txt for complete list
+
+## Installation
+
+1. Clone the repository
+2. Install dependencies:
+   ```
+   pip install -r requirements.txt
+   ```
+3. Run the application:
+   ```
+   streamlit run app.py
+   ```
+
+## Deployment to Hugging Face Spaces
+
+This application is designed to be deployed on Hugging Face Spaces. To deploy:
+
+1. Push this repository to GitHub
+2. Create a new Space on Hugging Face
+3. Connect your GitHub repository
+4. Set the Space SDK to "Streamlit"
+5. The application will automatically deploy
+
+## Development Roadmap
+
+- **Phase 1**: Basic visual analysis with YOLO
+- **Phase 2**: Database integration for emotion tracking
+- **Phase 3**: Hume.ai integration and advanced multi-agent system
+
+## Recent Changes to Analysis History
+
+### Group Analysis Update (April 2025)
+
+The Group Analysis and History functionality have been enhanced with several important improvements:
+
+#### 1. Group Size Limitation
+- **Updated Limit**: Group analysis is now limited to a maximum of 5 faces per image
+- **Improved Performance**: This change improves processing speed and UI responsiveness
+- **Clear User Feedback**: Warning messages clearly inform users when images exceed the limit
+
+#### 2. Mandatory Face Labeling
+- **Required Fields**: All selected faces in group analysis now require name labels
+- **Validation System**: Prevents saving analyses with incomplete labeling
+- **Visual Indicators**: Warning messages appear next to empty name fields
+- **Enhanced UI**: Improved face cropping for clearer identification during labeling
+
+#### 3. Comprehensive Analysis History
+- **Dual Analysis Storage**: Group photos now generate both:
+  - One group analysis with aggregate statistics
+  - Individual analyses for each labeled person in the photo
+- **Enhanced Filtering**: Filter history by person name across all analyses
+- **Improved Navigation**: Clear separation between individual and group analyses
+
+### Synchronization Update (April 2025)
+
+The Analysis History functionality has been completely synchronized between the local and Hugging Face versions to ensure consistent behavior. Below are the key improvements:
+
+#### 1. Tab Structure Enhancement
+- Added the "Statistics" tab between "Recent Analyses" and "Export Data"
+- Implemented clear sequential numbering (1, 2, 3...) for all sections
+
+#### 2. Person Filtering System
+- Fixed the person tag system to properly save and display person names
+- Implemented dropdown filtering by person name across all History tabs
+- Corrected tag saving to use actual person names instead of emotion labels
+
+#### 3. Export Functionality Expansion
+- Added "Current Session" vs "All Sessions" filtering options
+- Implemented adjustable record limit for exports
+- Enhanced person filtering for export data
+
+#### 4. Data Visualization Improvements
+- Improved record display with expandable sections
+- Enhanced chart visualization for emotion distributions
+- Added detailed display of advanced data (age, gender) when available
+
+### UI Architecture Improvements (Late April 2025)
+
+Several significant technical improvements have been implemented to enhance the robustness and maintainability of the application:
+
+#### 1. Modular Architecture
+- **Complete Refactoring**: Application has been reorganized into controllers, services, and utility modules
+- **Dependency Injection**: Services now receive configuration rather than hardcoding it
+- **Separation of Concerns**: UI logic, business logic, and data access have been separated
+
+#### 2. Streamlit Column Nesting Fix
+- **Problem Solved**: Fixed the Streamlit limitation that only allows one level of column nesting
+- **Enhanced UI Components**: Redesigned UI elements using tabs and flat layouts instead of nested columns
+- **Tab-Based Navigation**: Implemented tabs for content organization to avoid excessive column usage
+
+#### 3. False Positive Detection
+- **Detection Validation**: Added checks to warn users about potential false positives in face detection
+- **Confidence Thresholds**: Clear warnings when detected faces have low confidence scores
+- **Size Validation**: Alerts for unusually small or large detected face regions
+
+#### 4. Static Asset Management
+- **Robust Directory Creation**: Automatic creation of required directories like "static/" and "static/results/"
+- **Image Fallbacks**: Graceful handling of missing images with base64 backups
+- **Platform Compatibility**: Consistent path handling across both local and Hugging Face environments
+
+### Technical Details
+
+The Hugging Face version previously handled tags differently from the local version. This has been corrected to ensure complete consistency:
+
+- **Old Method (Fixed)**: Saved generic tags like 'emotion_analysis' and emotion names
+- **New Method**: Uses the person's name as the sole tag, identical to local version
+
+This ensures that filters now show actual person names rather than emotion categories, making it easier to track analyses by individual.
+
+### Additional Debugging
+
+The Hugging Face version includes extra debugging statements to help troubleshoot database operations, especially for tag handling and record retrieval, which are particularly important given the platform's permission restrictions.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Additional Information
+
+### EmotionMirror - Facial Emotion Analysis with Computer Vision
+
+EmotionMirror is an emotional analysis application based on computer vision that uses artificial intelligence models to detect and analyze emotions from facial expressions.
+
+### Features
+
+- **Facial Analysis**: Detection of faces and recognition of basic emotions
+- **Results Visualization**: Clear presentation of data with numbered and sequential text
+- **Intuitive Interface**: Minimalist design with well-defined sections
+- **Group Analysis**: Process group photos with up to 5 people
+- **Mandatory Labeling**: All faces in group photos must be labeled with names
+- **Comprehensive History**: View both group analyses and individual analyses from group photos
+
+### Technologies
+
+- Streamlit for the user interface
+- YOLOv8 for facial detection and pose analysis
+- Custom agent framework for analysis coordination
+- DeepFace for advanced emotion detection (when enabled)
+
+### Usage
+
+1. Navigate to the "Visual Analysis" page
+2. Upload an image containing faces
+3. Click on "Detect Faces in Image"
+4. For single face images:
+   - Enter the person's name
+   - Click "Analyze Individual"
+5. For group images (2-5 faces):
+   - Select which faces to analyze using the checkboxes
+   - Provide names for each selected face (mandatory)
+   - Enter a group name
+   - Click "Save Group Analysis"
+6. View analysis results in the History page, which includes:
+   - Individual analyses (both from single photos and group photos)
+   - Group analyses with aggregate statistics
+
+### Version Notes
+
+Current version: 0.1.3 (Phase 1.3 - April 2025)
+- Basic facial detection implementation
+- Functional Streamlit user interface
+- Basic emotion classification
+- Group analysis with up to 5 people
+- Mandatory face labeling system
+- Improved history display showing both group and individual analyses

agent_framework/__init__.py

@@ -0,0 +1,4 @@
+"""
+Agent framework package for EmotionMirror application.
+Contains agent implementations for visual processing and emotion analysis.
+"""

agent_framework/agent_manager.py

@@ -0,0 +1,91 @@
+"""
+Agent manager for EmotionMirror application.
+Coordinates communication between different agents.
+"""
+import logging
+from typing import Dict, Any, Optional
+
+from agent_framework.base_agent import BaseAgent
+from agent_framework.visual_agent import VisualAgent
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+class AgentManager:
+    """Manages agents and coordinates their communication"""
+    
+    _instance = None
+    
+    def __new__(cls):
+        """Singleton pattern implementation"""
+        if cls._instance is None:
+            cls._instance = super(AgentManager, cls).__new__(cls)
+            cls._instance._initialized = False
+        return cls._instance
+    
+    def __init__(self):
+        """Initialize the agent manager"""
+        if self._initialized:
+            return
+            
+        self._initialized = True
+        logger.info("Initializing AgentManager")
+        
+        # Dictionary to store agents
+        self.agents = {}
+        
+        # Initialize agents
+        self._initialize_agents()
+    
+    def _initialize_agents(self) -> None:
+        """Initialize available agents"""
+        # In Phase 1, we only have the VisualAgent
+        self.register_agent(VisualAgent())
+    
+    def register_agent(self, agent: BaseAgent) -> None:
+        """
+        Register an agent with the manager.
+        
+        Args:
+            agent: Agent instance to register
+        """
+        self.agents[agent.name] = agent
+        logger.info(f"Agent registered: {agent.name}")
+    
+    def get_agent(self, agent_name: str) -> Optional[BaseAgent]:
+        """
+        Get an agent by name.
+        
+        Args:
+            agent_name: Name of the agent
+            
+        Returns:
+            Agent instance or None if not found
+        """
+        return self.agents.get(agent_name)
+    
+    def process_visual(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Process visual data using the VisualAgent.
+        
+        Args:
+            data: Input data for processing
+            
+        Returns:
+            Processing results
+        """
+        visual_agent = self.get_agent("VisualAgent")
+        if visual_agent:
+            return visual_agent.process(data)
+        else:
+            logger.error("VisualAgent not found")
+            return {"error": "VisualAgent not available"}
+    
+    def list_agents(self) -> Dict[str, str]:
+        """
+        List all registered agents.
+        
+        Returns:
+            Dictionary of agent names and descriptions
+        """
+        return {name: agent.description for name, agent in self.agents.items()}

agent_framework/base_agent.py

@@ -0,0 +1,58 @@
+"""
+Base agent class for EmotionMirror application.
+Provides the foundation for all agent implementations.
+"""
+from abc import ABC, abstractmethod
+import logging
+from typing import Dict, Any
+
+class BaseAgent(ABC):
+    """Base class for all agents in EmotionMirror"""
+    
+    def __init__(self, name: str, description: str = ""):
+        """
+        Initialize the base agent.
+        
+        Args:
+            name: Name of the agent
+            description: Description of the agent's purpose
+        """
+        self.name = name
+        self.description = description
+        self.logger = logging.getLogger(f"agent.{name}")
+        
+    @abstractmethod
+    def process(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Process data and return a result.
+        
+        Args:
+            data: Input data to process
+            
+        Returns:
+            Dictionary with processing results
+        """
+        pass
+    
+    def log_activity(self, message: str, level: str = 'info') -> None:
+        """
+        Log agent activity.
+        
+        Args:
+            message: Log message
+            level: Log level (debug, info, warning, error, critical)
+        """
+        log_methods = {
+            'debug': self.logger.debug,
+            'info': self.logger.info,
+            'warning': self.logger.warning,
+            'error': self.logger.error,
+            'critical': self.logger.critical
+        }
+        
+        log_method = log_methods.get(level.lower(), self.logger.info)
+        log_method(f"[{self.name}] {message}")
+        
+    def __str__(self) -> str:
+        """String representation of the agent"""
+        return f"Agent({self.name}): {self.description}"

agent_framework/visual_agent.py

@@ -0,0 +1,194 @@
+"""
+Visual agent for EmotionMirror application.
+Handles image processing and facial analysis.
+"""
+import cv2
+import numpy as np
+import logging
+from typing import Dict, Any, List, Tuple
+
+from agent_framework.base_agent import BaseAgent
+from services.model_service import ModelService
+from services import get_emotion_service  
+
+class VisualAgent(BaseAgent):
+    """Agent for visual processing and emotion analysis"""
+    
+    def __init__(self):
+        """Initialize the visual agent"""
+        super().__init__(name="VisualAgent", description="Processes images to detect faces and emotions")
+        self.model_service = ModelService()
+        self.emotion_service = get_emotion_service()  
+        self.detection_model = None
+        self.pose_model = None
+    
+    def _ensure_models_loaded(self) -> bool:
+        """
+        Ensure that required models are loaded.
+        
+        Returns:
+            True if models are loaded successfully, False otherwise
+        """
+        try:
+            if self.detection_model is None:
+                self.log_activity("Loading detection model")
+                self.detection_model = self.model_service.load_model('detection')
+                
+            if self.pose_model is None:
+                self.log_activity("Loading pose model")
+                self.pose_model = self.model_service.load_model('pose')
+                
+            return self.detection_model is not None and self.pose_model is not None
+        except Exception as e:
+            self.log_activity(f"Error loading models: {str(e)}", "error")
+            return False
+    
+    def process(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Process an image to detect faces and basic expressions.
+        
+        Args:
+            data: Dictionary with:
+                - 'image_path': Path to the image
+                - 'image': (Optional) numpy array of the image
+                - 'confidence': Detection confidence threshold
+                - 'use_preprocessed_image': (Optional) Whether to use preprocessed image
+                - 'preprocessed_image_path': (Optional) Path to preprocessed image
+            
+        Returns:
+            Dictionary with visual analysis results
+        """
+        # Ensure models are loaded
+        if not self._ensure_models_loaded():
+            return {"error": "Failed to load required models"}
+        
+        # Get image data
+        image_path = data.get('image_path')
+        image = data.get('image')
+        confidence = data.get('confidence', 0.25)
+        detection_confidence = data.get('detection_confidence', confidence)  # Support new parameter name
+        
+        # STEP 4: Handle preprocessed image
+        use_preprocessed = data.get('use_preprocessed_image', False)
+        preprocessed_path = data.get('preprocessed_image_path', None)
+        
+        if image_path is None and image is None:
+            return {'error': 'Image or image path is required'}
+        
+        # Load image if path is provided
+        if image_path is not None:
+            try:
+                # STEP 4: Choose between original and preprocessed image
+                if use_preprocessed and preprocessed_path:
+                    self.log_activity(f"Using preprocessed image from: {preprocessed_path}")
+                    image = cv2.imread(preprocessed_path)
+                    if image is None:
+                        self.log_activity("Preprocessed image not found, falling back to original", "warning")
+                        image = cv2.imread(image_path)
+                else:
+                    image = cv2.imread(image_path)
+                    
+                if image is None:
+                    return {'error': 'Failed to read image from provided path'}
+            except Exception as e:
+                self.log_activity(f"Error reading image: {e}", 'error')
+                return {'error': f'Error reading image: {str(e)}'}
+        
+        # Process with detection model (for faces)
+        self.log_activity("Running detection model")
+        detection_results = self.detection_model(image, conf=detection_confidence)
+        
+        # Process with pose model (for body language)
+        self.log_activity("Running pose model")
+        pose_results = self.pose_model(image, conf=detection_confidence)
+        
+        # Extract faces (person detections)
+        faces = self._extract_faces(detection_results, image)
+        
+        # Extract poses
+        poses = self._extract_poses(pose_results)
+        
+        # Return combined results
+        return {
+            'faces': faces,
+            'poses': poses,
+            'face_count': len(faces),
+            'timestamp': data.get('timestamp'),
+            'used_preprocessed_image': use_preprocessed and preprocessed_path is not None
+        }
+    
+    def _extract_faces(self, results: List, image: np.ndarray) -> List[Dict[str, Any]]:
+        """
+        Extract face information from detection results.
+        
+        Args:
+            results: Detection model results
+            image: Original image
+            
+        Returns:
+            List of face data dictionaries
+        """
+        faces = []
+        
+        for r in results:
+            boxes = r.boxes
+            for box in boxes:
+                # Filter only for persons (class 0 in COCO)
+                if int(box.cls[0]) == 0:  # 'person' in COCO dataset
+                    x1, y1, x2, y2 = map(int, box.xyxy[0])
+                    
+                    # Extract face region
+                    face_img = image[y1:y2, x1:x2]
+                    
+                    # Analyze emotion of the face
+                    emotion_data = self.emotion_service.analyze_emotion(face_img)
+                    
+                    # Check if advanced service was used
+                    using_advanced = False
+                    if hasattr(self.emotion_service, 'is_advanced_service_active'):
+                        using_advanced = self.emotion_service.is_advanced_service_active()
+                    
+                    # Basic face data
+                    face_data = {
+                        'bbox': [x1, y1, x2, y2],
+                        'confidence': float(box.conf[0]),
+                        'emotion': emotion_data['emotion'],
+                        'emotion_confidence': emotion_data['confidence'],
+                        'emotions': emotion_data['emotions'],
+                        'features': emotion_data['features'],  # Usar el mismo nombre de clave que en emotion_service
+                        'emotion_features': emotion_data['features'],  # Mantener para compatibilidad
+                        'using_advanced': using_advanced  # Indicador de si se utilizó el servicio avanzado
+                    }
+                    
+                    # Add advanced data if available (from DeepFace)
+                    if 'age' in emotion_data['features']:
+                        face_data['age'] = emotion_data['features']['age']
+                    if 'gender' in emotion_data['features']:
+                        face_data['gender'] = emotion_data['features']['gender']
+                    
+                    faces.append(face_data)
+        
+        return faces
+    
+    def _extract_poses(self, results: List) -> List[Dict[str, Any]]:
+        """
+        Extract pose information from pose model results.
+        
+        Args:
+            results: Pose model results
+            
+        Returns:
+            List of pose data dictionaries
+        """
+        poses = []
+        
+        for r in results:
+            if hasattr(r, 'keypoints') and r.keypoints is not None:
+                for i, keypoints in enumerate(r.keypoints.data):
+                    pose_data = {
+                        'keypoints': keypoints.tolist(),
+                        'person_idx': i
+                    }
+                    poses.append(pose_data)
+        
+        return poses

app.py

@@ -0,0 +1,843 @@
+"""
+EmotionMirror - Emotional Analysis Application
+
+A Streamlit application for analyzing emotions using computer vision.
+"""
+import os
+import time
+import uuid
+import logging
+import streamlit as st
+from datetime import datetime
+from PIL import Image
+import numpy as np
+import cv2
+import json
+import pandas as pd
+
+# Import app modules
+from config import settings
+from agent_framework.agent_manager import AgentManager
+from utils.file_utils import allowed_file, save_uploaded_file
+from utils.export_utils import export_to_json, export_to_csv, get_download_link, generate_emotion_summary
+from utils.preprocessing_ui import display_preprocessing_comparison, setup_preprocessing_controls, display_processing_status, get_processing_image, show_preprocessing_ui
+from services.database_service import DatabaseService
+from services.image_service import ImageService
+# Import the new image visualization module (from root directory)
+import sys
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from image_visualization import display_image_with_controls, create_image_tabs
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# Page configuration
+st.set_page_config(
+    page_title="EmotionMirror",
+    page_icon="📊",
+    layout="wide",
+    initial_sidebar_state="expanded",
+    menu_items={
+        'Get Help': 'https://www.example.com/help',
+        'Report a bug': 'https://www.example.com/bug',
+        'About': 'EmotionMirror is an emotion analysis application.'
+    }
+)
+
+# Apply custom CSS to improve stability and reduce flickering
+st.markdown("""
+<style>
+    /* Reduce animation and transitions to minimize flickering */
+    * {
+        transition: none !important;
+        animation: none !important;
+        transform: none !important;
+    }
+    
+    /* Make containers more stable */
+    .stApp {
+        transform: translateZ(0);
+        backface-visibility: hidden;
+        perspective: 1000px;
+    }
+    
+    /* Further stabilize the main content area */
+    .main .block-container {
+        transform: translateZ(0);
+        will-change: auto;
+    }
+    
+    /* Ensure column stability */
+    [data-testid="column"] {
+        transform: translateZ(0);
+    }
+    
+    /* Improve scrolling stability */
+    .main {
+        overflow-y: auto;
+        overflow-x: hidden;
+    }
+</style>
+""", unsafe_allow_html=True)
+
+# Initialize agent manager
+@st.cache_resource
+def get_agent_manager():
+    """Get or create the agent manager singleton"""
+    return AgentManager()
+
+# Initialize database service
+@st.cache_resource
+def get_database_service():
+    """Get or create the database service singleton"""
+    return DatabaseService()
+
+# Initialize image service for enhanced image handling
+@st.cache_resource
+def get_image_service():
+    """
+    Get or create the image service singleton.
+    Part of Step 3 implementation: Added for image validation, dimension and quality analysis.
+    """
+    return ImageService()
+
+# Session state initialization
+if "session_id" not in st.session_state:
+    st.session_state.session_id = str(uuid.uuid4())
+    logger.info(f"New session started: {st.session_state.session_id}")
+
+if "upload_history" not in st.session_state:
+    st.session_state.upload_history = []
+
+# Store the advanced emotion setting in session state to persist between pages
+if 'use_advanced_emotion' not in st.session_state:
+    st.session_state.use_advanced_emotion = settings.USE_ADVANCED_EMOTION
+
+# App title and description
+st.title("EmotionMirror")
+st.markdown("""
+    Welcome to EmotionMirror, an application for analyzing emotions using computer vision.
+    
+    This is a prototype version that demonstrates the basic functionality.
+""")
+
+# Sidebar
+with st.sidebar:
+    st.title("EmotionMirror")
+    st.subheader("Facial Emotion Analysis")
+    
+    # Navigation options
+    page = st.radio(
+        "Navigation",
+        ["Home", "Visual Analysis", "History", "About"]
+    )
+    
+    st.divider()
+    
+    # Settings section in sidebar
+    st.subheader("Settings")
+    
+    # Add option to switch between basic and advanced emotion detection
+    use_advanced = st.checkbox(
+        "Use Advanced Emotion Detection", 
+        value=st.session_state.use_advanced_emotion,
+        help="When enabled, DeepFace will be used for more accurate emotion detection"
+    )
+    
+    # Update the setting if changed
+    if st.session_state.use_advanced_emotion != use_advanced:
+        st.session_state.use_advanced_emotion = use_advanced
+        settings.USE_ADVANCED_EMOTION = use_advanced
+        
+        # Show a note about reloading
+        if use_advanced:
+            st.info("Advanced detection enabled")
+        else:
+            st.info("Basic detection enabled")
+    
+    # General confidence threshold
+    confidence_threshold = st.slider(
+        "Detection Confidence", 
+        min_value=0.1, 
+        max_value=1.0, 
+        value=0.45,
+        step=0.05,
+        help="Adjust the confidence threshold for detections"
+    )
+    
+    st.divider()
+    st.caption(f"Session ID: {st.session_state.session_id}")
+    st.caption(f"Version: 0.1.3 (Phase 1.3)")
+
+# Home page
+if page == "Home":
+    st.header("EmotionMirror - Emotional Analysis System")
+    
+    st.subheader("Features")
+    col1, col2, col3 = st.columns(3)
+    
+    with col1:
+        st.markdown("### 📷 Visual Analysis")
+        st.markdown("Upload images to analyze facial expressions and emotions.")
+    
+    with col2:
+        st.markdown("### 📊 Emotion Tracking")
+        st.markdown("Track emotions over time with detailed analytics. (Coming soon)")
+    
+    with col3:
+        st.markdown("### 🧠 AI Recommendations")
+        st.markdown("Get personalized recommendations based on your emotional state. (Coming soon)")
+    
+    st.subheader("Getting Started")
+    st.markdown("""
+        1. Navigate to the **Visual Analysis** page
+        2. Upload an image containing faces
+        3. View the analysis results
+    """)
+
+# Visual Analysis page
+elif page == "Visual Analysis":
+    # Use modular page handler with correct parameters
+    st.header("Visual Emotion Analysis")
+    st.markdown("""
+    Upload an image to analyze emotions. 
+    For best results, use a clear image of a face with good lighting.
+    """)
+    
+    # Initialize services explicitly
+    agent_mgr = get_agent_manager()
+    img_service = get_image_service()
+    database_service = get_database_service()
+    
+    # Initialize the visual agent at the start
+    visual_agent = agent_mgr.get_agent("VisualAgent")
+    if not visual_agent:
+        st.warning("Visual agent not available. The system is initializing or there is a configuration issue.")
+        logger.error("Failed to get VisualAgent from agent_manager")
+    
+    # Create numbered sections for clear navigation
+    st.subheader("1. Upload an Image")
+    
+    # Add reset button for clearing current image
+    if "original_image" in st.session_state:
+        col1, col2 = st.columns([3, 1])
+        with col2:
+            if st.button("Clear Current Image", key="clear_image"):
+                # Clear the session state
+                if "original_image" in st.session_state:
+                    del st.session_state["original_image"]
+                if "processed_image" in st.session_state:
+                    del st.session_state["processed_image"]
+                if "current_image_path" in st.session_state:
+                    del st.session_state["current_image_path"]
+                st.experimental_rerun()
+    
+    # Create file uploader
+    uploaded_file = st.file_uploader(
+        "Choose an image...", 
+        type=["jpg", "jpeg", "png"], 
+        help="Upload a clear image of a face for analysis."
+    )
+    
+    # Display information about detection methods
+    with st.expander("About the Detection Methods", expanded=False):
+        st.markdown("""
+        ### About the Detection Methods
+        
+        Currently using: **Advanced Detection**
+        
+        * **Basic detection** is faster but less accurate. It works by analyzing simple facial features.
+        * **Advanced detection (DeepFace)** uses deep learning models that are trained on thousands of faces to recognize subtle emotional cues.
+        
+        You can change the default detection method in the sidebar settings.
+        """)
+    
+    # Display image and interface when uploaded
+    if uploaded_file is not None:
+        try:
+            # Process the uploaded file
+            file_bytes = np.asarray(bytearray(uploaded_file.read()), dtype=np.uint8)
+            uploaded_file.seek(0)  # Reset the file pointer for further processing
+            
+            # Validate image file - includes format, size, and dimensions
+            validation_result = img_service.validate_image_file(
+                uploaded_file,
+                check_content=True,
+                check_dimensions=True
+            )
+            
+            # If the image is valid, process it
+            if validation_result["valid"]:
+                # Process the uploaded image to improve quality if possible
+                try:
+                    # Load image for processing with OpenCV (this will be in BGR format)
+                    img = cv2.imdecode(file_bytes, cv2.IMREAD_COLOR)
+                    
+                    # Convert from BGR to RGB for preprocessing display
+                    img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+                    
+                    # Store original RGB image for display
+                    if "original_image" not in st.session_state:
+                        st.session_state.original_image = img_rgb.copy()
+                    
+                    # Determine which image to process based on preprocessing settings
+                    use_improved = st.session_state.get("use_improved_image", False)
+                    
+                    # Choose image for processing
+                    img_to_process = get_processing_image(img_rgb, img_service, use_improved)
+                    
+                    # STEP 5: Display the image with visualization controls
+                    st.subheader("2. Image Visualization")
+                    st.markdown("""
+                    View the uploaded image with basic controls. You can:
+                    - Zoom in/out to see details
+                    - Reset view to original size
+                    - Download the current image
+                    """)
+                    
+                    # Check if we have both original and processed images
+                    if "processed_image" in st.session_state:
+                        # Create tabs to display original and processed images
+                        image_tabs_result = create_image_tabs(
+                            st.session_state.original_image,
+                            st.session_state.processed_image
+                        )
+                    else:
+                        # Display just the original image
+                        display_result = display_image_with_controls(
+                            st.session_state.original_image,
+                            title="Uploaded Image",
+                            allow_zoom=True,
+                            allow_download=True
+                        )
+                        
+                        # Store the processed image if available for comparison
+                        if use_improved and img_to_process is not None:
+                            st.session_state.processed_image = img_to_process
+                    
+                    # Add space between sections
+                    st.markdown("<div style='height: 20px;'></div>", unsafe_allow_html=True)
+                    
+                    # Display image analysis from validation
+                    st.subheader("3. Image Analysis")
+                    analysis_expander = st.expander("View Image Analysis Details", expanded=False)
+                    
+                    with analysis_expander:
+                        # Show image metadata
+                        if "image_metadata" in validation_result:
+                            metadata = validation_result["image_metadata"]
+                            st.markdown("#### Image Details")
+                            
+                            # Create columns for metadata display
+                            meta_cols = st.columns(3)
+                            
+                            with meta_cols[0]:
+                                st.markdown("**Dimensions**")
+                                width = metadata.get("width", 0)
+                                height = metadata.get("height", 0)
+                                st.write(f"{width} × {height}")
+                                
+                            with meta_cols[1]:
+                                st.markdown("**Format**")
+                                img_format = metadata.get("format", "Unknown")
+                                st.write(f"{img_format}")
+                                
+                            with meta_cols[2]:
+                                st.markdown("**Size**")
+                                size_kb = metadata.get("size_kb", 0)
+                                st.write(f"{size_kb:.1f} KB")
+                            
+                            # Quality metrics if available
+                            if "quality" in metadata:
+                                st.markdown("#### Quality Metrics")
+                                quality = metadata["quality"]
+                                
+                                # Create columns for quality metrics
+                                metric_cols = st.columns(3)
+                                
+                                with metric_cols[0]:
+                                    st.markdown("**Sharpness**")
+                                    sharpness = int(quality.get("sharpness", 0) * 100)
+                                    st.write(f"{sharpness}%")
+                                    
+                                with metric_cols[1]:
+                                    st.markdown("**Brightness**")
+                                    brightness = int(quality.get("brightness", 0) * 100)
+                                    st.write(f"{brightness}%")
+                                    
+                                with metric_cols[2]:
+                                    st.markdown("**Contrast**")
+                                    contrast = int(quality.get("contrast", 0.26) * 100)
+                                    st.write(f"{contrast}%")
+                    
+                    # Add space between sections
+                    st.markdown("<div style='height: 20px;'></div>", unsafe_allow_html=True)
+                    
+                    # NOW display the preprocessing UI
+                    st.subheader("4. Image Preprocessing")
+                    preprocessing_result = show_preprocessing_ui(img_service, img_rgb)
+                    
+                    if not preprocessing_result.get("success", False):
+                        st.error(f"Error in preprocessing: {preprocessing_result.get('message', 'Unknown error')}")
+                    
+                    # Store path in session state for future use
+                    if "current_image_path" not in st.session_state:
+                        # Save the file for reference
+                        save_path = img_service.save_uploaded_image(img_to_process)
+                        st.session_state["current_image_path"] = save_path
+                    
+                    # Add some space to improve layout
+                    st.markdown("<div style='height: 20px;'></div>", unsafe_allow_html=True)
+                    
+                    # Analysis section
+                    st.subheader("5. Emotion Analysis")
+                    st.info("Image successfully uploaded. Emotion analysis functionality will be available soon.")
+                    
+                    # Add a disabled button as placeholder for future functionality
+                    st.button("Analyze Emotions (Coming Soon)", disabled=True, key="analyze_button")
+                    
+                except Exception as e:
+                    logger.error(f"Error processing image: {e}", exc_info=True)
+                    st.error(f"Error processing image: {str(e)}")
+            else:
+                # Show validation issues
+                st.error("Image validation failed:")
+                for issue in validation_result["issues"]:
+                    st.warning(issue)
+                    
+        except Exception as e:
+            logger.error(f"Error in Visual Analysis: {e}", exc_info=True)
+            st.error(f"Error processing image: {str(e)}")
+
+# History page
+elif page == "History":
+    st.header("Analysis History")
+    st.markdown("View your previous analyses and export results.")
+    
+    # Initialize database service
+    db_service = get_database_service()
+    
+    # Create tabs for different views - Using numbered sequence for clear navigation
+    history_tabs = ["1. Recent Analyses", "2. Statistics", "3. Export Data"]
+    tab1, tab2, tab3 = st.tabs(history_tabs)
+    
+    with tab1:
+        st.subheader("Recent Emotion Analyses")
+        
+        # Get available person tags from the database
+        # [April 2025] - Person filtering system synchronized with local version
+        # to show actual person names instead of emotion tags
+        try:
+            all_analyses = db_service.get_history(session_id=st.session_state.session_id, limit=100)
+            person_tags = set()
+            for analysis in all_analyses:
+                if 'tags' in analysis and analysis['tags']:
+                    for tag in analysis['tags']:
+                        person_tags.add(tag)
+            
+            person_tags = sorted(list(person_tags))
+            
+            # Create a filter dropdown if there are person tags
+            selected_person = None
+            if person_tags:
+                filter_options = ["All People"] + person_tags
+                selected_filter = st.selectbox(
+                    "Filter by Person",
+                    options=filter_options,
+                    index=0,
+                    help="Select a person to filter the analysis history"
+                )
+                
+                if selected_filter != "All People":
+                    selected_person = selected_filter
+                    st.info(f"Showing analyses for: **{selected_filter}**")
+        except Exception as e:
+            logger.error(f"Error retrieving tags: {e}")
+            person_tags = []
+            selected_person = None
+        
+        # Get analysis history from database, filtered by person if selected
+        analyses = []
+        try:
+            # Get analyses, filtered by tag if a person is selected
+            if selected_person:
+                # For simplicity, we'll retrieve all analyses and filter them here
+                # In a production app, we'd want to filter in the database query
+                all_analyses = db_service.get_history(session_id=st.session_state.session_id, limit=20)
+                analyses = [a for a in all_analyses if 'tags' in a and a['tags'] and selected_person in a['tags']]
+            else:
+                analyses = db_service.get_history(session_id=st.session_state.session_id, limit=10)
+                
+            print(f"[DEBUG] Found {len(analyses)} analyses to display")
+            for a in analyses:
+                print(f"[DEBUG] Analysis ID: {a.get('id', 'unknown')} Timestamp: {a.get('timestamp', 'unknown')}")
+        except Exception as e:
+            logger.error(f"Error retrieving analyses: {e}")
+            print(f"[DEBUG] Error retrieving analyses: {e}")
+        
+        if analyses:
+            for i, analysis in enumerate(analyses):
+                with st.expander(f"Analysis #{analysis['id']} - {analysis['timestamp'][:16]}", expanded=(i==0)):
+                    # Create columns for layout
+                    col1, col2 = st.columns([1, 2])
+                    
+                    with col1:
+                        # Show image if available and path exists
+                        image_path = analysis['image_path']
+                        if os.path.exists(image_path):
+                            try:
+                                img = Image.open(image_path)
+                                st.image(img, caption=f"Analyzed Image", use_column_width=True)
+                            except Exception as e:
+                                st.error(f"Unable to load image: {str(e)}")
+                        else:
+                            st.warning("Image file no longer available")
+                    
+                    with col2:
+                        # Display analysis details
+                        st.markdown(f"**Date:** {analysis['timestamp'][:19]}")
+                        st.markdown(f"**Faces Detected:** {analysis['face_count']}")
+                        
+                        # Show person name if available
+                        if 'tags' in analysis and analysis['tags']:
+                            st.markdown(f"**Person:** {analysis['tags'][0]}")
+                        
+                        # Check if advanced detection was used
+                        # Comprobar si los resultados ya son un diccionario o una cadena JSON
+                        if isinstance(analysis['results'], dict):
+                            results_dict = analysis['results']
+                        else:
+                            results_dict = json.loads(analysis['results'])
+                        
+                        using_advanced = False
+                        has_advanced_data = False
+                        age_data = None
+                        gender_data = None
+                        
+                        # Check for advanced detection usage and data
+                        if 'faces' in results_dict and len(results_dict['faces']) > 0:
+                            first_face = results_dict['faces'][0]
+                            using_advanced = first_face.get('using_advanced', False)
+                            
+                            # Check for advanced data
+                            if 'age' in first_face:
+                                has_advanced_data = True
+                                age_data = first_face['age']
+                            if 'gender' in first_face:
+                                has_advanced_data = True
+                                gender_data = first_face['gender']
+                        
+                        # Show detection method used
+                        if using_advanced:
+                            st.markdown("**Detection:** <span style='background-color:#4CAF50;color:white;padding:2px 6px;border-radius:3px;font-size:0.7em;'>DeepFace</span>", unsafe_allow_html=True)
+                        
+                        # Show advanced data if available
+                        if has_advanced_data:
+                            st.markdown("### Advanced Data")
+                            if age_data is not None:
+                                st.markdown(f"**Age Estimate:** {age_data}")
+                            if gender_data is not None:
+                                # Capitalize gender
+                                if isinstance(gender_data, str) and len(gender_data) > 0:
+                                    gender_data = gender_data[0].upper() + gender_data[1:].lower() if len(gender_data) > 0 else gender_data
+                                st.markdown(f"**Gender Estimate:** {gender_data}")
+                        
+                        # Show emotion data
+                        if analysis['face_count'] > 0:
+                            st.markdown("### 1. Detected Emotions")
+                        
+                        # Display each face
+                        for j, face in enumerate(results_dict['faces']):
+                            # Get emotion data
+                            emotion = face['emotion'].capitalize()
+                            confidence = face.get('emotion_confidence', face.get('confidence', 0))
+                            
+                            # Show badge for DeepFace if used
+                            if face.get('using_advanced', False):
+                                st.markdown(f"**Face {j+1}:** {emotion} <span style='background-color:#4CAF50;color:white;padding:2px 6px;border-radius:3px;font-size:0.7em;'>DeepFace</span> (Confidence: {confidence:.2f})", unsafe_allow_html=True)
+                            else:
+                                st.markdown(f"**Face {j+1}:** {emotion} (Confidence: {confidence:.2f})")
+                            
+                            # Create emotion dataframe for visualization
+                            if 'emotions' in face:
+                                emotions = face['emotions']
+                                emotion_df = pd.DataFrame({
+                                    'Emotion': [k.capitalize() for k in emotions.keys()],
+                                    'Score': list(emotions.values())
+                                })
+                                emotion_df = emotion_df.sort_values('Score', ascending=False)
+                                
+                                # Display mini chart
+                                st.bar_chart(emotion_df.set_index('Emotion'), height=150)
+                    
+                    # Option to delete analysis
+                    if st.button(f"Delete Analysis #{analysis['id']}", key=f"del_{analysis['id']}"):
+                        if db_service.delete_record(analysis['id']):
+                            st.success("Analysis deleted successfully!")
+                            st.experimental_rerun()
+                        else:
+                            st.error("Failed to delete analysis")
+        else:
+            st.info("No previous analyses found in the database.")
+            
+            # Display session upload history if available
+            if st.session_state.upload_history:
+                st.markdown("### Recent Uploads (Not yet saved to database)")
+                for i, upload in enumerate(st.session_state.upload_history):
+                    st.markdown(f"**{i+1}. {upload['file_name']}**")
+                    st.markdown(f"* Timestamp: {upload['timestamp']}")
+            
+    with tab2:
+        st.subheader("Emotion Analytics")
+        
+        # Add filter by person to statistics view
+        try:
+            all_analyses = db_service.get_history(session_id=st.session_state.session_id, limit=100)
+            person_tags = set()
+            for analysis in all_analyses:
+                if 'tags' in analysis and analysis['tags']:
+                    for tag in analysis['tags']:
+                        person_tags.add(tag)
+            
+            person_tags = sorted(list(person_tags))
+            
+            # Create a filter dropdown if there are person tags
+            selected_person = None
+            if person_tags:
+                filter_options = ["All People"] + person_tags
+                selected_filter = st.selectbox(
+                    "1. Select Person to Analyze",
+                    options=filter_options,
+                    index=0,
+                    help="Select a person to view their emotion statistics"
+                )
+                
+                if selected_filter != "All People":
+                    selected_person = selected_filter
+        except Exception as e:
+            logger.error(f"Error retrieving tags for statistics: {e}")
+            person_tags = []
+            selected_person = None
+        
+        # Get emotion statistics
+        emotion_stats = db_service.get_emotion_stats(session_id=st.session_state.session_id)
+        
+        if emotion_stats:
+            # Display chart of emotion frequencies
+            st.markdown("### 2. Emotion Distribution")
+            
+            # Create dataframe for visualization
+            stats_df = pd.DataFrame({
+                'Emotion': list(emotion_stats.keys()),
+                'Frequency': list(emotion_stats.values())
+            })
+            
+            # Sort by frequency for better visualization
+            stats_df = stats_df.sort_values('Frequency', ascending=False)
+            
+            # Display chart
+            st.bar_chart(stats_df.set_index('Emotion'))
+            
+            # Show numeric values below the chart
+            st.markdown("### 3. Detailed Percentages")
+            
+            # Create columns for better presentation
+            cols = st.columns(3)
+            for i, (emotion, frequency) in enumerate(zip(stats_df['Emotion'], stats_df['Frequency'])):
+                col_idx = i % 3
+                with cols[col_idx]:
+                    st.metric(
+                        emotion.capitalize(),
+                        f"{frequency:.1%}",
+                        delta=None
+                    )
+                    
+            # Add explanation of statistics
+            st.markdown("---")
+            st.markdown("### 4. Understanding These Statistics")
+            st.markdown("""
+            The data above shows the distribution of emotions detected across all analyses:
+            
+            1. **Emotion Distribution** - The bar chart visualizes the relative frequency of each emotion
+            2. **Detailed Percentages** - Exact percentage values for each emotion detected
+            3. **Sample Size** - Based on all faces detected in the selected analyses
+            """)
+        else:
+            st.info("No emotion data available for analysis yet.")
+            
+    with tab3:
+        st.subheader("Export Analysis Data")
+        
+        # Add filter by person for export
+        selected_person_tag = None
+        try:
+            all_analyses = db_service.get_history(session_id=st.session_state.session_id, limit=100)
+            person_tags = set()
+            for analysis in all_analyses:
+                if 'tags' in analysis and analysis['tags']:
+                    for tag in analysis['tags']:
+                        person_tags.add(tag)
+            
+            person_tags = sorted(list(person_tags))
+            
+            # Create a person filter dropdown if person tags exist
+            if person_tags:
+                person_options = ["All People"] + person_tags
+                person_filter = st.selectbox(
+                    "1. Select Person to Export",
+                    options=person_options,
+                    index=0,
+                    help="Filter export data to include only analyses for a specific person"
+                )
+                
+                if person_filter != "All People":
+                    selected_person_tag = person_filter
+                    st.info(f"Export will only include analyses for: {selected_person_tag}")
+        except Exception as e:
+            logger.error(f"Error retrieving person tags for export: {e}")
+        
+        # Options for export format
+        export_type = st.radio(
+            "2. Select Export Format",
+            ["JSON", "CSV"],
+            horizontal=True
+        )
+        
+        export_scope = st.radio(
+            "3. Select Data Scope",
+            ["Current Session", "All Sessions"],
+            horizontal=True
+        )
+        
+        session_id = st.session_state.session_id if export_scope == "Current Session" else None
+        
+        # Option to limit number of records
+        record_limit = st.slider(
+            "4. Maximum Records to Export",
+            min_value=1,
+            max_value=100,
+            value=20,
+            step=1
+        )
+        
+        # Generate export button
+        if st.button("Generate Export"):
+            with st.spinner("Preparing export..."):
+                # Get export data
+                export_data = db_service.export_data(
+                    session_id=session_id,
+                    limit=record_limit
+                )
+                
+                # Filter data by person if selected
+                if selected_person_tag and 'analyses' in export_data:
+                    filtered_analyses = []
+                    for analysis in export_data['analyses']:
+                        if 'tags' in analysis and analysis['tags'] and selected_person_tag in analysis['tags']:
+                            filtered_analyses.append(analysis)
+                    
+                    export_data['analyses'] = filtered_analyses
+                    export_data['metadata']['record_count'] = len(filtered_analyses)
+                    export_data['metadata']['person_filter'] = selected_person_tag
+                
+                if not export_data or not export_data.get('analyses'):
+                    st.warning("No data available to export")
+                else:
+                    st.success(f"Export generated with {len(export_data.get('analyses', []))} analyses")
+                    
+                    # Create download options based on export type
+                    if export_type == "JSON":
+                        json_str = export_to_json(export_data)
+                        filename = f"emotion_analysis_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
+                        
+                        # Create download button
+                        st.download_button(
+                            label="Download JSON",
+                            data=json_str,
+                            file_name=filename,
+                            mime="application/json"
+                        )
+                    else:  # CSV
+                        csv_str = export_to_csv(export_data)
+                        filename = f"emotion_analysis_{datetime.now().strftime('%Y%m%d_%H%M%S')}.csv"
+                        
+                        # Create download button
+                        st.download_button(
+                            label="Download CSV",
+                            data=csv_str,
+                            file_name=filename,
+                            mime="text/csv"
+                        )
+                    
+                    # Show summary statistics
+                    summary = generate_emotion_summary(export_data)
+                    
+                    st.markdown("### Export Summary")
+                    st.markdown(f"**Total Analyses:** {summary['total_analyses']}")
+                    st.markdown(f"**Total Faces Analyzed:** {summary['total_faces']}")
+                    
+                    if summary['total_faces'] > 0:
+                        # Display emotion distribution
+                        st.markdown("**Emotion Distribution:**")
+                        
+                        # Create dataframe for visualization
+                        emotions_df = pd.DataFrame({
+                            'Emotion': list(summary['emotion_percentages'].keys()),
+                            'Percentage': list(summary['emotion_percentages'].values())
+                        })
+                        
+                        # Sort by percentage
+                        emotions_df = emotions_df.sort_values('Percentage', ascending=False)
+                        
+                        # Display chart
+                        st.bar_chart(emotions_df.set_index('Emotion'))
+                        
+                        # Add explanation of export formats below visualization
+                        st.markdown("---")
+                        st.markdown("### 5. About Export Formats")
+                        st.markdown("""
+                        The exported data includes analysis details in your chosen format:
+                        
+                        1. **JSON Format** - Complete data structure with all details, ideal for further processing
+                        2. **CSV Format** - Tabular data format, can be opened in spreadsheet software
+                        3. **Data Contents** - Each export includes timestamps, emotion labels, confidence values, and facial features
+                        4. **Person Information** - If you specified a person name, it's included with each analysis
+                        """)
+
+# About page
+elif page == "About":
+    st.header("About EmotionMirror")
+    
+    st.markdown("""
+        ## EmotionMirror: Emotional Analysis System
+        
+        EmotionMirror is an application that uses computer vision and artificial intelligence
+        to analyze emotions from facial expressions and body language.
+        
+        ### Technology Stack
+        
+        * **Streamlit**: For the user interface
+        * **YOLOv8**: For object detection, pose estimation, and facial analysis
+        * **Agent Framework**: A custom multi-agent system for coordinated analysis
+        
+        ### Future Features
+        
+        * Enhanced emotion recognition with Hume.ai integration
+        * Temporal emotion tracking and pattern analysis
+        * Personalized recommendations based on emotional states
+        * Guided emotional wellness sessions
+        
+        ### Privacy
+        
+        * All image processing is done locally
+        * We don't store your images after processing
+        * No personal data is shared with third parties
+    """)
+
+# Footer
+st.markdown("---")
+st.markdown(" EmotionMirror | Developed as a prototype application")

app.py.backup

@@ -0,0 +1,927 @@
+"""
+EmotionMirror - Emotional Analysis Application
+
+A Streamlit application for analyzing emotions using computer vision.
+"""
+import os
+import time
+import uuid
+import logging
+import streamlit as st
+from datetime import datetime
+from PIL import Image
+import numpy as np
+import cv2
+import json
+import pandas as pd
+
+# Import app modules
+from config import settings
+from agent_framework.agent_manager import AgentManager
+from utils.file_utils import allowed_file, save_uploaded_file
+from utils.export_utils import export_to_json, export_to_csv, get_download_link, generate_emotion_summary
+from utils.preprocessing_ui import display_preprocessing_comparison, setup_preprocessing_controls, display_processing_status, get_processing_image, show_preprocessing_ui
+from services.database_service import DatabaseService
+from services.image_service import ImageService
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# Page configuration
+st.set_page_config(
+    page_title="EmotionMirror",
+    page_icon="📊",
+    layout="wide",
+    initial_sidebar_state="expanded"
+)
+
+# Initialize agent manager
+@st.cache_resource
+def get_agent_manager():
+    """Get or create the agent manager singleton"""
+    return AgentManager()
+
+# Initialize database service
+@st.cache_resource
+def get_database_service():
+    """Get or create the database service singleton"""
+    return DatabaseService()
+
+# Initialize image service for enhanced image handling
+@st.cache_resource
+def get_image_service():
+    """
+    Get or create the image service singleton.
+    Part of Step 3 implementation: Added for image validation, dimension and quality analysis.
+    """
+    return ImageService()
+
+# Session state initialization
+if "session_id" not in st.session_state:
+    st.session_state.session_id = str(uuid.uuid4())
+    logger.info(f"New session started: {st.session_state.session_id}")
+
+if "upload_history" not in st.session_state:
+    st.session_state.upload_history = []
+
+# Store the advanced emotion setting in session state to persist between pages
+if 'use_advanced_emotion' not in st.session_state:
+    st.session_state.use_advanced_emotion = settings.USE_ADVANCED_EMOTION
+
+# App title and description
+st.title("EmotionMirror")
+st.markdown("""
+    Welcome to EmotionMirror, an application for analyzing emotions using computer vision.
+    
+    This is a prototype version that demonstrates the basic functionality.
+""")
+
+# Sidebar
+with st.sidebar:
+    st.title("EmotionMirror")
+    st.subheader("Facial Emotion Analysis")
+    
+    # Navigation options
+    page = st.radio(
+        "Navigation",
+        ["Home", "Visual Analysis", "History", "About"]
+    )
+    
+    st.divider()
+    
+    # Settings section in sidebar
+    st.subheader("Settings")
+    
+    # Add option to switch between basic and advanced emotion detection
+    use_advanced = st.checkbox(
+        "Use Advanced Emotion Detection", 
+        value=st.session_state.use_advanced_emotion,
+        help="When enabled, DeepFace will be used for more accurate emotion detection"
+    )
+    
+    # Update the setting if changed
+    if st.session_state.use_advanced_emotion != use_advanced:
+        st.session_state.use_advanced_emotion = use_advanced
+        settings.USE_ADVANCED_EMOTION = use_advanced
+        
+        # Show a note about reloading
+        if use_advanced:
+            st.info("Advanced detection enabled")
+        else:
+            st.info("Basic detection enabled")
+    
+    # General confidence threshold
+    confidence_threshold = st.slider(
+        "Detection Confidence", 
+        min_value=0.1, 
+        max_value=1.0, 
+        value=0.45,
+        step=0.05,
+        help="Adjust the confidence threshold for detections"
+    )
+    
+    st.divider()
+    st.caption(f"Session ID: {st.session_state.session_id}")
+    st.caption(f"Version: 0.1.3 (Phase 1.3)")
+
+# Home page
+if page == "Home":
+    st.header("EmotionMirror - Emotional Analysis System")
+    
+    st.subheader("Features")
+    col1, col2, col3 = st.columns(3)
+    
+    with col1:
+        st.markdown("### 📷 Visual Analysis")
+        st.markdown("Upload images to analyze facial expressions and emotions.")
+    
+    with col2:
+        st.markdown("### 📊 Emotion Tracking")
+        st.markdown("Track emotions over time with detailed analytics. (Coming soon)")
+    
+    with col3:
+        st.markdown("### 🧠 AI Recommendations")
+        st.markdown("Get personalized recommendations based on your emotional state. (Coming soon)")
+    
+    st.subheader("Getting Started")
+    st.markdown("""
+        1. Navigate to the **Visual Analysis** page
+        2. Upload an image containing faces
+        3. View the analysis results
+    """)
+
+# Visual Analysis page
+elif page == "Visual Analysis":
+    st.title("Visual Emotion Analysis")
+    st.markdown("Upload an image to analyze emotions")
+    
+    # Initialize the image service for improved image handling
+    # STEP 3: Using the enhanced image service for validation of dimensions and quality
+    image_service = get_image_service()
+    
+    # Implement Steps 1, 2 & 3: Interface design, format validation, and dimension/quality analysis
+    uploaded_file = image_service.setup_image_upload_interface(st)
+    
+    # Model settings in a cleaner expandable section
+    with st.expander("Detection Settings"):
+        # Add explanation text about the detection methods
+        detection_type = "Advanced Detection" if st.session_state.use_advanced_emotion else "Basic Detection"
+        st.markdown(f"""
+        ### About the Detection Methods
+        
+        Currently using: **{detection_type}**
+        
+        - **Basic detection** is faster but less accurate. It works by analyzing simple facial features.
+        - **Advanced detection (DeepFace)** uses deep learning models that are trained on thousands of faces to recognize subtle emotional cues.
+        
+        You can change the default detection method in the sidebar settings.
+        """)
+    
+    # Display image and interface when uploaded
+    if uploaded_file is not None:
+        # We're removing redundant title and image display since our image service 
+        # already handles this in the two-column layout
+        
+        # Keep this for processing, but no display
+        file_bytes = np.asarray(bytearray(uploaded_file.read()), dtype=np.uint8)
+        uploaded_file.seek(0)  # Reset the file pointer for further processing
+        
+        # Get image service for processing and validation
+        image_service = get_image_service()
+        
+        # Validate image file - includes format, size, and dimensions
+        validation_result = image_service.validate_image_file(
+            uploaded_file,
+            check_content=True,
+            check_dimensions=True
+        )
+        
+        if validation_result["valid"]:
+            # Process the uploaded image to improve quality if possible
+            # STEP 4: Add image preprocessing functionality
+            try:
+                # Load image for processing
+                img = cv2.imdecode(file_bytes, cv2.IMREAD_COLOR)
+                
+                # Use the modular preprocessing UI handler
+                preprocessing_result = show_preprocessing_ui(image_service, img)
+                
+                if not preprocessing_result.get("success", False):
+                    st.error(f"Error in preprocessing: {preprocessing_result.get('message', 'Unknown error')}")
+                
+            except Exception as e:
+                st.error(f"Error preprocessing image: {str(e)}")
+                logging.error(f"Preprocessing error: {str(e)}", exc_info=True)
+        
+        # Continue with original code - now using PIL to open the file
+        image = Image.open(uploaded_file)
+        
+        # Add person name field
+        st.subheader("2. Person Information")
+        st.markdown("Enter the name of the person in the image")
+        
+        person_name = st.text_input(
+            "Person Name", 
+            key="person_name",
+            help="Enter the name of the person whose emotions you want to analyze"
+        )
+        
+        # Process button - disabled if no name entered
+        process_button = st.button(
+            "Analyze Image", 
+            disabled=(not person_name or len(person_name.strip()) == 0),
+            help="You must enter a person name before analyzing"
+        )
+        
+        # Show warning if name field is empty
+        if not person_name or len(person_name.strip()) == 0:
+            st.warning("Please enter the person's name before analyzing the image")
+        
+        # Only proceed if button is clicked and name is provided
+        if process_button:
+            # Validate person name again for safety
+            if not person_name or len(person_name.strip()) == 0:
+                st.error("Person name is required. Please enter a name to proceed.")
+            else:
+                with st.spinner("Processing image..."):
+                    # Save the uploaded file
+                    success, message, file_path = save_uploaded_file(
+                        uploaded_file, 
+                        settings.UPLOADS_DIR
+                    )
+                    
+                    if not success:
+                        st.error(message)
+                    else:
+                        # Add to history
+                        st.session_state.upload_history.append({
+                            "timestamp": datetime.now().isoformat(),
+                            "file_path": file_path,
+                            "file_name": uploaded_file.name
+                        })
+                        
+                        # Prepare data for processing
+                        process_data = {
+                            "image_path": file_path,
+                            "person_name": person_name.strip(),
+                            "detection_confidence": confidence_threshold,
+                            "use_advanced_emotion": st.session_state.use_advanced_emotion
+                        }
+                        
+                        # STEP 4: Get the appropriate image for processing (original or preprocessed)
+                        if "original_image" in st.session_state:
+                            processing_img = get_processing_image(image_service, st.session_state.original_image)
+                            
+                            # Convert to proper format if needed for agent processing
+                            if "using_preprocessed_image" in st.session_state and st.session_state["using_preprocessed_image"]:
+                                # Make sure we're using the preprocessed image for processing
+                                process_data["use_preprocessed_image"] = True
+                                process_data["preprocessed_image_path"] = st.session_state.get("preprocessed_image_path", "")
+                        
+                        # Process the image
+                        agent_manager = get_agent_manager()
+                        results = agent_manager.process_visual(process_data)
+                        
+                        # Display results
+                        st.subheader("Analysis Results")
+                        
+                        if "error" in results:
+                            st.error(results["error"])
+                        else:
+                            # Display faces detected
+                            st.markdown(f"**Faces Detected:** {results['face_count']}")
+                            
+                            # Save analysis results to the database
+                            try:
+                                # Clean the person name
+                                clean_name = person_name.strip()
+                                
+                                # Save to database with person name as tag
+                                # [April 2025] - Updated tag handling to use person name as the sole tag
+                                # This ensures consistency with the local version and improves filtering
+                                # Previously used generic tags like 'emotion_analysis' and emotion names
+                                db_service = get_database_service()
+                                result_id = db_service.save_analysis_results(
+                                    session_id=st.session_state.session_id,
+                                    image_path=file_path,
+                                    results=results,
+                                    tags=[clean_name]
+                                )
+                                
+                                # Print debugging information
+                                print(f"[DEBUG] Analysis saved with ID: {result_id}")
+                                print(f"[DEBUG] Person tag: {clean_name}")
+                                
+                                st.success(f"Analysis saved to history with tag: {clean_name}")
+                            except Exception as e:
+                                print(f"[DEBUG] Error saving analysis results: {e}")
+                                logger.error(f"Error saving analysis results: {e}")
+                            
+                            if results["face_count"] > 0:
+                                st.markdown("### Detected Faces")
+                                
+                                # Load image for visualization
+                                img_path = os.path.join(settings.STATIC_DIR, os.path.relpath(file_path, start=settings.STATIC_DIR))
+                                img = cv2.imread(file_path)
+                                img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+                                
+                                # Create a clean copy of the image without annotations
+                                clean_img = img.copy()
+                                
+                                # Draw bounding boxes and labels
+                                for i, face in enumerate(results["faces"]):
+                                    x1, y1, x2, y2 = face["bbox"]
+                                    
+                                    # Get emotion and corresponding color
+                                    emotion = face["emotion"]
+                                    confidence = face.get("confidence", 0.55)
+                                    
+                                    # Create color based on emotion - default to green if no matching service
+                                    color = (0, 255, 0)  # Default color (green)
+                                    
+                                    # Draw rectangle with emotion-based color
+                                    cv2.rectangle(img, (x1, y1), (x2, y2), color, 2)
+                                    
+                                    # Draw just the face number in a small font at the top-left corner
+                                    # to minimize overlap issues
+                                    cv2.putText(
+                                        img, 
+                                        f"{i+1}", 
+                                        (x1 + 5, y1 + 15), 
+                                        cv2.FONT_HERSHEY_SIMPLEX, 
+                                        0.5,  # Smaller font
+                                        color, 
+                                        2
+                                    )
+                                
+                                # Display the annotated image
+                                st.image(img, caption="Analysis Results", use_column_width=True)
+                                
+                                # Create tabbed interface for emotion details with clear numbering
+                                face_tabs = [f"1. Face {i+1}" for i in range(len(results["faces"]))]
+                                tabs = st.tabs(face_tabs)
+                                
+                                # Display detailed emotion information for each face
+                                for i, (tab, face) in enumerate(zip(tabs, results["faces"])):
+                                    with tab:
+                                        # Create two columns for layout
+                                        col1, col2 = st.columns([2, 3])
+                                        
+                                        with col1:
+                                            # 1. Display the primary emotion with text representation
+                                            emotion = face["emotion"]
+                                            emotion_name = emotion.capitalize()
+                                            
+                                            # Use text representation instead of emoji to avoid display issues
+                                            emotion_icons = {
+                                                'joy': '(Happy)',
+                                                'sadness': '(Sad)',
+                                                'anger': '(Angry)',
+                                                'fear': '(Afraid)',
+                                                'surprise': '(Surprised)',
+                                                'disgust': '(Disgusted)',
+                                                'neutral': '(Neutral)',
+                                                'unknown': '(Unknown)'
+                                            }
+                                            
+                                            emotion_text = emotion_icons.get(emotion, '')
+                                            st.markdown(f"## {emotion_name} {emotion_text}")
+                                            st.markdown(f"**Confidence:** {face.get('confidence', 0.0):.2f}")
+                                            
+                                            # Show advanced data if available from DeepFace
+                                            if 'age' in face:
+                                                st.markdown(f"**Age Estimate:** {face['age']}")
+                                            if 'gender' in face:
+                                                gender = face['gender']
+                                                # Capitalize first letter
+                                                gender = gender[0].upper() + gender[1:].lower() if len(gender) > 0 else gender
+                                                st.markdown(f"**Gender Estimate:** {gender}")
+                                            
+                                            # Get facial features
+                                            features = face.get("features", {})
+                                            # Fallback to emotion_features if features is not present
+                                            if not features and "emotion_features" in face:
+                                                features = face.get("emotion_features", {})
+                                            
+                                            # Create metrics in a row - clearly labeled
+                                            st.markdown("### 1. Facial Metrics")
+                                            cols = st.columns(3)
+                                            with cols[0]:
+                                                st.metric("Brightness", f"{features.get('brightness', 0):.1f}")
+                                            with cols[1]:
+                                                st.metric("Contrast", f"{features.get('contrast', 0):.1f}")
+                                            with cols[2]:
+                                                st.metric("Symmetry", f"{features.get('symmetry', 0):.1f}")
+                                        
+                                        with col2:
+                                            # 2. Create a bar chart of all emotions
+                                            # Obtener emociones o usar valores predeterminados 
+                                            # Asegurar que todas las emociones estén presentes
+                                            all_emotions = {
+                                                'anger': 0.0,
+                                                'disgust': 0.0, 
+                                                'fear': 0.0,
+                                                'joy': 0.0,
+                                                'neutral': 0.0,
+                                                'sadness': 0.0,
+                                                'surprise': 0.0
+                                            }
+                                            
+                                            # Actualizar con valores detectados
+                                            emotions = face.get('emotions', {'neutral': 1.0})
+                                            for emotion, value in emotions.items():
+                                                if emotion in all_emotions:
+                                                    all_emotions[emotion] = value
+                                            
+                                            # Create a title for the chart section
+                                            st.markdown("### 2. Emotion Confidence")
+                                            
+                                            # Display the bar chart
+                                            import pandas as pd
+                                            emotions_df = pd.DataFrame({
+                                                'Emotion': list(all_emotions.keys()),
+                                                'Confidence': list(all_emotions.values())
+                                            })
+                                            
+                                            # First show the chart
+                                            st.bar_chart(emotions_df.set_index('Emotion'))
+                                            
+                                            # Then show the exact values in a clean format
+                                            values_col1, values_col2, values_col3 = st.columns(3)
+                                            
+                                            # Split the emotion values into 3 columns for better presentation
+                                            emotions_list = list(all_emotions.items())
+                                            chunk_size = (len(emotions_list) + 2) // 3  # Ceiling division
+                                            chunks = [emotions_list[i:i + chunk_size] for i in range(0, len(emotions_list), chunk_size)]
+                                            
+                                            # Add values to each column
+                                            for i, col in enumerate([values_col1, values_col2, values_col3]):
+                                                if i < len(chunks):
+                                                    with col:
+                                                        for emotion, value in chunks[i]:
+                                                            # Format to 2 decimal places
+                                                            st.markdown(f"**{emotion.capitalize()}**: {value:.2f}")
+                                            
+                                            # 3. Display features that contributed to the emotion
+                                            st.markdown("### 3. Analysis Features")
+                                            
+                                            # Explanation text with numbered sequence
+                                            st.markdown("""
+                                            ### 4. How We Determined This Emotion
+                                            
+                                            1. **Face Detection**: We located the face in the image
+                                            2. **Feature Extraction**: We analyzed brightness, contrast, and symmetry
+                                            3. **Emotion Classification**: We matched these features to emotional patterns
+                                            """)
+                                    
+                                    # Display detailed results in expandable section with improved title and description
+                                    with st.expander("Technical Data (For Developers)"):
+                                        st.markdown("""
+                                        This section displays the raw JSON data from the analysis process. 
+                                        It's intended for developers and technical users who need access to the exact values and parameters used in the emotion detection process.
+                                        
+                                        **Uses for this data:**
+                                        - Transparency on how the system works
+                                        - Debugging and development
+                                        - Access to precise numerical values
+                                        - Export for use in other systems or tools
+                                        """)
+                                        st.json(results)
+                                else:
+                                    st.info("No faces were detected in the image. Please try another image.")
+                        except Exception as e:
+                            logger.error(f"Error processing image: {e}")
+                            st.error(f"Error processing image: {str(e)}")
+
+# History page
+elif page == "History":
+    st.header("Analysis History")
+    st.markdown("View your previous analyses and export results.")
+    
+    # Initialize database service
+    db_service = get_database_service()
+    
+    # Create tabs for different views - Using numbered sequence for clear navigation
+    history_tabs = ["1. Recent Analyses", "2. Statistics", "3. Export Data"]
+    tab1, tab2, tab3 = st.tabs(history_tabs)
+    
+    with tab1:
+        st.subheader("Recent Emotion Analyses")
+        
+        # Get available person tags from the database
+        # [April 2025] - Person filtering system synchronized with local version
+        # to show actual person names instead of emotion tags
+        try:
+            all_analyses = db_service.get_history(session_id=st.session_state.session_id, limit=100)
+            person_tags = set()
+            for analysis in all_analyses:
+                if 'tags' in analysis and analysis['tags']:
+                    for tag in analysis['tags']:
+                        person_tags.add(tag)
+            
+            person_tags = sorted(list(person_tags))
+            
+            # Create a filter dropdown if there are person tags
+            selected_person = None
+            if person_tags:
+                filter_options = ["All People"] + person_tags
+                selected_filter = st.selectbox(
+                    "Filter by Person",
+                    options=filter_options,
+                    index=0,
+                    help="Select a person to filter the analysis history"
+                )
+                
+                if selected_filter != "All People":
+                    selected_person = selected_filter
+                    st.info(f"Showing analyses for: **{selected_filter}**")
+        except Exception as e:
+            logger.error(f"Error retrieving tags: {e}")
+            person_tags = []
+            selected_person = None
+        
+        # Get analysis history from database, filtered by person if selected
+        analyses = []
+        try:
+            # Get analyses, filtered by tag if a person is selected
+            if selected_person:
+                # For simplicity, we'll retrieve all analyses and filter them here
+                # In a production app, we'd want to filter in the database query
+                all_analyses = db_service.get_history(session_id=st.session_state.session_id, limit=20)
+                analyses = [a for a in all_analyses if 'tags' in a and a['tags'] and selected_person in a['tags']]
+            else:
+                analyses = db_service.get_history(session_id=st.session_state.session_id, limit=10)
+                
+            print(f"[DEBUG] Found {len(analyses)} analyses to display")
+            for a in analyses:
+                print(f"[DEBUG] Analysis ID: {a.get('id', 'unknown')} Timestamp: {a.get('timestamp', 'unknown')}")
+        except Exception as e:
+            logger.error(f"Error retrieving analyses: {e}")
+            print(f"[DEBUG] Error retrieving analyses: {e}")
+        
+        if analyses:
+            for i, analysis in enumerate(analyses):
+                with st.expander(f"Analysis #{analysis['id']} - {analysis['timestamp'][:16]}", expanded=(i==0)):
+                    # Create columns for layout
+                    col1, col2 = st.columns([1, 2])
+                    
+                    with col1:
+                        # Show image if available and path exists
+                        image_path = analysis['image_path']
+                        if os.path.exists(image_path):
+                            try:
+                                img = Image.open(image_path)
+                                st.image(img, caption=f"Analyzed Image", use_column_width=True)
+                            except Exception as e:
+                                st.error(f"Unable to load image: {str(e)}")
+                        else:
+                            st.warning("Image file no longer available")
+                    
+                    with col2:
+                        # Display analysis details
+                        st.markdown(f"**Date:** {analysis['timestamp'][:19]}")
+                        st.markdown(f"**Faces Detected:** {analysis['face_count']}")
+                        
+                        # Show person name if available
+                        if 'tags' in analysis and analysis['tags']:
+                            st.markdown(f"**Person:** {analysis['tags'][0]}")
+                        
+                        # Check if advanced detection was used
+                        # Comprobar si los resultados ya son un diccionario o una cadena JSON
+                        if isinstance(analysis['results'], dict):
+                            results_dict = analysis['results']
+                        else:
+                            results_dict = json.loads(analysis['results'])
+                        
+                        using_advanced = False
+                        has_advanced_data = False
+                        age_data = None
+                        gender_data = None
+                        
+                        # Check for advanced detection usage and data
+                        if 'faces' in results_dict and len(results_dict['faces']) > 0:
+                            first_face = results_dict['faces'][0]
+                            using_advanced = first_face.get('using_advanced', False)
+                            
+                            # Check for advanced data
+                            if 'age' in first_face:
+                                has_advanced_data = True
+                                age_data = first_face['age']
+                            if 'gender' in first_face:
+                                has_advanced_data = True
+                                gender_data = first_face['gender']
+                        
+                        # Show detection method used
+                        if using_advanced:
+                            st.markdown("**Detection:** <span style='background-color:#4CAF50;color:white;padding:2px 6px;border-radius:3px;font-size:0.7em;'>DeepFace</span>", unsafe_allow_html=True)
+                        
+                        # Show advanced data if available
+                        if has_advanced_data:
+                            st.markdown("### Advanced Data")
+                            if age_data is not None:
+                                st.markdown(f"**Age Estimate:** {age_data}")
+                            if gender_data is not None:
+                                # Capitalize gender
+                                if isinstance(gender_data, str) and len(gender_data) > 0:
+                                    gender_data = gender_data[0].upper() + gender_data[1:].lower() if len(gender_data) > 0 else gender_data
+                                st.markdown(f"**Gender Estimate:** {gender_data}")
+                        
+                        # Show emotion data
+                        if analysis['face_count'] > 0:
+                            st.markdown("### 1. Detected Emotions")
+                        
+                        # Display each face
+                        for j, face in enumerate(results_dict['faces']):
+                            # Get emotion data
+                            emotion = face['emotion'].capitalize()
+                            confidence = face.get('emotion_confidence', face.get('confidence', 0))
+                            
+                            # Show badge for DeepFace if used
+                            if face.get('using_advanced', False):
+                                st.markdown(f"**Face {j+1}:** {emotion} <span style='background-color:#4CAF50;color:white;padding:2px 6px;border-radius:3px;font-size:0.7em;'>DeepFace</span> (Confidence: {confidence:.2f})", unsafe_allow_html=True)
+                            else:
+                                st.markdown(f"**Face {j+1}:** {emotion} (Confidence: {confidence:.2f})")
+                            
+                            # Create emotion dataframe for visualization
+                            if 'emotions' in face:
+                                emotions = face['emotions']
+                                emotion_df = pd.DataFrame({
+                                    'Emotion': [k.capitalize() for k in emotions.keys()],
+                                    'Score': list(emotions.values())
+                                })
+                                emotion_df = emotion_df.sort_values('Score', ascending=False)
+                                
+                                # Display mini chart
+                                st.bar_chart(emotion_df.set_index('Emotion'), height=150)
+                    
+                    # Option to delete analysis
+                    if st.button(f"Delete Analysis #{analysis['id']}", key=f"del_{analysis['id']}"):
+                        if db_service.delete_record(analysis['id']):
+                            st.success("Analysis deleted successfully!")
+                            st.experimental_rerun()
+                        else:
+                            st.error("Failed to delete analysis")
+        else:
+            st.info("No previous analyses found in the database.")
+            
+            # Display session upload history if available
+            if st.session_state.upload_history:
+                st.markdown("### Recent Uploads (Not yet saved to database)")
+                for i, upload in enumerate(st.session_state.upload_history):
+                    st.markdown(f"**{i+1}. {upload['file_name']}**")
+                    st.markdown(f"* Timestamp: {upload['timestamp']}")
+            
+    with tab2:
+        st.subheader("Emotion Analytics")
+        
+        # Add filter by person to statistics view
+        try:
+            all_analyses = db_service.get_history(session_id=st.session_state.session_id, limit=100)
+            person_tags = set()
+            for analysis in all_analyses:
+                if 'tags' in analysis and analysis['tags']:
+                    for tag in analysis['tags']:
+                        person_tags.add(tag)
+            
+            person_tags = sorted(list(person_tags))
+            
+            # Create a filter dropdown if there are person tags
+            selected_person = None
+            if person_tags:
+                filter_options = ["All People"] + person_tags
+                selected_filter = st.selectbox(
+                    "1. Select Person to Analyze",
+                    options=filter_options,
+                    index=0,
+                    help="Select a person to view their emotion statistics"
+                )
+                
+                if selected_filter != "All People":
+                    selected_person = selected_filter
+        except Exception as e:
+            logger.error(f"Error retrieving tags for statistics: {e}")
+            person_tags = []
+            selected_person = None
+        
+        # Get emotion statistics
+        emotion_stats = db_service.get_emotion_stats(session_id=st.session_state.session_id)
+        
+        if emotion_stats:
+            # Display chart of emotion frequencies
+            st.markdown("### 2. Emotion Distribution")
+            
+            # Create dataframe for visualization
+            stats_df = pd.DataFrame({
+                'Emotion': list(emotion_stats.keys()),
+                'Frequency': list(emotion_stats.values())
+            })
+            
+            # Sort by frequency for better visualization
+            stats_df = stats_df.sort_values('Frequency', ascending=False)
+            
+            # Display chart
+            st.bar_chart(stats_df.set_index('Emotion'))
+            
+            # Show numeric values below the chart
+            st.markdown("### 3. Detailed Percentages")
+            
+            # Create columns for better presentation
+            cols = st.columns(3)
+            for i, (emotion, frequency) in enumerate(zip(stats_df['Emotion'], stats_df['Frequency'])):
+                col_idx = i % 3
+                with cols[col_idx]:
+                    st.metric(
+                        emotion.capitalize(),
+                        f"{frequency:.1%}",
+                        delta=None
+                    )
+                    
+            # Add explanation of statistics
+            st.markdown("---")
+            st.markdown("### 4. Understanding These Statistics")
+            st.markdown("""
+            The data above shows the distribution of emotions detected across all analyses:
+            
+            1. **Emotion Distribution** - The bar chart visualizes the relative frequency of each emotion
+            2. **Detailed Percentages** - Exact percentage values for each emotion detected
+            3. **Sample Size** - Based on all faces detected in the selected analyses
+            """)
+        else:
+            st.info("No emotion data available for analysis yet.")
+            
+    with tab3:
+        st.subheader("Export Analysis Data")
+        
+        # Add filter by person for export
+        selected_person_tag = None
+        try:
+            all_analyses = db_service.get_history(session_id=st.session_state.session_id, limit=100)
+            person_tags = set()
+            for analysis in all_analyses:
+                if 'tags' in analysis and analysis['tags']:
+                    for tag in analysis['tags']:
+                        person_tags.add(tag)
+            
+            person_tags = sorted(list(person_tags))
+            
+            # Create a person filter dropdown if person tags exist
+            if person_tags:
+                person_options = ["All People"] + person_tags
+                person_filter = st.selectbox(
+                    "1. Select Person to Export",
+                    options=person_options,
+                    index=0,
+                    help="Filter export data to include only analyses for a specific person"
+                )
+                
+                if person_filter != "All People":
+                    selected_person_tag = person_filter
+                    st.info(f"Export will only include analyses for: {selected_person_tag}")
+        except Exception as e:
+            logger.error(f"Error retrieving person tags for export: {e}")
+        
+        # Options for export format
+        export_type = st.radio(
+            "2. Select Export Format",
+            ["JSON", "CSV"],
+            horizontal=True
+        )
+        
+        export_scope = st.radio(
+            "3. Select Data Scope",
+            ["Current Session", "All Sessions"],
+            horizontal=True
+        )
+        
+        session_id = st.session_state.session_id if export_scope == "Current Session" else None
+        
+        # Option to limit number of records
+        record_limit = st.slider(
+            "4. Maximum Records to Export",
+            min_value=1,
+            max_value=100,
+            value=20,
+            step=1
+        )
+        
+        # Generate export button
+        if st.button("Generate Export"):
+            with st.spinner("Preparing export..."):
+                # Get export data
+                export_data = db_service.export_data(
+                    session_id=session_id,
+                    limit=record_limit
+                )
+                
+                # Filter data by person if selected
+                if selected_person_tag and 'analyses' in export_data:
+                    filtered_analyses = []
+                    for analysis in export_data['analyses']:
+                        if 'tags' in analysis and analysis['tags'] and selected_person_tag in analysis['tags']:
+                            filtered_analyses.append(analysis)
+                    
+                    export_data['analyses'] = filtered_analyses
+                    export_data['metadata']['record_count'] = len(filtered_analyses)
+                    export_data['metadata']['person_filter'] = selected_person_tag
+                
+                if not export_data or not export_data.get('analyses'):
+                    st.warning("No data available to export")
+                else:
+                    st.success(f"Export generated with {len(export_data.get('analyses', []))} analyses")
+                    
+                    # Create download options based on export type
+                    if export_type == "JSON":
+                        json_str = export_to_json(export_data)
+                        filename = f"emotion_analysis_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
+                        
+                        # Create download button
+                        st.download_button(
+                            label="Download JSON",
+                            data=json_str,
+                            file_name=filename,
+                            mime="application/json"
+                        )
+                    else:  # CSV
+                        csv_str = export_to_csv(export_data)
+                        filename = f"emotion_analysis_{datetime.now().strftime('%Y%m%d_%H%M%S')}.csv"
+                        
+                        # Create download button
+                        st.download_button(
+                            label="Download CSV",
+                            data=csv_str,
+                            file_name=filename,
+                            mime="text/csv"
+                        )
+                    
+                    # Show summary statistics
+                    summary = generate_emotion_summary(export_data)
+                    
+                    st.markdown("### Export Summary")
+                    st.markdown(f"**Total Analyses:** {summary['total_analyses']}")
+                    st.markdown(f"**Total Faces Analyzed:** {summary['total_faces']}")
+                    
+                    if summary['total_faces'] > 0:
+                        # Display emotion distribution
+                        st.markdown("**Emotion Distribution:**")
+                        
+                        # Create dataframe for visualization
+                        emotions_df = pd.DataFrame({
+                            'Emotion': list(summary['emotion_percentages'].keys()),
+                            'Percentage': list(summary['emotion_percentages'].values())
+                        })
+                        
+                        # Sort by percentage
+                        emotions_df = emotions_df.sort_values('Percentage', ascending=False)
+                        
+                        # Display chart
+                        st.bar_chart(emotions_df.set_index('Emotion'))
+                        
+                        # Add explanation of export formats below visualization
+                        st.markdown("---")
+                        st.markdown("### 5. About Export Formats")
+                        st.markdown("""
+                        The exported data includes analysis details in your chosen format:
+                        
+                        1. **JSON Format** - Complete data structure with all details, ideal for further processing
+                        2. **CSV Format** - Tabular data format, can be opened in spreadsheet software
+                        3. **Data Contents** - Each export includes timestamps, emotion labels, confidence values, and facial features
+                        4. **Person Information** - If you specified a person name, it's included with each analysis
+                        """)
+
+# About page
+elif page == "About":
+    st.header("About EmotionMirror")
+    
+    st.markdown("""
+        ## EmotionMirror: Emotional Analysis System
+        
+        EmotionMirror is an application that uses computer vision and artificial intelligence
+        to analyze emotions from facial expressions and body language.
+        
+        ### Technology Stack
+        
+        * **Streamlit**: For the user interface
+        * **YOLOv8**: For object detection, pose estimation, and facial analysis
+        * **Agent Framework**: A custom multi-agent system for coordinated analysis
+        
+        ### Future Features
+        
+        * Enhanced emotion recognition with Hume.ai integration
+        * Temporal emotion tracking and pattern analysis
+        * Personalized recommendations based on emotional states
+        * Guided emotional wellness sessions
+        
+        ### Privacy
+        
+        * All image processing is done locally
+        * We don't store your images after processing
+        * No personal data is shared with third parties
+    """)
+
+# Footer
+st.markdown("---")
+st.markdown(" EmotionMirror | Developed as a prototype application")

config/__init__.py

@@ -0,0 +1,3 @@
+"""
+Configuration package for EmotionMirror application.
+"""

config/settings.py

@@ -0,0 +1,102 @@
+"""
+Settings module for EmotionMirror application.
+Contains configuration parameters and environment settings.
+"""
+import os
+import secrets
+
+# Base directory
+BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+# Determine if running in Hugging Face environment
+HF_SPACE = os.environ.get('HF_SPACE', '') == 'true'
+
+# Debug mode
+DEBUG = os.environ.get('DEBUG', 'false').lower() == 'true'
+
+# Secret key for secure operations
+SECRET_KEY = os.environ.get('SECRET_KEY', secrets.token_hex(16))
+
+# Folder paths
+STATIC_DIR = os.path.join(BASE_DIR, 'static')
+MODELS_DIR = os.path.join(BASE_DIR, 'models')
+UPLOADS_DIR = os.path.join(STATIC_DIR, 'uploads')
+RESULTS_DIR = os.path.join(STATIC_DIR, 'results')
+TEMP_DIR = os.path.join(BASE_DIR, 'temp')  # Directorio temporal para DeepFace
+
+# Ensure directories exist
+os.makedirs(UPLOADS_DIR, exist_ok=True)
+os.makedirs(RESULTS_DIR, exist_ok=True)
+os.makedirs(MODELS_DIR, exist_ok=True)
+os.makedirs(TEMP_DIR, exist_ok=True)  # Crear directorio temporal
+
+# File extensions
+ALLOWED_EXTENSIONS = {'png', 'jpg', 'jpeg', 'gif', 'mp4', 'avi'}
+
+# Model configuration
+MODEL_MAPPING = {
+    'detection': 'yolov8n.pt',
+    'segmentation': 'yolov8n-seg.pt',
+    'pose': 'yolov8n-pose.pt',
+    'classification': 'yolov8n-cls.pt'
+}
+
+# Database configuration
+"""
+IMPORTANT NOTE ABOUT DIFFERENCES BETWEEN LOCAL AND HUGGING FACE VERSIONS:
+-----------------------------------------------------------------------
+In the local version, the database is stored in the 'database' directory
+inside the project.
+
+In Hugging Face (HF_SPACE=true), due to write permission restrictions,
+additional logic is implemented:
+1. First attempts to write to the project's 'database' directory
+2. If this fails (due to permission restrictions), uses an alternative location
+   at '/tmp/emotion_data.db' which normally has write permissions
+3. Detailed messages are logged to facilitate debugging
+
+This difference is necessary to ensure that the analysis saving functionality
+works correctly in the restricted Hugging Face environment.
+"""
+if HF_SPACE:
+    # Usar un directorio específico para la base de datos en Hugging Face
+    # que tenga más probabilidades de tener permisos de escritura
+    DB_DIR = os.path.join(BASE_DIR, 'database')
+    os.makedirs(DB_DIR, exist_ok=True)
+    DB_PATH = os.path.join(DB_DIR, 'emotion_data.db')
+    print(f"Hugging Face DB Path: {DB_PATH}")
+    # Intentar crear un archivo de prueba para verificar permisos
+    try:
+        test_file = os.path.join(DB_DIR, 'test_write.txt')
+        with open(test_file, 'w') as f:
+            f.write('test')
+        os.remove(test_file)
+        print(f"Successfully wrote to {DB_DIR}, permissions OK")
+    except Exception as e:
+        print(f"Warning: Could not write to {DB_DIR}: {e}")
+        # Intentar alternativa en el directorio /tmp que suele tener permisos
+        DB_PATH = '/tmp/emotion_data.db'
+        print(f"Using alternative DB path: {DB_PATH}")
+else:
+    # Use database directory for local development
+    DB_DIR = os.path.join(BASE_DIR, 'database')
+    os.makedirs(DB_DIR, exist_ok=True)
+    DB_PATH = os.path.join(DB_DIR, 'emotions.db')
+
+# Hume.ai API configuration
+HUME_API_KEY = os.environ.get('HUME_API_KEY', '')
+HUME_API_ENABLED = bool(HUME_API_KEY)
+
+# DeepFace configuration
+USE_ADVANCED_EMOTION = os.environ.get('USE_ADVANCED_EMOTION', 'true').lower() == 'true'
+
+# Emotion categories
+EMOTIONS = ['joy', 'sadness', 'anger', 'fear', 'surprise', 'disgust', 'neutral']
+
+# DeepFace model settings
+DEEPFACE_SETTINGS = {
+    'detector_backend': 'retinaface',  # Options: opencv, ssd, mtcnn, retinaface, mediapipe
+    'emotion_model': 'fer',           # Options: fer (default), resmob
+    'enforce_detection': False,       # Don't fail if face detection fails
+    'actions': ['emotion', 'age', 'gender']
+}

database/__init__.py

@@ -0,0 +1,6 @@
+"""
+Database module for EmotionMirror application.
+
+This module contains database-related components for storing and retrieving
+emotion analysis history.
+"""

database/db_manager.py

@@ -0,0 +1,463 @@
+"""
+Database Manager for EmotionMirror Application
+
+This module provides functionality for database operations, including:
+- Creating and initializing the SQLite database
+- Storing analysis results
+- Retrieving historical data
+- Managing database connections
+
+All database operations are encapsulated in this module to ensure clean separation
+of concerns and modularity.
+"""
+
+import os
+import json
+import sqlite3
+import logging
+from datetime import datetime
+from typing import Dict, List, Any, Optional, Tuple
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+class DatabaseManager:
+    """
+    Manages database operations for the EmotionMirror application.
+    
+    This class handles all interactions with the SQLite database, providing
+    a clean interface for the rest of the application to store and retrieve data.
+    """
+    
+    def __init__(self, db_path: str):
+        """
+        Initialize the database manager.
+        
+        Args:
+            db_path: Path to the SQLite database file
+        """
+        self.db_path = db_path
+        self._initialize_db()
+    
+    def _initialize_db(self) -> None:
+        """
+        Initialize the database by creating necessary tables if they don't exist.
+        """
+        os.makedirs(os.path.dirname(self.db_path), exist_ok=True)
+        
+        conn = None
+        try:
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+            
+            # Create analyses table
+            cursor.execute('''
+            CREATE TABLE IF NOT EXISTS analyses (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                session_id TEXT NOT NULL,
+                timestamp TEXT NOT NULL,
+                image_path TEXT NOT NULL,
+                face_count INTEGER NOT NULL,
+                results TEXT NOT NULL,
+                tags TEXT
+            )
+            ''')
+            
+            # Create faces table
+            cursor.execute('''
+            CREATE TABLE IF NOT EXISTS faces (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                analysis_id INTEGER NOT NULL,
+                face_index INTEGER NOT NULL,
+                emotion TEXT NOT NULL,
+                confidence REAL NOT NULL,
+                features TEXT NOT NULL,
+                emotions TEXT NOT NULL,
+                FOREIGN KEY (analysis_id) REFERENCES analyses (id)
+            )
+            ''')
+            
+            conn.commit()
+            logger.info("Database initialized successfully")
+        except sqlite3.Error as e:
+            logger.error(f"Database initialization error: {e}")
+        finally:
+            if conn:
+                conn.close()
+    
+    def save_analysis(self, 
+                     session_id: str, 
+                     image_path: str, 
+                     results: Dict[str, Any],
+                     tags: Optional[List[str]] = None) -> int:
+        """
+        Save analysis results to the database.
+        
+        Args:
+            session_id: Current session identifier
+            image_path: Path to the analyzed image
+            results: Analysis results dictionary
+            tags: Optional list of tags for the analysis
+            
+        Returns:
+            The ID of the newly inserted analysis record
+        """
+        conn = None
+        try:
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+            
+            # Convert tags list to JSON string if provided
+            tags_json = json.dumps(tags) if tags else None
+            
+            # Insert analysis record
+            cursor.execute(
+                '''
+                INSERT INTO analyses 
+                (session_id, timestamp, image_path, face_count, results, tags)
+                VALUES (?, ?, ?, ?, ?, ?)
+                ''',
+                (
+                    session_id,
+                    datetime.now().isoformat(),
+                    image_path,
+                    results.get('face_count', 0),
+                    json.dumps(results),
+                    tags_json
+                )
+            )
+            
+            analysis_id = cursor.lastrowid
+            
+            # Insert face records if present
+            faces = results.get('faces', [])
+            for i, face in enumerate(faces):
+                cursor.execute(
+                    '''
+                    INSERT INTO faces
+                    (analysis_id, face_index, emotion, confidence, features, emotions)
+                    VALUES (?, ?, ?, ?, ?, ?)
+                    ''',
+                    (
+                        analysis_id,
+                        i,
+                        face.get('emotion', 'unknown'),
+                        face.get('confidence', 0.0),
+                        json.dumps(face.get('features', {})),
+                        json.dumps(face.get('emotions', {}))
+                    )
+                )
+            
+            conn.commit()
+            logger.info(f"Saved analysis with ID {analysis_id} and {len(faces)} faces")
+            return analysis_id
+            
+        except sqlite3.Error as e:
+            logger.error(f"Error saving analysis: {e}")
+            if conn:
+                conn.rollback()
+            return -1
+        finally:
+            if conn:
+                conn.close()
+    
+    def get_analysis_history(self, 
+                           session_id: Optional[str] = None, 
+                           limit: int = 10) -> List[Dict[str, Any]]:
+        """
+        Retrieve analysis history from the database.
+        
+        Args:
+            session_id: Optional session ID to filter by
+            limit: Maximum number of records to return
+            
+        Returns:
+            List of analysis records as dictionaries
+        """
+        conn = None
+        try:
+            conn = sqlite3.connect(self.db_path)
+            conn.row_factory = sqlite3.Row  # This enables name-based access to columns
+            cursor = conn.cursor()
+            
+            query = '''
+            SELECT 
+                id, 
+                session_id, 
+                timestamp, 
+                image_path, 
+                face_count, 
+                results,
+                tags
+            FROM analyses
+            '''
+            
+            params = []
+            if session_id:
+                query += ' WHERE session_id = ?'
+                params.append(session_id)
+                
+            query += '''
+            ORDER BY timestamp DESC
+            LIMIT ?
+            '''
+            params.append(limit)
+            
+            cursor.execute(query, params)
+            
+            # Convert row objects to dictionaries
+            analyses = []
+            for row in cursor.fetchall():
+                analysis = dict(row)
+                
+                # Parse JSON fields
+                analysis['results'] = json.loads(analysis['results'])
+                if analysis['tags']:
+                    analysis['tags'] = json.loads(analysis['tags'])
+                
+                # Get faces for this analysis
+                face_cursor = conn.cursor()
+                face_cursor.execute(
+                    '''
+                    SELECT 
+                        id,
+                        face_index,
+                        emotion,
+                        confidence,
+                        features,
+                        emotions
+                    FROM faces
+                    WHERE analysis_id = ?
+                    ORDER BY face_index
+                    ''',
+                    (analysis['id'],)
+                )
+                
+                faces = []
+                for face_row in face_cursor.fetchall():
+                    face = dict(face_row)
+                    
+                    # Parse JSON fields
+                    face['features'] = json.loads(face['features'])
+                    face['emotions'] = json.loads(face['emotions'])
+                    
+                    faces.append(face)
+                
+                analysis['faces'] = faces
+                analyses.append(analysis)
+                
+            return analyses
+            
+        except sqlite3.Error as e:
+            logger.error(f"Error retrieving analysis history: {e}")
+            return []
+        finally:
+            if conn:
+                conn.close()
+    
+    def get_analysis_by_id(self, analysis_id: int) -> Optional[Dict[str, Any]]:
+        """
+        Retrieve a specific analysis by ID.
+        
+        Args:
+            analysis_id: ID of the analysis to retrieve
+            
+        Returns:
+            Analysis record as a dictionary, or None if not found
+        """
+        conn = None
+        try:
+            conn = sqlite3.connect(self.db_path)
+            conn.row_factory = sqlite3.Row
+            cursor = conn.cursor()
+            
+            cursor.execute(
+                '''
+                SELECT 
+                    id, 
+                    session_id, 
+                    timestamp, 
+                    image_path, 
+                    face_count, 
+                    results,
+                    tags
+                FROM analyses
+                WHERE id = ?
+                ''',
+                (analysis_id,)
+            )
+            
+            row = cursor.fetchone()
+            if not row:
+                return None
+                
+            analysis = dict(row)
+            
+            # Parse JSON fields
+            analysis['results'] = json.loads(analysis['results'])
+            if analysis['tags']:
+                analysis['tags'] = json.loads(analysis['tags'])
+            
+            # Get faces for this analysis
+            face_cursor = conn.cursor()
+            face_cursor.execute(
+                '''
+                SELECT 
+                    id,
+                    face_index,
+                    emotion,
+                    confidence,
+                    features,
+                    emotions
+                FROM faces
+                WHERE analysis_id = ?
+                ORDER BY face_index
+                ''',
+                (analysis_id,)
+            )
+            
+            faces = []
+            for face_row in face_cursor.fetchall():
+                face = dict(face_row)
+                
+                # Parse JSON fields
+                face['features'] = json.loads(face['features'])
+                face['emotions'] = json.loads(face['emotions'])
+                
+                faces.append(face)
+            
+            analysis['faces'] = faces
+            return analysis
+            
+        except sqlite3.Error as e:
+            logger.error(f"Error retrieving analysis by ID: {e}")
+            return None
+        finally:
+            if conn:
+                conn.close()
+    
+    def get_emotion_statistics(self, 
+                             session_id: Optional[str] = None, 
+                             limit: int = 50) -> Dict[str, float]:
+        """
+        Compute emotion statistics across multiple analyses.
+        
+        Args:
+            session_id: Optional session ID to filter by
+            limit: Maximum number of records to analyze
+            
+        Returns:
+            Dictionary of emotion frequencies
+        """
+        conn = None
+        try:
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+            
+            query = '''
+            SELECT emotion, COUNT(*) as count
+            FROM faces
+            '''
+            
+            params = []
+            if session_id:
+                query += '''
+                JOIN analyses ON faces.analysis_id = analyses.id
+                WHERE analyses.session_id = ?
+                '''
+                params.append(session_id)
+            
+            query += '''
+            GROUP BY emotion
+            ORDER BY count DESC
+            '''
+            
+            cursor.execute(query, params)
+            rows = cursor.fetchall()
+            
+            # Calculate emotion frequencies
+            total = sum(count for _, count in rows)
+            stats = {emotion: count / total for emotion, count in rows} if total > 0 else {}
+            
+            return stats
+            
+        except sqlite3.Error as e:
+            logger.error(f"Error computing emotion statistics: {e}")
+            return {}
+        finally:
+            if conn:
+                conn.close()
+                
+    def delete_analysis(self, analysis_id: int) -> bool:
+        """
+        Delete an analysis and its associated faces.
+        
+        Args:
+            analysis_id: ID of the analysis to delete
+            
+        Returns:
+            True if deletion was successful, False otherwise
+        """
+        conn = None
+        try:
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+            
+            # Delete associated faces first (due to foreign key constraint)
+            cursor.execute('DELETE FROM faces WHERE analysis_id = ?', (analysis_id,))
+            
+            # Delete the analysis
+            cursor.execute('DELETE FROM analyses WHERE id = ?', (analysis_id,))
+            
+            conn.commit()
+            return cursor.rowcount > 0
+            
+        except sqlite3.Error as e:
+            logger.error(f"Error deleting analysis: {e}")
+            if conn:
+                conn.rollback()
+            return False
+        finally:
+            if conn:
+                conn.close()
+    
+    def export_analysis_data(self, 
+                           analysis_id: Optional[int] = None, 
+                           session_id: Optional[str] = None,
+                           limit: int = 100) -> Dict[str, Any]:
+        """
+        Export analysis data in a structured format suitable for JSON/CSV export.
+        
+        Args:
+            analysis_id: Optional specific analysis ID to export
+            session_id: Optional session ID to filter by
+            limit: Maximum number of records to export
+            
+        Returns:
+            Dictionary containing the exported data
+        """
+        if analysis_id:
+            # Export a single analysis
+            analysis = self.get_analysis_by_id(analysis_id)
+            if not analysis:
+                return {'error': f'Analysis with ID {analysis_id} not found'}
+            
+            return {
+                'metadata': {
+                    'exported_at': datetime.now().isoformat(),
+                    'record_count': 1
+                },
+                'analyses': [analysis]
+            }
+        else:
+            # Export multiple analyses
+            analyses = self.get_analysis_history(session_id, limit)
+            
+            return {
+                'metadata': {
+                    'exported_at': datetime.now().isoformat(),
+                    'record_count': len(analyses),
+                    'session_id': session_id
+                },
+                'analyses': analyses
+            }

download_haarcascade.py

@@ -0,0 +1,49 @@
+import os
+import cv2
+import urllib.request
+import logging
+
+# Configurar logging
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+
+# Directorio donde guardar los archivos
+models_dir = "models"
+os.makedirs(models_dir, exist_ok=True)
+
+# URL del archivo haarcascade_smile.xml de OpenCV
+smile_cascade_url = "https://raw.githubusercontent.com/opencv/opencv/master/data/haarcascades/haarcascade_smile.xml"
+smile_cascade_path = os.path.join(models_dir, "haarcascade_smile.xml")
+
+# Descargar el archivo
+logging.info(f"Descargando {smile_cascade_url} a {smile_cascade_path}")
+try:
+    urllib.request.urlretrieve(smile_cascade_url, smile_cascade_path)
+    logging.info(f"Archivo descargado correctamente")
+except Exception as e:
+    logging.error(f"Error al descargar el archivo: {e}")
+
+# Verificar que el archivo existe
+if os.path.exists(smile_cascade_path):
+    logging.info(f"El archivo {smile_cascade_path} existe y tiene {os.path.getsize(smile_cascade_path)} bytes")
+else:
+    logging.error(f"El archivo {smile_cascade_path} no existe")
+
+# Verificar instalación de DeepFace
+try:
+    from deepface import DeepFace
+    logging.info("DeepFace está instalado correctamente")
+    
+    # Mostrar versión
+    import deepface
+    logging.info(f"Versión de DeepFace: {deepface.__version__}")
+    
+    # Mostrar backends disponibles
+    backends = DeepFace.detector_backends()
+    logging.info(f"Backends de detección disponibles: {backends}")
+    
+except ImportError:
+    logging.error("DeepFace no está instalado")
+except Exception as e:
+    logging.error(f"Error al importar DeepFace: {e}")
+
+logging.info("Verificación completada")

finalproject/Dockerfile

@@ -0,0 +1,36 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# Instalar dependencias esenciales del sistema para OpenCV
+RUN apt-get update && apt-get install -y \
+    libgl1-mesa-glx \
+    libglib2.0-0 \
+    libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Configurar variables de entorno para Matplotlib y Ultralytics
+ENV MPLCONFIGDIR=/tmp/matplotlib
+ENV YOLO_CONFIG_DIR=/tmp/ultralytics
+
+# Crear directorios necesarios
+RUN mkdir -p /app/static /app/models /app/database
+
+# Copiar requirements.txt primero para aprovechar caché de Docker
+COPY requirements.txt .
+
+# Instalar dependencias
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copiar el resto de archivos
+COPY . .
+
+# Crear directorios necesarios para la aplicación
+RUN mkdir -p /app/static/uploads /app/static/images /app/database \
+    && chmod -R 777 /app /tmp
+
+# Exponer el puerto que utiliza Streamlit por defecto
+EXPOSE 8501
+
+# Comando para ejecutar la aplicación
+CMD ["streamlit", "run", "app.py", "--server.headless", "true", "--server.port=8501", "--server.address=0.0.0.0"]

finalproject/app.py

@@ -0,0 +1,236 @@
+"""
+EmotionMirror - Emotional Analysis Application
+
+A Streamlit application for analyzing emotions using computer vision.
+"""
+import os
+import time
+import uuid
+import logging
+import streamlit as st
+from datetime import datetime
+from PIL import Image
+import numpy as np
+import cv2
+
+# Import app modules
+from config import settings
+from agent_framework.agent_manager import AgentManager
+from utils.file_utils import allowed_file, save_uploaded_file
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# Page configuration
+st.set_page_config(
+    page_title="EmotionMirror",
+    page_icon="📊",
+    layout="wide",
+    initial_sidebar_state="expanded"
+)
+
+# Initialize agent manager
+@st.cache_resource
+def get_agent_manager():
+    """Get or create the agent manager singleton"""
+    return AgentManager()
+
+# Session state initialization
+if "session_id" not in st.session_state:
+    st.session_state.session_id = str(uuid.uuid4())
+    logger.info(f"New session started: {st.session_state.session_id}")
+
+if "upload_history" not in st.session_state:
+    st.session_state.upload_history = []
+
+# App title and description
+st.title("EmotionMirror")
+st.markdown("""
+    Welcome to EmotionMirror, an application for analyzing emotions using computer vision.
+    
+    This is a prototype version that demonstrates the basic functionality.
+""")
+
+# Sidebar
+with st.sidebar:
+    st.header("Navigation")
+    page = st.selectbox(
+        "Choose a page",
+        ["Home", "Visual Analysis", "About"]
+    )
+    
+    st.header("Configuration")
+    model_confidence = st.slider(
+        "Detection Confidence",
+        min_value=0.05,
+        max_value=0.95,
+        value=0.25,
+        step=0.05,
+        help="Adjust the confidence threshold for detections"
+    )
+    
+    st.divider()
+    st.caption(f"Session ID: {st.session_state.session_id}")
+    st.caption(f"Version: 0.1.0 (Phase 1)")
+
+# Home page
+if page == "Home":
+    st.header("EmotionMirror - Emotional Analysis System")
+    
+    st.subheader("Features")
+    col1, col2, col3 = st.columns(3)
+    
+    with col1:
+        st.markdown("### 📷 Visual Analysis")
+        st.markdown("Upload images to analyze facial expressions and emotions.")
+    
+    with col2:
+        st.markdown("### 📊 Emotion Tracking")
+        st.markdown("Track emotions over time with detailed analytics. (Coming soon)")
+    
+    with col3:
+        st.markdown("### 🧠 AI Recommendations")
+        st.markdown("Get personalized recommendations based on your emotional state. (Coming soon)")
+    
+    st.subheader("Getting Started")
+    st.markdown("""
+        1. Navigate to the **Visual Analysis** page
+        2. Upload an image containing faces
+        3. View the analysis results
+    """)
+
+# Visual Analysis page
+elif page == "Visual Analysis":
+    st.header("Visual Analysis")
+    st.markdown("Upload an image to analyze facial expressions and emotions.")
+    
+    # File uploader
+    uploaded_file = st.file_uploader(
+        "Choose an image file",
+        type=["jpg", "jpeg", "png"],
+        help="Upload an image file to analyze"
+    )
+    
+    if uploaded_file is not None:
+        # Check if file is valid
+        if not allowed_file(uploaded_file.name, settings.ALLOWED_EXTENSIONS):
+            st.error(f"Invalid file type. Allowed types: {', '.join(settings.ALLOWED_EXTENSIONS)}")
+        else:
+            # Display the uploaded image
+            st.subheader("Uploaded Image")
+            image = Image.open(uploaded_file)
+            st.image(image, caption="Uploaded Image", use_column_width=True)
+            
+            # Process button
+            if st.button("Analyze Image"):
+                with st.spinner("Processing image..."):
+                    # Save the uploaded file
+                    success, message, file_path = save_uploaded_file(
+                        uploaded_file, 
+                        settings.UPLOADS_DIR
+                    )
+                    
+                    if not success:
+                        st.error(message)
+                    else:
+                        # Add to history
+                        st.session_state.upload_history.append({
+                            "timestamp": datetime.now().isoformat(),
+                            "file_path": file_path,
+                            "file_name": uploaded_file.name
+                        })
+                        
+                        # Process with visual agent
+                        try:
+                            agent_manager = get_agent_manager()
+                            
+                            # Prepare data for processing
+                            process_data = {
+                                "image_path": file_path,
+                                "confidence": model_confidence,
+                                "timestamp": datetime.now().isoformat()
+                            }
+                            
+                            # Process the image
+                            results = agent_manager.process_visual(process_data)
+                            
+                            # Display results
+                            st.subheader("Analysis Results")
+                            
+                            if "error" in results:
+                                st.error(results["error"])
+                            else:
+                                # Display faces detected
+                                st.markdown(f"**Faces Detected:** {results['face_count']}")
+                                
+                                # Show each face
+                                if results["face_count"] > 0:
+                                    st.markdown("### Detected Faces")
+                                    
+                                    # Load image for visualization
+                                    img = cv2.imread(file_path)
+                                    img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+                                    
+                                    # Draw bounding boxes and labels
+                                    for i, face in enumerate(results["faces"]):
+                                        x1, y1, x2, y2 = face["bbox"]
+                                        cv2.rectangle(img, (x1, y1), (x2, y2), (0, 255, 0), 2)
+                                        cv2.putText(
+                                            img, 
+                                            f"Face {i+1}: {face['emotion']}", 
+                                            (x1, y1-10), 
+                                            cv2.FONT_HERSHEY_SIMPLEX, 
+                                            0.8, 
+                                            (0, 255, 0), 
+                                            2
+                                        )
+                                    
+                                    # Display the annotated image
+                                    st.image(img, caption="Analysis Results", use_column_width=True)
+                                    
+                                    # Display detailed results
+                                    with st.expander("View Detailed Results"):
+                                        st.json(results)
+                                else:
+                                    st.info("No faces were detected in the image. Please try another image.")
+                        except Exception as e:
+                            logger.error(f"Error processing image: {e}")
+                            st.error(f"Error processing image: {str(e)}")
+
+# About page
+elif page == "About":
+    st.header("About EmotionMirror")
+    
+    st.markdown("""
+        ## EmotionMirror: Emotional Analysis System
+        
+        EmotionMirror is an application that uses computer vision and artificial intelligence
+        to analyze emotions from facial expressions and body language.
+        
+        ### Technology Stack
+        
+        * **Streamlit**: For the user interface
+        * **YOLOv8**: For object detection, pose estimation, and facial analysis
+        * **Agent Framework**: A custom multi-agent system for coordinated analysis
+        
+        ### Future Features
+        
+        * Enhanced emotion recognition with Hume.ai integration
+        * Temporal emotion tracking and pattern analysis
+        * Personalized recommendations based on emotional states
+        * Guided emotional wellness sessions
+        
+        ### Privacy
+        
+        * All image processing is done locally
+        * We don't store your images after processing
+        * No personal data is shared with third parties
+    """)
+
+# Footer
+st.markdown("---")
+st.markdown("© 2025 EmotionMirror | Developed as a prototype application")

finalproject/packages.txt

@@ -0,0 +1,7 @@
+libgl1-mesa-glx
+libglib2.0-0
+libgomp1
+libsm6
+libxext6
+libxrender-dev
+libpython3-dev

finalproject/requirements.txt

@@ -0,0 +1,9 @@
+streamlit==1.26.0
+ultralytics==8.0.196
+Pillow==9.5.0
+numpy==1.24.3
+opencv-python==4.8.0.76
+torch==2.0.1
+torchvision==0.15.2
+requests==2.31.0
+python-dotenv==1.0.0

packages.txt

@@ -0,0 +1,7 @@
+libgl1-mesa-glx
+libglib2.0-0
+libgomp1
+libsm6
+libxext6
+libxrender-dev
+libpython3-dev

requirements.txt

@@ -0,0 +1,15 @@
+streamlit==1.26.0
+ultralytics==8.0.196
+Pillow==9.5.0
+numpy==1.23.5
+opencv-python==4.6.0.66
+torch==2.0.1
+torchvision==0.15.2
+requests==2.31.0
+python-dotenv==1.0.0
+scikit-learn==1.3.2
+pandas==2.1.0
+deepface==0.0.75
+protobuf==3.20.3
+tensorflow==2.8.0
+dlib-bin==19.24.6

services/__init__.py

@@ -0,0 +1,37 @@
+"""
+Services package for EmotionMirror application.
+Contains modular services for image processing, model management and emotion analysis.
+"""
+import logging
+
+from config import settings
+from services.emotion_service import EmotionService
+
+# Import DeepFaceEmotionService conditionally to avoid errors if deepface isn't installed
+try:
+    from services.deepface_emotion_service import DeepFaceEmotionService, DEEPFACE_AVAILABLE
+except ImportError:
+    logging.warning("DeepFaceEmotionService could not be imported. Advanced emotion detection will be unavailable.")
+    DeepFaceEmotionService = None
+    DEEPFACE_AVAILABLE = False
+
+def get_emotion_service():
+    """
+    Factory function that returns the appropriate emotion service based on configuration.
+    
+    Returns:
+        EmotionService: The configured emotion service (basic or advanced)
+    """
+    # Choose between basic and advanced emotion service based on configuration
+    if settings.USE_ADVANCED_EMOTION and DEEPFACE_AVAILABLE and DeepFaceEmotionService is not None:
+        try:
+            # Simplemente intentamos crear el servicio avanzado
+            logging.info("Using advanced emotion detection with DeepFace")
+            return DeepFaceEmotionService()
+        except Exception as e:
+            logging.error(f"Error initializing DeepFaceEmotionService: {e}")
+            logging.warning("Falling back to basic emotion service")
+    
+    # Fall back to basic emotion service
+    logging.info("Using basic emotion service")
+    return EmotionService()

services/database_service.py

@@ -0,0 +1,397 @@
+"""
+Database Service for EmotionMirror Application
+
+This service provides a high-level interface for database operations,
+integrating the database manager with the rest of the application.
+"""
+
+import os
+import json
+import logging
+import streamlit as st
+from typing import Dict, List, Any, Optional, Tuple
+from datetime import datetime
+
+from config import settings
+from database.db_manager import DatabaseManager
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+class DatabaseService:
+    """
+    Service for handling database operations in the EmotionMirror application.
+    
+    This class integrates the database functionality with the rest of the
+    application, providing a service-oriented interface.
+    
+    IMPORTANT NOTE ABOUT DIFFERENCES BETWEEN LOCAL AND HUGGING FACE VERSIONS:
+    -----------------------------------------------------------------------
+    In environments with permission restrictions such as Hugging Face, this class
+    implements additional logic to handle write errors:
+    
+    1. Verifies that the database directory has write permissions
+    2. Attempts to write a test file to confirm permissions
+    3. If it fails, uses an alternative location (/tmp/emotion_mirror.db)
+    4. Logs detailed debugging information
+    
+    This behavior is different from the local version, where it is assumed
+    that there are no write permission restrictions.
+    
+    HISTORY FUNCTIONALITY DIFFERENCES:
+    --------------------------------
+    The history retrieval system also differs between versions:
+    
+    Local Version:
+    - Uses standard DatabaseManager method for data retrieval
+    - Requires explicit session ID for filtering
+    - Implements basic error handling
+    - Assumes stable database connection
+    
+    Hugging Face Version:
+    - Uses a multi-layered approach with direct SQL fallback
+    - Auto-detects current session ID when possible
+    - Implements enhanced error recovery with detailed diagnostics
+    - Tests database connection and table existence before operations
+    - Performs preliminary count of available records
+    - Provides detailed logging of database operations
+    
+    These differences ensure the history functionality works reliably in the
+    more restrictive Hugging Face environment.
+    """
+    
+    def __init__(self):
+        """Initialize the database service with the configured database path."""
+        # Ensure the database directory exists
+        db_dir = os.path.dirname(settings.DB_PATH)
+        os.makedirs(db_dir, exist_ok=True)
+        
+        # Log database path for debugging
+        logger.info(f"Initializing DatabaseService with DB at: {settings.DB_PATH}")
+        logger.info(f"Database directory exists: {os.path.exists(db_dir)}")
+        logger.info(f"Database directory is writable: {os.access(db_dir, os.W_OK)}")
+        
+        # Print to console for immediate visibility in logs
+        print(f"[DEBUG] Database path: {settings.DB_PATH}")
+        print(f"[DEBUG] Database dir exists: {os.path.exists(db_dir)}")
+        print(f"[DEBUG] Database dir writable: {os.access(db_dir, os.W_OK)}")
+        
+        try:
+            # Test if we can write to the directory
+            test_file = os.path.join(db_dir, '.db_test')
+            with open(test_file, 'w') as f:
+                f.write('test')
+            os.remove(test_file)
+            logger.info(f"Successfully wrote test file to {db_dir}")
+            print(f"[DEBUG] Successfully wrote test file to {db_dir}")
+        except Exception as e:
+            logger.error(f"Failed to write test file to {db_dir}: {e}")
+            print(f"[DEBUG] Failed to write test file to {db_dir}: {e}")
+            # No need to raise exception, we'll let the DatabaseManager handle this
+        
+        # List of possible fallback paths from most to least preferred
+        fallback_paths = [
+            os.path.join('/tmp', 'emotion_mirror.db'),
+            os.path.join('/home/user', 'emotion_mirror.db'),
+            ':memory:'  # SQLite in-memory database as last resort
+        ]
+        
+        # Initialize the database manager
+        db_initialized = False
+        db_path_used = settings.DB_PATH
+        
+        try:
+            self.db_manager = DatabaseManager(settings.DB_PATH)
+            logger.info(f"Database manager initialized successfully")
+            print(f"[DEBUG] Database manager initialized successfully with {settings.DB_PATH}")
+            
+            # Verify we can actually write to the database
+            try:
+                # Test direct SQLite connection instead of using a method that might not exist
+                import sqlite3
+                conn = sqlite3.connect(settings.DB_PATH)
+                cursor = conn.cursor()
+                cursor.execute("PRAGMA quick_check")
+                result = cursor.fetchone()
+                print(f"[DEBUG] Database integrity check: {result}")
+                
+                # Test insert and select
+                cursor.execute("CREATE TABLE IF NOT EXISTS test_table (id INTEGER PRIMARY KEY, test TEXT)")
+                cursor.execute("INSERT INTO test_table (test) VALUES ('test_write')")
+                conn.commit()
+                cursor.execute("SELECT * FROM test_table LIMIT 1")
+                test_result = cursor.fetchone()
+                print(f"[DEBUG] Database test write/read successful: {test_result}")
+                cursor.execute("DROP TABLE test_table")
+                conn.commit()
+                conn.close()
+                db_initialized = True
+            except Exception as e:
+                logger.error(f"Database write test failed: {e}")
+                print(f"[DEBUG] Database write test failed: {e}")
+                raise Exception(f"Database write test failed: {e}")
+                
+        except Exception as e:
+            logger.error(f"Error initializing database manager: {e}")
+            print(f"[DEBUG] Error initializing database manager: {e}")
+            
+            # Try fallback paths
+            for fallback_path in fallback_paths:
+                try:
+                    print(f"[DEBUG] Trying fallback database path: {fallback_path}")
+                    
+                    # Test direct SQLite connection for fallback path
+                    if fallback_path != ':memory:':
+                        fallback_dir = os.path.dirname(fallback_path)
+                        if fallback_dir:  # Skip directory check for :memory:
+                            os.makedirs(fallback_dir, exist_ok=True)
+                            test_file = os.path.join(fallback_dir, '.db_test')
+                            with open(test_file, 'w') as f:
+                                f.write('test')
+                            os.remove(test_file)
+                    
+                    # Test database connection and operations
+                    import sqlite3
+                    conn = sqlite3.connect(fallback_path)
+                    cursor = conn.cursor()
+                    cursor.execute("CREATE TABLE IF NOT EXISTS test_table (id INTEGER PRIMARY KEY, test TEXT)")
+                    cursor.execute("INSERT INTO test_table (test) VALUES ('test_write')")
+                    conn.commit()
+                    cursor.execute("SELECT * FROM test_table LIMIT 1")
+                    test_result = cursor.fetchone()
+                    cursor.execute("DROP TABLE test_table")
+                    conn.commit()
+                    conn.close()
+                    
+                    # If we got here, the database works with this path
+                    self.db_manager = DatabaseManager(fallback_path)
+                    db_path_used = fallback_path
+                    
+                    print(f"[DEBUG] Successfully initialized database with fallback path: {fallback_path}")
+                    logger.info(f"Using alternative database path: {fallback_path}")
+                    db_initialized = True
+                    break
+                except Exception as e:
+                    print(f"[DEBUG] Failed to use fallback path {fallback_path}: {e}")
+                    logger.warning(f"Failed to use fallback path {fallback_path}: {e}")
+                    continue
+        
+        if not db_initialized:
+            error_msg = "CRITICAL: Could not initialize database with any path. History functionality will not work."
+            logger.critical(error_msg)
+            print(f"[DEBUG] {error_msg}")
+            # Create an in-memory database as last resort
+            try:
+                self.db_manager = DatabaseManager(":memory:")
+                print("[DEBUG] Created in-memory database as last resort. History will not persist.")
+            except Exception as e:
+                print(f"[DEBUG] Even in-memory database failed: {e}")
+                # Initialize a dummy database manager that will log but not throw errors
+                class DummyDBManager:
+                    def __init__(self):
+                        pass
+                    def __getattr__(self, name):
+                        def dummy_method(*args, **kwargs):
+                            print(f"[DEBUG] Called dummy DB method {name} with {args}, {kwargs}")
+                            if name.startswith('get_'):
+                                return []
+                            return 0
+                        return dummy_method
+                self.db_manager = DummyDBManager()
+        
+        print(f"[DEBUG] DatabaseService initialization complete. Using DB: {db_path_used}")
+        logger.info(f"DatabaseService initialization complete. Using DB: {db_path_used}")
+    
+    def save_analysis_results(self, 
+                            session_id: str, 
+                            image_path: str, 
+                            results: Dict[str, Any],
+                            tags: Optional[List[str]] = None) -> int:
+        """
+        Save analysis results to the database.
+        
+        Args:
+            session_id: Current session identifier
+            image_path: Path to the analyzed image
+            results: Analysis results dictionary
+            tags: Optional list of tags for the analysis
+            
+        Returns:
+            The ID of the saved analysis record
+        """
+        try:
+            logger.info(f"Saving analysis results for session: {session_id}")
+            print(f"[DEBUG] Attempting to save analysis for session: {session_id}, image: {image_path}")
+            result_id = self.db_manager.save_analysis(session_id, image_path, results, tags)
+            print(f"[DEBUG] Analysis saved successfully with ID: {result_id}")
+            return result_id
+        except Exception as e:
+            error_msg = f"Failed to save analysis results: {e}"
+            logger.error(error_msg)
+            print(f"[DEBUG] {error_msg}")
+            # Return 0 to indicate failure but continue execution
+            return 0
+    
+    def get_history(self, 
+                  session_id: Optional[str] = None, 
+                  limit: int = 10) -> List[Dict[str, Any]]:
+        """
+        Retrieve analysis history.
+        
+        Args:
+            session_id: Optional session ID to filter by
+            limit: Maximum number of records to return
+            
+        Returns:
+            List of analysis records
+        """
+        try:
+            logger.info(f"Retrieving analysis history for session: {session_id or 'all sessions'}")
+            print(f"[DEBUG] Attempting to get history for session: {session_id}, limit: {limit}")
+            
+            # If session_id is None, use current session ID
+            if session_id is None and hasattr(st, 'session_state') and 'session_id' in st.session_state:
+                session_id = st.session_state.session_id
+                print(f"[DEBUG] Using session_id from session_state: {session_id}")
+            
+            # First check if the database file exists
+            if not os.path.exists(self.db_manager.db_path):
+                print(f"[DEBUG] Database file does not exist: {self.db_manager.db_path}")
+                logger.warning(f"Database file does not exist: {self.db_manager.db_path}")
+                return []
+            
+            # Test database connection
+            try:
+                import sqlite3
+                conn = sqlite3.connect(self.db_manager.db_path)
+                cursor = conn.cursor()
+                
+                # Check if the analyses table exists
+                cursor.execute("SELECT name FROM sqlite_master WHERE type='table' AND name='analyses'")
+                if not cursor.fetchone():
+                    print("[DEBUG] The 'analyses' table does not exist in the database")
+                    conn.close()
+                    return []
+                
+                # Get a count of records for this session
+                if session_id:
+                    cursor.execute("SELECT COUNT(*) FROM analyses WHERE session_id = ?", (session_id,))
+                else:
+                    cursor.execute("SELECT COUNT(*) FROM analyses")
+                
+                count = cursor.fetchone()[0]
+                print(f"[DEBUG] Found {count} records in the database")
+                
+                conn.close()
+            except Exception as e:
+                print(f"[DEBUG] Error testing database connection: {e}")
+                logger.error(f"Error testing database connection: {e}")
+            
+            # Try to get records using the db_manager
+            records = self.db_manager.get_analysis_history(session_id, limit)
+            print(f"[DEBUG] Retrieved {len(records)} records from db_manager")
+            
+            # If no records were found but we expect some (from the count above)
+            # try a direct query as a fallback
+            if not records and count > 0:
+                print("[DEBUG] No records returned from db_manager but count > 0, trying direct query")
+                try:
+                    conn = sqlite3.connect(self.db_manager.db_path)
+                    conn.row_factory = sqlite3.Row
+                    cursor = conn.cursor()
+                    
+                    if session_id:
+                        query = "SELECT * FROM analyses WHERE session_id = ? ORDER BY timestamp DESC LIMIT ?"
+                        cursor.execute(query, (session_id, limit))
+                    else:
+                        query = "SELECT * FROM analyses ORDER BY timestamp DESC LIMIT ?"
+                        cursor.execute(query, (limit,))
+                    
+                    rows = cursor.fetchall()
+                    records = []
+                    
+                    for row in rows:
+                        record = {key: row[key] for key in row.keys()}
+                        # Parse the JSON fields
+                        try:
+                            if 'results' in record and record['results']:
+                                record['results'] = json.loads(record['results'])
+                            if 'tags' in record and record['tags']:
+                                record['tags'] = json.loads(record['tags'])
+                        except:
+                            pass
+                        records.append(record)
+                    
+                    conn.close()
+                    print(f"[DEBUG] Retrieved {len(records)} records via direct query")
+                except Exception as e:
+                    print(f"[DEBUG] Error in direct SQL query fallback: {e}")
+                    logger.error(f"Error in direct SQL query fallback: {e}")
+            
+            return records
+        except Exception as e:
+            error_msg = f"Failed to retrieve analysis history: {e}"
+            logger.error(error_msg)
+            print(f"[DEBUG] {error_msg}")
+            # Return empty list to avoid breaking the UI
+            return []
+    
+    def get_analysis(self, analysis_id: int) -> Optional[Dict[str, Any]]:
+        """
+        Retrieve a specific analysis.
+        
+        Args:
+            analysis_id: ID of the analysis to retrieve
+            
+        Returns:
+            Analysis record or None if not found
+        """
+        logger.info(f"Retrieving analysis with ID: {analysis_id}")
+        return self.db_manager.get_analysis_by_id(analysis_id)
+    
+    def get_emotion_stats(self, 
+                        session_id: Optional[str] = None, 
+                        limit: int = 50) -> Dict[str, float]:
+        """
+        Get emotion statistics.
+        
+        Args:
+            session_id: Optional session ID to filter by
+            limit: Maximum number of records to analyze
+            
+        Returns:
+            Dictionary of emotion frequencies
+        """
+        logger.info(f"Computing emotion statistics for session: {session_id or 'all sessions'}")
+        return self.db_manager.get_emotion_statistics(session_id, limit)
+    
+    def delete_record(self, analysis_id: int) -> bool:
+        """
+        Delete an analysis record.
+        
+        Args:
+            analysis_id: ID of the analysis to delete
+            
+        Returns:
+            True if deletion was successful, False otherwise
+        """
+        logger.info(f"Deleting analysis with ID: {analysis_id}")
+        return self.db_manager.delete_analysis(analysis_id)
+    
+    def export_data(self, 
+                  analysis_id: Optional[int] = None, 
+                  session_id: Optional[str] = None,
+                  limit: int = 100) -> Dict[str, Any]:
+        """
+        Export analysis data in a structured format.
+        
+        Args:
+            analysis_id: Optional specific analysis ID to export
+            session_id: Optional session ID to filter by
+            limit: Maximum number of records to export
+            
+        Returns:
+            Dictionary containing the exported data
+        """
+        logger.info(f"Exporting data for analysis ID: {analysis_id or 'multiple'}")
+        return self.db_manager.export_analysis_data(analysis_id, session_id, limit)

services/deepface_emotion_service.py

@@ -0,0 +1,269 @@
+"""
+Advanced emotion analysis service using DeepFace for EmotionMirror application.
+Provides high-precision facial emotion detection and analysis.
+"""
+import os
+import logging
+import tempfile
+import cv2
+import numpy as np
+from typing import Dict, Any, List, Optional
+import traceback
+
+# Importar settings desde config
+from config import settings
+from services.emotion_service import EmotionService
+
+# Importar DeepFace con manejo de errores
+try:
+    from deepface import DeepFace
+    DEEPFACE_AVAILABLE = True
+    logging.info("DeepFace está disponible. Se puede usar la detección avanzada de emociones.")
+except (ImportError, ModuleNotFoundError, ValueError) as e:
+    DEEPFACE_AVAILABLE = False
+    logging.warning(f"No se pudo importar DeepFace: {str(e)}. Se usará el servicio básico de emociones.")
+
+class DeepFaceEmotionService(EmotionService):
+    """
+    Servicio para análisis avanzado de emociones usando DeepFace.
+    Proporciona detección de emociones, edad y género.
+    Si DeepFace falla, recurrirá al servicio básico de emociones.
+    """
+    
+    _instance = None
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super(DeepFaceEmotionService, cls).__new__(cls)
+            cls._instance._initialized = False
+        return cls._instance
+    
+    def __init__(self):
+        # Llamar al inicializador de la clase padre primero
+        super().__init__()
+        
+        # Atributos de inicialización - siempre definidos
+        self.deepface_initialized = False
+        self.deepface_available = DEEPFACE_AVAILABLE
+        self.actions = ['emotion', 'age', 'gender']  # Definir actions aquí para que siempre exista
+        self.detector_backend = "opencv"  # Valor por defecto
+        
+        # Definir emotion_mapping aquí para que siempre exista
+        self.emotion_mapping = {
+            'angry': 'anger',
+            'disgust': 'disgust',
+            'fear': 'fear',
+            'happy': 'joy',
+            'sad': 'sadness',
+            'surprise': 'surprise',
+            'neutral': 'neutral'
+        }
+        
+        # Evitar inicialización múltiple
+        if getattr(self, '_initialized', False):
+            return
+        
+        self._initialized = True
+        
+        # Crear directorio temporal si no existe
+        if not os.path.exists(settings.TEMP_DIR):
+            os.makedirs(settings.TEMP_DIR, exist_ok=True)
+        
+        # Verificar disponibilidad de DeepFace
+        if not DEEPFACE_AVAILABLE:
+            logging.warning("DeepFace no está disponible. Usando EmotionService básico como respaldo.")
+            return
+        
+        try:
+            # Verificar que DeepFace funciona correctamente
+            logging.info("Inicializando DeepFace...")
+            detector_backends = DeepFace.detector_backends()
+            logging.info(f"DeepFace detector backends disponibles: {detector_backends}")
+            
+            # Actualizar la configuración de DeepFace si está disponible
+            if "opencv" in detector_backends:
+                self.detector_backend = "opencv"
+            elif "retinaface" in detector_backends:
+                self.detector_backend = "retinaface"
+            
+            # Marcar como inicializado correctamente
+            self.deepface_initialized = True
+            logging.info("DeepFace inicializado correctamente")
+            
+        except Exception as e:
+            logging.error(f"Error al inicializar DeepFace: {str(e)}")
+            logging.error(traceback.format_exc())
+            self.deepface_initialized = False
+    
+    def is_advanced_service_active(self) -> bool:
+        """
+        Check if the advanced emotion service (DeepFace) is active and available.
+        
+        Returns:
+            bool: True if advanced service is available and initialized
+        """
+        return self.deepface_available and self.deepface_initialized
+    
+    def analyze_emotion(self, face_img: np.ndarray) -> Dict[str, Any]:
+        """
+        Analiza las emociones usando DeepFace.
+        Si ocurre un error, recurre al servicio básico de emociones.
+        
+        Args:
+            face_img: Imagen de la cara a analizar
+            
+        Returns:
+            Diccionario con resultados de análisis de emociones, edad y género
+        """
+        # Si DeepFace no está disponible, usar el servicio básico
+        if not DEEPFACE_AVAILABLE:
+            logging.info("DeepFace no está disponible. Usando servicio básico.")
+            return super().analyze_emotion(face_img)
+        
+        # Guardar la imagen temporalmente
+        temp_face_path = os.path.join(settings.TEMP_DIR, "temp_face.jpg")
+        try:
+            # Guardar imagen para análisis
+            cv2.imwrite(temp_face_path, face_img)
+            
+            # Intentar análisis con DeepFace
+            try:
+                # Realizar análisis
+                analysis_result = DeepFace.analyze(
+                    img_path=temp_face_path,
+                    actions=self.actions,
+                    detector_backend=self.detector_backend,
+                    enforce_detection=False  # Continuar incluso si no se detecta cara
+                )
+                
+                # DeepFace returns a list for batch processing, get first result
+                if isinstance(analysis_result, list):
+                    analysis_result = analysis_result[0]
+                
+                # Extract emotion data
+                emotions_raw = analysis_result.get('emotion', {})
+                
+                # Map emotions to our standard set
+                emotions = {}
+                for df_emotion, score in emotions_raw.items():
+                    standard_emotion = self.emotion_mapping.get(df_emotion.lower(), df_emotion.lower())
+                    emotions[standard_emotion] = score / 100.0  # DeepFace scores are 0-100
+                
+                # Add any missing standard emotions with zero scores
+                for emotion in settings.EMOTIONS:
+                    if emotion not in emotions:
+                        emotions[emotion] = 0.0
+                
+                # Find primary emotion (highest score)
+                primary_emotion = max(emotions.items(), key=lambda x: x[1])
+                
+                # Calculate basic image features (for compatibility with existing code)
+                gray_face = cv2.cvtColor(face_img, cv2.COLOR_BGR2GRAY)
+                brightness = np.mean(gray_face)
+                contrast = np.std(gray_face)
+                
+                # Extract additional features
+                age = analysis_result.get('age', 0)
+                gender = analysis_result.get('gender', 'unknown')
+                
+                # For compatibility with existing code
+                h, w = gray_face.shape
+                mid = w // 2
+                left_half = gray_face[:, :mid]
+                right_half = cv2.flip(gray_face[:, mid:], 1)
+                
+                # Calculate symmetry (if sizes match)
+                if left_half.shape == right_half.shape:
+                    symmetry = 1.0 - (np.sum(cv2.absdiff(left_half, right_half)) / (255 * left_half.size))
+                else:
+                    symmetry = 0.5  # Default value if face isn't properly centered
+                    
+                # Formato del resultado
+                result = {
+                    "emotion": primary_emotion[0],
+                    "confidence": primary_emotion[1],  # Añadir la clave 'confidence' con el valor de confianza
+                    "emotions": emotions,  # Usar 'emotions' en lugar de 'emotion_scores'
+                    "is_advanced_detection": True,
+                    "features": {
+                        'brightness': float(brightness),
+                        'contrast': float(contrast),
+                        'symmetry': float(symmetry),
+                        'smile_score': float(emotions.get('joy', 0.0)),  # Use joy as smile score
+                        'age': float(age),
+                        'gender': gender
+                    }
+                }
+                
+                return result
+                
+            except Exception as e:
+                # Log del error y caída al servicio básico
+                logging.error(f"Error en DeepFace.analyze: {str(e)}. Usando servicio básico.")
+                return super().analyze_emotion(face_img)
+        except Exception as e:
+            # Error al guardar o procesar la imagen
+            logging.error(f"Error al procesar la imagen para DeepFace: {str(e)}")
+            return super().analyze_emotion(face_img)
+        finally:
+            # Asegurar limpieza de archivos temporales
+            if os.path.exists(temp_face_path):
+                try:
+                    os.remove(temp_face_path)
+                except Exception as e:
+                    logging.warning(f"No se pudo eliminar el archivo temporal: {str(e)}")
+    
+    def get_advanced_attributes(self, face_img: np.ndarray) -> Dict[str, Any]:
+        """
+        Get advanced facial attributes using DeepFace.
+        
+        Args:
+            face_img: Face image to analyze
+            
+        Returns:
+            Dictionary with advanced attributes (age, gender, race)
+        """
+        if not DEEPFACE_AVAILABLE or face_img is None or face_img.size == 0:
+            return {
+                'age': 0,
+                'gender': 'unknown',
+                'race': 'unknown'
+            }
+        
+        try:
+            # Save face image to a temporary file
+            temp_face_path = os.path.join(settings.TEMP_DIR, "temp_face_attr.jpg")
+            os.makedirs(settings.TEMP_DIR, exist_ok=True)
+            cv2.imwrite(temp_face_path, face_img)
+            
+            # Analyze with DeepFace
+            attr_result = DeepFace.analyze(
+                img_path=temp_face_path,
+                actions=['age', 'gender', 'race'],
+                detector_backend=self.detector_backend,
+                enforce_detection=False,
+            )
+            
+            # Extract first result if list
+            if isinstance(attr_result, list):
+                attr_result = attr_result[0]
+            
+            # Return attributes
+            return {
+                'age': attr_result.get('age', 0),
+                'gender': attr_result.get('gender', 'unknown'),
+                'race': attr_result.get('dominant_race', 'unknown')
+            }
+        except Exception as e:
+            logging.error(f"Error in advanced attribute detection: {e}")
+            return {
+                'age': 0,
+                'gender': 'unknown',
+                'race': 'unknown'
+            }
+        finally:
+            # Clean up temporary file
+            try:
+                if os.path.exists(temp_face_path):
+                    os.remove(temp_face_path)
+            except:
+                pass

services/emotion_service.py

@@ -0,0 +1,381 @@
+"""
+Emotion analysis service for EmotionMirror application.
+Provides emotional classification and analysis features.
+"""
+import os
+import logging
+import cv2
+import numpy as np
+from typing import Dict, Optional, Any, List, Tuple
+
+# Definir constante para dlib
+DLIB_AVAILABLE = False
+logging.warning("dlib ha sido desactivado para compatibilidad con el despliegue.")
+
+from config import settings
+
+logger = logging.getLogger(__name__)
+
+class EmotionService:
+    """Service for emotion analysis and classification"""
+    
+    _instance = None
+    
+    def __new__(cls):
+        """Singleton pattern implementation"""
+        if cls._instance is None:
+            cls._instance = super(EmotionService, cls).__new__(cls)
+            cls._instance._initialized = False
+        return cls._instance
+    
+    def __init__(self):
+        """Initialize the emotion service"""
+        if self._initialized:
+            return
+            
+        self._initialized = True
+        logger.info("Initializing EmotionService")
+        
+        # Initialize the face classifier
+        self.face_cascade = cv2.CascadeClassifier(cv2.data.haarcascades + 'haarcascade_frontalface_default.xml')
+        
+        # Inicializar el detector de sonrisas para mejorar la detección
+        cascade_path = os.path.join(settings.MODELS_DIR, "haarcascade_smile.xml")
+        
+        # Verificar si existe el archivo
+        if os.path.exists(cascade_path):
+            self.smile_cascade = cv2.CascadeClassifier(cascade_path)
+            logger.info(f"Smile cascade loaded from: {cascade_path}")
+        else:
+            # Si no existe el archivo, intentar usar el predeterminado de OpenCV
+            logger.warning(f"Smile cascade not found at: {cascade_path}, using default")
+            self.smile_cascade = cv2.CascadeClassifier(cv2.data.haarcascades + 'haarcascade_smile.xml')
+        
+        # Inicializar el detector de landmarks faciales (opcional, solo si está disponible dlib)
+        self.landmark_detector = None
+        self.face_detector = None
+        
+        if DLIB_AVAILABLE:
+            try:
+                # Cargar el detector de rostros
+                self.face_detector = dlib.get_frontal_face_detector()
+                
+                # Cargar el predictor de landmarks faciales
+                model_path = os.path.join(settings.MODELS_DIR, "shape_predictor_68_face_landmarks.dat")
+                if os.path.exists(model_path):
+                    self.landmark_detector = dlib.shape_predictor(model_path)
+                    logger.info("Landmark detector loaded successfully")
+                else:
+                    logger.warning(f"Landmark model not found at: {model_path}")
+            except Exception as e:
+                logger.error(f"Error loading facial landmark detector: {e}")
+                self.landmark_detector = None
+                self.face_detector = None
+        
+        logger.info("Emotion classifier initialized")
+    
+    def _initialize_emotion_classifier(self):
+        """Initialize the emotion classifier"""
+        # This is a simplified implementation for Subfase 1.2
+        # In future phases, this will be replaced with a proper ML model
+        self.emotion_map = {
+            # Map facial features to emotions based on simple heuristics
+            # Will be replaced with ML model in later phases
+        }
+        logger.info("Emotion classifier initialized")
+    
+    def analyze_emotion(self, face_img: np.ndarray) -> Dict[str, Any]:
+        """
+        Analyze emotion from a face image.
+        
+        Args:
+            face_img: Face image to analyze
+            
+        Returns:
+            Dictionary with emotion data
+        """
+        if face_img is None or face_img.size == 0:
+            return {
+                'emotion': 'unknown',
+                'confidence': 0.0,
+                'emotions': {'unknown': 1.0},
+                'features': {
+                    'brightness': 0.0,
+                    'contrast': 0.0,
+                    'symmetry': 0.0,
+                    'smile_score': 0.0
+                }
+            }
+            
+        # Convert to grayscale for analysis
+        gray_face = cv2.cvtColor(face_img, cv2.COLOR_BGR2GRAY)
+        
+        # Calculate basic image features
+        brightness = np.mean(gray_face)
+        contrast = np.std(gray_face)
+        
+        # Calculate symmetry
+        h, w = gray_face.shape
+        mid = w // 2
+        left_half = gray_face[:, :mid]
+        right_half = gray_face[:, mid:]
+        right_half_flipped = cv2.flip(right_half, 1)
+        
+        # Resize if the halves have different shapes
+        if left_half.shape != right_half_flipped.shape:
+            min_width = min(left_half.shape[1], right_half_flipped.shape[1])
+            left_half = left_half[:, :min_width]
+            right_half_flipped = right_half_flipped[:, :min_width]
+            
+        diff = cv2.absdiff(left_half, right_half_flipped)
+        symmetry = 1.0 - (np.sum(diff) / (h * mid * 255))
+        
+        # Comprobar si el brillo general es bajo - indicativo de tristeza o falta de emoción
+        norm_brightness = brightness / 255.0
+        
+        # Get base emotions from rule-based classification
+        emotions = self._rule_based_emotion_classification(brightness, contrast, symmetry)
+        
+        # Check for smile indicators SOLO para imágenes de brillo alto
+        smile_detected = False
+        smile_score = 0.0
+        
+        if norm_brightness >= 0.6:  # Solo buscar sonrisas si el brillo es ALTO
+            smile_detected = self._detect_smile_cascade(gray_face)
+            
+            # Try landmark-based smile detection if available
+            if self.landmark_detector:
+                smile_score = self._detect_smile_landmarks(gray_face)
+                logger.info(f"Landmark smile score: {smile_score}")
+                
+            # Si se detecta una sonrisa con brillo alto, aumentamos alegría
+            if smile_detected or smile_score > 0.4:
+                smile_confidence = max(0.8 if smile_detected else 0.0, smile_score)
+                logger.info(f"Detectada SONRISA con score {smile_confidence:.2f} - clasificando como Joy")
+                emotions['joy'] = max(emotions['joy'], smile_confidence)
+        else:
+            # FORZAR tristeza/neutral para rostros oscuros
+            emotions['sadness'] = max(emotions['sadness'], 0.6)
+            emotions['neutral'] = max(emotions['neutral'], 0.3)
+            emotions['joy'] = min(emotions['joy'], 0.1)  # Reducir alegría drásticamente
+            logger.info(f"FORZANDO TRISTEZA por brillo bajo: {norm_brightness}")
+        
+        # Normalize emotions
+        total = sum(emotions.values())
+        if total > 0:
+            emotions = {k: v/total for k, v in emotions.items()}
+        
+        # Find dominant emotion
+        emotion = max(emotions.items(), key=lambda x: x[1])
+        
+        return {
+            'emotion': emotion[0],
+            'confidence': emotion[1],
+            'emotions': emotions,
+            'features': {
+                'brightness': float(brightness),
+                'contrast': float(contrast),
+                'symmetry': float(symmetry),
+                'smile_score': float(smile_score)
+            }
+        }
+    
+    def _detect_smile_cascade(self, gray_face: np.ndarray) -> bool:
+        """
+        Detecta sonrisas usando el clasificador en cascada de OpenCV.
+        
+        Args:
+            gray_face: Imagen en escala de grises de la cara
+            
+        Returns:
+            bool: True si se detecta sonrisa, False en caso contrario
+        """
+        try:
+            # Ajustar parámetros para hacer la detección MÁS SENSIBLE
+            # Increasing minNeighbors makes detection more selective
+            smiles = self.smile_cascade.detectMultiScale(
+                gray_face,
+                scaleFactor=1.3,
+                minNeighbors=25,  # Aumentado de 20 a 25 para mayor selectividad
+                minSize=(25, 25)
+            )
+            
+            logger.info(f"Smile detection: {len(smiles)} smiles detected")
+            
+            if len(smiles) > 0:
+                logger.info("Sonrisa detectada con detector de cascada")
+                return True
+            return False
+        except Exception as e:
+            logger.error(f"Error in smile detection: {e}")
+            return False
+    
+    def _detect_smile_landmarks(self, face_img: np.ndarray) -> float:
+        """
+        Detecta sonrisas usando landmarks faciales.
+        
+        Args:
+            face_img: Imagen de la cara
+            
+        Returns:
+            float: Puntaje de sonrisa entre 0 y 1
+        """
+        if not DLIB_AVAILABLE or self.landmark_detector is None:
+            return 0.0
+            
+        try:
+            # Convertir a escala de grises si es necesario
+            if len(face_img.shape) == 3:
+                gray = cv2.cvtColor(face_img, cv2.COLOR_BGR2GRAY)
+            else:
+                gray = face_img
+                
+            faces = self.face_detector(gray)
+            
+            if len(faces) == 0:
+                return 0.0
+                
+            # Usar el primer rostro detectado
+            landmarks = self.landmark_detector(gray, faces[0])
+            
+            # Extraer los puntos como coordenadas (x,y)
+            landmarks_points = []
+            for i in range(68):
+                x = landmarks.part(i).x
+                y = landmarks.part(i).y
+                landmarks_points.append((x, y))
+                
+            # Calcular la curvatura de los labios
+            mouth_top = landmarks_points[48:55]
+            mouth_bottom = landmarks_points[55:60]
+            
+            x = [p[0] for p in mouth_top]
+            y = [p[1] for p in mouth_top]
+            
+            # Encontrar la línea que mejor ajusta los puntos
+            z = np.polyfit(x, y, 2)
+            
+            # El coeficiente cuadrático indica la curvatura (negativo = sonrisa)
+            curvature = -z[0]  # Negativo porque en coordenadas de imagen, y aumenta hacia abajo
+            
+            # Convertir a un score entre 0 y 1
+            smile_score = max(0, min(1, curvature * 500))  # Ajustar según sea necesario
+            
+            return smile_score
+        except Exception as e:
+            logger.error(f"Error detectando sonrisa con landmarks: {e}")
+            return 0.0
+    
+    def _rule_based_emotion_classification(self, brightness, contrast, symmetry) -> Dict[str, float]:
+        """
+        Simple rule-based emotion classification.
+        
+        Args:
+            brightness: Image brightness
+            contrast: Image contrast
+            symmetry: Facial symmetry
+            
+        Returns:
+            Dictionary with emotion probabilities
+        """
+        # Normalize values
+        norm_brightness = brightness / 255.0
+        norm_contrast = min(contrast / 80.0, 1.0)
+        
+        # Initialize all emotions with low probability
+        emotions = {e: 0.05 for e in settings.EMOTIONS}
+        
+        # DETECCIÓN FUERTE: Para rostros con brillo bajo, FORZAR tristeza
+        if norm_brightness < 0.6:
+            # Cuanto más oscuro el rostro, más tristeza
+            sadness_score = 0.7 + (0.6 - norm_brightness) * 0.7
+            logger.info(f"REGLA FORZADA: Detectando TRISTEZA por brillo bajo: {norm_brightness}")
+            
+            emotions['sadness'] = sadness_score
+            emotions['neutral'] = 0.4
+            emotions['joy'] = 0.1  # Reducir alegría significativamente
+            
+            # Normalizar
+            total = sum(emotions.values())
+            emotions = {k: v/total for k, v in emotions.items()}
+            return emotions
+            
+        # Para rostros brillantes favorecemos alegría
+        if norm_brightness > 0.65:
+            emotions['joy'] = 0.7 + norm_brightness * 0.3
+            logger.info(f"REGLA BALANCEADA: Detectando alegría por brillo alto: {norm_brightness}")
+            
+        # Apply standard rules for other scenarios
+        # Low brightness + high contrast → anger, sadness
+        if norm_brightness < 0.4 and norm_contrast > 0.4:
+            emotions['anger'] = 0.4 + norm_contrast * 0.3
+            emotions['sadness'] = 0.3 + (1 - norm_brightness) * 0.3
+            
+        # High symmetry → neutral
+        if symmetry > 0.7:
+            emotions['neutral'] = 0.3 + symmetry * 0.4
+            # If symmetry is high but brightness is also high, joy overrides neutral
+            if norm_brightness > 0.7:
+                emotions['joy'] = max(emotions['joy'], 0.6 + norm_brightness * 0.3)
+            
+        # Medium brightness, medium contrast → surprise
+        if 0.4 < norm_brightness < 0.6 and 0.3 < norm_contrast < 0.5:
+            emotions['surprise'] = 0.4 + norm_contrast * 0.2
+            
+        # Low symmetry → disgust, fear
+        if symmetry < 0.5:
+            emotions['disgust'] = 0.3 + (1 - symmetry) * 0.3
+            emotions['fear'] = 0.2 + (1 - symmetry) * 0.3
+        
+        # Normalize so they sum to 1
+        total = sum(emotions.values())
+        if total > 0:
+            emotions = {k: v/total for k, v in emotions.items()}
+            
+        return emotions
+    
+    def get_emotion_color(self, emotion: str) -> Tuple[int, int, int]:
+        """
+        Get a color associated with an emotion.
+        
+        Args:
+            emotion: Emotion name
+            
+        Returns:
+            RGB color tuple
+        """
+        emotion_colors = {
+            'joy': (0, 255, 255),       # Yellow
+            'sadness': (205, 108, 0),   # Blue
+            'anger': (0, 0, 255),       # Red
+            'fear': (211, 0, 148),      # Purple
+            'surprise': (0, 140, 255),  # Orange
+            'disgust': (50, 205, 50),   # Green
+            'neutral': (200, 200, 200), # Gray
+            'unknown': (150, 150, 150)  # Light Gray
+        }
+        
+        return emotion_colors.get(emotion, (200, 200, 200))
+    
+    def get_emotion_emoji(self, emotion: str) -> str:
+        """
+        Get an emoji representing the emotion.
+        
+        Args:
+            emotion: Emotion name
+            
+        Returns:
+            Emoji string
+        """
+        emotion_emojis = {
+            'joy': '😊',
+            'sadness': '😢',
+            'anger': '😠',
+            'fear': '😨',
+            'surprise': '😲',
+            'disgust': '🤢',
+            'neutral': '😐',
+            'unknown': '❓'
+        }
+        
+        return emotion_emojis.get(emotion, '❓')

services/image_service.py

@@ -0,0 +1,828 @@
+"""
+Image service for EmotionMirror application.
+Provides functionality for image loading, validation and basic processing.
+
+This module implements:
+1. Design of the upload interface - Clear presentation and information
+2. Implementation of format validation - Extension and MIME type verification
+3. Validation of dimensions and size - Ensuring optimal images for facial analysis
+4. Image preprocessing - Adjusting brightness, contrast, and resizing
+"""
+import os
+import logging
+import numpy as np
+import cv2
+import imghdr
+import mimetypes
+import uuid
+import tempfile
+from typing import Tuple, Optional, Dict, Any, List
+import io
+import base64
+from PIL import Image
+import time
+
+logger = logging.getLogger(__name__)
+
+class ImageService:
+    """
+    Service for handling image operations including format validation.
+    
+    This service encapsulates functionality for validating image formats,
+    checking file sizes, dimensions, and quality to ensure images meet 
+    application requirements for effective facial detection.
+    """
+    
+    def __init__(self):
+        """Initialize image service with default settings"""
+        # Define supported formats for upload
+        self.supported_formats = ["jpg", "jpeg", "png"]
+        
+        # Define maximum file size (10MB by default)
+        self.max_file_size = 10 * 1024 * 1024  # 10MB
+        
+        # STEP 3: Define dimension constraints for image validation
+        self.min_width = 320
+        self.min_height = 240
+        self.max_width = 4096
+        self.max_height = 4096
+        self.optimal_width = 640
+        self.optimal_height = 480
+        
+        # Initialize temp directory for processed images
+        self.temp_dir = tempfile.gettempdir()
+        logger.info(f"Image service initialized. Temp directory: {self.temp_dir}")
+        
+        # Initialize MIME types mapping
+        self._init_mime_types()
+    
+    def _init_mime_types(self):
+        """Initialize MIME types mapping for common image formats"""
+        # Ensure MIME types are properly registered
+        mimetypes.init()
+        
+        # Add common image MIME types if not registered
+        if not mimetypes.guess_type('.jpg')[0]:
+            mimetypes.add_type('image/jpeg', '.jpg')
+            mimetypes.add_type('image/jpeg', '.jpeg')
+            
+        if not mimetypes.guess_type('.png')[0]:
+            mimetypes.add_type('image/png', '.png')
+    
+    def get_supported_formats(self) -> list:
+        """
+        Return list of supported image formats.
+        
+        Returns:
+            List of file extensions that the application accepts
+        """
+        return self.supported_formats
+    
+    def get_format_info(self) -> str:
+        """
+        Return user-friendly format info message.
+        
+        Returns:
+            A human-readable string explaining supported formats
+        """
+        return "Supported formats: JPG, JPEG, PNG."
+        
+    def validate_file_extension(self, filename: str) -> Tuple[bool, str]:
+        """
+        Validates if the file has an allowed extension.
+        
+        Args:
+            filename: The name of the uploaded file
+            
+        Returns:
+            Tuple containing (is_valid, message)
+        """
+        if not filename:
+            return False, "No file provided."
+            
+        # Get the file extension
+        file_ext = os.path.splitext(filename)[1].lower().replace('.', '')
+        
+        if file_ext not in self.supported_formats:
+            return False, f"Invalid file format. {self.get_format_info()}"
+            
+        return True, "Valid file format."
+    
+    def validate_file_mime(self, file_content: bytes) -> Tuple[bool, str]:
+        """
+        Validates the actual MIME type of the file by examining its content.
+        
+        Args:
+            file_content: The content of the file as bytes
+            
+        Returns:
+            Tuple containing (is_valid, message)
+        """
+        if not file_content:
+            return False, "Could not read file content."
+            
+        # Use imghdr to check the image format from the file content
+        img_format = imghdr.what(None, h=file_content)
+        
+        # Log the detected format for debugging
+        logger.debug(f"Detected image format: {img_format}")
+        
+        if img_format is None:
+            # Try alternative detection method
+            try:
+                # Try to decode with OpenCV to verify it's a valid image
+                img_array = np.frombuffer(file_content, np.uint8)
+                img = cv2.imdecode(img_array, cv2.IMREAD_COLOR)
+                
+                if img is None:
+                    return False, "The file does not appear to be a valid image."
+                    
+                # If OpenCV can read it but imghdr couldn't identify format,
+                # we'll assume it's valid but with unknown format
+                return True, "Valid image (specific format not identified)."
+                
+            except Exception as e:
+                logger.error(f"Error validating image content: {e}")
+                return False, "Error validating image content."
+            
+        # Handle specific formats - normalize format names
+        if img_format == "jpeg":
+            img_format = "jpg"
+            
+        if img_format not in ["jpg", "png"]:
+            return False, f"Unsupported image format: {img_format}. {self.get_format_info()}"
+            
+        return True, f"Valid image in {img_format.upper()} format."
+    
+    # STEP 3: Implementation of dimension validation
+    def validate_image_dimensions(self, img: np.ndarray) -> Dict[str, Any]:
+        """
+        Validates image dimensions for facial processing.
+        Part of Step 3: Validation of dimensions and size.
+        
+        This method analyzes the image dimensions to ensure they meet
+        the requirements for effective facial detection and analysis.
+        It checks for minimum/maximum sizes and aspect ratio issues.
+        
+        Args:
+            img: The image as a numpy array
+            
+        Returns:
+            Dict with validation results including:
+            - valid: True if dimensions are acceptable, False otherwise
+            - width, height: Image dimensions
+            - warnings: List of warnings if dimensions are not optimal
+            - messages: List of informational messages
+        """
+        result = {
+            "valid": True,
+            "width": 0,
+            "height": 0,
+            "aspect_ratio": 0,
+            "warnings": [],
+            "messages": []
+        }
+        
+        if img is None:
+            result["valid"] = False
+            result["messages"].append("Could not process image to validate dimensions.")
+            return result
+        
+        # Get dimensions
+        height, width = img.shape[:2]
+        aspect_ratio = width / height if height > 0 else 0
+        
+        result["width"] = width
+        result["height"] = height
+        result["aspect_ratio"] = aspect_ratio
+        
+        # Validate minimum size
+        if width < self.min_width or height < self.min_height:
+            result["valid"] = False
+            result["warnings"].append(f"Image too small: {width}x{height}. Minimum recommended size: {self.min_width}x{self.min_height}")
+        
+        # Validate maximum size
+        if width > self.max_width or height > self.max_height:
+            result["warnings"].append(f"Image very large: {width}x{height}. May affect performance.")
+        
+        # Check if dimensions are optimal
+        if self.min_width <= width < self.optimal_width or self.min_height <= height < self.optimal_height:
+            result["messages"].append(f"Acceptable but not optimal dimensions. Ideal: {self.optimal_width}x{self.optimal_height}")
+        elif width >= self.optimal_width and height >= self.optimal_height:
+            result["messages"].append(f"Optimal dimensions for facial analysis: {width}x{height}")
+        
+        # Verify aspect ratio (very elongated can be problematic)
+        if aspect_ratio > 2.5 or aspect_ratio < 0.4:
+            result["warnings"].append(f"Unusual aspect ratio: {aspect_ratio:.2f}. May affect facial detection.")
+        
+        return result
+    
+    # STEP 3: Implementation of quality assessment
+    def check_image_quality(self, img: np.ndarray) -> Dict[str, Any]:
+        """
+        Evaluates the overall image quality for facial detection.
+        Part of Step 3: Validation of dimensions and size.
+        
+        This method performs various quality assessments including:
+        - Blurriness detection using Laplacian variance
+        - Brightness level measurement
+        - Contrast calculation
+        
+        These metrics are combined into an overall quality score and
+        specific recommendations are provided for improving quality.
+        
+        Args:
+            img: The image as a numpy array
+            
+        Returns:
+            Dict with quality metrics and recommendations
+        """
+        result = {
+            "quality_score": 0.0,
+            "is_blurry": False,
+            "brightness": 0.0,
+            "contrast": 0.0,
+            "warnings": [],
+            "suggestions": []
+        }
+        
+        if img is None:
+            result["warnings"].append("Could not evaluate image quality.")
+            return result
+        
+        # Convert to grayscale for some metrics
+        gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) if len(img.shape) == 3 else img
+        
+        # Evaluate sharpness (using Laplacian variance)
+        laplacian_var = cv2.Laplacian(gray, cv2.CV_64F).var()
+        result["is_blurry"] = laplacian_var < 100
+        
+        # Calculate brightness (pixel average)
+        brightness = np.mean(gray)
+        result["brightness"] = brightness / 255.0  # Normalized to 0-1
+        
+        # Calculate contrast (pixel standard deviation)
+        contrast = np.std(gray)
+        result["contrast"] = contrast / 255.0  # Normalized to 0-1
+        
+        # General quality evaluation (weighted combination)
+        sharpness_score = min(1.0, laplacian_var / 500)
+        brightness_score = 1.0 - abs(0.5 - result["brightness"]) * 2  # optimal near 0.5
+        contrast_score = min(1.0, result["contrast"] * 3)  # higher contrast is better
+        
+        # Total quality (0-1)
+        result["quality_score"] = (sharpness_score * 0.5 + brightness_score * 0.25 + contrast_score * 0.25)
+        
+        # Generate warnings and suggestions based on metrics
+        if result["is_blurry"]:
+            result["warnings"].append("The image appears to be blurry.")
+            result["suggestions"].append("Use a sharper image to improve facial detection accuracy.")
+        
+        if result["brightness"] < 0.2:
+            result["warnings"].append("The image is too dark.")
+            result["suggestions"].append("Try using a better illuminated image.")
+        elif result["brightness"] > 0.8:
+            result["warnings"].append("The image is too bright.")
+            result["suggestions"].append("Try using an image with more balanced lighting.")
+        
+        if result["contrast"] < 0.1:
+            result["warnings"].append("The image has very low contrast.")
+            result["suggestions"].append("An image with higher contrast will improve facial feature detection.")
+        
+        return result
+    
+    def load_image(self, file) -> np.ndarray:
+        """
+        Load image from file to numpy array.
+        
+        Args:
+            file: The uploaded file object
+            
+        Returns:
+            The image as a numpy array
+        """
+        try:
+            # Read file content
+            file_bytes = np.frombuffer(file.read(), np.uint8)
+            # Reset file pointer for subsequent reads
+            file.seek(0)
+            
+            # Decode image
+            img = cv2.imdecode(file_bytes, cv2.IMREAD_COLOR)
+            
+            if img is None:
+                logger.error("Failed to decode image")
+                raise ValueError("Could not decode image. The file may be corrupted.")
+                
+            return img
+        except Exception as e:
+            logger.error(f"Error loading image: {str(e)}")
+            raise ValueError(f"Error loading image: {str(e)}")
+            
+    def load_image_from_path(self, path: str) -> np.ndarray:
+        """
+        Load image from file path to numpy array.
+        
+        Args:
+            path: Path to the image file
+            
+        Returns:
+            The image as a numpy array
+        """
+        try:
+            # Read image from file path
+            img = cv2.imread(path)
+            
+            if img is None:
+                logger.error(f"Failed to load image from path: {path}")
+                raise ValueError("Could not load image. The file may be corrupted or not found.")
+                
+            return img
+        except Exception as e:
+            logger.error(f"Error loading image from path: {str(e)}")
+            raise ValueError(f"Error loading image: {str(e)}")
+    
+    # STEP 4: Image Preprocessing Methods
+    
+    def preprocess_image(self, img: np.ndarray) -> Dict[str, Any]:
+        """
+        Apply preprocessing to improve image quality for facial analysis.
+        Step 4: Implementation of preprocessing techniques to enhance image for better detection.
+        
+        This method applies a series of image enhancements to make the image more suitable
+        for facial detection and emotion analysis:
+        1. Adjust brightness if needed
+        2. Adjust contrast for better feature visibility
+        3. Resize if dimensions are too large or too small
+        
+        Args:
+            img: The image as a numpy array
+            
+        Returns:
+            Dict containing:
+            - original_image: The original image
+            - processed_image: The enhanced image
+            - improvements: List of applied enhancements
+        """
+        if img is None or img.size == 0:
+            raise ValueError("Invalid image provided for preprocessing")
+            
+        # Make a copy of the original image
+        original = img.copy()
+        processed = img.copy()
+        improvements = []
+        
+        # Get image quality metrics
+        quality = self.check_image_quality(processed)
+        brightness = quality.get('brightness', 0.5)
+        contrast = quality.get('contrast', 0.5)
+        
+        # 1. Adjust brightness if needed
+        if brightness < 0.3:
+            # Image is too dark, increase brightness
+            processed = self.adjust_brightness(processed, factor=1.3)
+            improvements.append("Brightness increased by 30%")
+        elif brightness > 0.8:
+            # Image is too bright, decrease brightness
+            processed = self.adjust_brightness(processed, factor=0.7)
+            improvements.append("Brightness decreased by 30%")
+            
+        # 2. Adjust contrast for better facial feature detection
+        # For facial analysis, slightly reducing contrast often helps
+        # with reducing shadows and improving feature detection
+        processed = self.adjust_contrast(processed, factor=0.7)
+        improvements.append("Contrast decreased by 30%")
+        
+        # 3. Resize if dimensions are not optimal
+        h, w = processed.shape[:2]
+        if w > self.max_width or h > self.max_height:
+            # Scale down to optimal size
+            processed = self.resize_image(processed, 
+                                         target_width=min(w, self.optimal_width),
+                                         target_height=min(h, self.optimal_height))
+            improvements.append(f"Resized to optimal dimensions")
+        
+        # Return results of preprocessing
+        return {
+            "original_image": original,
+            "processed_image": processed,
+            "improvements": improvements
+        }
+    
+    def resize_image(self, img: np.ndarray, target_width: int = None, target_height: int = None) -> np.ndarray:
+        """
+        Resize image to target dimensions while maintaining aspect ratio.
+        
+        Args:
+            img: The image as a numpy array
+            target_width: Target width for the resized image
+            target_height: Target height for the resized image
+            
+        Returns:
+            Resized image as a numpy array
+        """
+        if img is None or img.size == 0:
+            raise ValueError("Invalid image provided for resizing")
+            
+        # Get current dimensions
+        h, w = img.shape[:2]
+        
+        if target_width is None and target_height is None:
+            # If no target dimensions provided, use optimal values
+            target_width = self.optimal_width
+            target_height = self.optimal_height
+            
+        # Calculate aspect ratio
+        aspect = w / h
+        
+        # Determine new dimensions preserving aspect ratio
+        if target_width and not target_height:
+            # Width specified, calculate height
+            new_width = min(target_width, w)
+            new_height = int(new_width / aspect)
+        elif target_height and not target_width:
+            # Height specified, calculate width
+            new_height = min(target_height, h)
+            new_width = int(new_height * aspect)
+        else:
+            # Both dimensions specified, use the most constraining one
+            width_ratio = target_width / w
+            height_ratio = target_height / h
+            
+            if width_ratio < height_ratio:
+                new_width = target_width
+                new_height = int(target_width / aspect)
+            else:
+                new_height = target_height
+                new_width = int(target_height * aspect)
+        
+        # Resize the image
+        resized = cv2.resize(img, (new_width, new_height), interpolation=cv2.INTER_AREA)
+        
+        return resized
+    
+    def adjust_brightness(self, img: np.ndarray, factor: float = 1.0) -> np.ndarray:
+        """
+        Adjust image brightness.
+        
+        Args:
+            img: The image as a numpy array
+            factor: Brightness adjustment factor (1.0 = no change, >1.0 = brighter, <1.0 = darker)
+            
+        Returns:
+            Brightness-adjusted image as a numpy array
+        """
+        if img is None or img.size == 0:
+            raise ValueError("Invalid image provided for brightness adjustment")
+            
+        # Convert to HSV
+        hsv = cv2.cvtColor(img, cv2.COLOR_BGR2HSV)
+        
+        # Scale the V channel
+        hsv[:,:,2] = np.clip(hsv[:,:,2] * factor, 0, 255).astype(np.uint8)
+        
+        # Convert back to BGR
+        adjusted = cv2.cvtColor(hsv, cv2.COLOR_HSV2BGR)
+        
+        return adjusted
+    
+    def adjust_contrast(self, img: np.ndarray, factor: float = 1.0) -> np.ndarray:
+        """
+        Adjust image contrast.
+        
+        Args:
+            img: The image as a numpy array
+            factor: Contrast adjustment factor (1.0 = no change, >1.0 = more contrast, <1.0 = less contrast)
+            
+        Returns:
+            Contrast-adjusted image as a numpy array
+        """
+        if img is None or img.size == 0:
+            raise ValueError("Invalid image provided for contrast adjustment")
+            
+        # Apply contrast adjustment: pixel = (pixel - 127.5) * factor + 127.5
+        mean = 127.5
+        adjusted = np.clip((img.astype(np.float32) - mean) * factor + mean, 0, 255).astype(np.uint8)
+        
+        return adjusted
+    
+    def save_processed_image(self, img: np.ndarray) -> str:
+        """
+        Save a processed image to a temporary file.
+        
+        Args:
+            img: The processed image as a numpy array
+            
+        Returns:
+            Path to the saved temporary image file
+        """
+        if img is None or img.size == 0:
+            raise ValueError("Invalid image provided for saving")
+            
+        # Generate a unique filename
+        filename = f"processed_{uuid.uuid4()}.jpg"
+        filepath = os.path.join(self.temp_dir, filename)
+        
+        # Save the image
+        success, buffer = cv2.imencode('.jpg', img)
+        if not success:
+            raise ValueError("Failed to encode image")
+            
+        with open(filepath, 'wb') as f:
+            f.write(buffer)
+            
+        logger.info(f"Saved processed image to {filepath}")
+        
+        return filepath
+    
+    def save_uploaded_image(self, img: np.ndarray) -> str:
+        """
+        Save an uploaded image to a temporary file, ensuring correct color conversion.
+        
+        Args:
+            img: The image as a numpy array in BGR format (OpenCV default)
+            
+        Returns:
+            Path to the saved temporary image file
+        """
+        if img is None or img.size == 0:
+            raise ValueError("Invalid image provided for saving")
+            
+        # Create a unique filename
+        unique_id = str(uuid.uuid4())
+        temp_filename = f"uploaded_image_{unique_id}.jpg"
+        temp_path = os.path.join(self.temp_dir, temp_filename)
+        
+        # Convert BGR to RGB for correct color display
+        if len(img.shape) == 3 and img.shape[2] == 3:
+            # Convert BGR to RGB for proper display
+            img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+            
+            # Then convert RGB back to BGR for OpenCV to save correctly
+            img_to_save = cv2.cvtColor(img_rgb, cv2.COLOR_RGB2BGR)
+        else:
+            # If not a 3-channel image, just use as is
+            img_to_save = img
+        
+        # Save the image with high quality
+        cv2.imwrite(temp_path, img_to_save, [cv2.IMWRITE_JPEG_QUALITY, 95])
+        
+        logger.info(f"Saved uploaded image to {temp_path}")
+        return temp_path
+    
+    def encode_image_to_base64(self, img: np.ndarray) -> str:
+        """
+        Encode an image to base64 for embedding in HTML.
+        
+        Args:
+            img: Image as numpy array (RGB format)
+            
+        Returns:
+            Base64 encoded string
+        """
+        try:
+            # Ensure the image is in RGB format
+            img_rgb = img
+            if len(img.shape) == 3 and img.shape[2] == 3:
+                # Only convert if it's a 3-channel image (skip grayscale)
+                # Check if already RGB by looking at a known color pattern
+                # This is just a heuristic, not foolproof
+                img_rgb = img
+            
+            # Convert to PIL Image
+            pil_img = Image.fromarray(img_rgb)
+            
+            # Save to bytes buffer
+            buffer = io.BytesIO()
+            pil_img.save(buffer, format="JPEG")
+            buffer.seek(0)
+            
+            # Encode to base64
+            import base64
+            img_str = base64.b64encode(buffer.getvalue()).decode('utf-8')
+            
+            return img_str
+            
+        except Exception as e:
+            logger.error(f"Error encoding image to base64: {e}")
+            # Return empty string on error
+            return ""
+
+    def validate_image_file(self, file, check_content: bool = True, check_dimensions: bool = True) -> Dict[str, Any]:
+        """
+        Complete validation of an image file, checking format, dimensions and quality.
+        Combines Steps 2 & 3: Interface design, format validation,
+        and dimension/quality validation.
+        
+        Args:
+            file: The uploaded file object from Streamlit
+            check_content: Whether to also validate the file content
+            check_dimensions: Whether to validate image dimensions and quality
+            
+        Returns:
+            Dict with validation results and messages
+        """
+        result = {
+            "valid": False,
+            "messages": [],
+            "warnings": [],
+            "file_info": {},
+            "dimensions": {},
+            "quality": {}
+        }
+        
+        if file is None:
+            result["messages"].append("No file selected.")
+            return result
+            
+        # Validate file extension
+        ext_valid, ext_msg = self.validate_file_extension(file.name)
+        result["messages"].append(ext_msg)
+        
+        if not ext_valid:
+            return result
+            
+        # Check file size
+        file_size = len(file.getvalue())
+        result["file_info"]["size"] = file_size
+        result["file_info"]["name"] = file.name
+        
+        if file_size > self.max_file_size:
+            result["messages"].append(f"File is too large. Maximum size: {self.max_file_size/1024/1024:.1f}MB")
+            return result
+            
+        # Validate MIME type if requested
+        if check_content:
+            mime_valid, mime_msg = self.validate_file_mime(file.getvalue())
+            result["messages"].append(mime_msg)
+            
+            if not mime_valid:
+                return result
+        
+        # STEP 3: Validate dimensions and quality if requested
+        if check_dimensions:
+            try:
+                # Convert file to image for analysis
+                file_bytes = np.asarray(bytearray(file.getvalue()), dtype=np.uint8)
+                img = cv2.imdecode(file_bytes, cv2.IMREAD_COLOR)
+                
+                # Validate dimensions
+                dimension_results = self.validate_image_dimensions(img)
+                result["dimensions"] = dimension_results
+                
+                # Add dimension warnings to main result
+                result["warnings"].extend(dimension_results.get("warnings", []))
+                result["messages"].extend(dimension_results.get("messages", []))
+                
+                # If dimensions are invalid, mark the entire result as invalid
+                if not dimension_results.get("valid", True):
+                    result["valid"] = False
+                    return result
+                
+                # Check quality
+                quality_results = self.check_image_quality(img)
+                result["quality"] = quality_results
+                
+                # Add quality warnings
+                result["warnings"].extend(quality_results.get("warnings", []))
+                
+                # Add suggestions as messages
+                for suggestion in quality_results.get("suggestions", []):
+                    result["messages"].append(suggestion)
+                
+            except Exception as e:
+                logger.error(f"Error validating image dimensions/quality: {e}")
+                result["warnings"].append(f"Could not validate dimensions or quality: {str(e)}")
+                
+        # All validations passed
+        result["valid"] = True
+        return result
+        
+    def setup_image_upload_interface(self, st):
+        """
+        Implements the image upload interface according to specification.
+        Combines Steps 1, 2 & 3: Interface design, format validation,
+        and dimension/quality validation.
+        
+        Args:
+            st: The Streamlit module instance
+            
+        Returns:
+            The uploaded_file object if valid, None otherwise
+        """
+        st.subheader("1. Image Upload and Validation")
+        
+        # Clear information about supported formats
+        st.info(f"Please upload an image for facial analysis. {self.get_format_info()}")
+        
+        # Implement the file selection component
+        uploaded_file = st.file_uploader(
+            "Select an image", 
+            type=self.get_supported_formats(),
+            help="Use clear, well-lit images for best results."
+        )
+        
+        # Implement validation if a file is uploaded
+        if uploaded_file is not None:
+            with st.spinner("Validating image..."):
+                # Complete validation including dimensions and quality (Step 3)
+                validation_result = self.validate_image_file(
+                    uploaded_file, 
+                    check_content=True,
+                    check_dimensions=True
+                )
+                
+                # Display validation results with a space-efficient two-column layout
+                if validation_result["valid"]:
+                    # Basic file information
+                    file_info = validation_result["file_info"]
+                    size_kb = file_info["size"] / 1024
+                    st.success(f"✅ Valid image: {file_info['name']} ({size_kb:.1f} KB)")
+                    
+                    # Create two columns for better space usage
+                    image_col, info_col = st.columns([1, 1])
+                    
+                    with image_col:
+                        # Display the image
+                        try:
+                            # Convert the uploaded file to a format that can be displayed
+                            file_bytes = np.asarray(bytearray(uploaded_file.read()), dtype=np.uint8)
+                            img = cv2.imdecode(file_bytes, cv2.IMREAD_COLOR)
+                            img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+                            
+                            # Reset file pointer for subsequent reads
+                            uploaded_file.seek(0)
+                            
+                            # Display the image in the left column
+                            st.image(img_rgb, caption="Uploaded Image", use_column_width=True)
+                        except Exception as e:
+                            st.warning(f"Could not display image preview: {str(e)}")
+                    
+                    with info_col:
+                        # Create a compact display for all image information
+                        st.markdown("### Image Analysis")
+                        
+                        # STEP 3: Show dimension information compactly
+                        if "dimensions" in validation_result and validation_result["dimensions"]:
+                            dims = validation_result["dimensions"]
+                            if "width" in dims and "height" in dims:
+                                dim_status = "✅ Optimal" if "optimal" in " ".join(dims.get("messages", [])).lower() else "ℹ️ Acceptable"
+                                st.write(f"**Dimensions:** {dims['width']}x{dims['height']} pixels ({dim_status})")
+                        
+                        # STEP 3: Show quality information with a more compact UI
+                        if "quality" in validation_result and validation_result["quality"]:
+                            quality = validation_result["quality"]
+                            if "quality_score" in quality:
+                                # Convert quality score to percentage
+                                quality_percent = int(quality["quality_score"] * 100)
+                                
+                                # Show quality with a more compact display
+                                quality_label = "Good" if quality_percent >= 70 else "Fair" if quality_percent >= 40 else "Low"
+                                
+                                # Display quality score with progress bar
+                                st.write(f"**Image Quality:** {quality_percent}% ({quality_label})")
+                                st.progress(quality_percent/100)
+                                
+                                # Show metrics in a more compact way
+                                metrics_cols = st.columns(3)
+                                with metrics_cols[0]:
+                                    st.metric("Sharpness", "Good" if not quality["is_blurry"] else "Poor")
+                                with metrics_cols[1]:
+                                    st.metric("Brightness", f"{int(quality['brightness']*100)}%")
+                                with metrics_cols[2]:
+                                    st.metric("Contrast", f"{int(quality['contrast']*100)}%")
+                        
+                        # Show any warnings in a compact expandable section
+                        if validation_result.get("warnings", []):
+                            with st.expander("⚠️ Recommendations"):
+                                for i, warning in enumerate(validation_result.get("warnings", [])):
+                                    st.write(f"{i+1}. {warning}")
+                else:
+                    # Handle invalid images - show error messages
+                    # Separate error messages and informational messages
+                    error_messages = []
+                    info_messages = []
+                    
+                    for message in validation_result["messages"]:
+                        if "invalid" in message.lower() or "unsupported" in message.lower() or "error" in message.lower():
+                            error_messages.append(message)
+                        elif "valid" in message.lower():
+                            info_messages.append(message)
+                    
+                    # Display error messages
+                    for msg in error_messages:
+                        st.error(f"❌ {msg}")
+                    
+                    # If there are errors, show instructions for correction
+                    if error_messages:
+                        st.warning("""
+                        Please select an image that meets the following requirements:
+                        - Format: JPG, JPEG or PNG
+                        - Maximum size: 10MB
+                        - Minimum resolution: 320x240 pixels
+                        """)
+                        
+                        # If there are critical errors, return None to prevent further processing
+                        return None
+        
+        return uploaded_file

services/model_service.py

@@ -0,0 +1,113 @@
+"""
+Model service for EmotionMirror application.
+Handles loading and management of YOLO models.
+"""
+import os
+import logging
+from typing import Dict, Any, Optional
+import torch
+from ultralytics import YOLO
+
+from config import settings
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+class ModelService:
+    """Service for managing YOLO models"""
+    
+    _instance = None
+    _models = {}
+    
+    def __new__(cls):
+        """Singleton pattern implementation"""
+        if cls._instance is None:
+            cls._instance = super(ModelService, cls).__new__(cls)
+            cls._instance._initialized = False
+        return cls._instance
+    
+    def __init__(self):
+        """Initialize the model service"""
+        if self._initialized:
+            return
+            
+        self._initialized = True
+        logger.info("Initializing ModelService")
+    
+    def load_model(self, model_type: str) -> Optional[YOLO]:
+        """
+        Load a YOLO model based on the specified type.
+        
+        Args:
+            model_type: Type of model to load (detection, segmentation, pose, classification)
+            
+        Returns:
+            YOLO model instance or None if loading fails
+        """
+        # Check if model is already loaded
+        if model_type in self._models:
+            logger.info(f"Using cached model for {model_type}")
+            return self._models[model_type]
+            
+        # Check if model type is valid
+        if model_type not in settings.MODEL_MAPPING:
+            logger.error(f"Invalid model type: {model_type}")
+            return None
+            
+        try:
+            model_file = settings.MODEL_MAPPING[model_type]
+            logger.info(f"Loading {model_type} model: {model_file}")
+            
+            # Try to load from local models directory first
+            model_path = os.path.join(settings.MODELS_DIR, model_file)
+            
+            if os.path.exists(model_path):
+                logger.info(f"Loading model from local path: {model_path}")
+                model = YOLO(model_path)
+            else:
+                # Fall back to downloading from Ultralytics
+                logger.info(f"Model not found locally, downloading from Ultralytics: {model_file}")
+                model = YOLO(model_file)
+            
+            # Cache the loaded model
+            self._models[model_type] = model
+            return model
+            
+        except Exception as e:
+            logger.error(f"Error loading model {model_type}: {str(e)}")
+            return None
+    
+    def get_model_info(self, model_type: str) -> Dict[str, Any]:
+        """
+        Get information about a specific model.
+        
+        Args:
+            model_type: Type of model
+            
+        Returns:
+            Dictionary with model information
+        """
+        if model_type not in settings.MODEL_MAPPING:
+            return {"error": f"Invalid model type: {model_type}"}
+            
+        model_file = settings.MODEL_MAPPING[model_type]
+        model_path = os.path.join(settings.MODELS_DIR, model_file)
+        
+        return {
+            "type": model_type,
+            "file": model_file,
+            "available_locally": os.path.exists(model_path),
+            "is_loaded": model_type in self._models
+        }
+    
+    def get_available_models(self) -> Dict[str, Dict[str, Any]]:
+        """
+        Get information about all available models.
+        
+        Returns:
+            Dictionary with information about all available models
+        """
+        models_info = {}
+        for model_type in settings.MODEL_MAPPING:
+            models_info[model_type] = self.get_model_info(model_type)
+        return models_info

utils/__init__.py

@@ -0,0 +1,4 @@
+"""
+Utilities package for EmotionMirror application.
+Contains helper functions and utility classes.
+"""

utils/download_models.py

@@ -0,0 +1,100 @@
+"""
+Script para descargar modelos adicionales necesarios para EmotionMirror
+"""
+import os
+import sys
+import logging
+import requests
+import bz2
+import shutil
+from pathlib import Path
+
+# Configurar logging
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+logger = logging.getLogger(__name__)
+
+# URL del modelo de landmarks faciales
+LANDMARKS_MODEL_URL = "http://dlib.net/files/shape_predictor_68_face_landmarks.dat.bz2"
+
+def get_project_root():
+    """Obtiene la ruta raíz del proyecto"""
+    path = Path(__file__).parent.parent
+    return path
+
+def create_models_dir():
+    """Crea el directorio de modelos si no existe"""
+    root = get_project_root()
+    models_dir = root / "models"
+    models_dir.mkdir(exist_ok=True)
+    return models_dir
+
+def download_file(url, destination):
+    """Descarga un archivo desde una URL"""
+    try:
+        logger.info(f"Descargando {url} en {destination}")
+        response = requests.get(url, stream=True)
+        response.raise_for_status()  # Verificar si hay errores
+        
+        with open(destination, 'wb') as f:
+            for chunk in response.iter_content(chunk_size=8192):
+                if chunk:
+                    f.write(chunk)
+        
+        logger.info(f"Descarga completada: {destination}")
+        return True
+    except Exception as e:
+        logger.error(f"Error descargando archivo: {e}")
+        return False
+
+def extract_bz2(source, destination):
+    """Extrae un archivo .bz2 a un destino"""
+    try:
+        logger.info(f"Descomprimiendo {source} en {destination}")
+        with bz2.BZ2File(source, 'rb') as source_file:
+            with open(destination, 'wb') as dest_file:
+                shutil.copyfileobj(source_file, dest_file)
+        
+        logger.info(f"Descompresión completada: {destination}")
+        return True
+    except Exception as e:
+        logger.error(f"Error descomprimiendo archivo: {e}")
+        return False
+
+def download_landmarks_model():
+    """Descarga y configura el modelo de landmarks faciales"""
+    models_dir = create_models_dir()
+    model_compressed = models_dir / "shape_predictor_68_face_landmarks.dat.bz2"
+    model_path = models_dir / "shape_predictor_68_face_landmarks.dat"
+    
+    # Verificar si el modelo ya existe
+    if model_path.exists():
+        logger.info(f"El modelo ya existe en {model_path}")
+        return True
+    
+    # Descargar el modelo comprimido
+    if not download_file(LANDMARKS_MODEL_URL, model_compressed):
+        return False
+    
+    # Extraer el modelo
+    if not extract_bz2(model_compressed, model_path):
+        return False
+    
+    # Eliminar el archivo comprimido después de extraerlo
+    try:
+        os.remove(model_compressed)
+        logger.info(f"Archivo comprimido eliminado: {model_compressed}")
+    except Exception as e:
+        logger.warning(f"No se pudo eliminar el archivo comprimido: {e}")
+    
+    return True
+
+if __name__ == "__main__":
+    logger.info("Iniciando descarga de modelos adicionales...")
+    
+    if download_landmarks_model():
+        logger.info("Modelo de landmarks faciales descargado correctamente.")
+    else:
+        logger.error("Error descargando el modelo de landmarks faciales.")
+        sys.exit(1)
+    
+    logger.info("Todos los modelos han sido descargados correctamente.")

utils/export_utils.py

@@ -0,0 +1,201 @@
+"""
+Export Utilities for EmotionMirror Application
+
+This module provides functions for exporting analysis data to various formats,
+including CSV, JSON, and visual reports.
+"""
+
+import os
+import csv
+import json
+import logging
+from typing import Dict, List, Any, Optional
+from datetime import datetime
+import pandas as pd
+import base64
+from io import BytesIO, StringIO
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+def export_to_json(data: Dict[str, Any], filepath: Optional[str] = None) -> str:
+    """
+    Export data to JSON format.
+    
+    Args:
+        data: Data to export
+        filepath: Optional path to save the JSON file
+        
+    Returns:
+        JSON string if filepath is None, else filepath where saved
+    """
+    try:
+        json_str = json.dumps(data, indent=4)
+        
+        if filepath:
+            with open(filepath, 'w', encoding='utf-8') as f:
+                f.write(json_str)
+            logger.info(f"Data exported to JSON file: {filepath}")
+            return filepath
+        
+        return json_str
+    
+    except Exception as e:
+        logger.error(f"Error exporting data to JSON: {e}")
+        raise
+
+def export_to_csv(data: Dict[str, Any], filepath: Optional[str] = None) -> str:
+    """
+    Export analysis data to CSV format.
+    
+    Args:
+        data: Analysis data to export
+        filepath: Optional path to save the CSV file
+        
+    Returns:
+        CSV string if filepath is None, else filepath where saved
+    """
+    try:
+        # Flatten the data structure for CSV format
+        rows = []
+        
+        for analysis in data.get('analyses', []):
+            base_row = {
+                'analysis_id': analysis.get('id'),
+                'session_id': analysis.get('session_id'),
+                'timestamp': analysis.get('timestamp'),
+                'image_path': analysis.get('image_path'),
+                'face_count': analysis.get('face_count')
+            }
+            
+            # Add tags if present
+            if analysis.get('tags'):
+                base_row['tags'] = ','.join(analysis['tags'])
+            
+            # Add face-specific data
+            for i, face in enumerate(analysis.get('faces', [])):
+                row = base_row.copy()
+                row['face_index'] = i
+                row['emotion'] = face.get('emotion')
+                row['confidence'] = face.get('confidence')
+                
+                # Add feature values
+                for feature, value in face.get('features', {}).items():
+                    row[f'feature_{feature}'] = value
+                
+                # Add emotion values
+                for emotion, value in face.get('emotions', {}).items():
+                    row[f'emotion_{emotion}'] = value
+                
+                rows.append(row)
+        
+        if not rows:
+            logger.warning("No data to export to CSV")
+            return "" if filepath is None else filepath
+        
+        # Create a DataFrame and export to CSV
+        df = pd.DataFrame(rows)
+        
+        if filepath:
+            df.to_csv(filepath, index=False)
+            logger.info(f"Data exported to CSV file: {filepath}")
+            return filepath
+        
+        # Return CSV string if no filepath provided
+        csv_buffer = StringIO()
+        df.to_csv(csv_buffer, index=False)
+        return csv_buffer.getvalue()
+    
+    except Exception as e:
+        logger.error(f"Error exporting data to CSV: {e}")
+        raise
+
+def get_download_link(content: str, filename: str, mimetype: str) -> str:
+    """
+    Generate a download link for the content.
+    
+    Args:
+        content: String content to download
+        filename: Name for the downloaded file
+        mimetype: MIME type of the file
+        
+    Returns:
+        HTML download link
+    """
+    try:
+        b64 = base64.b64encode(content.encode()).decode()
+        href = f'data:{mimetype};base64,{b64}'
+        return f'<a href="{href}" download="{filename}" class="download-button">Download {filename}</a>'
+    
+    except Exception as e:
+        logger.error(f"Error creating download link: {e}")
+        return ""
+
+def generate_emotion_summary(data: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Generate a summary of emotion data across multiple analyses.
+    
+    Args:
+        data: Dictionary of analysis data
+        
+    Returns:
+        Dictionary with summarized emotion data
+    """
+    try:
+        # Initialize counters
+        emotion_counts = {}
+        total_faces = 0
+        emotion_confidence = {}
+        
+        # Process each analysis
+        for analysis in data.get('analyses', []):
+            for face in analysis.get('faces', []):
+                # Count primary emotions
+                emotion = face.get('emotion')
+                if emotion:
+                    emotion_counts[emotion] = emotion_counts.get(emotion, 0) + 1
+                    
+                    # Track confidence values
+                    if emotion not in emotion_confidence:
+                        emotion_confidence[emotion] = []
+                    emotion_confidence[emotion].append(face.get('confidence', 0))
+                    
+                    total_faces += 1
+        
+        # Calculate statistics
+        if total_faces > 0:
+            # Calculate percentages
+            emotion_percentages = {
+                emotion: (count / total_faces) * 100 
+                for emotion, count in emotion_counts.items()
+            }
+            
+            # Calculate average confidence per emotion
+            avg_confidence = {
+                emotion: sum(values) / len(values) 
+                for emotion, values in emotion_confidence.items() if values
+            }
+            
+            return {
+                'total_analyses': len(data.get('analyses', [])),
+                'total_faces': total_faces,
+                'emotion_counts': emotion_counts,
+                'emotion_percentages': emotion_percentages,
+                'avg_confidence': avg_confidence
+            }
+        
+        return {
+            'total_analyses': len(data.get('analyses', [])),
+            'total_faces': 0,
+            'emotion_counts': {},
+            'emotion_percentages': {},
+            'avg_confidence': {}
+        }
+    
+    except Exception as e:
+        logger.error(f"Error generating emotion summary: {e}")
+        return {
+            'error': str(e),
+            'total_analyses': 0,
+            'total_faces': 0
+        }

utils/file_utils.py

@@ -0,0 +1,69 @@
+"""
+File utility functions for EmotionMirror application.
+"""
+import os
+import uuid
+import logging
+from typing import Set, Optional, Tuple
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+def allowed_file(filename: str, allowed_extensions: Set[str]) -> bool:
+    """
+    Check if a file has an allowed extension.
+    
+    Args:
+        filename: Name of the file to check
+        allowed_extensions: Set of allowed extensions
+        
+    Returns:
+        True if file extension is allowed, False otherwise
+    """
+    if '.' not in filename:
+        return False
+    extension = filename.rsplit('.', 1)[1].lower()
+    return extension in allowed_extensions
+
+def generate_unique_filename(filename: str) -> str:
+    """
+    Generate a unique filename preserving the original extension.
+    
+    Args:
+        filename: Original filename
+        
+    Returns:
+        Unique filename with original extension
+    """
+    if '.' not in filename:
+        return f"{uuid.uuid4().hex}"
+    
+    extension = filename.rsplit('.', 1)[1].lower()
+    return f"{uuid.uuid4().hex}.{extension}"
+
+def save_uploaded_file(uploaded_file, upload_dir: str) -> Tuple[bool, str, Optional[str]]:
+    """
+    Save an uploaded file to the specified directory.
+    
+    Args:
+        uploaded_file: File object from Streamlit
+        upload_dir: Directory to save the file
+        
+    Returns:
+        Tuple of (success, message, file_path)
+    """
+    try:
+        os.makedirs(upload_dir, exist_ok=True)
+        
+        # Generate unique filename
+        unique_filename = generate_unique_filename(uploaded_file.name)
+        file_path = os.path.join(upload_dir, unique_filename)
+        
+        # Save the file
+        with open(file_path, "wb") as f:
+            f.write(uploaded_file.getbuffer())
+            
+        return True, f"File saved successfully as {unique_filename}", file_path
+    except Exception as e:
+        logger.error(f"Error saving file: {e}")
+        return False, f"Error saving file: {str(e)}", None

utils/image_visualization.py

@@ -0,0 +1,283 @@
+"""
+Image Visualization Module for EmotionMirror application.
+
+This module contains functions for visualizing images with interactive controls
+such as zoom, pan, and reset functionality.
+"""
+import streamlit as st
+import numpy as np
+from PIL import Image
+import io
+import logging
+import base64
+from typing import Dict, Any, Tuple, Optional
+
+logger = logging.getLogger(__name__)
+
+def get_image_download_link(img, filename="emotion_mirror_image.png", text="Download Image"):
+    """
+    Generate a download link for an image.
+    
+    Args:
+        img: PIL Image or numpy array
+        filename: Name of the file to download
+        text: Text to display for the download link
+        
+    Returns:
+        HTML string with download link
+    """
+    try:
+        # Convert numpy array to PIL Image if necessary
+        if isinstance(img, np.ndarray):
+            img_pil = Image.fromarray(img)
+        else:
+            img_pil = img
+            
+        # Create a byte buffer
+        buffered = io.BytesIO()
+        img_pil.save(buffered, format="PNG")
+        
+        # Encode the bytes to base64
+        img_str = base64.b64encode(buffered.getvalue()).decode()
+        
+        # Create download link HTML
+        href = f'<a href="data:file/png;base64,{img_str}" download="{filename}">{text}</a>'
+        return href
+    except Exception as e:
+        logger.error(f"Error creating image download link: {e}")
+        return None
+
+def display_image_with_controls(image, 
+                              title: str = "Image Viewer", 
+                              allow_zoom: bool = True,
+                              allow_download: bool = True) -> Dict[str, Any]:
+    """
+    Display an image with zoom, pan and reset controls.
+    
+    Args:
+        image: PIL Image or numpy array to display
+        title: Title to display above the image
+        allow_zoom: Whether to show zoom controls
+        allow_download: Whether to show download option
+        
+    Returns:
+        Dict containing the status and any relevant info
+    """
+    try:
+        # Ensure image is not None
+        if image is None:
+            return {"success": False, "message": "No image provided"}
+            
+        # Convert numpy array to PIL Image if necessary
+        if isinstance(image, np.ndarray):
+            pil_image = Image.fromarray(image)
+        else:
+            pil_image = image
+        
+        # Store original image dimensions
+        original_width, original_height = pil_image.size
+        
+        # Create container for image display
+        st.subheader(title)
+        
+        # Image controls in columns for better layout
+        col1, col2, col3 = st.columns([1, 2, 1])
+        
+        # Zoom functionality
+        zoom_factor = 1.0
+        if allow_zoom:
+            with col1:
+                zoom_factor = st.slider(
+                    "Zoom", 
+                    min_value=0.5, 
+                    max_value=2.0, 
+                    value=1.0, 
+                    step=0.1,
+                    help="Adjust the zoom level of the image"
+                )
+        
+        # Reset button in the third column
+        with col3:
+            reset_pressed = st.button("Reset View", help="Reset zoom and view settings")
+            if reset_pressed:
+                zoom_factor = 1.0
+                st.session_state.zoom_factor = 1.0  # Store in session state
+                
+        # Apply zoom if needed
+        if zoom_factor != 1.0:
+            # Calculate new dimensions
+            new_width = int(original_width * zoom_factor)
+            new_height = int(original_height * zoom_factor)
+            
+            # Resize the image
+            resized_image = pil_image.resize((new_width, new_height), Image.LANCZOS)
+        else:
+            resized_image = pil_image
+        
+        # Display the image
+        st.image(resized_image, use_column_width=True)
+        
+        # Add download option
+        if allow_download:
+            download_link = get_image_download_link(pil_image)
+            if download_link:
+                st.markdown(download_link, unsafe_allow_html=True)
+                
+        return {
+            "success": True, 
+            "zoom_factor": zoom_factor,
+            "image_dimensions": (original_width, original_height),
+            "displayed_dimensions": resized_image.size
+        }
+        
+    except Exception as e:
+        logger.error(f"Error displaying image with controls: {e}")
+        return {"success": False, "message": str(e)}
+
+def handle_image_viewer(image_data, 
+                      title: str = "Image Viewer", 
+                      description: str = None,
+                      allow_zoom: bool = True, 
+                      allow_reset: bool = True,
+                      allow_download: bool = True) -> Dict[str, Any]:
+    """
+    Complete image viewer with all controls and options.
+    
+    Args:
+        image_data: PIL Image or numpy array
+        title: Title for the image viewer
+        description: Optional description text
+        allow_zoom: Whether to include zoom controls
+        allow_reset: Whether to include reset button
+        allow_download: Whether to include download option
+        
+    Returns:
+        Dict containing status and control information
+    """
+    st.subheader(title)
+    
+    if description:
+        st.markdown(description)
+    
+    # Create container for the viewer
+    viewer_container = st.container()
+    
+    with viewer_container:
+        # Create a two-column layout for controls and image
+        control_col, image_col = st.columns([1, 3])
+        
+        with control_col:
+            st.markdown("### Controls")
+            
+            # Zoom controls
+            zoom_factor = 1.0
+            if allow_zoom:
+                zoom_factor = st.slider(
+                    "Zoom", 
+                    min_value=0.5, 
+                    max_value=3.0, 
+                    value=1.0, 
+                    step=0.1,
+                    help="Adjust the zoom level"
+                )
+            
+            # Reset button
+            if allow_reset:
+                if st.button("Reset View", key="reset_view"):
+                    zoom_factor = 1.0
+                    # Reset any other relevant state
+            
+            # Add some spacing
+            st.markdown("<br>", unsafe_allow_html=True)
+            
+            # Download option
+            if allow_download and image_data is not None:
+                download_link = get_image_download_link(image_data)
+                if download_link:
+                    st.markdown("### Download")
+                    st.markdown(download_link, unsafe_allow_html=True)
+        
+        with image_col:
+            if image_data is not None:
+                # Process the image based on controls
+                try:
+                    # Convert to PIL if numpy array
+                    if isinstance(image_data, np.ndarray):
+                        pil_image = Image.fromarray(image_data)
+                    else:
+                        pil_image = image_data
+                    
+                    # Apply zoom if needed
+                    if zoom_factor != 1.0:
+                        original_width, original_height = pil_image.size
+                        new_width = int(original_width * zoom_factor)
+                        new_height = int(original_height * zoom_factor)
+                        displayed_image = pil_image.resize((new_width, new_height), Image.LANCZOS)
+                    else:
+                        displayed_image = pil_image
+                        
+                    # Display the image
+                    st.image(displayed_image, use_column_width=True)
+                    
+                    return {
+                        "success": True,
+                        "zoom_factor": zoom_factor,
+                        "image_displayed": True
+                    }
+                    
+                except Exception as e:
+                    st.error(f"Error displaying image: {str(e)}")
+                    logger.error(f"Error in image viewer: {e}")
+                    return {"success": False, "message": str(e)}
+            else:
+                st.info("No image to display. Please upload an image first.")
+                return {"success": False, "message": "No image data provided"}
+
+def create_image_tabs(original_image, processed_image=None):
+    """
+    Create tabs to display original and processed images side by side.
+    
+    Args:
+        original_image: The original image (PIL or numpy array)
+        processed_image: The processed image (PIL or numpy array), optional
+        
+    Returns:
+        Dict with status information
+    """
+    # Create tabs
+    if processed_image is not None:
+        tab1, tab2 = st.tabs(["Original Image", "Processed Image"])
+        
+        with tab1:
+            result1 = display_image_with_controls(
+                original_image, 
+                title="Original Image", 
+                allow_zoom=True,
+                allow_download=True
+            )
+            
+        with tab2:
+            result2 = display_image_with_controls(
+                processed_image, 
+                title="Processed Image", 
+                allow_zoom=True,
+                allow_download=True
+            )
+            
+        return {
+            "success": result1.get("success", False) and result2.get("success", False),
+            "tabs_created": True
+        }
+    else:
+        # Only original image available
+        result = display_image_with_controls(
+            original_image, 
+            title="Uploaded Image", 
+            allow_zoom=True,
+            allow_download=True
+        )
+        
+        return {
+            "success": result.get("success", False),
+            "tabs_created": False
+        }

utils/page_handlers.py

@@ -0,0 +1,290 @@
+"""
+Page Handlers Module for EmotionMirror application.
+
+This module contains handler functions for different pages in the EmotionMirror application.
+Following the principle of modularization, each page's logic is separated into its own function.
+"""
+import logging
+import streamlit as st
+import cv2
+import numpy as np
+from utils.preprocessing_ui import show_preprocessing_ui, get_processing_image
+from utils.image_visualization import display_image_with_controls, create_image_tabs, handle_image_viewer
+from PIL import Image
+import io
+import os
+import json
+import time
+from typing import Dict, Any
+from datetime import datetime
+from utils.export_utils import export_to_json, export_to_csv, get_download_link, generate_emotion_summary
+
+logger = logging.getLogger(__name__)
+
+def handle_visual_analysis(agent_manager, image_service, db_service, uploaded_file=None):
+    """
+    Handle the Visual Analysis page logic.
+    
+    Args:
+        agent_manager: The agent manager instance
+        image_service: The image service instance
+        db_service: The database service instance
+        uploaded_file: The uploaded file, if any
+    """
+    st.header("Visual Emotion Analysis")
+    st.markdown("""
+    Upload an image to analyze emotions. 
+    For best results, use a clear image of a face with good lighting.
+    """)
+    
+    # Ensure agent_manager is properly initialized
+    if not agent_manager:
+        st.error("Agent manager is not initialized correctly. Please refresh the page.")
+        return
+        
+    # Initialize the visual agent at the start
+    visual_agent = agent_manager.get_agent("VisualAgent")
+    if not visual_agent:
+        st.warning("Visual agent not available. The system is initializing or there is a configuration issue.")
+        logger.error("Failed to get VisualAgent from agent_manager")
+    
+    # Create numbered sections to match local version
+    st.subheader("1. Upload an Image")
+    
+    # Add reset button for clearing current image
+    if "original_image" in st.session_state:
+        col1, col2 = st.columns([3, 1])
+        with col2:
+            if st.button("Clear Current Image", key="clear_image"):
+                # Clear the session state
+                if "original_image" in st.session_state:
+                    del st.session_state["original_image"]
+                if "processed_image" in st.session_state:
+                    del st.session_state["processed_image"]
+                if "current_image_path" in st.session_state:
+                    del st.session_state["current_image_path"]
+                st.experimental_rerun()
+    
+    # Create file uploader
+    if uploaded_file is None:
+        uploaded_file = st.file_uploader(
+            "Choose an image...", 
+            type=["jpg", "jpeg", "png"], 
+            help="Upload a clear image of a face for analysis."
+        )
+        
+    # Display information about detection methods
+    with st.expander("About the Detection Methods", expanded=False):
+        st.markdown("""
+        ### About the Detection Methods
+        
+        Currently using: **Advanced Detection**
+        
+        * **Basic detection** is faster but less accurate. It works by analyzing simple facial features.
+        * **Advanced detection (DeepFace)** uses deep learning models that are trained on thousands of faces to recognize subtle emotional cues.
+        
+        You can change the default detection method in the sidebar settings.
+        """)
+    
+    # Display image and interface when uploaded
+    if uploaded_file is not None:
+        try:
+            # Process the uploaded file
+            file_bytes = np.asarray(bytearray(uploaded_file.read()), dtype=np.uint8)
+            uploaded_file.seek(0)  # Reset the file pointer for further processing
+            
+            # Validate image file - includes format, size, and dimensions
+            validation_result = image_service.validate_image_file(
+                uploaded_file,
+                check_content=True,
+                check_dimensions=True
+            )
+            
+            # If the image is valid, process it
+            if validation_result["valid"]:
+                # Process the uploaded image to improve quality if possible
+                try:
+                    # Load image for processing with OpenCV (this will be in BGR format)
+                    img = cv2.imdecode(file_bytes, cv2.IMREAD_COLOR)
+                    
+                    # Convert from BGR to RGB for preprocessing display
+                    img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+                    
+                    # Store original RGB image for display
+                    if "original_image" not in st.session_state:
+                        st.session_state.original_image = img_rgb.copy()
+                    
+                    # Determine which image to process based on preprocessing settings
+                    use_improved = st.session_state.get("use_improved_image", False)
+                    
+                    # Choose image for processing
+                    img_to_process = get_processing_image(img_rgb, image_service, use_improved)
+                    
+                    # Step 5: Display the image with visualization controls
+                    st.subheader("2. Image Visualization")
+                    st.markdown("""
+                    View the uploaded image with basic controls. You can:
+                    - Zoom in/out to see details
+                    - Reset view to original size
+                    - Download the current image
+                    """)
+                    
+                    # Check if we have both original and processed images
+                    if "processed_image" in st.session_state:
+                        # Create tabs to display original and processed images
+                        image_tabs_result = create_image_tabs(
+                            st.session_state.original_image,
+                            st.session_state.processed_image
+                        )
+                    else:
+                        # Display just the original image
+                        display_result = display_image_with_controls(
+                            st.session_state.original_image,
+                            title="Uploaded Image",
+                            allow_zoom=True,
+                            allow_download=True
+                        )
+                        
+                        # Store the processed image if available for comparison
+                        if use_improved and img_to_process is not None:
+                            st.session_state.processed_image = img_to_process
+                    
+                    # Add space between sections
+                    st.markdown("<div style='height: 20px;'></div>", unsafe_allow_html=True)
+                    
+                    # Display image analysis from validation
+                    st.subheader("3. Image Analysis")
+                    analysis_expander = st.expander("View Image Analysis Details", expanded=False)
+                    
+                    with analysis_expander:
+                        # Show image metadata
+                        if "image_metadata" in validation_result:
+                            metadata = validation_result["image_metadata"]
+                            st.markdown("#### Image Details")
+                            
+                            # Create columns for metadata display
+                            meta_cols = st.columns(3)
+                            
+                            with meta_cols[0]:
+                                st.markdown("**Dimensions**")
+                                width = metadata.get("width", 0)
+                                height = metadata.get("height", 0)
+                                st.write(f"{width} × {height}")
+                                
+                            with meta_cols[1]:
+                                st.markdown("**Format**")
+                                img_format = metadata.get("format", "Unknown")
+                                st.write(f"{img_format}")
+                                
+                            with meta_cols[2]:
+                                st.markdown("**Size**")
+                                size_kb = metadata.get("size_kb", 0)
+                                st.write(f"{size_kb:.1f} KB")
+                            
+                            # Quality metrics if available
+                            if "quality" in metadata:
+                                st.markdown("#### Quality Metrics")
+                                quality = metadata["quality"]
+                                
+                                # Create columns for quality metrics
+                                metric_cols = st.columns(3)
+                                
+                                with metric_cols[0]:
+                                    st.markdown("**Sharpness**")
+                                    sharpness = int(quality.get("sharpness", 0) * 100)
+                                    st.write(f"{sharpness}%")
+                                    
+                                with metric_cols[1]:
+                                    st.markdown("**Brightness**")
+                                    brightness = int(quality.get("brightness", 0) * 100)
+                                    st.write(f"{brightness}%")
+                                    
+                                with metric_cols[2]:
+                                    st.markdown("**Contrast**")
+                                    contrast = int(quality.get("contrast", 0.26) * 100)
+                                    st.write(f"{contrast}%")
+                    
+                    # Add space between sections
+                    st.markdown("<div style='height: 20px;'></div>", unsafe_allow_html=True)
+                    
+                    # NOW display the preprocessing UI AFTER the Image Analysis section
+                    st.subheader("4. Image Preprocessing")
+                    preprocessing_result = show_preprocessing_ui(image_service, img_rgb)
+                    
+                    if not preprocessing_result.get("success", False):
+                        st.error(f"Error in preprocessing: {preprocessing_result.get('message', 'Unknown error')}")
+                    
+                    # Store path in session state for future use
+                    if "current_image_path" not in st.session_state:
+                        # Save the file for reference
+                        save_path = image_service.save_uploaded_image(img_to_process)
+                        st.session_state["current_image_path"] = save_path
+                    
+                    # Add some space to improve layout
+                    st.markdown("<div style='height: 20px;'></div>", unsafe_allow_html=True)
+                    
+                    # Analysis section
+                    st.subheader("5. Emotion Analysis")
+                    st.info("Image successfully uploaded. Emotion analysis functionality will be available soon.")
+                    
+                    # Add a disabled button as placeholder for future functionality
+                    st.button("Analyze Emotions (Coming Soon)", disabled=True, key="analyze_button")
+                    
+                except Exception as e:
+                    logger.error(f"Error processing image: {e}", exc_info=True)
+                    st.error(f"Error processing image: {str(e)}")
+            else:
+                # Show validation issues
+                st.error("Image validation failed:")
+                for issue in validation_result["issues"]:
+                    st.warning(issue)
+                    
+        except Exception as e:
+            logger.error(f"Error in Visual Analysis: {e}", exc_info=True)
+            st.error(f"Error processing image: {str(e)}")
+
+def handle_history_page(db_service):
+    """
+    Handle the History page logic.
+    
+    Args:
+        db_service: The database service instance
+    """
+    st.header("Analysis History")
+    st.markdown("View your previous analyses and export results.")
+    
+    # Create tabs for different views - Using numbered sequence for clear navigation
+    history_tabs = ["1. Recent Analyses", "2. Statistics", "3. Export Data"]
+    tab1, tab2, tab3 = st.tabs(history_tabs)
+    
+    with tab1:
+        # Implementation of recent analyses tab
+        pass  # Implement the rest of the history page functionality
+        
+    with tab2:
+        # Implementation of statistics tab
+        pass  # Implement statistics functionality
+        
+    with tab3:
+        # Implementation of export data tab
+        pass  # Implement export functionality
+
+def handle_about_page():
+    """Handle the About page logic."""
+    st.header("About EmotionMirror")
+    st.markdown("""
+    EmotionMirror is an application that uses computer vision to analyze emotions in facial expressions.
+    
+    **Version:** 0.1.3 (Phase 1.3)
+    **Features:**
+    - Facial emotion detection using computer vision
+    - Support for image uploads
+    - Analysis history and data export
+    - Image preprocessing for improved detection
+    
+    **Technology:**
+    - Python
+    - OpenCV for image processing
+    - Deep learning models for emotion classification
+    - Streamlit for the user interface
+    """)

utils/preprocessing_ui.py

@@ -0,0 +1,336 @@
+"""
+Image Preprocessing UI Component for EmotionMirror application.
+
+This module implements the UI components for showing image preprocessing options,
+including the comparison between original and processed images.
+Part of Step 4: Implementation of preprocessing techniques.
+"""
+import streamlit as st
+import logging
+import numpy as np
+import cv2
+from typing import Dict, Any, Optional
+import io
+from PIL import Image
+import os
+import time
+import traceback
+
+logger = logging.getLogger(__name__)
+
+def show_preprocessing_ui(image_service, img: np.ndarray) -> Dict[str, Any]:
+    """
+    Complete UI handler for image preprocessing - this is the main entry point
+    that should be called from app.py
+    
+    Args:
+        image_service: The image service instance
+        img: The image to preprocess
+        
+    Returns:
+        Dict with information about the preprocessing state and user choices
+    """
+    try:
+        # Save the original image in session state
+        if "original_image" not in st.session_state:
+            st.session_state.original_image = img.copy()
+            
+        # Apply image preprocessing 
+        preprocessing_result = image_service.preprocess_image(img)
+        
+        # Store preprocessed image result in session state
+        st.session_state.preprocessing_result = preprocessing_result
+        
+        # Print debugging information
+        logger.info("[DEBUG] Preprocessing result obtained successfully")
+        logger.info(f"[DEBUG] Improvements: {preprocessing_result.get('improvements', [])}")
+        
+        # Show preprocessing status if already set
+        display_processing_status()
+        
+        # Display preprocessing UI with expandable section
+        show_preprocessing_expandable(image_service, preprocessing_result)
+        
+        # Return success information
+        return {
+            "success": True,
+            "message": "Preprocessing UI displayed successfully",
+            "using_preprocessed": st.session_state.get("using_preprocessed_image", False)
+        }
+        
+    except Exception as e:
+        # Log detailed error information
+        error_trace = traceback.format_exc()
+        logger.error(f"Error in preprocessing UI: {str(e)}\n{error_trace}")
+        
+        # Show error to user
+        st.error(f"Error preparing image preprocessing: {str(e)}")
+        
+        # Return error information
+        return {
+            "success": False,
+            "message": f"Error: {str(e)}",
+            "error": str(e)
+        }
+
+def show_preprocessing_expandable(image_service, preprocessing_result: Dict[str, Any]) -> None:
+    """
+    Display preprocessing UI with an expandable section.
+    This is the standalone implementation that doesn't depend on other functions.
+    
+    Args:
+        image_service: The image service instance
+        preprocessing_result: Dict with preprocessing results
+    """
+    # Only show if there are improvements
+    if not preprocessing_result or "improvements" not in preprocessing_result or not preprocessing_result["improvements"]:
+        logger.info("No improvements to display")
+        return
+        
+    try:
+        # Direct expandable implementation 
+        with st.expander("Suggested improvements available", expanded=True):
+            # Create columns for side-by-side comparison
+            original_col, improved_col = st.columns(2)
+            
+            with original_col:
+                st.markdown("**Original Image**")
+                st.image(preprocessing_result["original_image"], use_column_width=True)
+            
+            with improved_col:
+                st.markdown("**Improved Image**")
+                st.image(preprocessing_result["processed_image"], use_column_width=True)
+            
+            # Display improvements applied
+            st.markdown("**Improvements applied:**")
+            for improvement in preprocessing_result["improvements"]:
+                st.markdown(f"- {improvement}")
+            
+            # Add explanation about benefits
+            st.markdown("### Why these improvements help facial analysis")
+            st.markdown("""
+            **Technical Benefits:**
+            - **Balanced contrast:** Enhances the visibility of facial features while reducing shadows and highlights
+            - **Optimal brightness:** Ensures facial features are clearly distinguishable without over-exposure
+            - **Proper sizing:** Maintains ideal dimensions for detection algorithms to recognize facial landmarks
+            
+            **Impact on Emotion Detection:**
+            - **More accurate emotion classification:** Cleaner input images lead to more reliable emotion detection
+            - **Better feature extraction:** Facial features like eyes, mouth, and eyebrows are more clearly defined
+            - **Reduced noise and artifacts:** Minimizes false detections and improves confidence scores
+            """)
+            
+            # Add buttons to select image
+            setup_image_selection_buttons(image_service, preprocessing_result)
+    
+    except Exception as e:
+        logger.error(f"Error in expandable UI: {str(e)}")
+        st.warning(f"Could not display image comparison: {str(e)}")
+        
+        # Fallback to old display method if needed
+        try:
+            display_preprocessing_comparison(preprocessing_result)
+            setup_preprocessing_controls(image_service, preprocessing_result)
+        except Exception as fallback_error:
+            logger.error(f"Fallback display also failed: {str(fallback_error)}")
+
+def display_preprocessing_comparison(preprocessing_result: Dict[str, Any]) -> None:
+    """
+    Display the comparison between original and processed images.
+    
+    Args:
+        preprocessing_result: Dictionary containing preprocessing results
+    """
+    if not preprocessing_result or "improvements" not in preprocessing_result:
+        return
+        
+    # Only show if there are improvements applied
+    if preprocessing_result["improvements"]:
+        st.subheader("Image Enhancement Options")
+        
+        # Display side-by-side comparison
+        before_col, after_col = st.columns(2)
+        
+        with before_col:
+            st.markdown("**Original Image**")
+            st.image(preprocessing_result["original_image"], use_column_width=True)
+        
+        with after_col:
+            st.markdown("**Improved Image**")
+            st.image(preprocessing_result["processed_image"], use_column_width=True)
+        
+        # Display improvements applied
+        st.markdown("**Improvements applied:**")
+        for improvement in preprocessing_result["improvements"]:
+            st.markdown(f"- {improvement}")
+        
+        # Add explanation about why these improvements are beneficial
+        st.markdown("### Why these improvements help facial analysis")
+        st.markdown("""
+        **Technical Benefits:**
+        - **Balanced contrast:** Enhances the visibility of facial features while reducing shadows and highlights
+        - **Optimal brightness:** Ensures facial features are clearly distinguishable without over-exposure
+        - **Proper sizing:** Maintains ideal dimensions for detection algorithms to recognize facial landmarks
+        
+        **Impact on Emotion Detection:**
+        - **More accurate emotion classification:** Cleaner input images lead to more reliable emotion detection
+        - **Better feature extraction:** Facial features like eyes, mouth, and eyebrows are more clearly defined
+        - **Reduced noise and artifacts:** Minimizes false detections and improves confidence scores
+        
+        These improvements help our algorithms perform more consistently across different lighting conditions and image sources.
+        """)
+
+def setup_image_selection_buttons(image_service, preprocessing_result: Dict[str, Any]) -> None:
+    """
+    Set up buttons for selecting between original and improved images.
+    
+    Args:
+        image_service: The image service instance
+        preprocessing_result: Dictionary containing preprocessing results
+    """
+    # Add buttons to use original or improved image
+    col1, col2 = st.columns(2)
+    
+    # Button for original image
+    with col1:
+        if st.button("Continue with Original"):
+            # Set session state to use original
+            st.session_state["using_preprocessed_image"] = False
+            st.session_state["image_processing_status"] = "using_original"
+            
+            # Display confirmation message
+            st.markdown("""
+            <div style="background-color: #17a2b8; color: white; padding: 10px; border-radius: 5px; margin-bottom: 10px;">
+                <strong>ℹ️ Using original image for analysis.</strong>
+            </div>
+            """, unsafe_allow_html=True)
+    
+    # Button for improved image
+    with col2:
+        if st.button("Use Improved Image"):
+            try:
+                # Save the processed image to a temporary file
+                temp_path = image_service.save_processed_image(
+                    preprocessing_result["processed_image"]
+                )
+                
+                # Update session state
+                st.session_state["preprocessed_image_path"] = temp_path
+                st.session_state["using_preprocessed_image"] = True
+                st.session_state["image_processing_status"] = "using_improved"
+                
+                # Display confirmation
+                st.markdown("""
+                <div style="background-color: #28a745; color: white; padding: 10px; border-radius: 5px; margin-bottom: 10px;">
+                    <strong>✅ Using improved image for analysis!</strong>
+                </div>
+                """, unsafe_allow_html=True)
+            except Exception as e:
+                logger.error(f"Error saving processed image: {str(e)}")
+                st.error(f"Could not save processed image: {str(e)}")
+
+def setup_preprocessing_controls(image_service, preprocessing_result: Dict[str, Any]) -> None:
+    """
+    Set up the controls for selecting between original and processed images.
+    
+    Args:
+        image_service: The image service instance
+        preprocessing_result: Dictionary containing preprocessing results
+    """
+    if not preprocessing_result or "improvements" not in preprocessing_result:
+        return
+        
+    # Only show if there are improvements applied
+    if preprocessing_result["improvements"]:
+        # Add buttons to use original or improved image
+        col1, col2 = st.columns(2)
+        with col1:
+            use_original = st.button("Continue with Original")
+        with col2:
+            use_improved = st.button("Use Improved Image")
+        
+        # Handle the user's choice
+        if use_improved:
+            # Save the processed image to a temporary file
+            temp_path = image_service.save_processed_image(
+                preprocessing_result["processed_image"]
+            )
+            
+            # Update session state to use the processed image
+            st.session_state["preprocessed_image_path"] = temp_path
+            st.session_state["using_preprocessed_image"] = True
+            
+            # Display a more prominent success message
+            st.markdown("""
+            <div style="background-color: #28a745; color: white; padding: 10px; border-radius: 5px; margin-bottom: 10px;">
+                <strong>✅ Using improved image for analysis!</strong>
+            </div>
+            """, unsafe_allow_html=True)
+            
+            # Store confirmation message in session state for persistence
+            st.session_state["image_processing_status"] = "using_improved"
+            
+            # Small delay to ensure UI updates
+            time.sleep(0.5)
+            
+        elif use_original:
+            # Set session state to use original
+            st.session_state["using_preprocessed_image"] = False
+            st.session_state["image_processing_status"] = "using_original"
+            
+            # Display a clear message
+            st.markdown("""
+            <div style="background-color: #17a2b8; color: white; padding: 10px; border-radius: 5px; margin-bottom: 10px;">
+                <strong>ℹ️ Using original image for analysis.</strong>
+            </div>
+            """, unsafe_allow_html=True)
+
+def display_processing_status() -> None:
+    """
+    Display the current image processing status (original or improved).
+    """
+    # Display persistent status indicator at the top of the interface
+    if "image_processing_status" in st.session_state:
+        if st.session_state["image_processing_status"] == "using_improved":
+            st.markdown("""
+            <div style="background-color: #28a745; color: white; padding: 5px; border-radius: 5px; margin-bottom: 10px;">
+                <strong>✅ Currently using improved image for analysis</strong>
+            </div>
+            """, unsafe_allow_html=True)
+        elif st.session_state["image_processing_status"] == "using_original":
+            st.markdown("""
+            <div style="background-color: #17a2b8; color: white; padding: 5px; border-radius: 5px; margin-bottom: 10px;">
+                <strong>ℹ️ Using original image for analysis</strong>
+            </div>
+            """, unsafe_allow_html=True)
+
+def get_processing_image(image_service, original_image: np.ndarray) -> np.ndarray:
+    """
+    Get the appropriate image for processing (preprocessed or original).
+    
+    Args:
+        image_service: The image service instance
+        original_image: The original image as backup
+        
+    Returns:
+        The appropriate image to use for processing
+    """
+    if "using_preprocessed_image" in st.session_state and st.session_state["using_preprocessed_image"] and "preprocessed_image_path" in st.session_state:
+        try:
+            # Load the preprocessed image from the temporary file
+            preprocessed_path = st.session_state["preprocessed_image_path"]
+            img = image_service.load_image_from_path(preprocessed_path)
+            
+            # Check if image was loaded successfully
+            if img is None or img.size == 0:
+                logger.warning("Could not load preprocessed image. Using original instead.")
+                return original_image
+            
+            return img
+        except Exception as e:
+            # Log error and fallback to original
+            logger.error(f"Error loading preprocessed image: {e}")
+            return original_image
+    else:
+        # Return the original image
+        return original_image