# agoniko/facechaser architecture

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

- Interactive diagram: https://gitdiagram.com/agoniko/facechaser
- Repository: https://github.com/agoniko/facechaser

## Overview

##### Main Components
- Video Processing & Face Detection/Tracking: At the core, FaceChaser captures video frames, detects faces, and tracks them over time. These functionalities are implemented primarily in Python (main.py, Engine.py, Person.py, and modules in the src directory). Models for face detection and embeddings are stored in src/model.
- Model Inference: Integration of external face models (e.g., RetinaFace for detection and SphereFace/SFace for face embeddings) is a key component. This module uses ONNX models and may use libraries indicated in requirements.txt.
- Configuration & Calibration: The generate_config.py script and config.json (which are generated at runtime) alongside the src/calib folder indicate that the system adjusts parameters for camera settings and spatial referencing, so include a “Configuration” and “Calibration” component.
- Robotic Arm Control: Managed through Arduino. The arduino folder (with servo.ino) represents the embedded side which receives calculated pan-tilt commands, while src/Arduino.py likely handles communication with these devices via serial ports.

##### Relationships and Interactions
- Data Flow: Show how video frames flow from the input device (camera) into the video processing module. From here, frames pass to the face detection module for running the inference on the imported ONNX models.
- Reference Transformation: Highlight the refsys module: this component uses calibration data and system reference transformations to convert detection coordinates into pan-tilt commands that can be understood by the robotic arm system.
- External Dependencies: Optionally note connections to external libraries (e.g., the batch_face repo, sphereface_pytorch) that underpin the model implementations.

##### Architectural Patterns and Design Principles
- Modular Design: The project is clearly divided into functional modules such as detection, tracking, transformation (refsys), and hardware interfacing. Emphasize modularity with edges showing clear interfaces between these components.
- Separation of Concerns: Different components handle specific tasks (e.g., image processing vs. hardware control).
- Extensibility: The structure (with clear subdirectories for calibration, reference systems, etc.) supports future extensions to additional tracking methods or hardware configurations.
- Real-Time Processing: Show how all components are orchestrated in a real-time pipeline, from video acquisition to robotic actuation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        CA["Camera Input"]
    end

    %% Processing Layer - Video Capture & Face Detection/Tracking
    subgraph "Processing Layer"
        A["Main Module"]:::software
        B["Engine Module"]:::software
        C["Person Module"]:::software
    end

    %% Inference & Tracking Layer
    subgraph "Inference & Tracking"
        D["ONNX Models"]:::external
        F["net_sphere Module"]:::software
        G["Reference Transformation"]:::software
    end

    %% Configuration & Calibration Layer
    subgraph "Configuration & Calibration"
        H["Config Generator"]:::software
        I["Config File"]:::software
        J["Calibration Modules"]:::software
    end

    %% Communication & Actuation Layer
    subgraph "Communication & Actuation"
        K["Arduino Communication"]:::software
        L["Servo Control (Arduino)"]:::hardware
    end

    %% Utilities Layer
    subgraph "Utilities"
        M["I/O Manager"]:::software
        N["Utility Functions"]:::software
    end

    %% Connections for main processing flow
    CA --> A
    A --> B
    B --> C
    B -->|"Inference"| D
    D -->|"ONNX Output"| F
    B --> F
    F -->|"Tracking"| G
    J -->|"Calibration"| G
    H -->|"Generates"| J
    I -->|"Loads"| J
    G -->|"Pan-Tilt Commands"| K
    K --> L

    %% Utilities support (dashed lines)
    M --- A
    M --- B
    N --- A
    N --- B

    %% Click Events
    click A "https://github.com/agoniko/facechaser/blob/main/main.py"
    click B "https://github.com/agoniko/facechaser/blob/main/src/Engine.py"
    click C "https://github.com/agoniko/facechaser/blob/main/src/Person.py"
    click D "https://github.com/agoniko/facechaser/tree/main/src/model"
    click F "https://github.com/agoniko/facechaser/blob/main/src/net_sphere.py"
    click G "https://github.com/agoniko/facechaser/tree/main/src/refsys"
    click H "https://github.com/agoniko/facechaser/blob/main/generate_config.py"
    click I "https://github.com/agoniko/facechaser/blob/main/config.json"
    click J "https://github.com/agoniko/facechaser/tree/main/src/calib"
    click K "https://github.com/agoniko/facechaser/blob/main/src/Arduino.py"
    click L "https://github.com/agoniko/facechaser/blob/main/arduino/servo/servo.ino"
    click M "https://github.com/agoniko/facechaser/blob/main/src/iomanager.py"
    click N "https://github.com/agoniko/facechaser/blob/main/src/utils.py"

    %% Styles
    classDef software fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef external fill:#d4edda,stroke:#155724,stroke-width:2px,stroke-dasharray: 5,5;
    classDef hardware fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
