# manish-9245/facial-emotion-recognition-using-opencv-and-deepface architecture

> Architecture diagram of the GitHub repository manish-9245/facial-emotion-recognition-using-opencv-and-deepface, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface
- Repository: https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface

## Overview

#### Purpose and execution

A single-process desktop computer-vision application for real-time webcam facial-emotion labeling. The executable entry point is `emotion.py`; it opens the default camera, processes frames continuously, and exits on user input. There is no server, persistence layer, or web interface.

#### Runtime and dependencies

The application runs under Python with OpenCV for camera I/O, image operations, face detection, drawing, and GUI display. DeepFace supplies pretrained emotion inference backed by TensorFlow/Keras. Dependency declarations are in `requirements.txt`.

Core runtime assets:
- `emotion.py`
- `requirements.txt`
- `haarcascade_frontalface_default.xml`

#### Camera acquisition and frame loop

`emotion.py` creates an OpenCV `VideoCapture` session for the default webcam and enters a continuous read/process/display loop. Each successful camera frame is the unit of work; processing is synchronous, so inference latency directly affects displayed frame rate.

The loop terminates when the user presses `q`, then releases the camera and closes OpenCV windows.

#### Face-detection boundary

Before emotion inference, frames are converted to grayscale and passed to an OpenCV Haar-cascade classifier. The classifier is loaded from the repository-local model asset:

- `emotion.py`
- `haarcascade_frontalface_default.xml`

This stage emits face bounding boxes. Haar detection determines which regions are analyzed; frames or regions without detections do not produce emotion labels.

#### Per-face emotion inference

For every detected bounding box, `emotion.py` crops the corresponding face region from the frame and invokes DeepFace emotion analysis/preprocessing. DeepFace owns the model-specific preparation and pretrained neural-network execution, returning emotion scores or a dominant emotion classification.

This is the principal external-model boundary: repository code manages frame/ROI orchestration, while DeepFace/TensorFlow manages learned-model inference.

#### Visualization and user interaction

The application overlays each face’s detection rectangle and predicted emotion text directly on the original camera frame, then renders it through an OpenCV display window. This creates a closed local pipeline:

webcam → OpenCV frame → Haar face boxes → face ROI → DeepFace emotion result → annotated frame → local display.

All UI is OpenCV window-based and ephemeral; no results are exported or retained.

Main entry points: [`emotion.py`](https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py) (Camera frame), [`haarcascade_frontalface_default.xml`](https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/haarcascade_frontalface_default.xml) (Haar face detector), [`requirements.txt`](https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/requirements.txt) (requirements.txt)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Desktop Runtime"]
  node_entry["emotion.py<br/>Python entry point<br/>[emotion.py]"]
  node_deps["requirements.txt<br/>dependencies<br/>[requirements.txt]"]
  node_webcam{{"Default webcam<br/>camera input"}}
  node_display["OpenCV display window<br/>local ephemeral UI<br/>[emotion.py]"]
  node_cleanup["Camera and window cleanup<br/>OpenCV shutdown<br/>[emotion.py]"]
end

subgraph group_vision["Vision Pipeline"]
  node_capture["VideoCapture loop<br/>OpenCV acquisition<br/>[emotion.py]"]
  node_frame["Camera frame<br/>image frame<br/>[emotion.py]"]
  node_grayscale["Grayscale conversion<br/>OpenCV image operation<br/>[emotion.py]"]
  node_boxes["Face boxes<br/>detection output<br/>[emotion.py]"]
  node_roi["Face ROI crop<br/>per-face region<br/>[emotion.py]"]
  node_emotion["Emotion result<br/>scores or dominant label<br/>[emotion.py]"]
  node_annotate["Frame annotation<br/>OpenCV drawing<br/>[emotion.py]"]
end

subgraph group_models["Model Boundaries"]
  node_cascade{{"Haar face detector<br/>OpenCV classifier"}}
  node_deepface{{"DeepFace analysis<br/>emotion inference API"}}
  node_tensorflow{{"TensorFlow/Keras model<br/>pretrained neural network"}}
end

node_deps -.->|"runtime dependencies"| node_entry
node_entry -->|"creates"| node_capture
node_webcam -->|"camera stream"| node_capture
node_capture -->|"reads"| node_frame
node_frame -->|"converts"| node_grayscale
node_grayscale -->|"detects faces"| node_cascade
node_cascade -->|"emits"| node_boxes
node_frame -->|"crops by box"| node_roi
node_boxes -->|"selects"| node_roi
node_roi -->|"analyzes"| node_deepface
node_deepface -->|"uses"| node_tensorflow
node_deepface -->|"returns"| node_emotion
node_frame -->|"base frame"| node_annotate
node_boxes -->|"rectangles"| node_annotate
node_emotion -->|"label text"| node_annotate
node_annotate -->|"renders"| node_display
node_display -.->|"continues until q"| node_capture
node_display -->|"q pressed"| node_cleanup

click node_entry "https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py"
click node_deps "https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/requirements.txt"
click node_capture "https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py"
click node_frame "https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py"
click node_grayscale "https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py"
click node_cascade "https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/haarcascade_frontalface_default.xml"
click node_boxes "https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py"
click node_roi "https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py"
click node_emotion "https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py"
click node_annotate "https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py"
click node_display "https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py"
click node_cleanup "https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_deps,node_webcam,node_display,node_cleanup toneBlue
class node_capture,node_frame,node_grayscale,node_boxes,node_roi,node_emotion,node_annotate toneAmber
class node_cascade,node_deepface,node_tensorflow toneMint
```

## Components

### Desktop Runtime

Single synchronous Python process.

- [emotion.py](https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py): Python entry point · Owns camera setup, loop, orchestration, and cleanup. · `emotion.py`
- [requirements.txt](https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/requirements.txt): dependencies · Declares OpenCV, DeepFace, and model runtime dependencies. · `requirements.txt`
- **Default webcam**: camera input
- [OpenCV display window](https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py): local ephemeral UI · Renders annotated frames and receives q to exit. · `emotion.py`
- [Camera and window cleanup](https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py): OpenCV shutdown · Releases the camera and closes windows. · `emotion.py`

### Vision Pipeline

Per-frame local processing.

- [VideoCapture loop](https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py): OpenCV acquisition · Reads frames synchronously until q is pressed. · `emotion.py`
- [Camera frame](https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py): image frame · `emotion.py`
- [Grayscale conversion](https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py): OpenCV image operation · `emotion.py`
- [Face boxes](https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py): detection output · Only detected regions proceed to emotion analysis. · `emotion.py`
- [Face ROI crop](https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py): per-face region · `emotion.py`
- [Emotion result](https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py): scores or dominant label · `emotion.py`
- [Frame annotation](https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/emotion.py): OpenCV drawing · Draws face rectangles and emotion text on the original frame. · `emotion.py`

### Model Boundaries

Repository and external pretrained models.

- [Haar face detector](https://github.com/manish-9245/facial-emotion-recognition-using-opencv-and-deepface/blob/main/haarcascade_frontalface_default.xml): OpenCV classifier · Finds face bounding boxes in grayscale frames. · `haarcascade_frontalface_default.xml`
- **DeepFace analysis**: emotion inference API · Performs model-specific preprocessing and emotion analysis.
- **TensorFlow/Keras model**: pretrained neural network · Executes learned emotion inference behind DeepFace.

## Connections

- requirements.txt → emotion.py: runtime dependencies
- emotion.py → VideoCapture loop: creates
- Default webcam → VideoCapture loop: camera stream
- VideoCapture loop → Camera frame: reads
- Camera frame → Grayscale conversion: converts
- Grayscale conversion → Haar face detector: detects faces
- Haar face detector → Face boxes: emits
- Camera frame → Face ROI crop: crops by box
- Face boxes → Face ROI crop: selects
- Face ROI crop → DeepFace analysis: analyzes
- DeepFace analysis → TensorFlow/Keras model: uses
- DeepFace analysis → Emotion result: returns
- Camera frame → Frame annotation: base frame
- Face boxes → Frame annotation: rectangles
- Emotion result → Frame annotation: label text
- Frame annotation → OpenCV display window: renders
- OpenCV display window → VideoCapture loop: continues until q
- OpenCV display window → Camera and window cleanup: q pressed