# mosidas/face-recognition architecture

> Architecture diagram of the GitHub repository mosidas/face-recognition, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mosidas/face-recognition
- Repository: https://github.com/mosidas/face-recognition

## Overview

##### Project Type and Purpose
- This is a multi‐application .NET 8.0 system for real‐time object detection and face recognition using ONNX models.
- It consists of a core library (“Recognizer”), a small utility library, multiple runnable apps (CLI, console real‐time detectors, unified detector, WPF UI), and a Python‐based ONNX analysis tool.

##### File Structure Analysis
- Top‐level:
- Recognizer core library in src/Recognizer
- Utility helpers in src/Utility
- Five consumer apps in src/ExampleCLI, src/RealTimeDetector, src/RealTimeFaceRecognizer, src/UnifiedDetector, src/WPFDetectorApp
- A tools folder (tools/onnx-analyzer) for model inspection
- face-recognition.sln and README.md for overall solution definition
- Each app project references Recognizer (and occasionally Utility). Apps are thin shells driving the detection/recognition pipeline.
- Configuration/deployment hints: .csproj files, Program.cs, App.xaml for WPF, and a Python pyproject.toml for the analyzer.

##### Key Insights from README
- Core functionality is ONNX‐based YOLO face/object detection and ArcFace (or similar) recognition.
- Multiple frontends (CLI, console, WPF).
- External resources: ONNX model files, reference face images, camera hardware (including infrared).
- GPU acceleration via CUDA supported.

##### Components
a. Main components:
- Recognizer Library (src/Recognizer)
- Utility Library (src/Utility)
- ExampleCLI app
- RealTimeDetector app
- RealTimeFaceRecognizer app
- UnifiedDetector app
- WPFDetectorApp (UI + Services)
- External ONNX Models (face_detector.onnx, object_detector.onnx, face_recognizer.onnx)
- External Inputs: Camera (RGB/IR), Reference Face Image Store
- Python ONNX Analyzer (tools/onnx-analyzer)
b. Relationships & Interactions:
- Each app → references → Recognizer Library
- Recognizer → uses → OnnxHelper → loads → ONNX Models
- Apps → read → camera frames → send to Recognizer → receive detections/recognitions → render to console or UI
- UnifiedDetector → orchestrates both object and face detectors and optionally smartphone auth
- Utility Library → provides Encipher, FloatConverter (used by Recognizer or apps)
- WPFDetectorApp → UI layer (XAML) → calls CameraService & LoggingService → passes frames into Recognizer
- ONNX Analyzer (Python) → dev‐time tool, independent from runtime apps
c. Architectural Patterns & Principles:
- Layered architecture:
- Layer 1: External hardware/resources (Camera, Model files)
- Layer 2: Core/Utility libraries (Recognizer, Utility)
- Layer 3: Application layer (CLI, console, UI)
- Dependency Inversion: High‐level apps depend on abstractions in Recognizer rather than on ONNX directly
- Separation of concerns: Core ML logic is isolated from presentation/UI and from tooling
d. Key Technologies & Frameworks:
- .NET 8.0, C# projects
- ONNX Runtime (via OnnxHelper) with CUDA support
- YOLOv8n-face / YOLOv11-face detectors and ArcFace/face_recognition models
- WPF (XAML/C#) for the Windows UI
- Python 3 (pyproject.toml) for ONNX model analysis

##### Essential Details
- ONNX model loading as a separate sub‐component inside Recognizer (OnnxHelper).
- GPU acceleration path if relevant (e.g., annotate ONNX runtime with “CUDA”).
- Two main data flows: object detection and face recognition, and how UnifiedDetector merges them.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Resources
    subgraph "External Resources"
        direction TB
        CAMERA["Camera (RGB/IR)"]:::ext
        REFSTORE["Reference Face Image Store"]:::ext
        subgraph "ONNX Models"
            direction TB
            MODEL_OBJ["object_detector.onnx"]:::ext
            MODEL_FACE["face_detector.onnx"]:::ext
            MODEL_RECOG["face_recognizer.onnx"]:::ext
        end
    end

    %% Core and Utility Libraries
    subgraph "Core / Utility Libraries"
        direction TB
        RECOGNIZER["Recognizer Library"]:::core
        ONNXHELPER["OnnxHelper"]:::core
        UTIL["Utility Library"]:::core
    end

    %% Applications
    subgraph "Applications"
        direction TB
        CLI["ExampleCLI.exe"]:::app
        RTD["RealTimeDetector.exe"]:::app
        subgraph "RealTimeDetector Flow"
            direction TB
            RTOBJ["RealTimeObjectDetector"]:::app
            RTFACE["RealTimeFaceDetector"]:::app
            ODR["ObjectDetectionRenderer"]:::app
            FDR["FaceDetectionRenderer"]:::app
        end
        FTR["RealTimeFaceRecognizer.exe"]:::app
        UD["UnifiedDetector.exe"]:::app
        WPFAPP["WPFDetectorApp"]:::app
    end

    %% WPF Subcomponents
    subgraph "WPFDetectorApp Layer"
        direction TB
        UI["MainWindow.xaml / App.xaml"]:::app
        CAMSERV["CameraService"]:::app
        LOGSERV["LoggingService"]:::app
    end

    %% Developer Tools
    subgraph "Developer Tools"
        direction TB
        ONNX_TOOL["Python ONNX Analyzer"]:::tool
    end

    %% Runtime Data Flows
    CAMERA -->|stream frames| RTOBJ
    CAMERA -->|stream frames| RTFACE
    RTOBJ -->|detect objects| RECOGNIZER
    RTFACE -->|detect faces| RECOGNIZER
    RECOGNIZER -->|results| ODR
    RECOGNIZER -->|results| FDR

    CAMERA -->|stream frames| WPFAPP
    WPFAPP -->|use| CAMSERV
    CAMSERV -->|frames| RECOGNIZER
    RECOGNIZER -->|detections| UI
    WPFAPP -->|logging| LOGSERV

    CAMERA -->|stream frames| UD
    UD -->|orchestrate detection| RECOGNIZER
    UD -->|orchestrate recognition| RECOGNIZER

    CLI -->|invoke recognition| RECOGNIZER
    FTR -->|invoke face pipeline| RECOGNIZER

    %% Model Loading
    RECOGNIZER -->|uses| ONNXHELPER
    ONNXHELPER -->|loads| MODEL_OBJ
    ONNXHELPER -->|loads| MODEL_FACE
    ONNXHELPER -->|loads| MODEL_RECOG

    %% Dev-time Tool
    ONNX_TOOL -->|analyzes| MODEL_OBJ
    ONNX_TOOL -->|analyzes| MODEL_FACE
    ONNX_TOOL -->|analyzes| MODEL_RECOG

    %% Project References (CSProj)
    CLI -.->|refs| RECOGNIZER
    RTD -.->|refs| RECOGNIZER
    RTD -.->|refs| UTIL
    FTR -.->|refs| RECOGNIZER
    UD -.->|refs| RECOGNIZER
    WPFAPP -.->|refs| RECOGNIZER
    WPFAPP -.->|refs| UTIL

    %% Click Events
    click RECOGNIZER "https://github.com/mosidas/face-recognition/tree/main/src/Recognizer"
    click ONNXHELPER "https://github.com/mosidas/face-recognition/blob/main/src/Recognizer/OnnxHelper.cs"
    click UTIL "https://github.com/mosidas/face-recognition/tree/main/src/Utility"
    click CLI "https://github.com/mosidas/face-recognition/tree/main/src/ExampleCLI"
    click RTD "https://github.com/mosidas/face-recognition/tree/main/src/RealTimeDetector"
    click RTOBJ "https://github.com/mosidas/face-recognition/blob/main/src/RealTimeDetector/RealTimeObjectDetector.cs"
    click RTFACE "https://github.com/mosidas/face-recognition/blob/main/src/RealTimeDetector/RealTimeFaceDetector.cs"
    click ODR "https://github.com/mosidas/face-recognition/blob/main/src/RealTimeDetector/ObjectDetectionRenderer.cs"
    click FDR "https://github.com/mosidas/face-recognition/blob/main/src/RealTimeDetector/FaceDetectionRenderer.cs"
    click FTR "https://github.com/mosidas/face-recognition/tree/main/src/RealTimeFaceRecognizer"
    click UD "https://github.com/mosidas/face-recognition/tree/main/src/UnifiedDetector"
    click CAMSERV "https://github.com/mosidas/face-recognition/blob/main/src/WPFDetectorApp/CameraService.cs"
    click LOGSERV "https://github.com/mosidas/face-recognition/blob/main/src/WPFDetectorApp/LoggingService.cs"
    click UI "https://github.com/mosidas/face-recognition/blob/main/src/WPFDetectorApp/App.xaml"
    click UI "https://github.com/mosidas/face-recognition/blob/main/src/WPFDetectorApp/MainWindow.xaml"
    click ONNX_TOOL "https://github.com/mosidas/face-recognition/tree/main/tools/onnx-analyzer"

    %% Styles
    classDef core fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef app fill:#DFF5E1,stroke:#28a745,color:#28a745
    classDef ext fill:#F0F0F0,stroke:#6a737d,color:#6a737d
    classDef tool fill:#FFEFD5,stroke:#d2691e,color:#d2691e
```
