# eko-347m4n/face-tracking-recognition architecture

> Architecture diagram of the GitHub repository eko-347m4n/face-tracking-recognition, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eko-347m4n/face-tracking-recognition
- Repository: https://github.com/eko-347m4n/face-tracking-recognition

## Overview

This is a real-time face-tracking and recognition application with blink-based liveness checks. The main workflow initializes the camera and known-face dataset, then runs a threaded pipeline that captures frames, detects or tracks faces within selected regions, identifies faces, checks liveness, and returns results for display. Dataset caching and automatic reloads support operation as the image collection changes. The pipeline excerpt is partial, so links for detection and liveness follow documented behavior; uncertain internal wiring is omitted.

Main entry points: [`main.py`](https://github.com/eko-347m4n/face-tracking-recognition/blob/main/main.py) (Application Orchestrator), [`core/processing_pipeline.py`](https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/processing_pipeline.py) (Threaded Pipeline), [`core/dataset_manager.py`](https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/dataset_manager.py) (Dataset Manager), [`core/camera_handler.py`](https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/camera_handler.py) (Camera Handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application Control"]
  node_main["Application Orchestrator<br/>[main.py]"]
  node_camera["Camera Handler<br/>[camera_handler.py]"]
end

subgraph group_vision["Frame Processing"]
  node_pipeline["Threaded Pipeline"]
  node_roi["ROI Utilities<br/>[roi.py]"]
end

subgraph group_identity["Identity and Liveness"]
  node_recognizer["Face Matcher<br/>[recognizer.py]"]
  node_liveness["Blink Detector<br/>[anti_spoofing.py]"]
  node_face_utils["Landmark Utilities<br/>[face_utils.py]"]
end

subgraph group_data_ui["Data and Presentation"]
  node_dataset_manager["Dataset Manager<br/>[dataset_manager.py]"]
  node_image_utils["Image Loader and Encoder<br/>[utils.py]"]
  node_encoding_cache[("Encoding Cache<br/>[dataset_manager.py]")]
  node_display["Frame Display<br/>[display.py]"]
end

node_operator(("Operator"))
node_webcam(("Webcam"))
node_dataset_files[("Face Images")]
node_mediapipe["Face Detector"]
node_tracker["Object Tracking"]

node_operator -->|"starts and quits"| node_main
node_webcam -->|"provides video"| node_camera
node_main -->|"initializes"| node_camera
node_camera -->|"returns capture"| node_main
node_main -->|"loads and reloads"| node_dataset_manager
node_dataset_manager -->|"reads images"| node_dataset_files
node_dataset_manager -->|"loads and encodes"| node_image_utils
node_dataset_manager -->|"reads and writes"| node_encoding_cache
node_main -->|"starts and stops"| node_pipeline
node_main -->|"creates detector"| node_mediapipe
node_pipeline -->|"detects faces"| node_mediapipe
node_pipeline -->|"tracks faces"| node_tracker
node_pipeline -->|"selects and draws ROI"| node_roi
node_pipeline -->|"matches encodings"| node_recognizer
node_pipeline -->|"checks blinks"| node_liveness
node_liveness -->|"calculates eye ratio"| node_face_utils
node_pipeline -->|"queues display data"| node_main
node_main -->|"renders results"| node_display
node_operator -->|"views output"| node_display

click node_main "https://github.com/eko-347m4n/face-tracking-recognition/blob/main/main.py"
click node_camera "https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/camera_handler.py"
click node_pipeline "https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/processing_pipeline.py"
click node_roi "https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/roi.py"
click node_recognizer "https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/recognizer.py"
click node_liveness "https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/anti_spoofing.py"
click node_face_utils "https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/face_utils.py"
click node_dataset_manager "https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/dataset_manager.py"
click node_image_utils "https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/utils.py"
click node_encoding_cache "https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/dataset_manager.py"
click node_display "https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/display.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_main,node_camera toneBlue
class node_pipeline,node_roi,node_dataset_files toneAmber
class node_recognizer,node_liveness,node_face_utils toneMint
class node_dataset_manager,node_image_utils,node_encoding_cache,node_display toneRose
class node_operator,node_webcam,node_mediapipe,node_tracker toneIndigo
```

## Components

### Application Control

- [Application Orchestrator](https://github.com/eko-347m4n/face-tracking-recognition/blob/main/main.py): `main.py`
- [Camera Handler](https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/camera_handler.py): `core/camera_handler.py`

### Frame Processing

- [Threaded Pipeline](https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/processing_pipeline.py): `core/processing_pipeline.py`
- [ROI Utilities](https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/roi.py): `core/roi.py`

### Identity and Liveness

- [Face Matcher](https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/recognizer.py): `core/recognizer.py`
- [Blink Detector](https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/anti_spoofing.py): `core/anti_spoofing.py`
- [Landmark Utilities](https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/face_utils.py): `core/face_utils.py`

### Data and Presentation

- [Dataset Manager](https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/dataset_manager.py): `core/dataset_manager.py`
- [Image Loader and Encoder](https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/utils.py): `core/utils.py`
- [Encoding Cache](https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/dataset_manager.py): `core/dataset_manager.py`
- [Frame Display](https://github.com/eko-347m4n/face-tracking-recognition/blob/main/core/display.py): `core/display.py`

### Other components

- **Operator**
- **Webcam**
- **Face Images**
- **Face Detector**
- **Object Tracking**

## Connections

- Operator → Application Orchestrator: starts and quits
- Webcam → Camera Handler: provides video
- Application Orchestrator → Camera Handler: initializes
- Camera Handler → Application Orchestrator: returns capture
- Application Orchestrator → Dataset Manager: loads and reloads
- Dataset Manager → Face Images: reads images
- Dataset Manager → Image Loader and Encoder: loads and encodes
- Dataset Manager → Encoding Cache: reads and writes
- Application Orchestrator → Threaded Pipeline: starts and stops
- Application Orchestrator → Face Detector: creates detector
- Threaded Pipeline → Face Detector: detects faces
- Threaded Pipeline → Object Tracking: tracks faces
- Threaded Pipeline → ROI Utilities: selects and draws ROI
- Threaded Pipeline → Face Matcher: matches encodings
- Threaded Pipeline → Blink Detector: checks blinks
- Blink Detector → Landmark Utilities: calculates eye ratio
- Threaded Pipeline → Application Orchestrator: queues display data
- Application Orchestrator → Frame Display: renders results
- Operator → Frame Display: views output